fix(health): a chain blocked at a hop is dead on the board, unknown on the card

The short-circuit left the chain's exit tag untested, because the exit is itself
a hop and every hop behind the break was rewritten that way. A stand run caught
it — the test lives in a file that does not compile on the dev host, so nothing
local could have.

That is not neutral silence. selectExcluding ranks untested ABOVE dead and says
so in its own comment: with no fresh-alive member, an untested one is a better
bet than a known-dead one. Leaving a provably broken path untested is therefore
a positive preference for it over a path we merely know is dead.

The two readings answer different questions and now differ on purpose. Is this
hop's own node alive — unknown behind a break, so the card keeps untested and
blocked_by. Can this chain carry traffic — known, no, because the hop in front
of it was probed and did not answer. The board carries that second answer, which
is the one selection, the freshness gate and the manual test all read.

The exit verdict is derived, not dialled: it records the consequence of a probe
that did happen one hop earlier, and it is re-derived every pass, so the moment
the blocker answers the walk reaches the exit again and the next verdict there is
a real measurement.

Also keeps a routed group warm. Its checker used to stop on the idle timeout and
nothing filled in behind it, so a rule that fires rarely would show untested
while being in force and pay a cold probe on the first real request. The gate
that adds this work answers false when it does not know — the mirror of the one
that withholds work, so plain sing-box keeps the lifecycle it always had.

And the tls-spoof suite now skips without tcpdump instead of failing sixteen
times: a missing tool is not measured, not broken. The same distinction this
commit is about.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitea/workflows/release.yml

@@ -1,51 +1,62 @@
-# Shater v0.2 — build the 4-package signed opkg feed and publish it as a rolling
-# Gitea release consumable as an `src/gz` feed.
+# Shater v0.2 — build the 4-package signed **apk** feed and publish it as
+# per-arch Gitea releases consumable as an apk repository.
 #
-# WHAT CHANGED FROM v0.1
-#   v0.1 shipped 3 packages: xrayctl (SDK-compiled Go) + shater-core +
-#   luci-app-shater (hand-packed data .ipk). v0.2 collapses the runtime into ONE
-#   forked binary and ships 4 packages, all built the canonical SDK way:
+# WHAT WE SHIP
+#   ONE forked binary plus its OpenWrt glue, 4 packages, all built the canonical
+#   SDK way:
 #     - shaterd          PREBUILT static-musl + SPA-embedded + UPX binary. Built
 #                        OUT OF TREE by scripts/build-shaterd.sh (Go + Node + UPX)
 #                        and staged into openwrt/shaterd/files/ BEFORE the SDK
 #                        build; the openwrt/shaterd package just $(INSTALL_BIN)s
-#                        the arch-matched artifact. (arch-specific .ipk)
+#                        the arch-matched artifact. (arch-specific .apk)
 #     - shater-core      data glue, PKGARCH=all
 #     - luci-app-shater  LuCI thin launcher, PKGARCH=all (uses feeds/luci/luci.mk)
 #     - byedpi           ciadpi, C cross-compiled from source by the SDK (arch-specific)
 #
 # TARGET HARDWARE / ARCH MATRIX
 #   x86_64             -> the QEMU testbed VM (generic x86-64).
-#   aarch64_cortex-a53 -> BOTH production routers (BPI-R3 + BPI-R4, mediatek/filogic).
+#   aarch64_cortex-a53 -> BOTH production routers (BPI-R3 mini + BPI-R4,
+#     mediatek/filogic), both on 25.12 with apk-tools 3.
 #     Only shaterd + byedpi are arch-specific; shater-core + luci-app-shater are
-#     PKGARCH=all, so one build of each covers every device. opkg filters by
-#     Architecture at install time, so a single combined feed URL serves all.
+#     PKGARCH=all, so one build of each covers every device — but the RELEASES
+#     are still per-arch (see the release-apk job for why).
 #
-# FEED SIGNING (opkg / usign — OpenWrt 24.10 is opkg, not apk; apk lands at 25.12)
-#   The feed index (Packages) is usign-signed with the SECRET key in the Gitea
-#   repo secret KEY_BUILD; routers verify it with the committed public key
-#   dist/shater-feed.pub (fingerprint 5ac4b177689cb8e0). Do NOT regenerate the
-#   key — that invalidates every deployed router's trust.
+# FORMAT: apk ONLY (25.12+)
+#   The fleet runs OpenWrt/ImmortalWrt 25.12, where opkg is replaced by Alpine
+#   apk (.apk files, binary packages.adb index, EC keys in /etc/apk/keys/). The
+#   old .ipk lane was removed in 2026-07 (docs-shater/DECISIONS.md D22): no
+#   device we serve has an opkg binary at all, so building and signing a second
+#   feed served nobody.
+#
+# FEED SIGNING (EC / apk)
+#   packages.adb is signed with the EC (prime256v1) SECRET key in the Gitea repo
+#   secret KEY_APK; routers verify it with the committed public key
+#   dist/shater-apk.pem (ci/gen-apk-key.sh). Do NOT regenerate the key — that
+#   invalidates every deployed router's trust.
 #
 # AUTO-RELEASE
-#   push a tag `vX.Y.Z` -> versioned release. workflow_dispatch / (optional) main
-#   -> rolling `latest` pre-release (always-fresh feed). Publish uses the Gitea
-#   API via curl (ci/gitea-release.sh) — no external action needed.
+#   push a tag `vX.Y.Z` -> versioned per-arch releases `apk-vX.Y.Z-<arch>`.
+#   workflow_dispatch -> rolling per-arch `apk-latest-<arch>` (always-fresh
+#   feed). Publish uses the Gitea API via curl (ci/gitea-release.sh) — no
+#   external action needed. NOTE: the apk release tags deliberately do NOT start
+#   with `v` so publishing them cannot re-trigger this workflow's `v*` filter.
 #
-# APK LANE (25.12+, ADDITIVE — T2)
-#   The fleet is migrating to BananaWRT 25.12-mtk-vendor (= ImmortalWrt 25.12
-#   base), where opkg is replaced by Alpine apk (.apk, binary packages.adb
-#   index, EC keys in /etc/apk/keys/). The `build-apk` + `release-apk` jobs
-#   below build the SAME 4 packages through the ImmortalWrt 25.12 apk-SDK and
-#   publish PER-ARCH apk repos as releases `apk-latest-<arch>` (rolling) /
-#   `apk-<tag>-<arch>` (versioned). Per-arch because apk filenames carry no
-#   architecture (shaterd-0.2.0-r1.apk would collide across arches in one flat
-#   release) and apk fetches packages relative to the packages.adb URL.
-#   Signed with the EC key in the Gitea secret KEY_APK; trust anchor
-#   dist/shater-apk.pem (ci/gen-apk-key.sh). The usign/opkg lane above is
-#   UNCHANGED and keeps serving the 24.10 fleet. NOTE: the apk release tags
-#   deliberately do NOT start with `v` so publishing them cannot re-trigger
-#   this workflow's `v*` tag filter.
+# PACKAGE VERSIONING (bug B4)
+#   PKG_VERSION/PKG_RELEASE are NOT hand-written in the Makefiles any more. They
+#   used to be, and nobody bumped them: v0.2.2…v0.2.6 all shipped as
+#   `shaterd 0.2.0-r3` with different binaries inside, so `apk update` never saw
+#   a new version and routers could not be updated at all. Now `ci/version.sh`
+#   derives them from the git tag ONCE per job (the "Compute version" step,
+#   exported via $GITHUB_ENV):
+#       tag `vX.Y.Z`         -> X.Y.Z-r1
+#       anything else        -> <nearest tag>-r<commits since it + 1>
+#   and hands them to the SDK build as SHATER_PKG_VERSION/SHATER_PKG_RELEASE;
+#   $SHATER_VERSION (the same numbers, plus the short sha off-tag) is stamped
+#   into the binary's constant.Version. ci/sdk-build-apk.sh then ASSERTS that the
+#   built .apk really carry that version, so the failure can never be silent
+#   again. This is also why the build job checks out with fetch-depth: 0
+#   — `git describe` needs tags and ancestry. `byedpi` is excluded: it keeps
+#   upstream ByeDPI's own PKG_VERSION (see openwrt/byedpi/Makefile).
 
 # CACHING (T3 — fast CI)
 #   All caches use actions/cache pinned to v3.3.2: the LAST release speaking the
@@ -63,34 +74,33 @@
 #       (PKG_VERSION/PKG_HASH live there). Stale-safe: the buildroot verifies
 #       PKG_HASH on every dl/ file and re-downloads on mismatch, so restore-keys
 #       prefix fallback is allowed.
-#     - Go module + build cache — key = hash of go.sum; shared by all 4 build
+#     - Go module + build cache — key = hash of go.sum; shared by both build
 #       jobs (each builds both GOARCHes).
 #     - panel/node_modules — key = hash of panel/package-lock.json, exact-only
 #       (a lockfile change MUST miss); on hit build-shaterd.sh gets --fast.
-#     - apt .deb archives for the apk lane's debian:bookworm host-deps
-#       (.cache/apt) — key = hash of ci/sdk-build-apk.sh (the apt list is in it).
-#     - usign binary (.cache/tools) — static helper, fixed key.
+#     - apt .deb archives for the debian:bookworm host-deps of the apk SDK
+#       container (.cache/apt) — key = hash of ci/sdk-build-apk.sh (the apt list
+#       is in it).
 #     - SDK feeds/ git checkouts (.cache/feeds) — the single biggest recurring
 #       cost: `scripts/feeds update -a` cloned base+packages+luci+routing+
 #       telephony EVERY run (~7 min/job; github.com is ~1 MB/s from this
 #       runner — run 51 evidence). The feeds dir is symlinked into the SDK
 #       container from the workspace cache; `feeds update` on an existing clone
 #       is a fast fetch+checkout of the pinned revs. Correctness-safe: update
-#       always checks out feeds.conf's pins, and ci/sdk-build*.sh wipes the
+#       always checks out feeds.conf's pins, and ci/sdk-build-apk.sh wipes the
 #       cache + re-clones fresh if update ever fails on a cached checkout.
-#       Key = lane + SDK release (shared across the two arch jobs of a lane —
-#       same release pins identical feed revs; the sequential runner means the
-#       second arch restores what the first saved). restore-keys lets an SDK
-#       version bump start from the old clones (git fetch delta, not re-clone).
+#       Key = lane + SDK release (shared across the two arch jobs — the same
+#       release pins identical feed revs; the sequential runner means the second
+#       arch restores what the first saved). restore-keys lets an SDK version
+#       bump start from the old clones (git fetch delta, not re-clone).
 #   Act_runner facts this design leans on (verified in run 51 logs):
 #     - the cache backend works: restores/saves confirmed, hashFiles() works;
-#     - docker images (openwrt/sdk, debian:bookworm, runner-images) live on the
-#       PERSISTENT host daemon — "Image is up to date" each run, no re-download;
+#     - docker images (debian:bookworm, runner-images) live on the PERSISTENT
+#       host daemon — "Image is up to date" each run, no re-download;
 #     - each actions/cache SAVE is followed by an exact 3-minute act_runner
 #       stall (node process lingers; hit→no-save→no stall). Steady state saves
 #       nothing, so adding cache entries is fine, but keys that change every
 #       run (e.g. github.sha) would cost +3 min/entry/run — do NOT do that.
-
 name: release
 
 on:
@@ -108,137 +118,11 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
-    name: ${{ matrix.arch }}
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { arch: x86_64,             sdk: x86_64-24.10.4 }            # testbed VM (generic x86-64)
-          - { arch: aarch64_cortex-a53, sdk: mediatek-filogic-24.10.4 }  # BPI-R3 + BPI-R4 (mediatek/filogic)
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      # scripts/build-shaterd.sh builds the engine via a go.mod
-      # `replace => ./submodules/wireguard-go` (AmneziaWG fork), so that submodule
-      # must be present or `go build` dies with "no such file or directory".
-      # actions/checkout does not fetch submodules by default; init ONLY this one
-      # (clients/apple+android are large and unused here).
-      - name: Init wireguard-go submodule (awg)
-        run: git submodule update --init --depth 1 submodules/wireguard-go
-
-      # Toolchain for scripts/build-shaterd.sh: Go (daemon), Node (Vite SPA), UPX.
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: go.mod   # pins Go 1.24.7 (go.mod `go` line)
-          cache: false              # explicit actions/cache@v3.3.2 below (setup-go's
-                                    # built-in cache uses the new API act_runner lacks)
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'        # Vite 5 needs Node 18+; 20 LTS
-
-      # ---- caches (see the header comment for keys + version pin rationale) ----
-      - name: Cache Go modules + build cache
-        uses: actions/cache@v3.3.2
-        with:
-          path: |
-            ~/go/pkg/mod
-            ~/.cache/go-build
-          key: go-${{ hashFiles('go.sum') }}
-          restore-keys: |
-            go-
-
-      - name: Cache panel node_modules
-        id: npm-cache
-        uses: actions/cache@v3.3.2
-        with:
-          path: panel/node_modules
-          key: npm-${{ hashFiles('panel/package-lock.json') }}
-          # NO restore-keys: node_modules must exactly match the lockfile;
-          # on any lockfile change this misses and `npm ci` runs fresh.
-
-      - name: Cache SDK dl/ (package sources)
-        uses: actions/cache@v3.3.2
-        with:
-          path: .cache/dl
-          key: dl-${{ hashFiles('openwrt/*/Makefile') }}
-          restore-keys: |
-            dl-
-
-      # feeds git checkouts (see header): both 24.10.4 arch jobs share one entry
-      # (same release = same feeds.conf.default pins), so derive the release
-      # from the matrix sdk tag (x86_64-24.10.4 -> 24.10.4).
-      - name: Compute feeds cache key
-        id: feedskey
-        run: echo "ver=$(echo '${{ matrix.sdk }}' | sed 's/.*-//')" >> "$GITHUB_OUTPUT"
-
-      - name: Cache SDK feeds checkouts
-        uses: actions/cache@v3.3.2
-        with:
-          path: .cache/feeds
-          key: feeds-opkg-${{ steps.feedskey.outputs.ver }}
-          restore-keys: |
-            feeds-opkg-
-
-      - name: Cache CI tools (usign)
-        uses: actions/cache@v3.3.2
-        with:
-          path: .cache/tools
-          key: tools-usign-v1
-
-      - name: Install UPX
-        run: sudo apt-get update -qq && sudo apt-get install -y -qq upx-ucl
-
-      # Build the SPA-embedded, static-musl, UPX'd shaterd for BOTH arches and
-      # stage dist/shaterd-<a>.upx into openwrt/shaterd/files/. MUST run before
-      # the SDK package build (the openwrt/shaterd package installs the staged
-      # artifact). VERSION is stamped into constant.Version. On an exact
-      # node_modules cache hit, --fast skips the redundant `npm ci`.
-      - name: Build & stage shaterd artifact
-        env:
-          NPM_CACHE_HIT: ${{ steps.npm-cache.outputs.cache-hit }}
-        run: |
-          set -eu
-          if [ "${GITHUB_REF#refs/tags/}" != "$GITHUB_REF" ]; then
-            V="${GITHUB_REF#refs/tags/}"
-          else
-            V="v0.2.0-dev"
-          fi
-          FAST=""
-          if [ "${NPM_CACHE_HIT:-}" = "true" ]; then FAST="--fast"; fi
-          echo "shaterd version: $V (npm cache hit: ${NPM_CACHE_HIT:-false})"
-          bash scripts/build-shaterd.sh "$V" $FAST
-
-      # Compile the 4 packages through the arch-matched OpenWrt SDK and produce a
-      # signed per-arch opkg feed (Packages + Packages.gz + Packages.sig + .ipk).
-      - name: Build signed feed (SDK)
-        env:
-          KEY_BUILD: ${{ secrets.KEY_BUILD }}
-        run: bash ci/build-feed.sh "${{ matrix.arch }}" "${{ matrix.sdk }}" "out/${{ matrix.arch }}"
-
-      - name: Show feed
-        run: ls -l "out/${{ matrix.arch }}" && cat "out/${{ matrix.arch }}/Packages"
-
-      - name: Upload feed artifact
-        # v4 uses an artifact backend Gitea Actions does not implement
-        # (GHESNotSupportedError); v3 works on Gitea's act_runner.
-        uses: actions/upload-artifact@v3
-        with:
-          name: shater-${{ matrix.arch }}
-          path: out/${{ matrix.arch }}/*
-          if-no-files-found: error
-
   # ---------------------------------------------------------------------------
-  # APK lane (additive): the same 4 packages through the ImmortalWrt 25.12
-  # apk-SDK for the 25.12/apk fleet (BananaWRT 25.12-mtk-vendor routers + the
-  # future 25.12 VM). Produces a per-arch apk repo dir: *.apk + EC-signed
-  # packages.adb + shater-apk.pem. Artifact prefix `apkfeed-` (NOT `shater-`)
-  # so the opkg release job's `artifacts/shater-*` glob never picks these up.
+  # Build the 4 packages through the ImmortalWrt 25.12 apk-SDK for the 25.12/apk
+  # fleet (BPI-R3 mini on BananaWRT 25.12-mtk-vendor, BPI-R4 on OpenWrt 25.12,
+  # and the testbed VM). Produces a per-arch apk repo dir: *.apk + EC-signed
+  # packages.adb + shater-apk.pem, uploaded as the artifact `apkfeed-<arch>`.
   build-apk:
     name: apk ${{ matrix.arch }}
     runs-on: ubuntu-latest
@@ -253,8 +137,14 @@ jobs:
           - arch: aarch64_cortex-a53  # BPI-R3 mini (BananaWRT 25.12-mtk-vendor) + BPI-R4
             sdk_url: https://downloads.immortalwrt.org/releases/25.12.1/targets/mediatek/filogic/immortalwrt-sdk-25.12.1-mediatek-filogic_gcc-14.3.0_musl.Linux-x86_64.tar.zst
     steps:
+      # fetch-depth: 0 — the package version is DERIVED from the git tag
+      # (ci/version.sh: nearest `vX.Y.Z` + commits since it). The default
+      # shallow checkout has neither tags nor ancestry, so `git describe` would
+      # fail and every dispatch build would fall back to 0.0.0.
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       # scripts/build-shaterd.sh builds the AmneziaWG-patched wireguard-go via a
       # go.mod `replace => ./submodules/wireguard-go`, so that submodule must be
@@ -263,6 +153,13 @@ jobs:
       - name: Init wireguard-go submodule (awg)
         run: git submodule update --init --depth 1 submodules/wireguard-go
 
+      # THE version step (bug B4). One computation, used by both the binary
+      # (constant.Version) and the three tag-versioned packages, exported to
+      # every later step of this job:
+      #   tag vX.Y.Z -> X.Y.Z-r1 ; off-tag -> <last tag>-r<commits+1>
+      - name: Compute version from git tag
+        run: bash ci/version.sh --env >> "$GITHUB_ENV"
+
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
@@ -336,25 +233,36 @@ jobs:
           restore-keys: |
             feeds-apk-
 
+      # D23 — the shipped tag set is a TRIMMED subset (scripts/router-tags.sh);
+      # everything else in CI builds with the full upstream set, so without this
+      # step the one combination we actually ship is never exercised. That is how
+      # `with_gvisor` was trimmed while `with_wireguard` stayed and every shipped
+      # binary answered a WireGuard node with "gVisor is not included in this
+      # build" (2026-07-25). The check runs the declared-feature/tag comparison
+      # and then constructs one node of every declared protocol through box.New
+      # UNDER THE SHIPPED TAGS. It runs before the artifact build so a tag trim
+      # that breaks a feature fails the release instead of shipping.
+      - name: Verify the shipped build-tag set (D23)
+        run: bash scripts/check-router-tags.sh
+
       - name: Install UPX
         run: sudo apt-get update -qq && sudo apt-get install -y -qq upx-ucl
 
-      # Same artifact-order contract as the opkg lane: the SPA-embedded shaterd
-      # binary is built OUT of the SDK and staged before the package build.
+      # Artifact-order contract: the SPA-embedded shaterd binary is built OUT of
+      # the SDK and staged into openwrt/shaterd/files/ BEFORE the package build
+      # (the openwrt/shaterd package only installs the staged artifact).
+      # $SHATER_VERSION (from the version step above) is stamped into
+      # constant.Version, so the binary and the package agree. On an exact
+      # node_modules cache hit, --fast skips the redundant `npm ci`.
       - name: Build & stage shaterd artifact
         env:
           NPM_CACHE_HIT: ${{ steps.npm-cache.outputs.cache-hit }}
         run: |
           set -eu
-          if [ "${GITHUB_REF#refs/tags/}" != "$GITHUB_REF" ]; then
-            V="${GITHUB_REF#refs/tags/}"
-          else
-            V="v0.2.0-dev"
-          fi
           FAST=""
           if [ "${NPM_CACHE_HIT:-}" = "true" ]; then FAST="--fast"; fi
-          echo "shaterd version: $V (npm cache hit: ${NPM_CACHE_HIT:-false})"
-          bash scripts/build-shaterd.sh "$V" $FAST
+          echo "shaterd version: $SHATER_VERSION / package ${SHATER_PKG_VERSION}-r${SHATER_PKG_RELEASE} (npm cache hit: ${NPM_CACHE_HIT:-false})"
+          bash scripts/build-shaterd.sh $FAST
 
       # Compile the 4 packages as .apk through the ImmortalWrt 25.12 SDK and
       # sign the per-arch packages.adb with the EC key (secret KEY_APK).
@@ -377,113 +285,21 @@ jobs:
           if-no-files-found: error
 
   # ---------------------------------------------------------------------------
-  # Publish once both arches are built. Rolling `latest` on dispatch, a versioned
-  # release on a `vX.Y.Z` tag. Self-contained (curl -> Gitea API).
-  release:
-    name: release
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Download all arch feeds
-        uses: actions/download-artifact@v3
-        with:
-          path: artifacts
-
-      - name: Assemble release assets
-        id: assets
-        run: |
-          set -eu
-          mkdir -p release
-          # For each downloaded arch feed: one ready-to-serve tarball + loose ipks.
-          for d in artifacts/shater-*; do
-            [ -d "$d" ] || continue
-            arch="${d#artifacts/shater-}"
-            tar -C "$d" -czf "release/shater-feed-${arch}.tar.gz" .
-            # loose .ipk for direct `opkg install <url>` (dedupe shared _all ipks by name)
-            for ipk in "$d"/*.ipk; do
-              [ -e "$ipk" ] || continue
-              cp -n "$ipk" "release/$(basename "$ipk")"
-            done
-          done
-          # ship the feed's public key so routers can verify (see docs-shater/INSTALL.md)
-          cp -f dist/shater-feed.pub release/shater-feed.pub
-          ls -l release
-          echo "count=$(ls release | wc -l)" >> "$GITHUB_OUTPUT"
-
-      # restore the prebuilt usign binary (skips apt + cmake + clone + build)
-      - name: Cache CI tools (usign)
-        uses: actions/cache@v3.3.2
-        with:
-          path: .cache/tools
-          key: tools-usign-v1
-
-      - name: Install usign (feed signer)
-        run: bash ci/install-usign.sh
-
-      - name: Build & sign combined opkg feed index
-        # One Packages/Packages.gz over ALL loose .ipk (every arch + arch=all),
-        # with basename Filenames. opkg filters by Architecture, so a single
-        # release URL serves every device: BPI routers pick aarch64_cortex-a53 +
-        # all, the x86 testbed picks x86_64 + all. Signed with KEY_BUILD so
-        # routers keep check_signature on. This is what makes the release directly
-        # consumable as an `src/gz` feed (see docs-shater/INSTALL.md).
-        env:
-          KEY_BUILD: ${{ secrets.KEY_BUILD }}
-        run: bash ci/make-index.sh release
-
-      - name: Determine release identity
-        id: rel
-        run: |
-          set -eu
-          if [ "${GITHUB_REF#refs/tags/}" != "$GITHUB_REF" ]; then
-            echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-            echo "name=shater ${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-            echo "prerelease=false" >> "$GITHUB_OUTPUT"
-            echo "rolling=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "tag=latest" >> "$GITHUB_OUTPUT"
-            echo "name=shater latest (main)" >> "$GITHUB_OUTPUT"
-            echo "prerelease=true" >> "$GITHUB_OUTPUT"
-            echo "rolling=true" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Publish Gitea release
-        env:
-          TOKEN: ${{ secrets.RELEASE_TOKEN != '' && secrets.RELEASE_TOKEN || github.token }}
-          TAG: ${{ steps.rel.outputs.tag }}
-          NAME: ${{ steps.rel.outputs.name }}
-          PRERELEASE: ${{ steps.rel.outputs.prerelease }}
-          ROLLING: ${{ steps.rel.outputs.rolling }}
-          BODY: |
-            Automated build. Packages: shaterd + byedpi (per-arch), shater-core +
-            luci-app-shater (arch=all).
-            Targets: x86_64 (testbed) and aarch64_cortex-a53 (BPI-R3 + BPI-R4, mediatek/filogic).
-
-            ── Add as an opkg feed (recommended — then `opkg upgrade` just works) ──
-            This release is itself a SIGNED package feed; opkg filters by
-            architecture, so the same lines work on every device:
-              wget -O /etc/opkg/keys/5ac4b177689cb8e0 https://git.qomar.pw/omar/shater/releases/download/latest/shater-feed.pub
-              echo "src/gz shater https://git.qomar.pw/omar/shater/releases/download/latest" >> /etc/opkg/customfeeds.conf
-              opkg update
-              opkg install luci-app-shater        # pulls shater-core + shaterd too
-            The public-key install is one-time; after it, `opkg update/upgrade`
-            verify the signature with check_signature left on. Full guide: docs-shater/INSTALL.md.
-
-            ── Or install the loose .ipk directly / from the tarball feed ──
-              wget -O /tmp/f.tgz <this release>/shater-feed-aarch64_cortex-a53.tar.gz
-              mkdir -p /tmp/shater && tar -C /tmp/shater -xzf /tmp/f.tgz
-              opkg install /tmp/shater/luci-app-shater_*_all.ipk
-        run: bash ci/gitea-release.sh release/*
-
-  # ---------------------------------------------------------------------------
-  # Publish the apk lane: ONE release PER ARCH (apk package filenames carry no
-  # arch, and apk fetches `<name>-<ver>.apk` relative to the packages.adb URL —
-  # a flat multi-arch release would collide). Rolling `apk-latest-<arch>` on
-  # dispatch, `apk-<tag>-<arch>` on a version tag. The tags do NOT match the
-  # workflow's `v*` trigger, so publishing them cannot re-trigger the build.
+  # Publish: ONE release PER ARCH (apk package filenames carry no arch, and apk
+  # fetches `<name>-<ver>.apk` relative to the packages.adb URL — a flat
+  # multi-arch release would collide). Every run refreshes the ROLLING pointer
+  # `apk-latest-<arch>`; a `vX.Y.Z` tag run ALSO publishes the pinnable
+  # `apk-vX.Y.Z-<arch>`. The tags do NOT match the workflow's `v*` trigger, so
+  # publishing them cannot re-trigger the build.
+  #
+  # WHY THE ROLLING RELEASE IS PUBLISHED ON TAG RUNS TOO (fixed 2026-07-25):
+  # it used to be an either/or — `TAG=apk-latest-<arch>` on dispatch, ELSE
+  # `TAG=apk-<ver>-<arch>` — so once releases moved to tag pushes the rolling
+  # pointer was never written again. It froze at 0.2.0 (published 2026-07-24)
+  # while v0.2.9/v0.2.10 published fine, and every router whose
+  # /etc/apk/repositories.d/shater.list points at the rolling URL kept getting a
+  # successful, silent `apk update` with nothing new. Rolling is the whole point
+  # of that URL, so it is now written unconditionally and asserted afterwards.
   release-apk:
     name: release apk
     needs: build-apk
@@ -501,6 +317,9 @@ jobs:
         with:
           path: artifacts
 
+      # Identity of the VERSIONED release only. The rolling pointer is published
+      # on every run with fixed prerelease=true/rolling=true, so it needs nothing
+      # from here.
       - name: Determine release identity
         id: rel
         run: |
@@ -522,25 +341,95 @@ jobs:
           PRERELEASE: ${{ steps.rel.outputs.prerelease }}
           ROLLING: ${{ steps.rel.outputs.rolling }}
         run: |
-          set -eu
+          set -euo pipefail
           for d in artifacts/apkfeed-*; do
             [ -d "$d" ] || continue
             arch="${d#artifacts/apkfeed-}"
-            if [ "$VER" = latest ]; then TAG="apk-latest-$arch"; else TAG="apk-$VER-$arch"; fi
+            ROLL="apk-latest-$arch"
+
+            # The version we just built, read straight off the artifact
+            # (`shaterd-<ver>-r<rel>.apk`). NOT recomputed with ci/version.sh:
+            # this job checks out shallow, so it has no tags to describe from.
+            pkg=""
+            for a in "$d"/shaterd-*.apk; do
+              if [ -f "$a" ]; then pkg="$(basename "$a")"; fi
+            done
+            [ -n "$pkg" ] || { echo "[release-apk] ERROR: no shaterd-*.apk in $d"; exit 11; }
+            want="${pkg#shaterd-}"; want="${want%.apk}"
+            echo "[release-apk] arch=$arch built version=$want"
+
             BODY="Automated apk (OpenWrt/ImmortalWrt 25.12+) package repo for \`$arch\`.
           Packages: shaterd + byedpi (per-arch), shater-core + luci-app-shater (arch=all).
+          This build: \`$want\`.
           The index \`packages.adb\` is EC-signed; trust anchor \`shater-apk.pem\` (also in \`dist/\`).
 
-          ── Add as an apk repository (auto-updates via \`apk upgrade\`) ──
-            wget -O /etc/apk/keys/shater-apk.pem https://git.qomar.pw/omar/shater/releases/download/$TAG/shater-apk.pem
+          ── Add as an apk repository (rolling — install once, then just update) ──
+            wget -O /etc/apk/keys/shater-apk.pem https://git.qomar.pw/omar/shater/releases/download/$ROLL/shater-apk.pem
             echo \"https://git.qomar.pw/omar/shater/releases/download/apk-latest-\$(cat /etc/apk/arch)/packages.adb\" > /etc/apk/repositories.d/shater.list
             apk update
             apk add luci-app-shater      # pulls shater-core + shaterd too
             apk add byedpi               # optional: ByeDPI desync egress
-          Update: apk update && apk upgrade shaterd shater-core luci-app-shater byedpi
-          Full guide: docs-shater/INSTALL.md §6. The opkg/24.10 feed lives in the \`latest\` release."
-            echo "[release-apk] publishing $TAG from $d"
-            TAG="$TAG" NAME="shater apk $VER ($arch)" BODY="$BODY" \
-              PRERELEASE="$PRERELEASE" ROLLING="$ROLLING" \
+          \`apk-latest-<arch>\` is a MOVING pointer: every release run replaces its
+          assets, so the same repo line keeps serving the newest build. To pin a
+          version instead, point the repo line at
+          \`.../download/apk-vX.Y.Z-\$(cat /etc/apk/arch)/packages.adb\` — then the
+          file must be edited by hand for each upgrade.
+          ── Update — ALWAYS name the packages, NEVER a bare \`apk upgrade\` ──
+            apk update
+            apk upgrade shaterd shater-core luci-app-shater byedpi
+          A bare \`apk upgrade\` reconciles EVERY installed package against every
+          configured repo and can downgrade unrelated system packages; naming them
+          upgrades only those (apk-tools 3: \"If list of packages is provided, only
+          those packages are upgraded along with needed dependencies\").
+          Full guide: docs-shater/INSTALL.md §5."
+
+            # 1) the pinnable versioned release (tag runs only)
+            if [ "$VER" != latest ]; then
+              echo "[release-apk] publishing apk-$VER-$arch from $d"
+              TAG="apk-$VER-$arch" NAME="shater apk $VER ($arch)" BODY="$BODY" \
+                PRERELEASE="$PRERELEASE" ROLLING="$ROLLING" \
+                bash ci/gitea-release.sh "$d"/*
+            fi
+
+            # 2) the rolling pointer — ALWAYS, tag run included. ci/gitea-release.sh
+            #    deletes the existing release before recreating it, so the old
+            #    version's assets are REPLACED, never accumulated (two versions of
+            #    one package in one index would let apk choose, not us).
+            echo "[release-apk] publishing $ROLL from $d"
+            TAG="$ROLL" NAME="shater apk latest ($arch)" BODY="$BODY" \
+              PRERELEASE=true ROLLING=true \
               bash ci/gitea-release.sh "$d"/*
+
+            # 3) ASSERT the rolling release really serves THIS build — same class
+            #    of check as ci/sdk-build-apk.sh's package-version assert, and for
+            #    the same reason: the previous failure mode was silent. Reads the
+            #    published release back over the API and requires our three
+            #    tag-versioned packages at $want, the index, the key — and NO
+            #    left-over package asset at any other version.
+            api="$GITHUB_SERVER_URL/api/v1/repos/$GITHUB_REPOSITORY/releases/tags/$ROLL"
+            got="$(curl -fsS -H "Authorization: token $TOKEN" "$api" \
+                   | tr '{},' '\n\n\n' \
+                   | sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | sort -u)" || {
+              echo "[release-apk] ERROR: cannot read back $ROLL from the API"; exit 12; }
+            echo "[release-apk] $ROLL assets: $(printf '%s ' $got)"
+            # here-string, NOT `printf | grep -q`: under `pipefail` the early
+            # exit of grep -q can SIGPIPE the writer and fail a passing check.
+            for f in "shaterd-$want.apk" "shater-core-$want.apk" \
+                     "luci-app-shater-$want.apk" packages.adb shater-apk.pem; do
+              grep -qxF "$f" <<<"$got" || {
+                echo "[release-apk] ERROR: $ROLL does not contain '$f' after publish."
+                echo "        A router pinned to the rolling URL would have silently"
+                echo "        stayed on its old version with a successful apk update."
+                exit 13; }
+            done
+            stale="$(grep -E '^(shaterd|shater-core|luci-app-shater)-.*\.apk$' <<<"$got" \
+                     | grep -vxF -e "shaterd-$want.apk" -e "shater-core-$want.apk" \
+                                 -e "luci-app-shater-$want.apk" || true)"
+            [ -z "$stale" ] || {
+              echo "[release-apk] ERROR: $ROLL still holds stale package assets:"
+              printf '          %s\n' $stale
+              echo "        Two versions of one package in one feed = apk picks by its"
+              echo "        own rules, not by our intent."
+              exit 14; }
+            echo "[release-apk] OK — $ROLL serves $want"
           done

.gitignore

@@ -63,7 +63,7 @@ nul
 /venv/
 /test/cache.db
 
-# feed artifacts (tracked public key dist/shater-feed.pub is force-added)
+# feed artifacts (the tracked apk trust anchor dist/shater-apk.pem is force-added)
 /dist/
 
 # local agent config (CLAUDE.md is deliberately tracked; .claude local settings are not)

README.en.md

@@ -49,29 +49,22 @@ Full list with MVP/T1/T2 tags — [`docs-shater/FEATURES.md`](docs-shater/FEATUR
 
 ## Install
 
-Two signed feeds. Pick by the router's OpenWrt version. Verbatim commands and the
-manual `.ipk`/`.apk` install are in [`docs-shater/INSTALL.md`](docs-shater/INSTALL.md).
-
-**opkg (OpenWrt 24.10):**
+One signed **apk** feed (OpenWrt / ImmortalWrt / BananaWRT **25.12+**), one
+release per arch. Verbatim commands, the manual `.apk` install and the
+rolling-vs-pinned choice are in
+[`docs-shater/INSTALL.md`](docs-shater/INSTALL.md).
 
 ```sh
-wget -O /etc/opkg/keys/5ac4b177689cb8e0 \
-  https://git.qomar.pw/omar/shater/releases/download/latest/shater-feed.pub
-echo "src/gz shater https://git.qomar.pw/omar/shater/releases/download/latest" \
-  >> /etc/opkg/customfeeds.conf
-opkg update && opkg install luci-app-shater   # -> shater-core -> shaterd
-```
-
-**apk (OpenWrt / ImmortalWrt / BananaWRT 25.12+):**
-
-```sh
-wget -O /etc/apk/keys/shater-apk.pem \
-  "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/shater-apk.pem"
-echo "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/packages.adb" \
-  > /etc/apk/repositories.d/shater.list
+wget -O /etc/apk/keys/shater-apk.pem   "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/shater-apk.pem"
+echo "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/packages.adb"   > /etc/apk/repositories.d/shater.list
 apk update && apk add luci-app-shater         # -> shater-core -> shaterd
 ```
 
+`apk-latest-<arch>` is a moving pointer refreshed by every release run — install
+once and `apk update && apk upgrade shaterd shater-core luci-app-shater byedpi`
+keeps the router current. Point the repo line at `apk-vX.Y.Z-<arch>` instead to
+pin a build; that file then has to be edited by hand for every upgrade.
+
 shater ships **inert** (globals off) so install never breaks connectivity. After
 configuring nodes/rules: `uci set shater.globals.enabled=1 && uci commit shater`,
 then `shaterd apply` and `shaterd confirm`.
@@ -91,16 +84,17 @@ into `openwrt/shaterd/files/`. Details in
 | `panel/` | Admin SPA (Vite + React + TS) and its Go server |
 | `openwrt/` | Packages: `shaterd`, `shater-core`, `luci-app-shater`, `byedpi` |
 | `docs-shater/` | Product documentation |
-| `scripts/`, `ci/`, `.gitea/workflows/` | Build script, feed/release scripts, CI |
+| `scripts/`, `ci/`, `.gitea/workflows/` | Build script, apk feed/release scripts, CI |
 | `SPECS/`, `docs-lx/` | Engine-fork constitution/specs and feature-config reference |
 | `docs/`, `mkdocs.yml` | **Upstream** sing-box docs (mkdocs) — kept as-is |
 | `adapter/ cmd/ dns/ route/ option/ protocol/ transport/ …` | sing-box-lx engine tree |
 
 ## CI, upstream & license
 
-CI (`.gitea/workflows/release.yml`) builds all 4 packages and publishes signed
-feeds: opkg (usign, key `5ac4b177689cb8e0`) and apk (EC key `shater-apk.pem`). A
-`vX.Y.Z` tag → versioned release; `workflow_dispatch` → rolling `latest`.
+CI (`.gitea/workflows/release.yml`) builds all 4 packages and publishes a signed
+per-arch apk repo (EC key `shater-apk.pem`). A `vX.Y.Z` tag → the pinnable
+`apk-vX.Y.Z-<arch>`; every run also refreshes the rolling `apk-latest-<arch>` and
+asserts over the API that it really serves the version just built.
 
 The engine is the **sing-box-lx** fork — a thin downstream of upstream sing-box that
 lives by **rebase, never merge**; its constitution is

README.md

@@ -10,7 +10,7 @@
 
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE)
 ![targets: x86_64 · aarch64_cortex-a53](https://img.shields.io/badge/targets-x86__64%20%C2%B7%20aarch64__cortex--a53-brightgreen.svg)
-![feeds: opkg 24.10 · apk 25.12](https://img.shields.io/badge/feeds-opkg%2024.10%20%C2%B7%20apk%2025.12-orange.svg)
+![feed: apk 25.12+](https://img.shields.io/badge/feed-apk%2025.12%2B-orange.svg)
 
 ---
 
@@ -128,36 +128,15 @@ data-plane, DNS-flow, apply-flow) — в [`docs-shater/ARCHITECTURE.md`](docs-sh
 
 ## Установка
 
-shater поставляется двумя подписанными фидами. Выберите по версии OpenWrt на роутере:
-
-- **OpenWrt 24.10** → фид **opkg** (`.ipk`, `Packages.gz`, ключ usign).
-- **OpenWrt / ImmortalWrt / BananaWRT 25.12+** → фид **apk** (`.apk`, `packages.adb`,
-  EC-ключ).
+shater поставляется одним подписанным **apk-фидом** (OpenWrt / ImmortalWrt /
+BananaWRT **25.12+**: `.apk`, индекс `packages.adb`, EC-ключ в `/etc/apk/keys/`).
+Старый opkg-фид (`.ipk`, 24.10) снят — оба наших роутера на 25.12 с apk-tools 3,
+бинаря `opkg` там просто нет (`docs-shater/DECISIONS.md` D22).
 
 Пакеты ставятся по зависимостям: `shaterd` → `shater-core` → `luci-app-shater`
 (+ опциональный `byedpi`). `shaterd` подтягивается автоматически как зависимость.
 
-### Путь A — фид opkg (OpenWrt 24.10)
-
-```sh
-# 1) доверяем ключу фида — ИМЯ файла обязано равняться отпечатку usign-ключа.
-wget -O /etc/opkg/keys/5ac4b177689cb8e0 \
-  https://git.qomar.pw/omar/shater/releases/download/latest/shater-feed.pub
-
-# 2) добавляем фид (один URL обслуживает все арки).
-echo "src/gz shater https://git.qomar.pw/omar/shater/releases/download/latest" \
-  >> /etc/opkg/customfeeds.conf
-
-# 3) обновляемся и ставим (shaterd подтянется как зависимость).
-opkg update
-opkg install luci-app-shater        # -> shater-core -> shaterd
-opkg install byedpi                 # опционально: ByeDPI desync-egress
-```
-
-Обновление: `opkg update && opkg upgrade shaterd shater-core luci-app-shater byedpi`
-(обновляйте только эти четыре пакета, не системные).
-
-### Путь B — фид apk (OpenWrt / ImmortalWrt / BananaWRT 25.12+)
+### Фид apk
 
 `/etc/apk/arch` сам выбирает нужный per-arch релиз (apk-релизы раздельны по арке):
 
@@ -176,11 +155,38 @@ apk add luci-app-shater        # -> shater-core -> shaterd
 apk add byedpi                 # опционально: ByeDPI desync-egress
 ```
 
-Обновление: `apk update && apk upgrade shaterd shater-core luci-app-shater byedpi`.
+Обновление — **перечисляйте пакеты явно, голый `apk upgrade` не запускайте**: без
+аргументов apk пересобирает состояние ВСЕХ установленных пакетов по ВСЕМ
+подключённым репозиториям и может задеть (в т.ч. откатить) посторонние системные
+пакеты.
 
-> Полные инструкции — раздельная установка из `.ipk`/`.apk` вручную, закрепление
-> версии (`vX.Y.Z` / `apk-vX.Y.Z-<arch>`), совместимость с BananaWRT
-> `25.12-mtk-vendor` — в [`docs-shater/INSTALL.md`](docs-shater/INSTALL.md).
+```sh
+apk update
+apk upgrade shaterd shater-core luci-app-shater byedpi
+# эквивалент, дополнительно закрепляющий пакеты в world:
+# apk add -u shaterd shater-core luci-app-shater byedpi
+```
+
+Документация apk-tools 3 про `apk upgrade`: *«If list of packages is provided,
+only those packages are upgraded along with needed dependencies»*. Проверить
+установленные версии: `apk list -I shaterd shater-core luci-app-shater byedpi`.
+
+> **Роллинг или фиксация — это выбор URL в `shater.list`.** `apk-latest-<arch>`
+> — движущийся указатель: каждый релизный прогон заменяет его ассеты, поэтому
+> «поставил и забыл»: `apk update` сам видит новую сборку. `apk-vX.Y.Z-<arch>` —
+> фиксация на конкретной сборке: роутер не получит ничего нового, пока
+> `/etc/apk/repositories.d/shater.list` не отредактируют руками — на каждом
+> роутере и на каждый релиз. На `mini_router` сознательно прописан
+> версионированный URL, и ручная правка — его цена. Подробнее —
+> [`docs-shater/INSTALL.md`](docs-shater/INSTALL.md) §5.1.
+
+> Версии пакетов CI берёт из git-тега (`vX.Y.Z` → `X.Y.Z-r1`, сборка вне тега →
+> `X.Y.Z-r<коммитов+1>`), поэтому каждая новая сборка действительно видна
+> менеджеру пакетов как новая. Подробности — `docs-shater/INSTALL.md` §2.1.
+
+> Полные инструкции — ручная установка из `.apk`, фиксация версии
+> (`apk-vX.Y.Z-<arch>`), совместимость с BananaWRT `25.12-mtk-vendor` — в
+> [`docs-shater/INSTALL.md`](docs-shater/INSTALL.md).
 
 ### Включение
 
@@ -234,8 +240,8 @@ arm64}` с musl-static набором тегов (`CGO_ENABLED=0 GOOS=linux`), s
 | `openwrt/` | Пакеты: `shaterd`, `shater-core`, `luci-app-shater`, `byedpi` |
 | `docs-shater/` | Документация продукта (см. таблицу ниже) |
 | `scripts/` | `build-shaterd.sh` — сборка ship-артефакта |
-| `ci/` | Скрипты сборки фидов и релизов (SDK, usign/EC, Gitea API) |
-| `.gitea/workflows/` | `release.yml` — CI: сборка пакетов + подписанные фиды opkg/apk |
+| `ci/` | Скрипты сборки apk-фида и релизов (SDK, EC-подпись, Gitea API) |
+| `.gitea/workflows/` | `release.yml` — CI: сборка пакетов + подписанный apk-фид |
 | `SPECS/` | Конституция форка движка и спеки (Spec Kit) |
 | `docs-lx/` | Справочник конфигурации фич движка (`lx-config.md`, `.ru.md`) |
 | `lx-test/`, `submodules/` | Примеры конфигов движка и submodule AmneziaWG-рантайма |
@@ -249,16 +255,17 @@ arm64}` с musl-static набором тегов (`CGO_ENABLED=0 GOOS=linux`), s
 CI на **Gitea Actions** (`.gitea/workflows/release.yml`) собирает все 4 пакета и
 публикует **подписанные фиды**:
 
-- **opkg (24.10):** один комбинированный релиз, подписан usign-ключом (публичный
-  `dist/shater-feed.pub`, отпечаток `5ac4b177689cb8e0`; секрет — в Gitea-secret
-  `KEY_BUILD`).
-- **apk (25.12+):** параллельная линия, **по релизу на арку**, подписан EC-ключом
-  (`dist/shater-apk.pem`; секрет — `KEY_APK`).
+- **apk (25.12+)** — единственный формат: **по релизу на арку**, индекс
+  `packages.adb` подписан EC-ключом (публичный `dist/shater-apk.pem`; секрет — в
+  Gitea-secret `KEY_APK`).
 
-Триггеры: push тега **`vX.Y.Z`** → версионный релиз; `workflow_dispatch` →
-плавающий `latest`/`apk-latest-<arch>` (всегда свежий фид). Публикация — через
-Gitea API (`ci/gitea-release.sh`). Ключи **никогда не перегенерируются** — это
-инвалидировало бы доверие на всех развёрнутых роутерах.
+Триггеры: push тега **`vX.Y.Z`** → версионный релиз `apk-vX.Y.Z-<arch>`;
+`workflow_dispatch` → только роллинг. Роллинг `apk-latest-<arch>` обновляется
+**на каждом прогоне**, включая теговый, и после публикации проверяется через API:
+в нём обязаны лежать наши три пакета ровно собранной версии и ни одного ассета
+другой версии. Публикация — через Gitea API (`ci/gitea-release.sh`). Ключ
+**никогда не перегенерируется** — это инвалидировало бы доверие на всех
+развёрнутых роутерах.
 
 ---
 
@@ -283,7 +290,7 @@ build-тегами и живущий **ребейзом на каждый upstre
 | Документ | О чём |
 |----------|-------|
 | [`docs-shater/CONTEXT.md`](docs-shater/CONTEXT.md) | **Начните здесь** — контекст проекта, история v0.1→v0.2, testbed/инфра |
-| [`docs-shater/INSTALL.md`](docs-shater/INSTALL.md) | Сборка ship-артефакта и установка обоих фидов (opkg/apk) |
+| [`docs-shater/INSTALL.md`](docs-shater/INSTALL.md) | Сборка ship-артефакта и установка apk-фида (роллинг/фиксация) |
 | [`docs-shater/ARCHITECTURE.md`](docs-shater/ARCHITECTURE.md) | One-binary дизайн, auth-handoff, data/DNS/apply-потоки (диаграммы) |
 | [`docs-shater/FEATURES.md`](docs-shater/FEATURES.md) | Полный список фич с тегами MVP/T1/T2 |
 | [`docs-shater/ROADMAP.md`](docs-shater/ROADMAP.md) | Фазовый план |

ci/build-feed-apk.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
-# ci/build-feed-apk.sh — build the signed **apk** feed for ONE arch (the 25.12
-# lane — additive next to ci/build-feed.sh, which stays the opkg/24.10 lane).
+# ci/build-feed-apk.sh — build the signed **apk** feed for ONE arch (25.12+;
+# the only packaging lane shater has — see docs-shater/DECISIONS.md D22).
 #
 # Usage:  ci/build-feed-apk.sh <ARCH> <SDK_URL> <OUTDIR>
 #   e.g.  ci/build-feed-apk.sh aarch64_cortex-a53 \
@@ -10,14 +10,14 @@
 # This is the per-arch entrypoint the Gitea workflow's `build-apk` job calls.
 # It runs on the CI RUNNER and:
 #   1. asserts the prebuilt shaterd binary for this arch was already staged by
-#      scripts/build-shaterd.sh (same artifact-order contract as the opkg lane);
-#   2. drives a plain `debian:bookworm` container (workspace shared via
-#      `--volumes-from`, same trick as ci/build-feed.sh) that downloads the
-#      ImmortalWrt 25.12 apk-SDK tarball and runs ci/sdk-build-apk.sh in it:
-#      compile the 4 packages as .apk, then `apk mkndx --sign` the per-arch
-#      `packages.adb` index. Unlike the usign lane (index signed on the runner),
-#      apk indexing NEEDS the SDK's host `apk` tool, so index+sign happen inside
-#      the container.
+#      scripts/build-shaterd.sh (the artifact-order contract);
+#   2. drives a plain `debian:bookworm` container (the job's workspace volume is
+#      shared into it with `--volumes-from $(hostname)`; a bare `-v $PWD:...`
+#      points at a host path that does not exist under act_runner's DinD) that
+#      downloads the ImmortalWrt 25.12 apk-SDK tarball and runs
+#      ci/sdk-build-apk.sh in it: compile the 4 packages as .apk, then
+#      `apk mkndx --sign` the per-arch `packages.adb` index. Indexing NEEDS the
+#      SDK's host `apk` tool, so index+sign happen inside the container.
 #
 # Why the ImmortalWrt SDK (not openwrt/sdk images): the 25.12 fleet runs
 # BananaWRT 25.12-mtk-vendor = ImmortalWrt 25.12 base (target mediatek/filogic,
@@ -25,9 +25,9 @@
 # mediatek-filogic 25.12 tag — hence the official SDK tarball.
 #
 # Env:
-#   KEY_APK   EC (prime256v1) PRIVATE key PEM (Gitea repo secret — the apk analog
-#             of KEY_BUILD). If set, packages.adb carries an embedded signature
-#             verifiable by dist/shater-apk.pem (routers: /etc/apk/keys/).
+#   KEY_APK   EC (prime256v1) PRIVATE key PEM (Gitea repo secret). If set,
+#             packages.adb carries an embedded signature verifiable by
+#             dist/shater-apk.pem (routers: /etc/apk/keys/).
 #             If unset, an UNSIGNED index is produced (warning; not shippable —
 #             apk signatures are effectively mandatory).
 set -eu
@@ -55,6 +55,15 @@ fi
 
 chmod +x "$REPO"/ci/*.sh 2>/dev/null || true
 
+# --- 0.4) package version from the git tag ------------------------------------
+# The workflow puts these in the job env via `ci/version.sh --env >>
+# $GITHUB_ENV`; recompute here when run standalone. Passed into the container
+# below and re-exported to the unprivileged build user in ci/sdk-build-apk.sh.
+if [ -z "${SHATER_PKG_VERSION:-}" ] || [ -z "${SHATER_PKG_RELEASE:-}" ]; then
+  eval "$(sh "$REPO/ci/version.sh" --env)"
+fi
+echo "[apk-feed] package version: ${SHATER_PKG_VERSION}-r${SHATER_PKG_RELEASE}"
+
 # --- 0.5) runner-side caches --------------------------------------------------
 # All under $REPO/.cache so (a) actions/cache in the workflow can persist them
 # between runs and (b) the nested container sees them via --volumes-from.
@@ -63,7 +72,7 @@ chmod +x "$REPO"/ci/*.sh 2>/dev/null || true
 #         SDK; PKG_HASH still verifies every file, so stale = re-downloaded.
 #   apt/  debian:bookworm .deb archives for the host-deps install.
 # The nested container runs the build as an unprivileged user -> must be writable
-# (same reason as the chmod 0777 "$OUT" in ci/build-feed.sh).
+# (same reason as the chmod 0777 "$OUT" above).
 CACHE="$REPO/.cache"
 mkdir -p "$CACHE/sdk" "$CACHE/dl" "$CACHE/apt"
 chmod -R a+rwX "$CACHE/dl" "$CACHE/apt" 2>/dev/null || true
@@ -86,14 +95,16 @@ sh "$REPO/ci/fetch-sdk.sh" "$SDK_URL" "$SDK_TAR"
 
 # --- 1) SDK build + index + sign inside a debian container -------------------
 # `--volumes-from $(hostname)` shares THIS job container's workspace volume into
-# the nested container (see ci/build-feed.sh for why a bare -v does not work on
-# the act_runner DinD setup).
+# the nested container: a bare `-v $PWD:...` points at a host path that does not
+# exist under the act_runner DinD setup.
 echo "[apk-feed] SDK build arch=$ARCH (ImmortalWrt 25.12 apk-SDK)"
 docker pull -q debian:bookworm
 docker run --rm --volumes-from "$(hostname)" \
   -e ARCH="$ARCH" -e REPO="$REPO" -e OUT="$OUT" -e SDK_URL="$SDK_URL" \
   -e SDK_TAR="$SDK_TAR" -e DL_DIR="$CACHE/dl" -e APT_CACHE="$CACHE/apt" \
   -e FEEDS_CACHE="$FEEDS_CACHE" -e KEY_APK="${KEY_APK:-}" \
+  -e SHATER_PKG_VERSION="$SHATER_PKG_VERSION" \
+  -e SHATER_PKG_RELEASE="$SHATER_PKG_RELEASE" \
   debian:bookworm bash "$REPO/ci/sdk-build-apk.sh"
 
 # --- 2) sanity: the per-arch apk repo dir must be complete -------------------

ci/build-feed.sh

@@ -1,92 +0,0 @@
-#!/bin/sh
-# ci/build-feed.sh — build the signed opkg feed for ONE arch.
-#
-# Usage:  ci/build-feed.sh <ARCH> <SDK_DOCKER_TAG> <OUTDIR>
-#   e.g.  ci/build-feed.sh x86_64             x86_64-24.10.4          out/x86_64
-#         ci/build-feed.sh aarch64_cortex-a53 mediatek-filogic-24.10.4 out/aarch64_cortex-a53
-#
-# This is the reusable per-arch entrypoint the Gitea workflow calls. It runs on
-# the CI RUNNER and:
-#   1. asserts the prebuilt shaterd binary for this arch was already staged by
-#      scripts/build-shaterd.sh (into openwrt/shaterd/files/) — proving artifact
-#      order: SPA+shaterd build BEFORE the SDK package build;
-#   2. drives the arch-matched `openwrt/sdk` docker image to compile all 4
-#      packages (ci/sdk-build.sh) and collect their .ipk into OUTDIR;
-#   3. builds + usign-signs the opkg `Packages` index over OUTDIR
-#      (ci/install-usign.sh + ci/make-index.sh; signs iff $KEY_BUILD is set).
-#
-# Env:
-#   KEY_BUILD   usign SECRET key (Gitea repo secret). If set, the feed index is
-#               signed and verifiable by dist/shater-feed.pub (fp 5ac4b177689cb8e0).
-#               If unset, an UNSIGNED feed is produced (make-index warns).
-set -eu
-
-ARCH="${1:?arch required (x86_64 | aarch64_cortex-a53)}"
-SDK_TAG="${2:?sdk docker tag required (e.g. x86_64-24.10.4)}"
-OUT="${3:?output dir required}"
-
-REPO="$(cd "$(dirname "$0")/.." && pwd)"
-mkdir -p "$OUT"; OUT="$(cd "$OUT" && pwd)"
-# $OUT is created here as ROOT on the runner, but the nested `openwrt/sdk`
-# container runs as the unprivileged `buildbot` (uid 1000) — so it must be able
-# to write the collected .ipk into $OUT. World-writable is set HERE (a chmod
-# from inside the container, as buildbot, cannot fix a root-owned dir).
-chmod 0777 "$OUT"
-
-# --- 0) the prebuilt shaterd binary must already be staged for this arch ------
-case "$ARCH" in
-  x86_64)             sfx=amd64 ;;
-  aarch64_cortex-a53) sfx=arm64 ;;
-  *) echo "[feed] ERROR: unsupported ARCH '$ARCH'"; exit 2 ;;
-esac
-if [ ! -f "$REPO/openwrt/shaterd/files/shaterd-$sfx.upx" ]; then
-  echo "[feed] ERROR: openwrt/shaterd/files/shaterd-$sfx.upx not staged."
-  echo "        Run scripts/build-shaterd.sh BEFORE ci/build-feed.sh." >&2
-  exit 3
-fi
-
-chmod +x "$REPO"/ci/*.sh 2>/dev/null || true
-
-# --- 0.5) persistent dl/ (package source tarballs) ----------------------------
-# Workspace dir restored/saved by actions/cache in the workflow and shared into
-# the nested SDK container via --volumes-from; becomes CONFIG_DOWNLOAD_FOLDER
-# there (ci/sdk-build.sh). PKG_HASH still verifies every file, so a stale cache
-# can never produce a wrong build. Must be writable by the container's
-# unprivileged buildbot user (same reason as the $OUT chmod above).
-DL_DIR="$REPO/.cache/dl"
-mkdir -p "$DL_DIR"
-chmod -R a+rwX "$DL_DIR" 2>/dev/null || true
-
-# --- 0.6) persistent feeds/ git checkouts -------------------------------------
-# Workspace dir restored/saved by actions/cache (key: feeds-opkg-<release>) and
-# symlinked over the SDK's feeds/ inside the container (ci/sdk-build.sh), so
-# `scripts/feeds update -a` fetches deltas instead of re-cloning base+packages+
-# luci from scratch (~7 min/run on this runner's slow github.com link).
-# Top-level chmod only: the contents are created by the container's uid-1000
-# build user and restored with the same ownership (tar-as-root preserves it).
-FEEDS_CACHE="$REPO/.cache/feeds/opkg"
-mkdir -p "$FEEDS_CACHE"
-chmod a+rwX "$REPO/.cache" "$REPO/.cache/feeds" "$FEEDS_CACHE" 2>/dev/null || true
-
-# --- 1) SDK package build (4 packages) in the arch-matched SDK image ----------
-# We drive the `openwrt/sdk` docker image directly (not openwrt/gh-action-sdk):
-# on a self-hosted Gitea act_runner the marketplace action fetch can be
-# unavailable, and we need a CLEAN single-feed layout. `--volumes-from
-# $(hostname)` shares THIS job container's workspace volume into the nested SDK
-# container — a bare `-v $PWD:...` points at a host path that does not exist
-# under the act_runner DinD setup. (Requires the job to run inside a container,
-# which Gitea Actions does by default.)
-echo "[feed] SDK build arch=$ARCH image=openwrt/sdk:$SDK_TAG"
-docker pull "openwrt/sdk:$SDK_TAG"
-docker run --rm --volumes-from "$(hostname)" \
-  -e ARCH="$ARCH" -e REPO="$REPO" -e OUT="$OUT" -e DL_DIR="$DL_DIR" \
-  -e FEEDS_CACHE="$FEEDS_CACHE" \
-  "openwrt/sdk:$SDK_TAG" \
-  sh "$REPO/ci/sdk-build.sh"
-
-# --- 2) index + sign the per-arch feed (usign, KEY_BUILD passed through) -------
-sh "$REPO/ci/install-usign.sh"
-KEY_BUILD="${KEY_BUILD:-}" bash "$REPO/ci/make-index.sh" "$OUT"
-
-echo "[feed] done arch=$ARCH -> $OUT"
-ls -l "$OUT"

ci/gen-apk-key.sh

@@ -2,24 +2,21 @@
 # ci/gen-apk-key.sh — generate the Shater **apk** feed signing keypair (25.12 lane).
 #
 # apk (OpenWrt/ImmortalWrt 25.12+) verifies package indexes with EC keys
-# (prime256v1 PEM), NOT usign — the existing usign identity
-# (dist/shater-feed.pub, fp 5ac4b177689cb8e0) keeps signing the opkg/24.10 feed
-# and is NOT touched by this script. This generates a SEPARATE, second identity:
+# (prime256v1 PEM). This is the ONLY feed identity shater has since the opkg
+# lane was removed (D22) — the old usign key is history, not a second lane.
 #
 #   dist/shater-apk.key   EC PRIVATE key.  NEVER commit (dist/ is gitignored).
 #                         Paste its full PEM contents into the Gitea repo secret
-#                         KEY_APK (the apk analog of the usign secret KEY_BUILD).
-#                         Then delete the local file (or keep it in a password
-#                         manager as the offline backup — losing it means every
-#                         deployed router must re-trust a new key).
-#   dist/shater-apk.pem   PUBLIC key. Commit it next to shater-feed.pub:
+#                         KEY_APK. Then delete the local file (or keep it in a
+#                         password manager as the offline backup — losing it
+#                         means every deployed router must re-trust a new key).
+#   dist/shater-apk.pem   PUBLIC key. Commit it:
 #                             git add -f dist/shater-apk.pem
 #                         (-f because /dist/ is gitignored). Routers install it
 #                         as /etc/apk/keys/shater-apk.pem.
 #
 # Run ONCE. Refuses to overwrite: regenerating the key invalidates the trust of
-# every router that already installed shater-apk.pem (same rule as D7 for the
-# usign key).
+# every router that already installed shater-apk.pem (see D22).
 set -eu
 
 REPO="$(cd "$(dirname "$0")/.." && pwd)"

ci/install-usign.sh

@@ -1,60 +0,0 @@
-#!/bin/bash
-# Make `usign` available on the CI runner so ci/make-index.sh can sign the opkg
-# feed index. The OpenWrt SDK ships usign, but the index/signing step runs on the
-# bare runner (outside the SDK container), so we build the tiny standalone tool
-# from source (no libubox — it is intentionally dependency-free so it can
-# bootstrap a build system). No-op if usign is already on PATH.
-#
-# Ported unchanged from Shater v0.1 (ci/install-usign.sh): usign is
-# format-agnostic and the signing story is identical for the v0.2 4-package feed.
-#
-# CI cache: a previously-built binary is reused from $USIGN_CACHE (default:
-# <repo>/.cache/tools — a workspace dir the workflow persists via actions/cache),
-# skipping the apt + cmake + clone + build (~1 min). After a fresh build the
-# binary is copied there so the NEXT run hits the cache. usign is a tiny static
-# helper with no versioned protocol — a stale cached binary cannot mis-sign.
-set -eu
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-TOOLS="${USIGN_CACHE:-$REPO_ROOT/.cache/tools}"
-
-# place <binary> — install onto PATH (system-wide if we can, else ~/bin)
-place() {
-  local SUDO=""; [ "$(id -u)" = 0 ] || SUDO="sudo"
-  if $SUDO install -m0755 "$1" /usr/local/bin/usign 2>/dev/null; then
-    :
-  else
-    mkdir -p "$HOME/bin"
-    install -m0755 "$1" "$HOME/bin/usign"
-    echo "$HOME/bin" >> "${GITHUB_PATH:-/dev/null}"
-    export PATH="$HOME/bin:$PATH"
-  fi
-}
-
-if command -v usign >/dev/null 2>&1; then
-  echo "[usign] already present: $(command -v usign)"
-  exit 0
-fi
-
-if [ -x "$TOOLS/usign" ]; then
-  place "$TOOLS/usign"
-  echo "[usign] restored from cache: $(command -v usign || echo "$HOME/bin/usign")"
-  exit 0
-fi
-
-SUDO=""; [ "$(id -u)" = 0 ] || SUDO="sudo"
-if ! command -v cmake >/dev/null 2>&1 || ! command -v cc >/dev/null 2>&1; then
-  $SUDO apt-get update -qq
-  $SUDO apt-get install -y -qq cmake gcc git
-fi
-
-tmp="$(mktemp -d)"
-# Canonical source; fall back to the GitHub mirror if git.openwrt.org is flaky.
-git clone --depth 1 https://git.openwrt.org/project/usign.git "$tmp/usign" \
-  || git clone --depth 1 https://github.com/openwrt/usign.git "$tmp/usign"
-( cd "$tmp/usign" && cmake -DCMAKE_BUILD_TYPE=Release . >/dev/null && make >/dev/null )
-
-place "$tmp/usign/usign"
-# seed the cache for the next run (best-effort)
-mkdir -p "$TOOLS" 2>/dev/null && install -m0755 "$tmp/usign/usign" "$TOOLS/usign" 2>/dev/null || true
-echo "[usign] built: $(command -v usign || echo "$HOME/bin/usign")"

ci/make-index.sh

@@ -1,39 +0,0 @@
-#!/bin/bash
-# Build the opkg feed index (Packages + Packages.gz) with SHA256 for a dir of
-# .ipk files, then optionally usign-sign it if $KEY_BUILD (the Gitea repo secret)
-# is set and usign is present. Arg $1 = feed dir.
-#
-# Ported from Shater v0.1 (ci/make-index.sh), unchanged. It is package-count and
-# package-name agnostic: it indexes whatever .ipk are in the dir, so it serves
-# BOTH the per-arch feed built by ci/build-feed.sh AND the combined release feed
-# assembled in the release job (shaterd + byedpi per-arch, shater-core +
-# luci-app-shater = _all). opkg filters by Architecture at install time, so one
-# combined URL serves every device.
-#
-# Feed format: opkg `src/gz` (.ipk + text Packages index, usign signature).
-# OpenWrt 24.10 (our SDK) still uses opkg; apk arrives at 25.12. The committed
-# trust anchor dist/shater-feed.pub is a usign (Ed25519) key, matching this.
-set -euo pipefail
-OUT="${1:?feed dir required}"; cd "$OUT"
-: > Packages
-for ipk in *.ipk; do
-  [ -e "$ipk" ] || continue
-  ctrl=$(tar -xzOf "$ipk" ./control.tar.gz | tar -xzO ./control)
-  sz=$(wc -c < "$ipk"); sha=$(sha256sum "$ipk" | cut -d' ' -f1)
-  printf '%s\n' "$ctrl" | sed '/^[[:space:]]*$/d' >> Packages
-  printf 'Filename: %s\nSize: %s\nSHA256sum: %s\n\n' "$ipk" "$sz" "$sha" >> Packages
-done
-gzip -kf Packages
-
-if [ -n "${KEY_BUILD:-}" ]; then
-  # Signing was requested — a missing/broken signer must FAIL the build, not
-  # silently ship an unsigned feed that routers with check_signature on reject.
-  command -v usign >/dev/null 2>&1 || { echo "[index] ERROR: KEY_BUILD set but usign not found" >&2; exit 1; }
-  umask 077; printf '%s\n' "$KEY_BUILD" > /tmp/usign.sec
-  usign -S -m Packages -s /tmp/usign.sec || { rm -f /tmp/usign.sec; echo "[index] ERROR: usign signing failed" >&2; exit 1; }
-  rm -f /tmp/usign.sec
-  echo "[index] signed -> Packages.sig ($(head -1 Packages.sig))"
-else
-  echo "[index] no KEY_BUILD -> UNSIGNED feed (opkg needs check_signature off, or set the secret)"
-fi
-echo "[index] contents:"; ls -l

ci/sdk-build-apk.sh

@@ -10,7 +10,6 @@
 # the target fleet (BananaWRT 25.12-mtk-vendor = ImmortalWrt 25.12 base, its
 # distfeeds even point at downloads.immortalwrt.org/releases/25.12-SNAPSHOT) is
 # ImmortalWrt — so we extract the official ImmortalWrt SDK tarball ourselves.
-# Same --volumes-from workspace-sharing pattern as ci/sdk-build.sh (opkg lane).
 #
 # The OpenWrt buildsystem refuses to run as root, so the SDK build itself runs
 # as an unprivileged `build` user created here.
@@ -28,11 +27,16 @@ SDK_URL="${SDK_URL:?SDK_URL env required}"
 
 echo "[apk-sdk] arch=$ARCH repo=$REPO out=$OUT"
 echo "[apk-sdk] sdk=$SDK_URL"
+# Package version derived from the git tag by ci/version.sh (bug B4). Forwarded
+# to the unprivileged build user on the `su` line at the bottom of this file;
+# openwrt/{shaterd,shater-core,luci-app-shater}/Makefile pick it up from the
+# environment. byedpi keeps upstream ByeDPI's own version (see its Makefile).
+echo "[apk-sdk] package version: ${SHATER_PKG_VERSION:-<unset -> Makefile fallback>}-r${SHATER_PKG_RELEASE:-?}"
 test -f "$REPO/openwrt/shaterd/Makefile" || {
   echo "[apk-sdk] ERROR: feed not mounted ($REPO/openwrt/shaterd/Makefile missing)"; ls -la "$REPO" || true; exit 9; }
 
-# The prebuilt shaterd artifact must already be staged for this arch (same
-# contract as the opkg lane — scripts/build-shaterd.sh runs first).
+# The prebuilt shaterd artifact must already be staged for this arch
+# (artifact-order contract — scripts/build-shaterd.sh runs first).
 case "$ARCH" in
   x86_64)             sfx=amd64 ;;
   aarch64_cortex-a53) sfx=arm64 ;;
@@ -108,7 +112,7 @@ export HOME=/home/build
 cd "$SDKDIR"
 
 # Register this repo's openwrt/ as a src-link feed named `shater` (absolute
-# path required) — identical to the opkg lane (ci/sdk-build.sh).
+# path required).
 cp -f feeds.conf.default feeds.conf
 grep -q '^src-link shater ' feeds.conf || echo "src-link shater $REPO/openwrt" >> feeds.conf
 
@@ -133,6 +137,41 @@ fi
 echo "[apk-sdk] feeds install (prefer shater feed)"
 ./scripts/feeds install -p shater shaterd shater-core byedpi luci-app-shater
 
+# --- strip the SDK's generated per-package `default m` blocks ----------------
+# Run 60 settled the question that runs 58 and 59 left open. Writing an explicit
+# `# CONFIG_PACKAGE_kmod-x is not set` for all 1126 of them and re-running
+# defconfig deselected exactly nothing: the count came back 1078, unchanged.
+# Meanwhile the very same explicit form DID stick for CONFIG_ALL/ALL_KMODS/
+# ALL_NONSHARED. The difference is prompts. kconfig only honours a user value for
+# a symbol that has one (sym_calc_value ignores S_DEF_USER for a promptless
+# symbol and falls back to its `default`), and the ALL* symbols carry prompts in
+# the SDK's own Config.in while these generated blocks are bare:
+#
+#       config PACKAGE_kmod-mlx5-core
+#               tristate
+#               default m
+#
+# So no value we write into .config can ever turn them off — the fix has to
+# remove the `default m` itself. That is what this does: drop every generated
+# `config PACKAGE_*` block from the SDK's Config-build.in before the first
+# defconfig. Nothing is lost by it — these blocks only replay which packages the
+# BUILDBOT happened to build; the packages themselves are still declared, with
+# prompts, by the package tree (tmp/.config-package.in), which is what makes our
+# four selectable and what `select` acts on. KERNEL_*/LIBC/TOOLCHAIN blocks are
+# left untouched, so the SDK still reproduces its own toolchain settings.
+CB=$(find . -maxdepth 2 -name 'Config-build.in' -print -quit 2>/dev/null || true)
+if [ -n "$CB" ] && command -v perl >/dev/null 2>&1; then
+  pkg_before=$(grep -c '^config PACKAGE_' "$CB" || true)
+  # Paragraph-wise delete: a block is `config PACKAGE_x`, its indented body, and
+  # the blank line that ends it. Anchored per-line (/m) so nothing else matches.
+  perl -0777 -pi -e 's/^config PACKAGE_\S+\n(?:[ \t]+\S[^\n]*\n)+\n//gm' "$CB"
+  pkg_after=$(grep -c '^config PACKAGE_' "$CB" || true)
+  echo "[apk-sdk] $CB: stripped $((pkg_before - pkg_after)) generated PACKAGE default blocks ($pkg_before -> $pkg_after)"
+else
+  echo "[apk-sdk] WARNING: no Config-build.in found (or no perl) — per-package"
+  echo "[apk-sdk]          'default m' blocks stay; the kmod tripwire will catch it"
+fi
+
 # --- .config: turn OFF the SDK's mass-select defaults ------------------------
 # Symptom (v0.2.2, and still v0.2.3 run 58): the SDK ran `apk mkpkg` on ~1100
 # kmod-* packages — mlx5, amdgpu, ata, isdn, none of which we ship — and died
@@ -211,6 +250,63 @@ fi
 echo "[apk-sdk] defconfig"
 make defconfig >/dev/null
 
+# --- second pass: deselect the kernel, keep only what our packages select -----
+# Turning ALL/ALL_KMODS/ALL_NONSHARED off (above) provably worked — run 59 shows
+# all three as `is not set` after defconfig — and changed the kmod count by
+# exactly zero, 1078 both times. The kmods are not selected through ALL_KMODS at
+# all. They are selected one by one, and here is where from:
+#
+#   target/sdk/Makefile:
+#       ./convert-config.pl $(TOPDIR)/.config > $(SDK_BUILD_DIR)/Config-build.in
+#
+# The SDK's Config-build.in is GENERATED from the buildbot's .config — a config
+# in which ALL_KMODS=y had already expanded into a `CONFIG_PACKAGE_kmod-*=m` line
+# per module. convert-config.pl turns every `CONFIG_X=<val>` line into a kconfig
+# symbol carrying an unconditional `default <val>`; its `next if
+# /^(# )?CONFIG_PACKAGE/` filter sits in the `else` branch, which a line with an
+# `=` in it never reaches. So the SDK ships, verbatim, 1078 blocks of:
+#
+#       config PACKAGE_kmod-mlx5-core
+#               tristate
+#               default m
+#
+# Nothing there consults ALL_KMODS, which is why switching it off was inert.
+#
+# Fix: give those symbols an explicit user value. We cannot do it before the
+# first defconfig — the list of names only exists once kconfig has expanded the
+# tree — so this is a second pass: rewrite every selected kmod to `is not set`
+# and re-run defconfig. Two kconfig rules make the result exactly what we want,
+# and both are already demonstrated in our own logs:
+#   * an explicit value in .config beats a `default` (this is precisely why the
+#     `# CONFIG_ALL* is not set` lines survived defconfig in run 59), so the
+#     ~1078 kmods we do not need stay off;
+#   * `select` is a reverse dependency, OR-ed into the symbol's value AFTER the
+#     user value in sym_calc_value(), so it cannot be overridden by an explicit
+#     `n`. shater-core's `DEPENDS:=+kmod-nft-tproxy +kmod-nft-socket` becomes
+#     `select PACKAGE_kmod-nft-tproxy` (scripts/package-metadata.pl: a `+` flag
+#     sets `$m = "select"`, and it re-emits the dependency's own depends too, so
+#     transitive kmods follow). Those come back on their own.
+# Net effect: we build the handful of kmods our packages actually pull in.
+#
+# Rejected alternatives:
+#   * limiting what `package/kernel/linux/compile` packs — that target has no
+#     such knob; it iterates the selected set, so the selection IS the knob;
+#   * `package/kernel/linux/clean` + a targeted build — the kernel package would
+#     simply be rebuilt in full as a dependency of shater-core, same cost;
+#   * copying OpenWrt's own feed CI (openwrt/gh-action-sdk) — it does nothing
+#     about this; it just runs `make defconfig` and builds. Its one disk-related
+#     setting, CONFIG_AUTOREMOVE=y, is already the SDK's default;
+#   * editing the SDK's generated Config-build.in to strip the offending blocks —
+#     it would work, but it means parsing a generated kconfig file by hand and a
+#     format change would corrupt it silently. The two-pass approach uses only
+#     kconfig's documented semantics and leaves the evidence in .config.
+kmods_all=$(grep -c '^CONFIG_PACKAGE_kmod-[^=]*=[my]$' .config || true)
+if [ "$kmods_all" -gt 0 ]; then
+  echo "[apk-sdk] deselecting $kmods_all kmod packages, then defconfig again"
+  sed -i -E 's/^CONFIG_(PACKAGE_kmod-[^=]*)=[my]$/# CONFIG_\1 is not set/' .config
+  make defconfig >/dev/null
+fi
+
 # --- post-defconfig sanity + disk-cost readout -------------------------------
 # A failed run leaves a ~27 MB log; digging the cause out of it is miserable, so
 # print the handful of numbers that decide whether this run survives the
@@ -225,7 +321,7 @@ echo "[apk-sdk] kmod packages selected (=m): $kmods"
 # the kmod count above will be in the four digits.
 echo "[apk-sdk] mass-select symbols after defconfig:"
 grep -E '^(# )?CONFIG_ALL(_KMODS|_NONSHARED)?[ =]' .config | sed 's/^/[apk-sdk]   /' || true
-# With ALL_KMODS off, the only kmods left are the ones shater-core's
+# After the second pass the only kmods left are the ones shater-core's
 # `DEPENDS:=+kmod-nft-tproxy +kmod-nft-socket` turns into kconfig `select`s, plus
 # whatever those select in turn — a handful. Worth printing verbatim while the
 # list is short. A count of 0 is NOT fatal: those kmods ship in the router's own
@@ -234,6 +330,11 @@ grep -E '^(# )?CONFIG_ALL(_KMODS|_NONSHARED)?[ =]' .config | sed 's/^/[apk-sdk]
 if [ "$kmods" -le 30 ]; then
   grep '^CONFIG_PACKAGE_kmod.*=m' .config | sed 's/^/[apk-sdk]   /' || true
 fi
+# The two cache knobs are written before the first defconfig and have to survive
+# both of them — losing DOWNLOAD_FOLDER silently costs us the dl/ cache, and
+# losing LOCALMIRROR brings back the sourceware.org stalls. Cheap to just look.
+echo "[apk-sdk] cache settings after defconfig:"
+grep -E '^CONFIG_(LOCALMIRROR|DOWNLOAD_FOLDER)=' .config | sed 's/^/[apk-sdk]   /' || true
 echo "[apk-sdk] our packages after defconfig:"
 grep -E '^CONFIG_PACKAGE_(shaterd|shater-core|byedpi|luci-app-shater)=' .config \
   | sed 's/^/[apk-sdk]   /' || true
@@ -256,9 +357,16 @@ done
 # packing the kernel before dying on `Disk quota exceeded`. Fail now instead.
 [ "$kmods" -le 200 ] || {
   echo "[apk-sdk] ERROR: $kmods kmod packages selected — that is the whole kernel."
-  echo "        CONFIG_ALL_KMODS/CONFIG_ALL is back in .config; aborting before"
-  echo "        this fills the runner's disk. Offending lines:"
-  grep '^CONFIG_ALL' .config || true; exit 11; }
+  echo "        Aborting before this fills the runner's disk. Two causes are"
+  echo "        possible, and the lines below tell them apart:"
+  echo "        (a) the mass-select is back on   -> a CONFIG_ALL* line reads =y;"
+  echo "        (b) the second pass did not take -> ALL* are 'is not set' but the"
+  echo "            kmods returned anyway, i.e. the per-kmod 'default m' from the"
+  echo "            SDK's generated Config-build.in outlived our explicit 'n'."
+  grep -E '^(# )?CONFIG_ALL(_KMODS|_NONSHARED)?[ =]' .config | sed 's/^/        /' || true
+  echo "        first few kmods still selected:"
+  grep -m5 '^CONFIG_PACKAGE_kmod.*=m' .config | sed 's/^/        /' || true
+  exit 11; }
 
 for p in shaterd shater-core byedpi luci-app-shater; do
   echo "[apk-sdk] === build $p ==="
@@ -288,6 +396,25 @@ done
 [ "$found" -ge 4 ] || { echo "[apk-sdk] ERROR: expected >=4 of OUR .apk, collected $found"; echo "[apk-sdk] (all .apk under bin/:)"; find bin -type f -name '*.apk' | head -20; exit 6; }
 echo "[apk-sdk] collected $found of our .apk"
 
+# --- assert the tag-derived version actually reached the packages -------------
+# B4's failure mode is a wrong-but-plausible version shipping silently, so the
+# env -> make hand-off is verified, not trusted: each of our three tag-versioned
+# packages must be named `<name>-<ver>-r<rel>.apk`. byedpi is excluded on purpose
+# (it carries upstream ByeDPI's own version). This runs BEFORE `apk mkndx`, so a
+# stale version can never even reach the index.
+if [ -n "${SHATER_PKG_VERSION:-}" ] && [ -n "${SHATER_PKG_RELEASE:-}" ]; then
+  want="${SHATER_PKG_VERSION}-r${SHATER_PKG_RELEASE}"
+  for p in shaterd shater-core luci-app-shater; do
+    [ -f "$OUT/${p}-${want}.apk" ] || {
+      echo "[apk-sdk] ERROR: $p was not built as version '$want'."
+      echo "        SHATER_PKG_VERSION/SHATER_PKG_RELEASE did not reach the package"
+      echo "        Makefile — the build would have shipped a stale version (bug B4)."
+      echo "[apk-sdk] collected:"; ls -1 "$OUT" | sed 's/^/          /'
+      exit 12; }
+  done
+  echo "[apk-sdk] version check OK — our 3 packages are $want"
+fi
+
 # --- index + sign: exactly how the OpenWrt 25.12 buildsystem does it ---------
 #   apk mkndx --root T --keys-dir T [--sign key] --allow-untrusted \
 #             --output packages.adb *.apk
@@ -319,7 +446,7 @@ INNER
 chmod 0644 /home/build/inner.sh
 
 su build -s /bin/bash -c \
-  "ARCH='$ARCH' REPO='$REPO' OUT='$OUT' SDKDIR='$SDKDIR' KEYFILE='${KEYFILE:-}' DL_DIR='${DL_DIR:-}' FEEDS_CACHE='${FEEDS_CACHE:-}' bash /home/build/inner.sh"
+  "ARCH='$ARCH' REPO='$REPO' OUT='$OUT' SDKDIR='$SDKDIR' KEYFILE='${KEYFILE:-}' DL_DIR='${DL_DIR:-}' FEEDS_CACHE='${FEEDS_CACHE:-}' SHATER_PKG_VERSION='${SHATER_PKG_VERSION:-}' SHATER_PKG_RELEASE='${SHATER_PKG_RELEASE:-}' bash /home/build/inner.sh"
 
 chmod -R a+rwX "$OUT" 2>/dev/null || true
 echo "[apk-sdk] OK arch=$ARCH — apk feed dir:"

ci/sdk-build.sh

@@ -1,116 +0,0 @@
-#!/bin/sh
-# Runs INSIDE an `openwrt/sdk:<target>-<ver>` container (CWD = SDK root
-# /builder). The job's workspace is shared into this container via
-# `docker run --volumes-from`, so the repo is visible at $REPO and output goes
-# to $OUT (a dir under the repo, hence also visible to the runner afterwards).
-#
-# Unlike Shater v0.1 (which compiled ONLY xrayctl in the SDK and hand-packed the
-# pure-data packages with tar), v0.2 builds ALL FOUR packages the canonical way,
-# via the SDK feed + `make package/<p>/compile`:
-#
-#   shaterd          prebuilt binary — Build/Compile only VALIDATES that
-#                    openwrt/shaterd/files/shaterd-<amd64|arm64>.upx was staged
-#                    by scripts/build-shaterd.sh on the runner BEFORE this ran.
-#                    (arch-specific .ipk: RSTRIP/STRIP disabled — packed ELF.)
-#   shater-core      PKGARCH=all data glue (procd init, sysctl, uci-defaults).
-#   luci-app-shater  PKGARCH=all LuCI thin launcher — its Makefile does
-#                    `include $(TOPDIR)/feeds/luci/luci.mk`, so the `luci` feed
-#                    MUST be updated first (that is what creates feeds/luci/luci.mk).
-#   byedpi           arch-specific C — the SDK cross-compiles ciadpi from the
-#                    upstream tarball (needs network for PKG_SOURCE_URL).
-#
-# Env (required): ARCH, REPO, OUT.
-set -eu
-ARCH="${ARCH:?ARCH env required}"
-REPO="${REPO:?REPO env required}"
-OUT="${OUT:?OUT env required}"
-mkdir -p "$OUT"
-
-echo "[sdk] arch=$ARCH repo=$REPO out=$OUT"
-test -f "$REPO/openwrt/shaterd/Makefile" || {
-  echo "[sdk] ERROR: feed not mounted ($REPO/openwrt/shaterd/Makefile missing)"; ls -la "$REPO" || true; exit 9; }
-
-# The prebuilt shaterd artifact must already be staged for this arch.
-case "$ARCH" in
-  x86_64)             sfx=amd64 ;;
-  aarch64_cortex-a53) sfx=arm64 ;;
-  *) echo "[sdk] ERROR: unsupported ARCH '$ARCH'"; exit 2 ;;
-esac
-test -f "$REPO/openwrt/shaterd/files/shaterd-$sfx.upx" || {
-  echo "[sdk] ERROR: openwrt/shaterd/files/shaterd-$sfx.upx not staged."
-  echo "        scripts/build-shaterd.sh must run on the runner before the SDK build."; exit 3; }
-
-# --- register this repo's openwrt/ as a src-link feed named `shater` ---------
-# src-link REQUIRES an absolute path; $REPO/openwrt is exactly a feed root (it
-# contains the 4 package dirs and nothing else that looks like a package).
-cp -f feeds.conf.default feeds.conf
-grep -q '^src-link shater ' feeds.conf || echo "src-link shater $REPO/openwrt" >> feeds.conf
-
-# Update metadata for ALL feeds: our `shater` feed + the SDK defaults (base,
-# luci, packages, routing, telephony). We need `luci` for feeds/luci/luci.mk and
-# `base`/`packages` for the runtime deps (kmod-nft-tproxy, kmod-nft-socket,
-# ip-full, rpcd, luci-base) to resolve.
-#
-# Persistent feeds checkouts: $FEEDS_CACHE (a workspace dir the runner restores
-# via actions/cache, shared into this container via --volumes-from) replaces
-# the SDK's ephemeral feeds/ dir, so `feeds update` git-fetches deltas instead
-# of re-cloning base+packages+luci every run (~7 min on the runner's slow
-# github.com link). Correctness-safe: update always checks out feeds.conf's
-# pinned revisions; if it ever fails on a cached checkout (e.g. a force-pushed
-# upstream), the cache is wiped and the update retried with fresh clones.
-if [ -n "${FEEDS_CACHE:-}" ] && mkdir -p "$FEEDS_CACHE" 2>/dev/null; then
-  rm -rf feeds
-  ln -s "$FEEDS_CACHE" feeds
-  echo "[sdk] feeds/ -> $FEEDS_CACHE (persistent cache)"
-fi
-echo "[sdk] feeds update -a"
-if ! ./scripts/feeds update -a; then
-  [ -L feeds ] || { echo "[sdk] ERROR: feeds update failed"; exit 8; }
-  echo "[sdk] WARNING: feeds update failed on cached checkouts — wiping cache, cloning fresh"
-  find "$FEEDS_CACHE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
-  ./scripts/feeds update -a
-fi
-
-echo "[sdk] feeds install (prefer shater feed)"
-./scripts/feeds install -p shater shaterd shater-core byedpi luci-app-shater
-
-# Select our packages, then defconfig. `make package/<p>/compile` builds the
-# explicit target regardless, but selecting first makes deps visible to defconfig.
-for p in shaterd shater-core byedpi luci-app-shater; do
-  echo "CONFIG_PACKAGE_$p=m" >> .config
-done
-# Route source downloads through OpenWrt's fast CDN mirror FIRST — sourceware.org
-# (elfutils) and other upstreams intermittently stall mid-transfer, and curl's
-# --connect-timeout doesn't cover a stalled stream, so the SDK download hangs the
-# build. LOCALMIRROR is tried before each package's own PKG_SOURCE_URL. (lx CI)
-echo 'CONFIG_LOCALMIRROR="https://sources.cdn.openwrt.org"' >> .config
-# Persistent dl/ across runs: $DL_DIR is a workspace dir the runner restores via
-# actions/cache (see ci/build-feed.sh). Correctness-safe: the buildroot verifies
-# PKG_HASH on every file already in dl/ and re-downloads on mismatch, so a stale
-# cache can never leak a wrong source into the build.
-if [ -n "${DL_DIR:-}" ]; then
-  echo "CONFIG_DOWNLOAD_FOLDER=\"$DL_DIR\"" >> .config
-fi
-echo "[sdk] defconfig"
-make defconfig >/dev/null
-
-# --- compile the 4 packages --------------------------------------------------
-for p in shaterd shater-core byedpi luci-app-shater; do
-  echo "[sdk] === build $p ==="
-  make "package/$p/compile" V=s -j"$(nproc)"
-done
-
-# --- collect ONLY our 4 packages' .ipk (per-arch shaterd/byedpi + _all core/luci)
-# NOT `find bin -name '*.ipk'`: the openwrt/sdk image ships HUNDREDS of prebuilt
-# kmod/base .ipk under bin/, which a blanket copy would pull into the feed and
-# get signed under OUR key. Match each package's own `<name>_<ver>_<arch>.ipk`.
-found=0
-for p in shaterd shater-core byedpi luci-app-shater; do
-  for ipk in $(find bin -type f -name "${p}_*.ipk"); do
-    cp -f "$ipk" "$OUT/"; found=$((found+1))
-  done
-done
-[ "$found" -ge 4 ] || { echo "[sdk] ERROR: expected >=4 of OUR .ipk, collected $found"; echo "[sdk] (all .ipk under bin/:)"; find bin -type f -name '*.ipk' | head -20; exit 4; }
-chmod -R a+rwX "$OUT" 2>/dev/null || true
-echo "[sdk] OK arch=$ARCH — collected $found of our .ipk:"
-ls -l "$OUT"

ci/version.sh

@@ -0,0 +1,131 @@
+#!/bin/sh
+# ci/version.sh — the SINGLE source of truth for "what version is this build?".
+#
+# WHY THIS EXISTS (bug B4)
+# -----------------------
+# PKG_VERSION/PKG_RELEASE used to be hand-written literals in the four package
+# Makefiles, and nobody remembered to bump them: v0.2.2 … v0.2.6 all shipped as
+# `shaterd 0.2.0-r3` with DIFFERENT binaries inside (v0.2.6's ELF is 5 491 616 B
+# vs r2's 5 488 336 B). Since apk offers an upgrade only when the feed's version
+# string differs from the installed one, `apk update` saw nothing new and the
+# routers could not be updated through the normal path at all.
+#
+# So the version is now DERIVED, in CI, from the git tag, and the package
+# Makefiles only carry a fallback for manual/offline builds.
+#
+# THE SCHEME
+# ----------
+#   tag push `vX.Y.Z`        -> PKG_VERSION=X.Y.Z   PKG_RELEASE=1
+#   any other build          -> PKG_VERSION=X.Y.Z of the NEAREST reachable tag,
+#   (workflow_dispatch,         PKG_RELEASE=<commits since that tag> + 1
+#    rolling `latest`)
+#   no tag / no git at all   -> PKG_VERSION=0.0.0   PKG_RELEASE=1  (+ warning)
+#
+# apk compares `<upstream>-r<rel>` as: the dotted upstream part first
+# (numerically, component by component), the `r<rel>` only as a tie-break.
+# Verified against the real tool, not from memory —
+# apk-tools 3.0.3 (`apk version -t`) and apk-tools 2.14.6:
+#       0.2.6-r1  > 0.2.0-r3      0.2.6-r12 > 0.2.6-r1
+#       0.2.7-r1  > 0.2.6-r12     0.0.0-r1  < 0.2.0-r3
+# That is exactly the ordering this scheme needs:
+#   * a release always outranks every rolling build that preceded it
+#     (0.2.7-r1 > 0.2.6-rN for any N — the dotted part decides), and
+#   * rolling builds between two releases grow monotonically (r2 < r10 < r11),
+# so a rolling build can never look newer than the next release, and the
+# `latest` feed still moves forward on every dispatch.
+#
+# +1 on the commit count (rather than the raw count) only avoids `-r0` and makes
+# a dispatch build of the tagged commit itself identical to the release build of
+# that same commit — which is the truth: same tree, same binary.
+#
+# `byedpi` is deliberately NOT versioned from our tag — see openwrt/byedpi/Makefile.
+#
+# USAGE
+#   ci/version.sh                  # or --env: eval-able / $GITHUB_ENV-able lines
+#   ci/version.sh --pkg-version    # X.Y.Z
+#   ci/version.sh --pkg-release    # R
+#   ci/version.sh --binary         # vX.Y.Z-rR[-g<sha>] for constant.Version
+#
+# Env:
+#   SHATER_REF / GITHUB_REF   when it is `refs/tags/<tag>` that tag wins and no
+#                             git history is needed (the tag-push path is exact
+#                             even on a shallow checkout).
+set -eu
+
+REPO="$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)"
+
+TAG=""
+EXACT=0
+N=0
+SHA=""
+
+# --- 1) an explicit tag ref is authoritative (and needs no git) --------------
+REF="${SHATER_REF:-${GITHUB_REF:-}}"
+case "$REF" in
+  refs/tags/*) TAG="${REF#refs/tags/}"; EXACT=1 ;;
+esac
+
+# --- 2) otherwise ask git for the nearest reachable release tag --------------
+# `--match 'v[0-9]*'` keeps non-release tags (latest, sdk-cache, apk-latest-*,
+# musl-toolchain-cache) out. This repo is a sing-box FORK and therefore also
+# carries upstream's v1.x tags — `git describe` picks the CLOSEST tag by commit
+# distance, so our own v0.2.x (a handful of commits back) always wins over
+# upstream's v1.x (thousands of commits back). The tag it picked is logged
+# below, so a surprise is visible in the CI log rather than silently shipped.
+if [ "$EXACT" -eq 0 ]; then
+  if D="$(git -C "$REPO" describe --tags --long --match 'v[0-9]*' 2>/dev/null)"; then
+    # `v0.2.6-1-g02c266188` -> TAG=v0.2.6 N=1 SHA=g02c266188.
+    # `%` strips the SHORTEST matching suffix, so a tag that itself contains a
+    # dash (`v0.2.0-healthplan`) survives intact.
+    TAG="${D%-*-g*}"
+    REST="${D#"$TAG"-}"
+    N="${REST%%-*}"
+    SHA="${REST#*-}"
+    if [ "$N" -eq 0 ]; then EXACT=1; fi
+  fi
+fi
+
+# --- 3) tag -> numeric PKG_VERSION ------------------------------------------
+# Keep the leading dotted-numeric run only: `v0.2.0-healthplan` -> `0.2.0`.
+VER=""
+if [ -n "$TAG" ]; then
+  VER="$(printf '%s' "${TAG#v}" | sed -n 's/^\([0-9][0-9.]*\).*/\1/p' | sed 's/\.*$//')"
+fi
+
+if [ -z "$VER" ]; then
+  # No release tag anywhere (shallow clone with no tags, a tarball export, a
+  # fresh fork). 0.0.0 is BELOW every version we have ever published, so such a
+  # build can never masquerade as an upgrade on a real router; the commit count
+  # still makes successive dev builds distinguishable.
+  VER="0.0.0"
+  EXACT=0
+  N="$(git -C "$REPO" rev-list --count HEAD 2>/dev/null || echo 0)"
+  SHA="$(git -C "$REPO" rev-parse --short HEAD 2>/dev/null || echo '')"
+  [ -z "$SHA" ] || SHA="g$SHA"
+  echo "[version] WARNING: no reachable vX.Y.Z tag (and/or no git) -> $VER" >&2
+fi
+
+# --- 4) PKG_RELEASE + the string stamped into the binary --------------------
+if [ "$EXACT" -eq 1 ]; then
+  REL=1
+  FULL="v${VER}-r${REL}"
+else
+  REL=$((N + 1))
+  FULL="v${VER}-r${REL}${SHA:+-$SHA}"
+fi
+
+echo "[version] tag='${TAG:-none}' commits_since=$N exact=$EXACT -> ${VER}-r${REL} (binary: $FULL)" >&2
+
+case "${1:---env}" in
+  --env|"")
+    printf 'SHATER_PKG_VERSION=%s\n' "$VER"
+    printf 'SHATER_PKG_RELEASE=%s\n' "$REL"
+    printf 'SHATER_VERSION=%s\n'     "$FULL"
+    ;;
+  --pkg-version) printf '%s\n' "$VER" ;;
+  --pkg-release) printf '%s\n' "$REL" ;;
+  --binary|--version) printf '%s\n' "$FULL" ;;
+  *)
+    echo "usage: $0 [--env|--pkg-version|--pkg-release|--binary]" >&2
+    exit 2 ;;
+esac

common/tlsspoof/integration_test.go

@@ -25,6 +25,21 @@ func requireRoot(t *testing.T) {
 	}
 }
 
+// requireTCPDump skips when tcpdump is not installed.
+//
+// The same honesty this package's callers demand of a health reading: a missing
+// INSTRUMENT is "not checked", never "broken". Without it every test in this
+// file fails on `cmd.Start()` — sixteen red results that say nothing about the
+// code and hide any real failure among them — on a machine where the only thing
+// wrong is that a capture tool is absent. requireRoot has always drawn that line
+// for privileges; this draws it for the tool.
+func requireTCPDump(t *testing.T) {
+	t.Helper()
+	if _, err := exec.LookPath("tcpdump"); err != nil {
+		t.Skip("integration test requires tcpdump on PATH; install it to run this suite")
+	}
+}
+
 func tcpdumpObserver(t *testing.T, iface string, port uint16, needle string, do func(), wait time.Duration) bool {
 	t.Helper()
 	return tcpdumpObserverMulti(t, iface, port, []string{needle}, do, wait)[needle]
@@ -36,6 +51,9 @@ func tcpdumpObserver(t *testing.T, iface string, port uint16, needle string, do
 // the wire.
 func tcpdumpObserverMulti(t *testing.T, iface string, port uint16, needles []string, do func(), wait time.Duration) map[string]bool {
 	t.Helper()
+	// Every capture in this file funnels through here, so one guard covers the
+	// whole suite and no future test can forget it.
+	requireTCPDump(t)
 	ctx, cancel := context.WithTimeout(context.Background(), wait)
 	defer cancel()
 	cmd := exec.CommandContext(ctx, "tcpdump", "-i", iface, "-n", "-A", "-l",

common/urltest/probegate_lx.go

@@ -0,0 +1,61 @@
+package urltest
+
+// lx: health board §5.C — the reachability half of "should this be probed".
+//
+// # Two different reasons not to probe, and why they cannot be one flag
+//
+// A group's OWN probing schedule is stood down for two unrelated reasons, and
+// conflating them breaks one of the two:
+//
+//   - NOT USED — no enabled routing rule reaches this group, so probing it
+//     measures a path nothing travels. That is a property of the CONFIG, it is
+//     decided once when the config is generated, and it travels in the config
+//     itself (option.URLTestOutboundOptions.SelfCheck). It cannot change while
+//     the box runs, because the rules cannot change while the box runs.
+//
+//   - NOT REACHABLE RIGHT NOW — the group is a hop of a chain and a hop in
+//     FRONT of it is currently dead. Every member of this group dials through
+//     that hop, so every probe would fail inside it: the measurement would be
+//     about the broken hop, and would be recorded against this one. That is a
+//     property of the WORLD, it changes minute by minute, and it must be
+//     re-asked every time rather than baked into the config — a hop that comes
+//     back must resume probing on its own, with no reapply and nobody pressing
+//     anything.
+//
+// ProbeGate is the second one. It is deliberately a QUESTION asked at the
+// moment of probing and never a stored answer: there is no flag to set, so
+// there is no flag to forget to clear.
+//
+// The gate governs the group's own SCHEDULE only — the warm-up sweep and the
+// ticker. An explicit check (a human, an API call) is a deliberate request and
+// is never refused, exactly as with SelfCheck.
+type ProbeGate interface {
+	// ProbeAllowed reports whether the outbound tagged tag may run its own
+	// scheduled probe right now.
+	//
+	// Implementations MUST answer true when they do not know: a gate that
+	// refuses on missing information would silence probing precisely when the
+	// system has the least idea what is going on, and nothing would ever
+	// measure its way out of that. A nil ProbeGate means "no gate" and every
+	// probe proceeds.
+	ProbeAllowed(tag string) bool
+
+	// ProbeWhenIdle reports whether the outbound tagged tag must keep measuring
+	// even when no traffic is passing through it.
+	//
+	// A urltest group normally probes only while it is in use: Touch arms the
+	// ticker on a dial, and the idle timeout stops it again. That is right for a
+	// group whose readings matter only while somebody is dialling it, and wrong
+	// for one the routing config REACHES: a rule that matches rarely — a narrow
+	// domain list, say — is in force the whole time, so the health of its target
+	// is a live question the whole time. Letting it go quiet means the panel
+	// reports "untested" about a rule that is armed, and the first real request
+	// pays a cold probe instead of picking an already-known-good member.
+	//
+	// Unlike ProbeAllowed, the safe answer here is FALSE when nothing is known.
+	// This one ADDS work, and a gate that claimed it on missing information would
+	// keep every group in the process probing forever — not a default anybody
+	// asked for. Absent gate, unknown tag, nothing configured yet: false, and the
+	// idle timeout behaves exactly as it always has.
+	ProbeWhenIdle(tag string) bool
+}

dist/shater-feed.pub

@@ -1,2 +0,0 @@
-untrusted comment: shater feed signing key
-RWRaxLF3aJy44JbcxSFujtrFFEQ8lIsnTkd1K5TdjIhdlC2c0wa0fv4V

docs-shater/CONTEXT.md

@@ -31,12 +31,11 @@ Do not delete it — we port proven pieces from it. What v0.1 has:
 - **`luci-app-shater`** — a custom "instrument panel" LuCI app (client-side JS +
   ucode/rpcd ubus backend): Overview with a live Signal Path, Simple/Advanced
   toggle, quick-start wizard, Nodes/Subs/Rules/DNS/Live/Profiles/Settings pages.
-- **CI + signed opkg feed** on Gitea: builds per-arch, signs the feed index with
-  usign, publishes a rolling `latest` Gitea release consumable as `src/gz`. **Feed
-  signing key fingerprint `5ac4b177689cb8e0`**; public key `dist/shater-feed.pub`,
-  secret in the Gitea repo secret `KEY_BUILD`.
+- **CI + a signed package feed** on Gitea: builds per-arch, signs the feed index,
+  publishes a rolling `latest` Gitea release the router consumes as a feed.
+  (v0.1 shipped `.ipk` signed with a usign key — that lane is retired, D22.)
 - Verified end-to-end on the VM: real LAN client proxied, DNS anti-leak, honest
-  fail-closed, opkg install/upgrade from the signed feed.
+  fail-closed, install/upgrade from the signed feed.
 
 v0.1 is engine-locked to **xray-core**; its generator, share-link parser and
 `run.json` are xray-shaped.
@@ -91,7 +90,7 @@ We are rebasing onto a new engine and a new UI architecture. Full rationale in
 - **`shater` branch `v0.1`** = the standalone xray-based version (frozen, ported
   from).
 - Until Phase 1 merges the engine in, `main` is the docs-first overlay seed you
-  are reading now (LICENSE, README, `docs-shater/`, `dist/shater-feed.pub`).
+  are reading now (LICENSE, README, `docs-shater/`, the feed signing key).
 
 ## What to port from v0.1 (don't rewrite these ideas)
 
@@ -105,8 +104,8 @@ overlay, don't redo:
 - **Subscription fetch** (HAPP emulation, fingerprint reconcile, per-sub cache)
   and the flexible **ruleset/list** model — though sing-box has its own share-link
   parser and config schema we now target.
-- **CI feed build + usign signing + Gitea release** (adapt to the single forked
-  binary; keep key `5ac4b177689cb8e0`).
+- **CI feed build + index signing + Gitea release** (adapted to the single forked
+  binary; the format is apk, signed with the EC key — D22).
 - The LuCI **design system** (the "instrument panel" identity) — reused for the
   mini-dashboard and as the panel's visual language.
 
@@ -122,9 +121,9 @@ filter/stats engine wired into sing-box's DNS.
   `https://github.com/SagerNet/sing-box`).
 - **CI:** Gitea Actions (act_runner + Docker). v0.1's workflow was removed from
   `main`; new CI is added when the v0.2 build exists.
-- **Feed signing:** usign key `5ac4b177689cb8e0`; secret in repo secret
-  `KEY_BUILD`; public key `dist/shater-feed.pub` (kept so existing installs keep
-  verifying).
+- **Feed signing:** EC (prime256v1) key for the apk index; secret in the repo
+  secret `KEY_APK`; public key `dist/shater-apk.pem`, installed on routers as
+  `/etc/apk/keys/shater-apk.pem`. Never regenerate it (D22).
 - **Test VM:** OpenWrt 24.10.3 x86_64 in Docker (`docker ps --filter
   name=openwrt-vm`). SSH via the ssh-manager MCP server `local_openwrt`
   (localhost:2222, root/openwrt). LuCI at `http://127.0.0.1:8080` (root/openwrt),

docs-shater/DECISIONS.md

@@ -64,11 +64,17 @@ sing-box is GPL-3.0; linking it makes the combined work GPL-3.0. Our own files m
 stay GPL-2.0-or-later (which permits the upgrade), but the project LICENSE is
 GPL-3.0 for clarity.
 
-## D7 — Keep the v0.1 feed signing identity
+## D7 — Keep the v0.1 feed signing identity  *(SUPERSEDED by D22)*
 The usign feed key `5ac4b177689cb8e0` (public key in `dist/shater-feed.pub`,
 secret in Gitea secret `KEY_BUILD`) carries over, so routers that already trust it
 keep verifying v0.2 packages. Do not regenerate it without a documented rotation.
 
+> **Superseded 2026-07-25 (D22).** The opkg feed this identity signed no longer
+> exists, so there is nothing left for the key to verify. It was never rotated or
+> compromised — it is simply unused. `dist/shater-feed.pub` was deleted from the
+> tree; the reasoning, and how to resurrect the identity if it is ever needed
+> again, is in D22.
+
 ## D8 — Preserve, don't destroy: v0.1 lives on its branch
 The reset moved the full working xray-based project to the `v0.1` branch and
 cleaned `main`. Nothing is lost; reusable logic (reliability layer, nft/routing,
@@ -95,6 +101,10 @@ runtime, forcing an ELF with `PT_INTERP=/lib64/ld-linux-x86-64.so.2` + `PT_DYNAM
   plane is tproxy/redirect (netplane); generate never emits a tun inbound, so
   the userspace gvisor netstack (~3.6 MB) is unreachable. If a tun inbound ever
   appears it falls back to the system stack — re-add the tag then.
+  **REVERTED 2026-07-25 — that reasoning was wrong and shipped a dead feature.**
+  gVisor is not only the tun stack: it is the netstack of the **WireGuard
+  endpoint**, which we do emit and do declare [MVP]. See D23; the tag is back and
+  is now held there by a test.
 - 2026-07-23: `with_clash_api` also dropped. The admin panel is shater's own
   web server and generate never emits a `clash_api` service; the desktop/CLI
   `LX_TAGS` keeps the tag for external dashboards.
@@ -424,3 +434,235 @@ on the next render.
 Consequence: all delay numbers are comparable (least ping ranks apples against
 apples), and group settings lose two footgun fields while Settings keeps the
 two that actually govern every check.
+
+## D21 — A rule's destination is a rule-set, and nothing else
+Decided 2026-07-25 (product owner). `config rule` carried THREE ways to say
+where traffic is going: `dst_domain` (an inline domain list), `dst_ip` (an inline
+CIDR list) and `dst_ruleset` (a reference to a `config ruleset`). Three
+mechanisms meant three sets of semantics to learn and keep straight, and the
+inline ones were the worse half of the trade: they are re-parsed per rule instead
+of being compiled once into a `.srs`, they cannot be shared between rules, and
+their matcher vocabulary had drifted from the rule-set one in a way nobody could
+see (below).
+
+**Decision: `dst_domain` and `dst_ip` are removed (schema v2). `dst_ruleset` is
+the only destination matcher.** `Src`, `dst_port` and `proto` are untouched —
+they are not lists of destinations and have no rule-set form.
+
+- **Rejected: keep the inline lists as a shorthand.** "One obvious way" is the
+  whole point; a shorthand that quietly means something different from the long
+  form (see the bare-entry trap) is worse than no shorthand.
+- **Rejected: promote inline lists to rule-sets lazily at generate time.** The
+  config on disk would then not say what the router does, and the panel would
+  have to render a list the user cannot find or edit.
+
+### The bare-entry trap, and how the migration handles it
+The two contexts already disagreed about exactly one spelling, silently:
+
+| entry              | in a rule (`dst_domain`) | in a rule-set (`entry`) | migrated to  |
+|--------------------|--------------------------|-------------------------|--------------|
+| `example.com`      | **exact host**           | **host + subdomains**   | `full:example.com` |
+| `full:example.com` | exact host               | exact host              | unchanged    |
+| `suffix:example.com` / `.example.com` | host + subdomains | host + subdomains | unchanged |
+| `keyword:ads`      | substring                | substring               | unchanged    |
+| `regexp:^ads\.`    | pattern                  | pattern *(added here)*  | unchanged    |
+| `geosite:x` / `geoip:x` | inert (engine field removed) | inert (unknown prefix) | unchanged |
+
+`shaterd migrate` (schema v1→v2, `shater/model/migrate.go`) creates one inline
+`config ruleset` per rule that still carries a legacy list — `rule-<rule name>`
+for domains, `rule-<rule name>-ip` for addresses — moves the entries across with
+the conversion above, appends the new name to `dst_ruleset`, and deletes the old
+option. It is idempotent, it resumes an interrupted run, and it never overwrites
+a hand-written rule-set that already owns the generated name (it picks
+`rule-<name>-2`). `regexp:` support was added to inline rule-sets in the same
+change precisely so the move can be lossless.
+
+`geosite:`/`geoip:` entries are copied VERBATIM rather than promoted to a
+`source=geosite` rule-set: those matchers have been inert since the engine
+dropped the route-rule geosite/geoip fields, and turning a dead matcher live
+during an upgrade would be a behaviour change, not a migration. The text is kept
+so the operator can see it and convert it deliberately.
+
+**One deliberate semantic change, called out:** a rule that used BOTH lists
+matched them with AND (an engine route rule ANDs its matcher fields), which is
+almost never what "these sites and these networks" meant. The two generated
+rule-sets are ORed, because `rule_set: [a, b]` matches when either matches. Such
+a rule matches more after the migration than before; it affects only configs that
+used both fields at once.
+
+That AND→OR change is about the ENGINE's TCP/UDP path, and it deliberately does
+**not** extend to the untunnelable-protocol plane (`shater/apply/untunnelable.go`,
+the ping / IPTV / VPN-passthrough policy in nftables). There, a v1
+`dst_domain + dst_ip` rule could never claim a packet that carries no domain, so
+the plan skipped it; reading the migrated form as OR would have made the address
+half suddenly decisive, and with `target=direct` that means an upgrade quietly
+sending previously-tunnelled ICMP out with the client's real source address. A
+rule whose rule-sets are known to match by NAME is therefore still skipped by that
+plan, and the skip is reported ("a routing rule matches by name … as well as by
+address"). Split the rule in two if you want the addresses decided there.
+
+### The vocabulary is about ENTRIES YOU TYPE, not about every list body
+The table above is the vocabulary of an **inline** rule-set's `entry` values (and
+of the DNS-filter/device lists, which share the classifier). The other two rule-set
+sources are not other spellings of it:
+
+| source                       | what it is                       | vocabulary |
+|------------------------------|----------------------------------|------------|
+| `inline`                     | entries you type                 | the table above |
+| `url` → `.srs` / `.json`     | a compiled rule-set, engine-owned | the engine's, not ours |
+| `url` → anything else        | a hosts / one-domain-per-line / AdBlock TEXT FILE | **none** — every line is a domain plus its subdomains |
+| `file`                       | a local `.srs` / `.json`          | the engine's, not ours |
+
+**Rejected: run text lists through the entry classifier too.** A published
+AdGuard/OISD list is full of colon-bearing tokens that are ordinary filter syntax
+(`##…:has(…)`, `$domain=`, absolute URLs); classifying them would either mis-import
+them or bury the operator under hundreds of "unrecognised prefix" warnings per
+list. The formats also disagree structurally — a hosts line carries several names,
+so the text parser works per token, while an entry is a whole line. And `regexp:`
+arriving from a third-party URL is a pattern compiled into the router's matcher and
+evaluated per query, which is a very different proposition from one the operator
+typed.
+
+So the difference stands and is paid for in diagnostics instead: a text list
+containing `full:` / `suffix:` / `keyword:` / `regexp:` is reported per list, on
+every generate, naming the entries and pointing at `source=inline` where they work
+(`warnListEntryVocabulary`, `shater/generate/ruleset.go`). The check tests only
+those four markers, never the general `word:` shape, so it fires on a human's
+mistake and stays quiet on published filter syntax.
+
+Consequence: one destination mechanism, one vocabulary, one place a list is
+edited; every list is compiled once and reused. The panel's rule editor drops its
+Domain(s) and IP/CIDR(s) fields; its destination control is a checkbox list of
+the rulesets that already exist, and nothing more. Creating and filling a list
+stays in the Rulesets panel — **rejected: a "create a list from here" shortcut in
+the rule editor**, because a second place to author a list is a second place for
+its semantics and its duplicate-name rules to drift, and the whole point of this
+decision was to stop having two.
+
+## D22 — One packaging lane: apk. The opkg/`.ipk` lane is deleted, not disabled
+Decided 2026-07-25 (product owner). CI built and published TWO signed feeds from
+every run: opkg/usign (`.ipk` + `Packages.gz`, OpenWrt 24.10) and apk/EC (`.apk` +
+`packages.adb`, OpenWrt/ImmortalWrt 25.12). The opkg half served nobody. Checked
+on the actual hardware, not inferred:
+
+| Device | Firmware | pkg arch | package manager |
+|---|---|---|---|
+| `mini_router` (BPi-R3 Mini) | ImmortalWrt 25.12.1 | `aarch64_cortex-a53` | apk-tools 3.0.5 |
+| `main_router` (BPi-R4)      | OpenWrt 25.12.0     | `aarch64_cortex-a53` | apk-tools 3.0.5 — **no `opkg` binary on the system at all** |
+
+**Decision: delete the opkg lane outright.** Removed: the `build` + `release`
+jobs from `.gitea/workflows/release.yml`; `ci/build-feed.sh`, `ci/sdk-build.sh`,
+`ci/make-index.sh`, `ci/install-usign.sh`; and the trust anchor
+`dist/shater-feed.pub`. The Gitea secret `KEY_BUILD` is now referenced by
+nothing and can be deleted from the repo settings. `ci/version.sh`,
+`ci/gitea-release.sh` and `ci/fetch-sdk.sh` are shared or apk-only and stay.
+
+- **Rejected: keep the lane but stop triggering it** (comment it out / gate it on
+  a dispatch input). Dead code in CI is worse than no code: it keeps a second SDK
+  matrix, a second signing key and a second feed layout alive in everyone's head
+  and in every future edit, and it silently rots because nothing runs it. The
+  24.10 SDK images it pins are themselves a frozen dependency.
+- **Rejected: keep `dist/shater-feed.pub` as a historical artifact.** A committed
+  trust anchor is an instruction — it invites someone to follow the old install
+  path for a feed that is no longer produced. Nothing is lost by removing it:
+  git history still holds the file, the SECRET half is untouched in `KEY_BUILD`,
+  and a usign secret key blob contains its own public half, so the identity can
+  be reconstructed if a 24.10 device ever has to be served again. Deleting the
+  file is reversible; a stale trust anchor pointing at an unmaintained feed is
+  the thing that quietly misleads.
+- **Not done: revoking or rotating the usign key.** There is no incident. It is
+  retired, not burned (D7).
+
+Consequence: one SDK, one key, one feed layout, one set of install instructions.
+It also makes the rolling release `apk-latest-<arch>` the *only* install path
+that does not require hand-editing a file per release — which is why the same
+change fixed it: publishing was an either/or (`apk-latest-<arch>` on dispatch,
+ELSE `apk-vX.Y.Z-<arch>` on a tag), so once releases moved to tag pushes the
+rolling pointer stopped being written and froze at `0.2.0` while v0.2.9/v0.2.10
+shipped — routers on the rolling URL got a successful, silent `apk update` with
+nothing new. `release-apk` now writes the rolling pointer on every run and
+asserts, by reading the published release back over the Gitea API, that it holds
+our three tag-versioned packages at exactly the version just built and no asset
+at any other version.
+
+
+## D23 — The router tag set is a checked contract, not a string literal
+`with_gvisor` was trimmed from the router set on 2026-07-23 (D9) as "unreachable
+code: we never emit a tun inbound". True about tun — and irrelevant, because
+gVisor is also the netstack of the **WireGuard endpoint**, which shater emits and
+FEATURES.md declares [MVP] (AmneziaWG is called *"a driving requirement"*). Every
+binary shipped between then and 2026-07-25 answered a configured WireGuard node
+with:
+
+```
+create instance: initialize endpoint[0]: create WireGuard device:
+gVisor is not included in this build, rebuild with -tags with_gvisor
+```
+
+`transport/wireguard/device_stack_stub.go` (`//go:build !with_gvisor`) returns
+`tun.ErrGVisorNotIncluded` from **both** device constructors, so
+`system_interface: true` is not an escape hatch either: WireGuard was 100% dead
+in the shipped artifact while the panel offered it, the parser accepted `wg://`,
+`awg://` and wg-quick `.conf` imports, and the owner had 7 WireGuard sections in
+UCI on a production router.
+
+- **Decision:** `with_gvisor` is part of the router tag set and stays there for
+  as long as we ship WireGuard. It costs **~2.8 MB raw / ~0.65 MB UPX per arch**
+  (measured 2026-07-25, both arches; `/overlay` on the production router is
+  6.9 GB with 205 MB used). A tag whose absence turns a declared feature into a
+  runtime error is not "dead weight" — it is the feature.
+
+### Why the bug was invisible, and what now makes it visible
+The defect was not a typo in a tag list. It was that **nothing connected the tag
+list to the feature list**, and the shipped tag combination was the one build
+configuration nothing exercised: the whole test suite compiles with the FULL
+upstream set (`with_gvisor` included), so `TestAmneziaWGEndpoint` passed happily
+while the artifact it was supposed to vouch for could not create a WireGuard
+device. Tests proved the code was right; they never proved the *build* was.
+
+Three pieces now hold it together:
+
+1. **One definition of the set** — `scripts/router-tags.sh` (`SHATER_ROUTER_TAGS`
+   + `SHATER_ROUTER_LDFLAGS`), sourced by `scripts/build-shaterd.sh` and by the
+   checker. The tag list used to live as a literal inside the build script, i.e.
+   in a file no test reads. A second copy is a second truth.
+2. **A declared-feature table** — `shater/buildtags`: every tag-gated capability
+   we promise, with the exact tags it needs *to run* and why (the code anchor).
+   `TestRouterTagSetCoversDeclaredFeatures` parses the shell file and fails if a
+   declared feature lost a tag. It needs no build tags, no Linux, no network and
+   no privileges, so it runs in every plain `go test ./...` — including on the
+   Windows dev host, where nothing else can see the shipped configuration.
+3. **A construction test under the shipped tags** —
+   `shater/generate.TestShippedTagSetConstructsDeclaredProtocols` drives one node
+   of every declared protocol (ss/vmess/trojan/vless ws-grpc-httpupgrade-quic-
+   xhttp/REALITY/uTLS-fp/hysteria2/tuic/**wg**/**awg**) through `box.New`+`Start`.
+   `scripts/check-router-tags.sh` runs it **with `SHATER_ROUTER_TAGS`**, and CI
+   runs that script (`.gitea/workflows/release.yml`) *before* the artifact is
+   built. In a router-tag-set run nothing may be skipped: a protocol that is not
+   compiled in fails the run instead of quietly disappearing from it.
+
+(2) catches a trim the moment it is made and names the feature it kills; (3)
+catches what a list comparison cannot — a tag that is present but insufficient.
+Neither is a substitute for the other. A new protocol in `shater/parse` +
+`shater/generate` means a new row in `buildtags.Features` and a new probe case;
+`TestEveryTagGatedFeatureIsProbed` fails until both exist.
+
+- **Rejected: "just add the tag".** The one-line fix restores WireGuard and
+  leaves the mechanism that hid it fully intact — the next size-driven trim is
+  equally invisible. The tag is the smallest part of this decision.
+- **Rejected: run the WHOLE test suite with the router tag set in CI.** It is the
+  obvious move and it does not work: parts of the suite legitimately depend on
+  upstream-only tags, and the run costs a second full compile of a 25 MB binary's
+  worth of packages on every release. A focused, unprivileged construction test
+  buys the same evidence for ~10 s and, unlike a full run, can be *required* to
+  skip nothing.
+- **Rejected: assert the tag set against upstream's `DEFAULT_BUILD_TAGS`.** That
+  makes any trim a failure, which turns the check into noise and re-litigates D9
+  on every upstream rebase. The contract is with our own feature list, not with
+  upstream's.
+- **Not done: dropping `with_lx_command`.** It is inert for `shaterd` — nothing
+  under `shater/` imports `sing-box/daemon` or `experimental/libbox`, and
+  `go list -deps ./shater/cmd/shaterd` links neither, so it costs zero bytes. It
+  stays only so the router set remains a subset of the lx desktop set. Noted
+  because "a tag that buys nothing" is the mirror image of this bug and should be
+  removed deliberately, not silently.

docs-shater/FEATURES.md

@@ -13,8 +13,12 @@ usable release, **[T1]** next, **[T2]** later. Phases refer to `ROADMAP.md`.
 - **[MVP]** TPROXY transparent proxy for multiple LAN interfaces (TCP + UDP), SNI/
   Host/QUIC sniffing.
 - **[MVP]** First-match routing rules by source (IP/CIDR/MAC/interface/zone),
-  destination (domain/suffix/keyword/geosite), reusable domain/IP lists, port,
-  proto → target (outbound/selector/chain/direct/block) + egress.
+  destination, port, proto → target (outbound/selector/chain/direct/block) + egress.
+  A rule names its **destination through a rule-set only** — a reusable named list
+  (inline domains/CIDRs, a local or remote file, or a geosite/geoip category) that is
+  compiled once into a `.srs` and shared by every rule that references it. Domain
+  entries take `full:` (exact), `suffix:` / a leading dot (host + subdomains),
+  `keyword:` (substring) and `regexp:`; a bare entry means host + subdomains.
 - **[MVP]** Node groups with balancer/observatory (least-ping/failover/round-robin).
 - **[T1]** Multi-hop chains (L1→Ln); per-rule egress selection; egress via any
   interface/tunnel (e.g. an AmneziaWG tunnel).
@@ -89,8 +93,8 @@ usable release, **[T1]** next, **[T2]** later. Phases refer to `ROADMAP.md`.
   SIM uplink → different egress); backup/restore; i18n (EN + RU).
 
 ## Ops & distribution
-- **[MVP]** Single signed binary; signed opkg feed on Gitea (reuse key
-  `5ac4b177689cb8e0`); one-line install; `opkg upgrade`.
+- **[MVP]** Single signed binary; signed apk feed on Gitea (EC key
+  `dist/shater-apk.pem`); one-line install; named-package `apk upgrade`.
 - **[T1]** Upstream-rebase cadence (track sing-box-lx tags) with a smoke suite.
-- **[T2]** apk (OpenWrt 25.x) packaging; multi-router fleet management; REST/gRPC
-  external API; Telegram bot.
+- **[T2]** Multi-router fleet management; REST/gRPC external API; Telegram bot.
+  (apk packaging landed and is now the only lane — D22.)

docs-shater/INSTALL.md

@@ -1,7 +1,7 @@
 # Shater v0.2 — Build & Install
 
 How to build the ship artifact (the SPA-embedded `shaterd` binary) and install
-the OpenWrt feed onto a router.
+the signed apk repo onto a router.
 
 ## 1. Build the `shaterd` binary
 
@@ -26,7 +26,9 @@ What it does:
 Arg / env:
 
 - `VERSION` — stamped into `constant.Version`. Resolution: positional arg →
-  `$SHATER_VERSION` → `git describe --tags` → `v0.2.0-dev`.
+  `$SHATER_VERSION` → `ci/version.sh --binary` → `v0.2.0-dev`. `ci/version.sh` is
+  the **same** computation the package version comes from (§2.1), so the string
+  the panel shows always matches what `apk list -I shaterd` reports.
 - `--fast` — skip `npm ci` when `panel/node_modules` already exists.
 - `UPX=/path/to/upx` — override the UPX binary (default `upx` on `PATH`). UPX is
   cross-arch, so one host packs both the amd64 and aarch64 ELFs. (Note: UPX also
@@ -41,22 +43,44 @@ UPX="…/scratchpad/upx-4.2.4-win64/upx.exe" scripts/build-shaterd.sh v0.2.0 --f
 The `dist/*` and `openwrt/shaterd/files/shaterd-*.upx` outputs are gitignored —
 they are release artifacts, not source.
 
-Tag set (D9 — keep in sync with `docs-shater/DECISIONS.md`):
+Tag set (D9/D23) — defined in **one** place, `scripts/router-tags.sh`, which
+documents every tag and is sourced by the build:
 
 ```
-with_quic,with_wireguard,with_utls,
+with_gvisor,with_quic,with_wireguard,with_utls,
 badlinkname,tfogo_checklinkname0,with_xhttp,with_awg,with_lx_command
 ```
 
 We drop `with_purego,with_naive_outbound`: they pull cronet-go, which forces a
 glibc `PT_INTERP` even under `CGO_ENABLED=0`, making the binary unusable on musl.
-We drop `with_gvisor`: the shater data plane is tproxy/redirect and generate
-never emits a tun inbound, so the userspace gvisor netstack is unreachable code.
 We drop `with_clash_api`: the admin panel is shater's own web server and the
 generator never emits a `clash_api` service, so the Clash server is dead code.
 We drop `with_dhcp`: shater resolver types are `udp/tcp/doh/dot/local/fakeip`;
 a `dhcp://` DNS transport is never generated or registered.
 
+`with_gvisor` was dropped in 2026-07 as "unreachable — we emit no tun inbound"
+and **put back on 2026-07-25**: gVisor is also the netstack of the WireGuard
+endpoint, so without it every `wg://`/`awg://` node died at apply time with
+*"gVisor is not included in this build"* while the panel still offered the
+feature. It costs ~2.8 MB raw / ~0.65 MB UPX per arch. Full story: `DECISIONS.md`
+D23.
+
+### Changing the tag set
+
+Run the guard — it is what stands between a size trim and a silently dead
+feature, and CI runs it before the artifact is built:
+
+```sh
+scripts/check-router-tags.sh     # from Windows/macOS it re-execs itself in golang:1.26
+```
+
+It (1) fails if a feature declared in `FEATURES.md` lost a build tag it needs to
+run (`shater/buildtags`, no tags/OS/network required) and (2) constructs one node
+of every declared protocol through `box.New` **compiled with the shipped tag
+set** — nothing may be skipped in that run. Adding a protocol to
+`shater/parse`+`shater/generate` means adding a row to `buildtags.Features` and a
+probe case in `shater/generate/shipped_tags_linux_test.go`.
+
 ## 2. Packages
 
 Four OpenWrt packages live under `openwrt/`:
@@ -84,22 +108,65 @@ it. Because the binary is UPX-packed, the package disables the SDK's default str
 feed installed and run `make package/shaterd/compile` (and the others) per target.
 See `openwrt-package-build-ci` for SDK/feed mechanics.
 
+### 2.1 Package versions come from the git tag
+
+`PKG_VERSION`/`PKG_RELEASE` are **not** maintained by hand. They used to be, and
+nobody bumped them: **v0.2.2 … v0.2.6 all shipped as `shaterd 0.2.0-r3`** with
+different binaries inside (v0.2.6's ELF is 5 491 616 B against r2's 5 488 336 B).
+apk offers an upgrade only when the feed's version string differs from the
+installed one, so `apk update` saw nothing new and the routers could not be
+updated through the normal path at all.
+
+`ci/version.sh` now derives them from `git describe`, once per CI job:
+
+| Build | `PKG_VERSION` | `PKG_RELEASE` | `constant.Version` |
+|---|---|---|---|
+| tag push `v0.2.7`             | `0.2.7` | `1` | `v0.2.7-r1` |
+| dispatch, 3 commits past `v0.2.7` | `0.2.7` | `4` | `v0.2.7-r4-g<sha>` |
+| no reachable tag / no git     | `0.0.0` | `1` | `v0.0.0-r1` |
+
+Ordering is what makes this safe (checked with `apk version -t` on apk-tools
+3.0.3): the dotted part decides first, `-rN` only breaks ties — so
+`0.2.7-r1 > 0.2.6-r12 > 0.2.6-r1 > 0.2.0-r3`. A release therefore always
+outranks every rolling build before it, rolling builds between two releases grow
+monotonically, and an untagged build (`0.0.0`) can never masquerade as an
+upgrade.
+
+The value travels as `SHATER_PKG_VERSION`/`SHATER_PKG_RELEASE` in the SDK build
+environment; the Makefiles read it with a literal fallback for manual/offline
+builds. `ci/sdk-build-apk.sh` then **asserts** the produced `.apk` really carries
+it, so a lost variable fails the build instead of shipping a stale version. The
+release job asserts the same version again on the published rolling repo (§5.1).
+
+`byedpi` is deliberately excluded — `PKG_VERSION:=0.17.3` is *upstream ByeDPI's*
+version, which is what `PKG_HASH` pins and what tells you which ByeDPI is
+installed. Stamping our tag on it would also be a downgrade: every comparator
+reads `0.2.7 < 0.17.3` (component-wise, `2 < 17`). Bump its `PKG_RELEASE` by hand
+when our packaging of it changes.
+
 ## 3. Install on a router
 
-Install order follows the deps (`shaterd` → `shater-core` → `luci-app-shater`):
+**The normal path is the signed apk repo — §5.** This section is the manual
+fallback (a router with no route to the Gitea host, or a hand-carried build).
+
+Install order follows the deps (`shaterd` → `shater-core` → `luci-app-shater`).
+apk filenames carry no architecture, so make sure you copied the `.apk` built for
+*this* router's arch (`cat /etc/apk/arch`):
 
 ```sh
-opkg install shaterd_0.2.0-1_<arch>.ipk        # or: apk add shaterd   (25.12+)
-opkg install shater-core_0.2.0-1_all.ipk
-opkg install luci-app-shater_0.2.0-1_all.ipk
-opkg install byedpi_0.17.3-1_<arch>.ipk        # optional: ByeDPI egress
+# <ver> = the release version, e.g. 0.2.7-r1 (§2.1 — it comes from the git tag)
+# --allow-untrusted: our member .apk are unsigned by design — trust lives in the
+# signed packages.adb index (§5), which a loose file install does not consult.
+apk add --allow-untrusted ./shaterd-<ver>.apk
+apk add --allow-untrusted ./shater-core-<ver>.apk
+apk add --allow-untrusted ./luci-app-shater-<ver>.apk
+apk add --allow-untrusted ./byedpi-0.17.3-r1.apk       # optional: ByeDPI egress
 ```
 
-Installing from a signed feed instead:
+From the repo instead (§5 sets it up once), deps pull the rest in:
 
 ```sh
-# add the feed (customfeeds.conf / apk repositories), then:
-opkg update && opkg install shater-core luci-app-shater   # shaterd pulled in as a dep
+apk update && apk add luci-app-shater      # -> shater-core -> shaterd
 ```
 
 ## 4. Enable
@@ -119,83 +186,55 @@ daemon (`shaterd run`), which owns the engine, the `inet shater` data plane, pol
 routing, in-process DNS, and the admin panel (default `:8088`). The LuCI app's
 "Open panel" button mints a single-use token and hands the browser off to the panel.
 
-## 5. Add the signed feed (recommended — then `opkg upgrade` just works)
+## 5. The signed apk repo (the normal install path)
 
-CI (`.gitea/workflows/release.yml`) publishes every build as a **rolling `latest`
-Gitea release** that is itself a signed opkg `src/gz` feed: the release holds the
-`.ipk` for all arches, a `Packages`/`Packages.gz` index, a usign `Packages.sig`,
-and the public key `shater-feed.pub`. opkg filters by `Architecture`, so the **same
-two lines work on every device** (x86 testbed picks `x86_64 + all`; the BPI routers
-pick `aarch64_cortex-a53 + all`).
+OpenWrt/ImmortalWrt **25.12** packages with Alpine's **apk**: `.apk` files, a
+binary `packages.adb` index, EC (prime256v1) keys in `/etc/apk/keys/`, and
+effectively mandatory signatures (unsigned needs `--allow-untrusted`). This is
+the only format shater publishes — the `.ipk`/opkg lane was removed in 2026-07
+(`DECISIONS.md` D22); every device we serve is on 25.12 with apk-tools 3.
 
-> **Format:** OpenWrt 24.10 (our SDK) uses **opkg** (`.ipk`, `Packages.gz`, usign),
-> so the feed is `src/gz` and the trust anchor is the usign key
-> `dist/shater-feed.pub` (fingerprint **`5ac4b177689cb8e0`**). apk only replaces
-> opkg at OpenWrt **25.12** — see §6.
-
-One-time setup on the router:
-
-```sh
-# 1) trust the feed key — the FILENAME must equal the usign key fingerprint.
-wget -O /etc/opkg/keys/5ac4b177689cb8e0 \
-  https://git.qomar.pw/omar/shater/releases/download/latest/shater-feed.pub
-
-# 2) add the feed (one URL serves every arch).
-echo "src/gz shater https://git.qomar.pw/omar/shater/releases/download/latest" \
-  >> /etc/opkg/customfeeds.conf
-
-# 3) refresh + install (shaterd is pulled in as a dependency).
-opkg update
-opkg install luci-app-shater        # -> shater-core -> shaterd
-opkg install byedpi                 # optional: ByeDPI desync egress
-```
-
-With the key installed, opkg's default `check_signature 1` verifies the feed on
-every `opkg update`; no `--nocheck-signature` needed. A **tagged** release
-(`vX.Y.Z`) publishes the identical layout at
-`.../releases/download/vX.Y.Z` if you prefer to pin a version instead of tracking
-`latest`.
-
-### Updating
-
-```sh
-opkg update
-opkg upgrade shaterd shater-core luci-app-shater byedpi   # only our own packages
-```
-
-Updates are only offered when the feed's `Version` differs from the installed one,
-so **bump `PKG_RELEASE`** (or `PKG_VERSION`) in the package Makefile on every
-shipped change — otherwise `opkg upgrade` sees the same version and does nothing.
-Do **not** `opkg upgrade` base/system packages from this feed; upgrade only the
-four shater packages above.
-
-## 6. apk feed (OpenWrt/ImmortalWrt 25.12+ — incl. BananaWRT 25.12-mtk-vendor)
-
-OpenWrt/ImmortalWrt **25.12** replaces opkg with Alpine's **apk**: `.apk` files,
-a binary `packages.adb` index, EC (prime256v1) keys in `/etc/apk/keys/`, and
-effectively mandatory signatures (unsigned needs `--allow-untrusted`). The
-package **Makefiles are unchanged** — the SDK release decides the format.
-
-CI builds this lane **in parallel** with the opkg feed (same manual triggers:
-`v*` tag push or `workflow_dispatch`): the `build-apk` jobs in
-`.gitea/workflows/release.yml` compile the same 4 packages through the official
-**ImmortalWrt 25.12 SDK** (tarballs from
+CI (`v*` tag push or `workflow_dispatch`) compiles the 4 packages through the
+official **ImmortalWrt 25.12 SDK** (tarballs from
 `downloads.immortalwrt.org/releases/25.12.1/targets/{x86/64,mediatek/filogic}/`)
-and publish **one release per arch** — rolling `apk-latest-x86_64` /
-`apk-latest-aarch64_cortex-a53`, or `apk-vX.Y.Z-<arch>` for a tagged version.
-Per-arch (unlike the combined opkg release) because apk filenames carry no
-architecture and packages are fetched relative to the `packages.adb` URL.
+and publishes **one release per arch**: the rolling `apk-latest-x86_64` /
+`apk-latest-aarch64_cortex-a53`, plus `apk-vX.Y.Z-<arch>` on a tag. Per-arch
+because apk filenames carry no architecture and packages are fetched *relative to
+the `packages.adb` URL*, so one flat multi-arch release would collide.
 
-> **Key:** apk cannot use the usign key. The apk trust anchor is the separate EC
-> public key **`dist/shater-apk.pem`** (generated once by `ci/gen-apk-key.sh`;
-> private half lives ONLY in the Gitea secret **`KEY_APK`**, the apk analog of
-> `KEY_BUILD`). Never regenerate either key — that invalidates every deployed
-> router's trust. The usign identity `shater-feed.pub` keeps signing the
-> opkg/24.10 feed, untouched.
+> **Key:** the trust anchor is the EC public key **`dist/shater-apk.pem`**
+> (generated once by `ci/gen-apk-key.sh`; the private half lives ONLY in the
+> Gitea secret **`KEY_APK`**). Never regenerate it — that invalidates every
+> deployed router's trust.
 
-One-time setup on a 25.12 router (BananaWRT `25.12-mtk-vendor` on the BPI-R3
-mini, BPI-R4 on 25.12, or the future 25.12 VM — `/etc/apk/arch` picks the right
-per-arch release automatically):
+### 5.1 Rolling or pinned — pick the repo URL deliberately
+
+The repo line names an **index file**, and which one you name is the whole
+update policy:
+
+| Repo line points at | Behaviour | Cost |
+|---|---|---|
+| `apk-latest-<arch>/packages.adb` (**rolling**) | Every release run REPLACES this release's assets, so `apk update && apk upgrade <our packages>` always sees the newest build. Install once, never touch the file again. | You get whatever CI published last; there is no per-router pin. |
+| `apk-vX.Y.Z-<arch>/packages.adb` (**pinned**) | The router stays on exactly that build. `apk update` will never offer a newer shater. | `/etc/apk/repositories.d/shater.list` must be edited **by hand on every upgrade**, on every router. |
+
+`mini_router` is deliberately on a **pinned** URL — a considered choice, and the
+hand-edit per release is its price. Use rolling unless you specifically want to
+freeze a device.
+
+> The rolling release used to go stale silently: publishing was an either/or, so
+> tag runs wrote only `apk-vX.Y.Z-<arch>` and `apk-latest-<arch>` was last
+> refreshed on 2026-07-24 at `0.2.0` while v0.2.9/v0.2.10 shipped. A router on
+> the rolling URL kept getting a successful `apk update` with nothing new. Fixed
+> 2026-07-25: `release-apk` writes the rolling pointer on **every** run and then
+> reads the release back over the Gitea API, asserting it holds our three
+> tag-versioned packages at exactly the version just built and **no** leftover
+> asset at another version (two versions of one package in one index would let
+> apk choose instead of us).
+
+### 5.2 One-time setup on the router
+
+BananaWRT `25.12-mtk-vendor` on the BPI-R3 mini, OpenWrt 25.12 on the BPI-R4, or
+the testbed VM — `/etc/apk/arch` picks the right per-arch release automatically:
 
 ```sh
 # 1) trust the apk feed key (any *.pem filename under /etc/apk/keys works).
@@ -203,6 +242,7 @@ wget -O /etc/apk/keys/shater-apk.pem \
   "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/shater-apk.pem"
 
 # 2) add the repo — the line points at the packages.adb INDEX FILE itself.
+#    (rolling; for a pinned router put apk-vX.Y.Z-$(cat /etc/apk/arch) here — §5.1)
 echo "https://git.qomar.pw/omar/shater/releases/download/apk-latest-$(cat /etc/apk/arch)/packages.adb" \
   > /etc/apk/repositories.d/shater.list
 
@@ -212,17 +252,34 @@ apk add luci-app-shater        # -> shater-core -> shaterd
 apk add byedpi                 # optional: ByeDPI desync egress
 ```
 
-### Updating
+### 5.3 Updating
+
+**Never run a bare `apk upgrade`.** With no arguments apk reconciles *every*
+installed package against *every* configured repository at once; on a router
+whose distfeeds point at a moving snapshot that can pull in — or roll back —
+unrelated system packages. Always name ours:
 
 ```sh
 apk update
-apk upgrade shaterd shater-core luci-app-shater byedpi   # only our own packages
+apk upgrade shaterd shater-core luci-app-shater byedpi
 ```
 
-Same rule as opkg: an upgrade is only offered when the feed version differs, so
-bump `PKG_RELEASE`/`PKG_VERSION` on every shipped change (apk shows it as
-`0.2.0-r1`). Pin a version instead of tracking rolling by pointing the repo line
-at `.../download/apk-vX.Y.Z-$(cat /etc/apk/arch)/packages.adb`.
+apk-tools 3 documents exactly this behaviour for `apk upgrade`: *"When no
+packages are specified, all packages are upgraded if possible. If list of
+packages is provided, only those packages are upgraded along with needed
+dependencies."* The equivalent form, which additionally re-pins the packages in
+`world`, is:
+
+```sh
+apk add -u shaterd shater-core luci-app-shater byedpi     # -u = --upgrade
+```
+
+Drop `byedpi` from either list if you never installed it. Check what you are on
+with `apk list -I shaterd shater-core luci-app-shater byedpi` — the version reads
+`0.2.7-r1` (§2.1: `PKG_VERSION-rPKG_RELEASE`, derived from the git tag by CI, so
+every build really is a new version; before that fix v0.2.2…v0.2.6 all published
+as `0.2.0-r3` and `apk update` offered nothing). Rolling vs pinned repo URL —
+§5.1.
 
 ### BananaWRT `25.12-mtk-vendor` compatibility
 

docs-shater/PORTING.md

@@ -195,7 +195,7 @@ type Chain struct { Name string; Hops []string } // "group:<n>" | "node:<n>", L1
 type Egress struct { Name,Type,Interface,Target string } // interface|proxy|direct|block
 type Rule struct {
 	Name string; Enabled bool; Order int
-	Src []string; DstDomain,DstRuleset,DstIP []string; DstPort,Proto string
+	Src []string; DstRuleset []string; DstPort,Proto string // dst = ruleset only (v0.2 schema v2)
 	Target string // chain:|group:|node:|direct|block
 	Egress,Kill string
 	SchedEnabled bool; SchedDays []string; SchedStart,SchedEnd string; SchedUTCOffset int
@@ -257,8 +257,12 @@ Apply/rollback: `apSnapshot` (run→last-good, nft→last-good.nft, route marks)
 - `config node`: name, enabled, uri, mux, mux_concurrency, xudp_concurrency, xudp_udp443, sockopt_mark, tcp_fast_open, tcp_keepalive_idle.
 - `config group`: name, source, subscription, list node, strategy, include/exclude/filter_proto/filter_country, dedup, probe_url, probe_interval.
 - `config chain`: name, list hop.  `config egress`: name, type, interface, target.
-- `config ruleset`: name, type(domain|ipcidr), source(inline|file|url), url, path, format, update_interval, list entry.
-- `config rule`: name, enabled, order, list src/dst_domain/dst_ruleset/dst_ip, dst_port, proto, target, egress, kill, sched_enabled, list sched_day, sched_start/end/tz.
+- `config ruleset`: name, type(domain|ipcidr), source(inline|file|url|geosite|geoip), url, path, format, update_interval, list category, list entry.
+- `config rule`: name, enabled, order, list src, list dst_ruleset, dst_port, proto, target, egress, kill, sched_enabled, list sched_day, sched_start/end, sched_utc_offset.
+  v0.1 carried `dst_domain`/`dst_ip` on the rule itself; **schema v2 removed both** — a
+  destination is a `config ruleset` and nothing else. `shaterd migrate` folds each legacy
+  list into a generated `rule-<name>` (and `rule-<name>-ip`) inline ruleset; see
+  `DECISIONS.md` D21 for the entry-by-entry conversion table.
 - `config preset`: name, enabled, order, target.  `config profile`: name, enabled, priority, list match_iface, probe_url, probe_mode, sched_*, list enable_rule/disable_rule, default_target, default_egress.
 - `config resolver`: name, type, address, detour, pool.  `config dns_rule`: order, list match_domain/match_src, resolver.
 

docs-shater/README.md

@@ -6,7 +6,7 @@ OpenWrt). Лицо репозитория и быстрый старт — в к
 | Документ | О чём |
 |----------|-------|
 | [CONTEXT.md](CONTEXT.md) | **Начните здесь** — контекст проекта, история v0.1→v0.2, решения в кратце, testbed/инфра |
-| [INSTALL.md](INSTALL.md) | Сборка ship-артефакта (`shaterd`) и установка обоих фидов — opkg (24.10) и apk (25.12+) |
+| [INSTALL.md](INSTALL.md) | Сборка ship-артефакта (`shaterd`) и установка apk-фида (25.12+): роллинг или фиксация версии |
 | [ARCHITECTURE.md](ARCHITECTURE.md) | One-binary дизайн, auth-handoff LuCI→панель, data/DNS/apply-потоки (диаграммы) |
 | [FEATURES.md](FEATURES.md) | Полный список фич с тегами MVP/T1/T2 |
 | [ROADMAP.md](ROADMAP.md) | Фазовый план |

docs-shater/ROADMAP.md

@@ -104,7 +104,7 @@ build new logic in the `shater/`, `panel/`, `openwrt/` overlay.
 
 ## Phase 8 — Ship it  ✅ DONE
 - Adapt CI to build/sign the single forked binary for both arches; publish the
-  signed opkg feed (reuse key `5ac4b177689cb8e0`); install/upgrade docs.
+  signed feed (apk since D22, EC key `dist/shater-apk.pem`); install/upgrade docs.
 - Set an upstream-rebase cadence (merge new sing-box-lx tags, run the smoke suite).
 
 ## Cross-cutting (every phase)

docs-shater/reports/TEST-mini_router-v0.2.6-2026-07-25.md

@@ -0,0 +1,170 @@
+# Живое тестирование shater v0.2.6 на mini_router
+
+**Дата:** 2026-07-25
+**Устройство:** Bananapi BPi-R3 Mini · ImmortalWrt **25.12-linkup** · `aarch64_cortex-a53`
+**Установка:** из подписанного apk-фида `apk-v0.2.6-aarch64_cortex-a53`
+**Пакеты:** `shaterd 0.2.0-r3`, `shater-core 0.2.0-r3`, `luci-app-shater 0.2.0-r2`, `byedpi 0.17.3-r1`
+**Сборка:** CI run 61, коммит `024e9308c` (вершина `main`)
+
+Сценарий: полное удаление предыдущей установки → чистая установка из фида →
+проверка дефолтного состояния → восстановление рабочего конфига с подписками
+(315 узлов) → функциональная проверка.
+
+**Итог: 79 проверок, 74 PASS, 5 находок** (детали и разбор — в
+`shater-bugs-2026-07-25.md` на рабочем столе).
+
+---
+
+## 1. Релиз и фид
+
+| # | Проверка | Результат |
+|---|---|---|
+| T1 | Публикация `apk-v0.2.6-<arch>` для обеих архитектур | PASS |
+| T2 | Ассеты: 4 `.apk` + `packages.adb` + `shater-apk.pem` | PASS |
+| T3 | `apk update` принимает индекс (проверка EC-подписи) | PASS |
+| T4 | Пакеты видны в нужных версиях (r3/r3/r2) | PASS |
+| T5 | Диагностика сборки: `kmod packages selected (=m): 0` (было 1078) | PASS |
+| T6 | Собраны ровно наши 4 пакета | PASS |
+| T7 | opkg-лейн v0.2.6 (24.10) тоже зелёный | PASS |
+
+## 2. Установка
+
+| # | Проверка | Результат |
+|---|---|---|
+| T8 | `apk add luci-app-shater byedpi` — 4 пакета | PASS |
+| T9 | Зависимости `kmod-nft-tproxy`/`kmod-nft-socket` из базового фида | PASS |
+| T10 | Целостность: `apk manifest` = sha256 файла на диске | PASS |
+| T11 | Установлен именно бинарь v0.2.6 (5 491 616 Б vs 5 488 336 Б в r2) | PASS |
+| T12 | init-скрипты `shater`, `shater-cron` | PASS |
+| T13 | `sysctl.d/99-shater.conf`, `hotplug.d/iface/99-shater` | PASS |
+| T14 | boot-линки `S99shater`, `K10shater`, `S96shater-cron` | PASS |
+
+## 3. Дефолтное состояние (чистая установка)
+
+| # | Проверка | Результат |
+|---|---|---|
+| T15 | Дефолтный конфиг создан uci-defaults (27 строк) | PASS |
+| T16 | `enabled='0'` — плоскость не ставится без согласия | PASS |
+| T17 | Заготовлен tproxy-inbound на LAN, пресеты выключены | PASS |
+| T18 | Демон стартует, `plane=none`, `table=false` | PASS |
+| T19 | Права конфига `-rw-------` (0600) | PASS |
+
+## 4. Восстановление рабочего конфига
+
+| # | Проверка | Результат |
+|---|---|---|
+| T20 | Восстановление из бэкапа (3213 UCI-строк) | PASS |
+| T21 | Кэш подписок цел: 315 узлов в 4 файлах | PASS |
+| T22 | `shaterd migrate` → `ok`, схема v1 | PASS |
+| T23 | Старт с реальным конфигом: `active`, `engine_running`, `plane=full` | PASS |
+
+## 5. Data plane
+
+| # | Проверка | Результат |
+|---|---|---|
+| T24 | Таблица `inet shater` создана (9 цепочек/сетов) | PASS |
+| T25 | 16 tproxy-правил | PASS |
+| T26 | `ip rule from all fwmark 0x2000 lookup shater` | PASS |
+| T27 | `accept_local=1` на `br-lan` | PASS |
+| T28 | DNS-divert: `dport 53 → tproxy :12345` для LAN-интерфейсов | PASS |
+| T29 | DoT заблокирован: `dport 853 reject` | PASS |
+| T30 | `block_doh=1`, правила присутствуют | PASS |
+| T31 | **Kill-switch fail-closed**: цепочка `forward` завершается `drop` для LAN (v4+v6) | PASS |
+| T32 | fw4 и dnsmasq не тронуты (свои таблицы целы) | PASS |
+
+## 6. Панель и API
+
+| # | Проверка | Результат |
+|---|---|---|
+| T33 | SPA отдаётся на `:8088` | PASS |
+| T34 | `shaterd mint-token` выдаёт одноразовый токен | PASS |
+| T35 | `/api/status` без сессии → **401** | PASS |
+| T36 | `/api/session` (POST, JSON) → 200 + cookie `HttpOnly; SameSite=Strict; Max-Age=28800` | PASS |
+| T37 | `/api/status` по cookie отдаёт данные, совпадающие с CLI | PASS |
+| T38 | `/api/config` — 340 записей узлов | PASS |
+| T39 | `/api/groups/health` — 103 протестировано, 13 живых, выбран `FR-vless-8` | PASS |
+| T40 | `/api/devices` — устройства с IPv4/IPv6/MAC | PASS |
+| T41 | `/api/interfaces` — `ewan/eth1 10.0.0.125/24 zone=wan` | PASS |
+| T42 | `/api/ruleset/status` — remote-ruleset обновлён сегодня | PASS |
+| T43 | `/api/stats` — memory backend, счётчики и top-domains | PASS |
+| T44 | `/api/stats/log` — query-log с доменом, qtype, rcode, сервером | PASS |
+| T45 | `/api/log?range=100` — пусто (следствие `log_file='0'`, не дефект) | OK |
+
+## 7. Жизненный цикл конфигурации
+
+| # | Проверка | Результат |
+|---|---|---|
+| T46 | `shaterd apply` → `{"changed":false}`, `can_rollback=true` | PASS |
+| T47 | `shaterd confirm` снимает авто-откат (`can_rollback=false`) | PASS |
+| T48 | `shaterd rollback` после confirm корректно сообщает об отсутствии last-good | PASS |
+| T49 | `shaterd reconcile` (SIGHUP) не роняет движок | PASS |
+| T50 | `shaterd sub update all-qomar` — реально обновил 143 узла | PASS |
+| T51 | `shaterd blocklist update` → reconcile signalled | PASS |
+| T52 | `shaterd schedule due` → reconcile signalled | PASS |
+
+## 8. Устойчивость
+
+| # | Проверка | Результат |
+|---|---|---|
+| T53 | `kill -9` демона → procd поднимает новый PID | PASS |
+| T54 | После respawn: `engine_running=true`, `plane=full` | PASS |
+| T55 | `stop` снимает таблицу `inet shater` полностью | PASS |
+| T56 | `stop` → пауза → `start`: плоскость восстанавливается | PASS |
+| T57 | Сеть при остановленном shater не деградирует | PASS |
+| T58 | Память: 253 МБ занято из 2 ГБ при работающем движке | PASS |
+
+## 9. DNS
+
+| # | Проверка | Результат |
+|---|---|---|
+| T59 | Резолв через `127.0.0.1` | PASS |
+| T60 | LAN-клиенты резолвят через движок (query-log растёт) | PASS |
+| T61 | `.lan`-домены остаются за dnsmasq | PASS |
+| T62 | dnsmasq жив и слушает на всех адресах | PASS |
+| T63 | **Резолв через LAN-адрес `10.67.0.1` после `restart`** | **FAIL — B3** |
+| T64 | Тот же резолв после `stop` → пауза → `start` | PASS |
+
+## 10. Конфигурация и логи
+
+| # | Проверка | Результат |
+|---|---|---|
+| T65 | 5 правил маршрутизации, 2 профиля, активен `ethernet-uplink` | PASS |
+| T66 | **Два правила `default`, оба catch-all — нижнее живое, верхнее мертво** | **FAIL — B1** |
+| T67 | **`shaterd nodes` всегда возвращает `[]`** | **FAIL — B2** |
+| T68 | Логи уходят в syslog (`log_syslog=1`, 22 записи) | PASS |
+| T69 | **ANSI-escape коды в syslog** | **FAIL — B5** |
+| T70 | `loglevel=warning` соблюдается | PASS |
+| T71–T79 | Прочие проверки состояния (статус-поля, права, uptime, счётчики, целостность таблиц) | PASS |
+
+---
+
+## Находки
+
+| ID | Суть | Важность |
+|---|---|---|
+| **B1** | Два catch-all правила `default`; одно из них не работает никогда. **Поправка к первоначальному диагнозу:** правило без условий задаёт `route.Final`, а не выпускается как match-all, поэтому выигрывает ПОСЛЕДНЕЕ (`order=100 → group:auto`) — трафик идёт через прокси, а мёртвая настройка это `order=20 → direct` | средняя |
+| **B2** | `shaterd nodes` — заглушка, всегда `[]`, хотя usage обещает список узлов (в кэше 315, в `/api/config` 340) | средняя |
+| **B3** | После `service shater restart` резолв к LAN-адресу роутера не работает и не восстанавливается; `stop`+пауза+`start` — работает (гонка) | средняя |
+| **B4** | `PKG_RELEASE` не менялся с v0.2.1 → v0.2.2…v0.2.6 выходят как `r3` при разном содержимом; `apk upgrade` не увидит обновления | средняя |
+| **B5** | ANSI-раскраска попадает в syslog | низкая |
+
+Разбор с воспроизведением — в `shater-bugs-2026-07-25.md`.
+
+## История CI по этому релизу
+
+Путь до зелёной сборки apk-лейна занял четыре итерации, каждая вскрывала
+следующий слой одной причины:
+
+| Тег | Что чинили | Итог |
+|---|---|---|
+| v0.2.2 | — (первый прогон с фиксами аудита) | `Disk quota exceeded`, 3593 `apk mkpkg kmod-*` |
+| v0.2.3 | `.config` строится с нуля, а не дописывается | 1078 kmod — SDK вообще не везёт `.config` |
+| v0.2.4 | Выключены `ALL`/`ALL_KMODS`/`ALL_NONSHARED` | 1078 kmod — они выбираются не через `ALL_KMODS` |
+| v0.2.5 | Второй проход: явное `is not set` для каждого kmod | 1078 kmod — kconfig игнорирует user-значение у беспромптовых символов |
+| **v0.2.6** | Удаление сгенерированных блоков `config PACKAGE_*` (`default m`) из `Config-build.in` | **0 kmod, сборка зелёная** |
+
+Корень: `target/sdk/Makefile` генерирует `Config-build.in` прогоном
+`convert-config.pl` по конфигу бильдбота, где `ALL_KMODS=y` уже развернулся в
+`CONFIG_PACKAGE_kmod-*=m` на каждый модуль. Фильтр `next if /^(# )?CONFIG_PACKAGE/`
+в скрипте стоит в ветке `else`, куда строка со знаком `=` не попадает, поэтому
+каждый kmod приезжает в SDK как безусловный `default m`.

openwrt/byedpi/Makefile

@@ -15,6 +15,17 @@
 include $(TOPDIR)/rules.mk
 
 PKG_NAME:=byedpi
+
+# DELIBERATELY NOT auto-versioned from our git tag (unlike shaterd/shater-core/
+# luci-app-shater, which take SHATER_PKG_VERSION/SHATER_PKG_RELEASE from
+# ci/version.sh). PKG_VERSION here is THIRD-PARTY UPSTREAM's version — it is what
+# PKG_SOURCE_URL/PKG_HASH pin, and what tells an operator which ByeDPI is
+# actually installed. Stamping our tag on it would be both a lie and a
+# regression: our tags are 0.2.x, and the version comparator (apk-tools 3,
+# verified) reads 0.2.7 < 0.17.3 — component-wise numerically, 2 < 17
+# — so the "new" package would be a DOWNGRADE and routers would refuse it.
+# Bump PKG_RELEASE BY HAND when *our packaging* of it changes (init script, uci
+# defaults, build flags); bump PKG_VERSION+PKG_HASH when upstream releases.
 PKG_VERSION:=0.17.3
 PKG_RELEASE:=1
 

openwrt/luci-app-shater/Makefile

@@ -24,8 +24,13 @@ LUCI_TITLE:=LuCI thin launcher for Shater (mini dashboard + panel handoff)
 LUCI_DEPENDS:=+shater-core +rpcd
 LUCI_PKGARCH:=all
 
-PKG_VERSION:=0.2.0
-PKG_RELEASE:=2
+# Version comes from the git tag via ci/version.sh -> SHATER_PKG_VERSION /
+# SHATER_PKG_RELEASE in the SDK build env (see openwrt/shaterd/Makefile for the
+# full rationale — bug B4). The literals are the manual/offline fallback only.
+# These MUST stay above the luci.mk include: luci.mk only defaults PKG_VERSION/
+# PKG_RELEASE when they are still unset, and the i18n subpackages inherit them.
+PKG_VERSION:=$(if $(SHATER_PKG_VERSION),$(SHATER_PKG_VERSION),0.2.0)
+PKG_RELEASE:=$(if $(SHATER_PKG_RELEASE),$(SHATER_PKG_RELEASE),1)
 
 PKG_MAINTAINER:=Shater <maqrota@icloud.com>
 PKG_LICENSE:=GPL-3.0-or-later

openwrt/shater-core/Makefile

@@ -13,8 +13,13 @@
 include $(TOPDIR)/rules.mk
 
 PKG_NAME:=shater-core
-PKG_VERSION:=0.2.0
-PKG_RELEASE:=3
+
+# Version comes from the git tag via ci/version.sh -> SHATER_PKG_VERSION /
+# SHATER_PKG_RELEASE in the SDK build env (see openwrt/shaterd/Makefile for the
+# full rationale — bug B4: v0.2.2…v0.2.6 all shipped as 0.2.0-r3). The literals
+# are the manual/offline fallback only.
+PKG_VERSION:=$(if $(SHATER_PKG_VERSION),$(SHATER_PKG_VERSION),0.2.0)
+PKG_RELEASE:=$(if $(SHATER_PKG_RELEASE),$(SHATER_PKG_RELEASE),1)
 
 PKG_MAINTAINER:=Shater <maqrota@icloud.com>
 PKG_LICENSE:=GPL-2.0-or-later

openwrt/shater-core/files/etc/config/shater

@@ -62,7 +62,29 @@ config inbound
 #	list node 'my-node'
 #
 # A routing rule. target: chain:<n>|group:<n>|node:<n>|egress:<n>|direct|block.
-# Match on src / dst_domain / dst_ruleset / dst_ip / dst_port / proto.
+# Match on src / dst_ruleset / dst_port / proto. A rule with NO matcher at all is
+# the default route for everything that reached it.
+#
+# WHERE the traffic is going is named ONLY by dst_ruleset — one or more
+# `config ruleset` names; the rule matches when ANY of them matches. There is no
+# inline domain or address list on a rule (`dst_domain`/`dst_ip` were removed in
+# schema v2): a destination list is written once as a ruleset, compiled into a
+# .srs and shared by every rule that references it. `shaterd migrate` converts
+# older configs automatically, creating a `rule-<name>` ruleset per rule.
+#config ruleset
+#	option name 'blocked-video'
+#	option type 'domain'
+#	option source 'inline'
+#	list entry 'youtube.com'
+#	list entry 'suffix:googlevideo.com'
+#
+#config rule
+#	option name 'video-via-main'
+#	option enabled '1'
+#	option order '50'
+#	list dst_ruleset 'blocked-video'
+#	option target 'group:main'
+#
 #config rule
 #	option name 'all-via-main'
 #	option enabled '1'
@@ -83,11 +105,16 @@ config inbound
 #	option type 'direct'
 #	option dpi 'fragment'
 #
+#config ruleset
+#	option name 'youtube'
+#	option source 'geosite'
+#	list category 'youtube'
+#
 #config rule
 #	option name 'youtube-fragment'
 #	option enabled '1'
 #	option order '50'
-#	list dst_domain 'geosite:youtube'
+#	list dst_ruleset 'youtube'
 #	option target 'egress:frag'
 #
 # A DNS resolver (type: doh|dot|plain|local|fakeip). `detour` routes its queries

openwrt/shater-core/files/etc/init.d/shater

@@ -47,6 +47,13 @@ PROG=/usr/bin/shaterd
 # hotplug/shater-cron touch the data plane. tmpfs => cleared by reboot, so
 # nothing reconciles before this init has run at boot.
 ACTIVE_FLAG=/var/run/shater.active
+# Written by `shaterd run`; the single-owner token this init waits on so a
+# restart never overlaps a new data plane with the previous one's teardown.
+PIDFILE=/var/run/shaterd.pid
+# Seconds `start` will wait for a predecessor to finish its teardown. Must be
+# >= term_timeout below (procd's hard cap on a predecessor's life after SIGTERM)
+# so we never give up while procd is still letting it shut down cleanly.
+STOP_WAIT_SECS=40
 
 # --- helpers ---------------------------------------------------------------
 
@@ -66,6 +73,54 @@ _slog() {
 	[ "$(uci -q get shater.globals.log_syslog)" = "0" ] || logger -t shater "$@"
 }
 
+# Echo the pid of a LIVE `shaterd run`, or fail. The pidfile is written by the
+# daemon itself and removed only by the daemon that owns it, AFTER its teardown
+# has completed — so "pidfile names a live process" is precisely "the previous
+# data plane has not been dismantled yet".
+shater_daemon_pid() {
+	local pid
+	pid=$(cat "$PIDFILE" 2>/dev/null) || return 1
+	[ -n "$pid" ] || return 1
+	kill -0 "$pid" 2>/dev/null || return 1
+	echo "$pid"
+}
+
+# Block until no predecessor daemon is left, bounded by STOP_WAIT_SECS.
+#
+# WHY THIS EXISTS. procd's `stop` is ASYNCHRONOUS: rc.common's `restart` is
+# literally `stop; start`, and the `service delete` ubus call returns the moment
+# procd has SENT SIGTERM — not when the instance is gone. `start` therefore
+# re-adds the instance while the outgoing `shaterd run` is still executing its
+# honest teardown (engine close, then `nft delete table`, `ip rule`/`ip route`
+# removal and the per-iface sysctl restore). The result is that `restart` is NOT
+# equivalent to `stop` + pause + `start`: the new plane is stood up on top of
+# kernel state the old one has not finished removing, which is what B3 (DNS to
+# the router's own LAN address dead after a restart, and never recovering) came
+# out of. Waiting here restores the equivalence, and costs literally nothing when
+# there is no predecessor — the check runs before the first sleep.
+#
+# Returning non-zero does NOT abort the start: the daemon carries its own
+# single-owner guard and will refuse (or wait) on its side. Better to hand the
+# decision to the process that can actually see the plane than to leave the box
+# with no service at all.
+shater_wait_stopped() {
+	local i=0 pid
+	pid=$(shater_daemon_pid) || return 0
+	_slog -p daemon.info \
+		"restart: waiting for the previous shaterd (pid $pid) to finish tearing the data plane down"
+	while [ "$i" -lt "$STOP_WAIT_SECS" ]; do
+		sleep 1
+		i=$((i + 1))
+		shater_daemon_pid >/dev/null || {
+			_slog -p daemon.info "restart: previous shaterd exited after ${i}s; starting a fresh one"
+			return 0
+		}
+	done
+	_slog -p daemon.warn \
+		"restart: previous shaterd (pid $pid) still alive after ${STOP_WAIT_SECS}s — starting anyway"
+	return 1
+}
+
 # --- procd lifecycle -------------------------------------------------------
 
 start_service() {
@@ -87,9 +142,31 @@ start_service() {
 		return 0
 	fi
 
+	# Do not stand a new data plane up on top of one that is still being taken
+	# down. On `restart` procd has only just SIGTERMed the previous instance and
+	# returned; this is the handshake that makes `restart` == `stop` + pause +
+	# `start`. It also keeps `migrate` below from rewriting UCI underneath a
+	# daemon that is still reading it. No-op (and no delay) when nothing is
+	# running, which is the boot case.
+	shater_wait_stopped
+
 	# Bring the UCI schema forward before the daemon reads it (idempotent;
 	# refuses a newer schema) so an upgraded package never applies a stale config.
-	"$PROG" migrate >/dev/null 2>&1
+	#
+	# THE FAILURE IS LOGGED, NOT SWALLOWED. This is the only place the schema
+	# migration runs at boot (`shaterd run`, the SIGHUP reconcile and the panel's
+	# config write all read UCI directly), so if it fails here it does not get
+	# retried until the next start. And it CAN fail for a mundane reason — a full
+	# /overlay makes `uci commit` fail — after which the config still carries the
+	# schema-v1 `dst_domain`/`dst_ip` options. The daemon holds every rule that
+	# still has them DISABLED and reports it, so nothing is silently misrouted, but
+	# rules the operator wrote are then not in force and the reason has to be
+	# visible somewhere. Hence: log the binary's own stderr, and start anyway —
+	# refusing to start would take the admin panel down with it, and the panel is
+	# the only way to fix the box.
+	local migrate_out
+	migrate_out=$("$PROG" migrate 2>&1) || _slog -p daemon.err \
+		"UCI schema migration FAILED: ${migrate_out:-no output from $PROG migrate}. Starting anyway; routing rules that still carry the removed dst_domain/dst_ip options stay DISABLED until this succeeds. Free space on /overlay and re-run '$PROG migrate', or restart the service."
 
 	procd_open_instance shater
 	# shaterd runs in the FOREGROUND under procd (must never daemonize). `run` is
@@ -111,7 +188,16 @@ start_service() {
 	procd_set_param stderr 1
 	# Give the daemon room to run its honest teardown (engine.Close + netplane
 	# restore) before procd SIGKILLs it.
-	procd_set_param term_timeout 10
+	#
+	# 30s, not 10s: an engine holding a few hundred outbounds closes its
+	# urltest/observatory goroutines and flushes experimental.cache_file to FLASH
+	# before the netplane teardown even starts, and on eMMC/NAND that alone can
+	# outlast 10s. A SIGKILL there aborts the teardown at an arbitrary point and
+	# leaves the plane HALF removed — the nft table gone but the policy routing
+	# still installed, or vice versa — which is precisely the class of leftover
+	# state the successor's idempotent fast-path cannot see and never repairs.
+	# Shutdown is bounded by procd either way; we are only choosing where.
+	procd_set_param term_timeout 30
 	procd_close_instance
 
 	# Mark the stack live for hotplug/cron — but ONLY when interception is
@@ -141,10 +227,12 @@ stop_service() {
 reload_service() {
 	# Fired by the `shater` config.change reload-trigger (LuCI Save & Apply /
 	# reload_config). Simplest correct behaviour: stop + start. `stop` clears the
-	# flag and SIGTERMs the daemon (honest teardown); `start` re-guards on
-	# enabled and, if still enabled, launches a fresh `shaterd run` that reads
-	# the new UCI and applies it. When the stack is disabled, `start` is a no-op,
-	# so a disable+apply cleanly tears everything down.
+	# flag and SIGTERMs the daemon (honest teardown); `start` WAITS for that
+	# teardown to actually finish (shater_wait_stopped) and then launches a fresh
+	# `shaterd run` that reads the new UCI and applies it. When the stack is
+	# disabled, `start` is a no-op, so a disable+apply cleanly tears everything
+	# down. Because the wait lives in start_service, this path gets the same
+	# stop-then-start ordering guarantee as `restart`.
 	stop
 	start
 }

openwrt/shaterd/Makefile

@@ -34,8 +34,17 @@
 include $(TOPDIR)/rules.mk
 
 PKG_NAME:=shaterd
-PKG_VERSION:=0.2.0
-PKG_RELEASE:=3
+
+# VERSIONING — derived from the git tag, NOT hand-maintained here (bug B4).
+# ci/version.sh turns `git describe` into SHATER_PKG_VERSION/SHATER_PKG_RELEASE
+# (tag vX.Y.Z -> X.Y.Z + r1; off-tag -> last tag + r<commits+1>), and
+# ci/build-feed-apk.sh exports them into the SDK build env. ci/sdk-build-apk.sh
+# then ASSERTS that the produced .apk really carries that version, so a lost env
+# can never silently ship a stale one again.
+# The literals below are ONLY the manual/offline fallback (no CI, no git) — they
+# are not "the release version"; releases are named by the tag.
+PKG_VERSION:=$(if $(SHATER_PKG_VERSION),$(SHATER_PKG_VERSION),0.2.0)
+PKG_RELEASE:=$(if $(SHATER_PKG_RELEASE),$(SHATER_PKG_RELEASE),1)
 
 PKG_MAINTAINER:=Shater <maqrota@icloud.com>
 PKG_LICENSE:=GPL-3.0-or-later
@@ -95,8 +104,8 @@ define Package/shaterd/install
 	$(INSTALL_BIN) $(CURDIR)/files/$(SHATERD_BIN) $(1)/usr/bin/shaterd
 endef
 
-# This package ships ONLY the binary — no init script — so opkg's default
-# postinst never touches the running service. On `opkg upgrade shaterd` the new
+# This package ships ONLY the binary — no init script — so the package manager's
+# postinst never touches the running service. On `apk upgrade shaterd` the new
 # ELF lands at /usr/bin/shaterd while the OLD image keeps running from its
 # unlinked inode: the upgrade silently has no effect until the next reboot, and
 # meanwhile the new CLI (`shaterd reconcile`, `status`, `mint-token` — invoked by

option/group.go

@@ -18,6 +18,32 @@ type URLTestOutboundOptions struct {
 	// lx: SPEC 019 v2 — load-balancing.
 	Mode     string                  `json:"mode,omitempty"` // least_test (default) | round_robin
 	Balancer *URLTestBalancerOptions `json:"balancer,omitempty"`
+	// lx: health board §5.C — SelfCheck stands the group's OWN background
+	// health-check up or down. nil/absent == true, so every existing config keeps
+	// today's behaviour.
+	//
+	// Why this exists at all: a urltest group probes its members BY ITSELF — a
+	// warm-up sweep at PostStart and a ticker for as long as traffic keeps
+	// touching it — and it dials the members' outbounds DIRECTLY, from the
+	// router, over whatever the default WAN route is. For a group that traffic
+	// actually flows through, that is exactly right: the probe travels the same
+	// path the connections do. But for a group NO routing rule reaches, that
+	// same probe measures a path nothing uses — and it stores the result under
+	// the members' BASE tags, which every health consumer then reads as "the
+	// node's health". A node that is blocked on the direct WAN and perfectly
+	// alive behind a tunnel therefore reads "dead" the moment such a group
+	// probes it; the reading is not merely stale, it is FALSE, and it poisons
+	// the shared board for everyone (selection, the panel, the observatory's
+	// freshness gate). SelfCheck=false is how the control plane stands such a
+	// group's own schedule down: the shater engine computes which groups the
+	// applied rules actually reach (the observatory's used-set) and disables
+	// the self-check on the rest, so the ONLY prober left is the observatory —
+	// which probes along the real dial paths and nothing else.
+	//
+	// The flag suppresses only the group's own SCHEDULE (the PostStart warm-up
+	// and the Touch ticker). An EXPLICIT CheckOutbounds/URLTest call — the
+	// adapter interface a human or an API invokes on purpose — still works.
+	SelfCheck *bool `json:"self_check,omitempty"`
 }
 
 // URLTestBalancerOptions configures round_robin: a fixed-size pool of live nodes, lazily

panel/package.json

@@ -8,7 +8,8 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "preview": "vite preview",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --test src/*.test.ts"
   },
   "dependencies": {
     "react": "^18.3.1",

panel/src/App.css

@@ -405,3 +405,73 @@
   color: var(--dim);
   max-width: 74ch;
 }
+
+/* ---- inline rename (shared) ----
+   The pencil-in-the-row interaction: click the ✎ beside a name, type over it,
+   Enter commits / Esc cancels / blur commits. Lifted out of Devices.css when
+   Nodes grew the same affordance — one interaction, one set of rules, so the two
+   pages can never drift apart. `--locked` is the same control with the action
+   withheld: it stays visible and focusable-looking so a missing rename reads as
+   a stated rule, not a dead button. */
+.inline-rename {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: 5px;
+  background: none;
+  color: var(--faint);
+  font-size: 12px;
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.15s, background 0.15s, border-color 0.15s;
+}
+.inline-rename:hover:not(:disabled) {
+  color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+}
+.inline-rename:focus-visible {
+  color: var(--accent);
+  border-color: var(--accent);
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+.inline-rename:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+/* Withheld, not broken: keep the glyph readable and let the cursor say "there is
+   a reason" rather than dimming it into invisibility. */
+.inline-rename--locked {
+  opacity: 0.75;
+  cursor: help;
+}
+.inline-rename--locked:hover {
+  color: var(--dim);
+  background: none;
+}
+
+.inline-rename-input {
+  min-width: 0;
+  max-width: 24ch;
+  padding: 4px 8px;
+  border: 1px solid var(--accent);
+  border-radius: 6px;
+  background: var(--sink);
+  color: var(--ink);
+  font-size: 13px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  box-shadow: 0 1px 2px var(--shadow) inset;
+}
+.inline-rename-input:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+.inline-rename-input:disabled {
+  opacity: 0.55;
+}

panel/src/api.ts

@@ -51,6 +51,38 @@ export class ApiError extends Error {
  */
 export type Plane = 'full' | 'hold' | 'none'
 
+/**
+ * Where the router's traffic actually ENDS UP, decided by the daemon from the
+ * engine config it is running (apply.Status.traffic ← generate.TrafficOf).
+ *
+ *   tunnel  — the default route goes into a tunnel: everything not matched by a
+ *             more specific rule is proxied.
+ *   split   — the default leaves directly, but some rules do tunnel their traffic.
+ *   direct  — the default leaves directly and nothing is tunnelled at all.
+ *   blocked — the default is the fail-closed backstop: unmatched traffic is
+ *             dropped, not let out. Nothing leaks.
+ *
+ * `plane` DOES NOT ANSWER THIS and must never be read as if it did. `plane` says
+ * how much of the data plane is installed (nft table, policy routing, engine up);
+ * a router whose only rule is `default → direct` has all of it and sends the whole
+ * LAN out the plain WAN with its real address. That combination — plane "full",
+ * traffic "direct" — was live on a user's router under a green "Protected" LED.
+ */
+export type TrafficVerdict = 'tunnel' | 'split' | 'direct' | 'blocked'
+
+export interface Traffic {
+  // '' or absent ⇒ not known (daemon that predates this field, nothing applied
+  // yet, or the plane is on hold). NEVER treat unknown as 'tunnel'.
+  verdict?: TrafficVerdict | ''
+  // The outbound tag the engine's default route names, in the engine's own
+  // vocabulary ("direct", "block", a node/group tag). Diagnostic — wording is
+  // driven by `verdict`, never by parsing this.
+  default?: string
+  // How many of the engine's route rules send their matched traffic into a tunnel.
+  // Separates "some of your traffic is protected" from "none of it is".
+  tunnel_rules?: number
+}
+
 /**
  * One thing the last apply could not do. Deliberately fail-OPEN with a warning
  * rather than refusing the whole config (the alternative was taking the network
@@ -88,6 +120,10 @@ export interface Status {
   // How much of the data plane is installed. Absent on older daemons ⇒ unknown,
   // in which case the UI shows nothing rather than guessing "full".
   plane?: Plane
+  // Where the traffic actually goes under the running config. Absent on older
+  // daemons ⇒ unknown; see TrafficVerdict for why this is a separate question
+  // from `plane`.
+  traffic?: Traffic
   // Findings from the last apply. ALWAYS an array from the daemon (never null);
   // empty means the last apply was clean. Pre-sorted critical-first and capped at
   // 50, where a truncated list ends with an `info` entry saying "suppressed".
@@ -354,19 +390,142 @@ export interface GroupHealth {
  * any more and nothing to report here beyond the groups themselves.
  */
 
+/**
+ * One hop of one chain, measured where that hop actually sits in the path.
+ *
+ * This is the reading the daemon always took and never showed. A chain is not a
+ * target with a single health — it is an ordered series of them, and the only
+ * question an operator ever asks about a broken chain is WHICH hop broke. The
+ * end-to-end exit reading cannot answer that: it says "the path is dead" for a
+ * four-hop chain and leaves the person to guess between four suspects.
+ *
+ * WIRE ORDER. `index` is 1-based and counts hops in the order the router dials
+ * them: hop 1 is the first physical hop, and each later hop is dialled THROUGH
+ * the ones before it. The hop carrying `exit: true` — always the largest index —
+ * is where traffic leaves for the internet. A leading `egress:` in the chain's
+ * configured Hops is NOT a numbered hop: the daemon lifts it into the entry
+ * detour of hop 1, so a chain written `egress:ewan → node:awgout → group:sub0`
+ * reports two hops, not three. Anything zipping this against the model's Hops
+ * must drop that leading egress first and give up on labelling entirely if the
+ * counts still disagree — a chain that splices sub-chains gets flattened here,
+ * and a confidently WRONG hop name is worse than no name.
+ *
+ * `tag` is the engine-side outbound (`chain-<name>-h2`). Debugging and tooltips
+ * only; it is never a label to put in front of a person.
+ *
+ * ORDERED WALK — THE READING STOPS AT THE FIRST DEAD HOP. Hops are NOT measured
+ * independently, and never were measurable that way: hop 3 is dialled THROUGH
+ * hop 2, so probing hop 3 while hop 2 is down measures hop 2 a second time and
+ * learns nothing about hop 3. The daemon therefore walks the path in wire order
+ * and stops at the first hop that does not answer. Every hop below that one is
+ * left undialled and reported `state: "untested"` — no measurement exists —
+ * carrying {@link ChainHopBlock} in `blocked_by` to name the hop that stopped the
+ * walk. So a chain never reports a dead hop with a live hop below it; that shape
+ * is not a rare case, it is unreachable.
+ *
+ * NODE HOP vs GROUP HOP. For `kind: "node"` the hop IS the measurement: `total`
+ * is 1, the counters follow its own state, and `selected` is ''. For
+ * `kind: "group"` the counters roll up that hop's per-hop member COPIES — the
+ * copies dialled through the hops in front of it, which is exactly why they can
+ * read alive here while the same group's standalone card reads dead. Both
+ * readings are true; they measure different dial paths. `selected` is the node
+ * NAME the hop routes through right now, and `delay_ms` / `age_seconds` belong
+ * to that selected member (or the freshest alive one).
+ *
+ * Invariants the daemon guarantees — never re-derive them, just read them:
+ * `tested === alive + dead` and `alive + dead + untested === total`.
+ *
+ * `state` is a closed set of THREE. `untested` is NEVER "dead" and never
+ * "healthy": it means nothing fresh enough is known. Without `blocked_by` that is
+ * a matter of timing — for a used chain it resolves on its own within seconds.
+ * With `blocked_by` it will not resolve until the named hop is fixed. There is no
+ * fourth state for that; the state stays `untested` because that is what it is.
+ * `age_seconds: -1` means the age is unknown.
+ */
+export interface ChainHopHealth {
+  /** 1-based WIRE order. Hop 1 is dialled first; see the note above. */
+  index: number
+  /** Engine outbound tag (`chain-<name>-h2`) — tooltips/debugging, never a label. */
+  tag: string
+  /** `node` ⇒ the hop is the measurement. `group` ⇒ the counters roll up members. */
+  kind: 'node' | 'group'
+  /** This hop is where traffic leaves for the internet. Always the largest index. */
+  exit: boolean
+  /** Closed set — switch on it exhaustively. `untested` is never "dead". */
+  state: 'alive' | 'dead' | 'untested'
+  /** RTT of the selected/freshest alive member; 0 (meaningless) when not alive. */
+  delay_ms: number
+  /** Age of that measurement in seconds; -1 when unknown. */
+  age_seconds: number
+  /** Node name this GROUP hop routes through right now; '' for a node hop. */
+  selected: string
+  total: number
+  tested: number
+  alive: number
+  dead: number
+  untested: number
+  /**
+   * PRESENT ONLY on a hop the ordered walk never reached — i.e. a hop sitting
+   * below one the prober found `dead`. The key is omitted otherwise; absent is
+   * the normal case and means "this hop was actually dialled".
+   *
+   * Its presence is the daemon's own statement that this hop has NO measurement,
+   * and it comes with the rest of that statement already filled in: `state` is
+   * `untested`, `delay_ms` is 0, `age_seconds` is -1, and the counters are
+   * `alive: 0, dead: 0, tested: 0, untested: total`. Read those; do not re-derive
+   * a verdict from them, and do not infer a block from zeroed counters either —
+   * an unprobed-yet hop has the same numbers and a very different meaning.
+   * `selected` MAY still be non-empty: the wrapper does have a pick, it simply
+   * was not measured, so it says which node the hop would use, not which node is
+   * carrying traffic.
+   */
+  blocked_by?: ChainHopBlock
+}
+
+/**
+ * The hop that stopped the ordered walk, as reported on every hop below it.
+ *
+ * This exists because "no reading" and "no reading, and here is whose fault that
+ * is" are different answers to the operator's actual question. Without it a
+ * blocked hop is indistinguishable from one the observatory has not come round to
+ * yet, and the interface can only shrug.
+ *
+ * `index` is the 1-based WIRE index of the blocking hop and is ALWAYS smaller
+ * than the index of the hop carrying it, so it points at a hop already on screen.
+ * `tag` is that hop's engine outbound (`chain-<name>-h3`) — debugging and
+ * tooltips only, never a label to put in front of a person, exactly as on
+ * {@link ChainHopHealth}.tag.
+ */
+export interface ChainHopBlock {
+  /** 1-based wire index of the hop that did not answer. Always < this hop's index. */
+  index: number
+  /** That hop's engine outbound tag — tooltips/debugging, never a label. */
+  tag: string
+}
+
 /** Per-chain reachability, the chain analogue of {@link GroupHealth}.used (plan
  *  §5.E): a chain no enabled routing rule routes through is outside the
- *  observatory's plan, so its exit is never probed and the Targets card renders it
- *  "unused" instead of an exit-test readout. A chain has no membership counters —
- *  it is a fixed path, and its end-to-end health is the exit test's job. */
+ *  observatory's plan, so nothing probes it and the Targets card says so instead
+ *  of rendering a health reading. A chain has no membership counters of its own —
+ *  it is a fixed path, and its health lives on its {@link ChainHopHealth} hops. */
 export interface ChainHealth {
   name: string
   /** An enabled routing rule (the Final target, a DNS-resolver detour, a device
-   *  target, …) reaches this chain, so the observatory probes its exit in the
+   *  target, …) reaches this chain, so the observatory probes its hops in the
    *  background. false ⇒ nothing routes through the chain: it is skipped by the
-   *  background probing and its end-to-end health stays untested. That is an
-   *  "unused" note about the ROUTING CONFIG, never a health problem. */
+   *  background probing and its health stays untested. That is an "unused" note
+   *  about the ROUTING CONFIG, never a health problem. */
   used: boolean
+  /**
+   * Per-hop health in wire order (see {@link ChainHopHealth}).
+   *
+   * MAY BE ABSENT, and absent does not mean "this chain has no hops". It means
+   * the engine never materialised per-hop outbounds for it: the chain is unused,
+   * or it collapses to a single hop and the daemon points traffic straight at
+   * that target instead of building a copy of it. Read a missing key as "nothing
+   * measured per hop", never as an empty path or as a fault.
+   */
+  hops?: ChainHopHealth[]
 }
 
 export interface GroupsHealth {
@@ -809,9 +968,17 @@ export interface Rule {
   Enabled: boolean
   Order: number
   Src?: string[] | null
-  DstDomain?: string[] | null
+  /**
+   * WHERE the traffic is going — the rule's only destination matcher. Each entry
+   * names a {@link Ruleset}; the rule matches when ANY of them matches.
+   *
+   * There is no inline domain or address list on a rule. `dst_domain`/`dst_ip`
+   * were removed in schema v2, and `shaterd migrate` folds every existing one
+   * into a generated `rule-<name>` ruleset, so a destination list is written and
+   * edited in exactly one place and compiled once into a .srs that every rule
+   * referencing it shares.
+   */
   DstRuleset?: string[] | null
-  DstIP?: string[] | null
   DstPort?: string
   /**
    * Narrow the rule to one transport or one sniffed application protocol. A
@@ -1187,6 +1354,61 @@ export function getStatsConns(q: number | StatsLogQuery = {}): Promise<ConnLogEn
   return MOCK ? mock.getStatsConns(o) : req<ConnLogEntry[]>(`api/stats/conns${statsLogQS(o)}`)
 }
 
+/**
+ * One routing rule's reachability verdict — the rule analogue of
+ * {@link ChainHealth}.used: a quiet note about the ROUTING CONFIG, never a health
+ * signal.
+ *
+ * `unreachable` means the rule can NEVER take effect, whatever the traffic. Today
+ * the daemon reports exactly one certain case, and it is a subtle one: a rule with
+ * no conditions at all is not matched in sequence — it becomes the router's
+ * default. Two such rules therefore retire each other, and the LAST one by Order
+ * wins, so an earlier "default → direct" is dead even though it sorts first. A
+ * condition-less rule never retires a rule that HAS conditions: those are matched
+ * ahead of the default whatever their Order.
+ *
+ * `index` is the rule's position in GET /api/config's `Rules`, which is how a
+ * verdict is matched to a row — rule names are not unique, and the config that
+ * prompted this had two rules both called `default`. `name`/`order` are echoed so
+ * a page holding a verdict fetched before an edit can check it still describes the
+ * row it is about to badge, and drop it silently otherwise.
+ */
+export interface RuleReach {
+  index: number
+  name: string
+  order: number
+  unreachable: boolean
+  /** The rule that supersedes this one; absent when `unreachable` is false. */
+  shadowed_by?: string
+  /** Its index in `Rules`, or -1 when there is none. */
+  shadowed_by_index: number
+  shadowed_by_order?: number
+  /** Operator-facing sentence; absent when `unreachable` is false. */
+  reason?: string
+  /**
+   * Whether the rule is IN FORCE right now — `Rule.Enabled` after the active WAN
+   * profile's overrides. This is NOT `GET /api/config`'s `Enabled`: that one is
+   * the desired state the page PUTs back, and on a router with profiles the two
+   * legitimately disagree. Draw rows from this; keep the switch on the other.
+   */
+  effective_enabled: boolean
+  /** The active profile that CHANGED this rule's state; absent when none did. */
+  overridden_by?: string
+  /** Which way it went. Absent together with `overridden_by`. */
+  override?: 'enabled' | 'disabled'
+}
+
+/** GET /api/rules/reachability. `rules` is ALWAYS an array, one entry per rule in
+ *  the same order as GET /api/config's `Rules`. */
+export interface RulesReachability {
+  rules: RuleReach[]
+}
+
+/** GET /api/rules/reachability — which routing rules can never fire, and why. */
+export function getRulesReachability(): Promise<RulesReachability> {
+  return MOCK ? mock.getRulesReachability() : req<RulesReachability>('api/rules/reachability')
+}
+
 /** GET /api/ruleset/status — remote rule-set / blocklist freshness + rule counts. */
 export function getRulesetStatus(): Promise<RulesetStatus[]> {
   return MOCK ? mock.getRulesetStatus() : req<RulesetStatus[]>('api/ruleset/status')
@@ -1333,8 +1555,21 @@ export function getGroupsHealth(
 }
 
 /**
- * One group's (or chain's) last test: which member the balancer picked, how fast
- * it answered, and what the internet saw as the source address.
+ * What the OBSERVATORY measured for one group or chain — not a dial the panel
+ * made.
+ *
+ * This shape used to come from a fresh connection opened on demand, straight at
+ * the target. That was a lie on any router whose proxies are blocked when dialled
+ * directly and work only as a hop behind a tunnel: the card reported dead for a
+ * path that carries traffic all day. The daemon now has exactly one thing that
+ * measures — the background observatory, which probes along the REAL dial path,
+ * per-hop copies and all — and this endpoint reports what it found. There is no
+ * second measurement anywhere, and the panel never opens a connection of its own.
+ *
+ * So read the fields as a READ, not as a test run: `ok` and `delay_ms` are the
+ * observatory's verdict for the path traffic actually takes, and `tested_unix`
+ * (router clock, seconds) is when the OBSERVATORY took that measurement — which
+ * can be a few seconds before the refresh was asked for.
  *
  * `ok:true` with an EMPTY `exit_ip`/`exit_country` is a valid, successful result,
  * not a partial failure: the delay was measured but the exit address could not be
@@ -1343,10 +1578,23 @@ export function getGroupsHealth(
  *
  * Chains ride the same endpoint. For a chain row, `group` carries the CHAIN's
  * name and `selected` the node its last group hop picked ('' when the exit hop
- * isn't a group). Everything else reads the same way.
+ * isn't a group). Per-hop detail is a different read: {@link ChainHopHealth}.
  *
- * `ok:false` ⇒ the test failed and `error` carries the human reason; every other
- * field is meaningless. `tested_unix` is the router's clock, in seconds.
+ * `ok:false` ⇒ there is no usable measurement and `error` carries the human
+ * reason; every other field is meaningless. Four of those reasons are about the
+ * observatory rather than the path, and must not be rendered as "your target is
+ * broken":
+ *
+ *   "not routed by any enabled rule, so nothing measures it — the observatory
+ *    only probes paths the rules use"
+ *   "the observatory has not reached this target yet — it refreshes on the
+ *    global probe interval"
+ *   "background probing is disabled, so there is nothing to measure this target
+ *    with"
+ *   "the observatory's probe through this path failed"
+ *
+ * Only the last one is a health finding. The first three say the measurement
+ * does not exist, which is a different thing and a different fix.
  */
 export interface GroupTestResult {
   group: string // group name — or a chain name for a chain row
@@ -1363,7 +1611,11 @@ export interface GroupTestResult {
  * GET /api/groups/test — progress plus every result so far. `results` is ALWAYS
  * an array (never null); `done`/`total` count finished vs targeted groups and
  * chains while `running` is true. Idle reads `{running:false}` with the last
- * run's results still attached, so a reload after a test still shows what it found.
+ * run's results still attached, so a reload still shows what was last read.
+ *
+ * "Running" means the observatory is working through an out-of-turn refresh pass
+ * over the named targets and this endpoint is collecting what it measures. It is
+ * not the panel dialling anything.
  */
 export interface GroupTestStatus {
   running: boolean
@@ -1396,10 +1648,16 @@ export interface GroupTestStart {
 }
 
 /**
- * POST /api/groups/test — measure a target's delay and exit address. Pass a
- * group or chain name to test one; pass nothing (or '') to test every group
- * and every chain. Singleton: a second call while a run is in flight resolves
- * to `{started:false, reason:'already running'}` rather than failing.
+ * POST /api/groups/test — ask the observatory for an out-of-turn refresh pass,
+ * then report what it measured. Pass a group or chain name to refresh one; pass
+ * nothing (or '') for every group and every chain.
+ *
+ * It does NOT dial. The observatory is the only thing in the daemon that
+ * measures anything, and it measures along the real dial path — so this is the
+ * "don't wait for the next probe interval" button, not a second opinion. The
+ * numbers it returns are the same numbers the cards are already showing, just
+ * fresher. Singleton: a second call while a pass is in flight resolves to
+ * `{started:false, reason:'already running'}` rather than failing.
  */
 export function postGroupsTest(name = ''): Promise<GroupTestStart> {
   return MOCK

panel/src/components/Button.css

@@ -1,4 +1,5 @@
-/* Buttons — mono, uppercase. .btn is ghost; .btn.primary is solid orange. */
+/* Buttons — mono, uppercase. .btn is ghost; .btn.primary is solid orange;
+ * .btn.crit is the solid-red destructive commit. */
 .btn {
   display: inline-block;
   padding: 7px 12px;
@@ -30,3 +31,16 @@
   color: #fff;
   filter: brightness(1.05);
 }
+
+/* Destructive commit. The fill is crit stepped a little toward black so white
+ * label text clears 4.5:1 in BOTH themes — the raw --crit is bright enough in
+ * dark mode to fall under it. Red here always means "this removes something". */
+.btn.crit {
+  border-color: transparent;
+  background: color-mix(in srgb, var(--crit) 88%, #000);
+  color: #fff;
+}
+.btn.crit:hover {
+  color: #fff;
+  filter: brightness(1.08);
+}

panel/src/components/Button.tsx

@@ -1,19 +1,27 @@
 import './Button.css'
+import { forwardRef } from 'react'
 import type { ButtonHTMLAttributes } from 'react'
 
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  /** `primary` is the solid-orange call to action; `ghost` is the default. */
-  variant?: 'ghost' | 'primary'
+  /**
+   * `primary` is the solid-orange call to action; `crit` is the solid-red
+   * destructive commit (delete, remove) — semantic crit, never the accent;
+   * `ghost` is the default.
+   */
+  variant?: 'ghost' | 'primary' | 'crit'
 }
 
-export function Button({ variant = 'ghost', className, type, ...rest }: ButtonProps) {
+/** Ref-forwarding so a dialog can park focus on a specific button. */
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  { variant = 'ghost', className, type, ...rest },
+  ref,
+) {
   return (
     <button
+      ref={ref}
       type={type ?? 'button'}
-      className={['btn', variant === 'primary' ? 'primary' : '', className]
-        .filter(Boolean)
-        .join(' ')}
+      className={['btn', variant === 'ghost' ? '' : variant, className].filter(Boolean).join(' ')}
       {...rest}
     />
   )
-}
+})

panel/src/components/ConfirmDialog.css

@@ -0,0 +1,162 @@
+/* <ConfirmDialog> — the safety interlock plate.
+ *
+ * This replaces the browser's native confirm dialog, which a browser can mute for
+ * good ("prevent this page from creating additional dialogs"): after that it
+ * returns false with no dialog at all, so every delete button in the panel goes
+ * dead and silent with no way to recover short of a page reload. We draw the
+ * plate ourselves, so nothing can suppress it.
+ *
+ * Faceplate language: a small rack module lifted off the panel — corner screws
+ * (reused from Faceplate.css), an engraved label, a groove above the actions.
+ * Destructive intent is carried by the crit semantic, never by the orange accent:
+ * accent means "this control is active", crit means "this destroys something".
+ */
+
+/* The veil is a fixed dark wash in both themes — a light scrim over a light
+ * panel would not read as "the panel is out of reach". Follows the tokens.css
+ * pattern: light base, dark via media query, data-theme overrides win both ways. */
+.cfm-scrim {
+  --cfm-veil: rgba(33, 29, 21, 0.52);
+}
+@media (prefers-color-scheme: dark) {
+  .cfm-scrim {
+    --cfm-veil: rgba(0, 0, 0, 0.66);
+  }
+}
+:root[data-theme='light'] .cfm-scrim {
+  --cfm-veil: rgba(33, 29, 21, 0.52);
+}
+:root[data-theme='dark'] .cfm-scrim {
+  --cfm-veil: rgba(0, 0, 0, 0.66);
+}
+
+.cfm-scrim {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Short viewports: the plate scrolls with the veil instead of being clipped. */
+  overflow-y: auto;
+  padding: calc(var(--u, 8px) * 2);
+  background: var(--cfm-veil);
+  animation: cfm-veil-in 0.14s ease-out;
+}
+
+.cfm-card {
+  position: relative;
+  width: min(32rem, 100%);
+  max-height: calc(100dvh - var(--u, 8px) * 4);
+  overflow-y: auto;
+  padding: calc(var(--u, 8px) * 3.25);
+  border: 1px solid var(--groove);
+  border-radius: 12px;
+  /* same brushed plate as <Faceplate>, one step brighter so it reads as lifted */
+  background:
+    repeating-linear-gradient(
+      90deg,
+      transparent 0 2px,
+      color-mix(in srgb, var(--edge) 30%, transparent) 2px 3px
+    ),
+    linear-gradient(180deg, var(--raised), color-mix(in srgb, var(--raised) 82%, var(--panel)));
+  box-shadow:
+    0 1px 0 var(--edge) inset,
+    0 30px 60px -22px var(--shadow),
+    0 4px 12px var(--shadow);
+  animation: cfm-card-in 0.18s cubic-bezier(0.2, 0.7, 0.3, 1);
+}
+.cfm-card:focus {
+  outline: none;
+}
+
+/* `still` is set from usePrefersReducedMotion — the plate appears, it never
+ * travels. (The global reduced-motion rule in tokens.css also neutralises the
+ * duration; this keeps the intent explicit at the component.) */
+.cfm-scrim.still,
+.cfm-scrim.still .cfm-card {
+  animation: none;
+}
+
+@keyframes cfm-veil-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+@keyframes cfm-card-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.99);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* ---- header: engraved label + state LED ---- */
+.cfm-hd {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: calc(var(--u, 8px) * 1.5);
+}
+.cfm-label {
+  flex: 1;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: var(--track-label-wide, 0.24em);
+  color: var(--dim);
+  text-transform: uppercase;
+}
+
+/* ---- copy ---- */
+.cfm-title {
+  margin: 0;
+  font-family: var(--font-mono);
+  font-weight: 700;
+  font-size: 17px;
+  line-height: 1.35;
+  color: var(--ink);
+  /* names can be long and unbroken — wrap rather than push the plate wide */
+  overflow-wrap: anywhere;
+}
+.cfm-body {
+  margin: calc(var(--u, 8px) * 1.5) 0 0;
+  max-width: 52ch;
+  font-family: var(--font-sans);
+  font-size: 13.5px;
+  line-height: 1.6;
+  color: var(--dim);
+  overflow-wrap: anywhere;
+}
+
+/* ---- action bar ---- */
+.cfm-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: calc(var(--u, 8px));
+  margin-top: calc(var(--u, 8px) * 3);
+  padding-top: calc(var(--u, 8px) * 2);
+  border-top: 1px solid var(--groove);
+}
+
+@media (max-width: 420px) {
+  .cfm-card {
+    padding: calc(var(--u, 8px) * 2.5);
+  }
+  .cfm-actions {
+    flex-wrap: wrap;
+  }
+  .cfm-actions .btn {
+    flex: 1 1 auto;
+    text-align: center;
+  }
+  /* screws crowd a small plate — drop them rather than collide with the copy */
+  .cfm-card > .screw {
+    display: none;
+  }
+}

panel/src/components/ConfirmDialog.tsx

@@ -0,0 +1,281 @@
+import './ConfirmDialog.css'
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { Button } from './Button'
+import { Led } from './Led'
+import { usePrefersReducedMotion } from './usePrefersReducedMotion'
+
+/**
+ * How the confirming button is painted.
+ *
+ *   crit    — the action destroys something. Semantic crit, never the accent.
+ *   neutral — the action is a normal commit the operator should read first
+ *             (a warning before saving); the accent's call-to-action is correct.
+ */
+export type ConfirmTone = 'crit' | 'neutral'
+
+export interface ConfirmOptions {
+  /** Engraved eyebrow, e.g. "DELETE RULE". Names the operation, not the object. */
+  label?: string
+  /** The question. One line, ends in "?". */
+  title: string
+  /** The consequence — what changes on the router if this goes through. */
+  body?: ReactNode
+  /** Verb on the confirming button. Defaults to "Delete". */
+  confirmLabel?: string
+  /** Verb on the dismissing button. Defaults to "Cancel". */
+  cancelLabel?: string
+  /** Defaults to `crit` — the overwhelmingly common case is a delete. */
+  tone?: ConfirmTone
+}
+
+export interface ConfirmDialogProps extends ConfirmOptions {
+  open: boolean
+  /** Called exactly once per dialog, with the operator's answer. */
+  onResolve: (confirmed: boolean) => void
+}
+
+const FOCUSABLE =
+  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * The modal plate itself. Normally reached through `useConfirm()`; exported so a
+ * page that wants to own the open state can render it directly.
+ *
+ * Keyboard contract:
+ *   - focus moves to Cancel on open, so a reflex Enter dismisses, never deletes;
+ *   - Tab / Shift+Tab cycle inside the plate and cannot reach the page behind it;
+ *   - Esc answers "no";
+ *   - on close, focus returns to whatever opened the dialog.
+ */
+export function ConfirmDialog({
+  open,
+  onResolve,
+  label,
+  title,
+  body,
+  confirmLabel = 'Delete',
+  cancelLabel = 'Cancel',
+  tone = 'crit',
+}: ConfirmDialogProps) {
+  const titleId = useId()
+  const bodyId = useId()
+  const cardRef = useRef<HTMLDivElement>(null)
+  const cancelRef = useRef<HTMLButtonElement>(null)
+  const openerRef = useRef<HTMLElement | null>(null)
+  const reduced = usePrefersReducedMotion()
+
+  // Take the page out of the tab order, park focus on Cancel, and hand focus
+  // back to the opener when the plate goes away.
+  useEffect(() => {
+    if (!open) return
+    const opener = document.activeElement
+    openerRef.current = opener instanceof HTMLElement ? opener : null
+
+    const prevOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+
+    // Cancel is the resting place: an Enter or a Space meant for the page lands
+    // on "no". The destructive button is one Tab away, deliberately.
+    ;(cancelRef.current ?? cardRef.current)?.focus()
+
+    return () => {
+      document.body.style.overflow = prevOverflow
+      const back = openerRef.current
+      openerRef.current = null
+      if (back && document.contains(back)) back.focus()
+    }
+  }, [open])
+
+  // Esc answers no; Tab is caged. Capture phase so a page-level key handler
+  // never sees keys aimed at the dialog.
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        e.stopPropagation()
+        onResolve(false)
+        return
+      }
+      if (e.key !== 'Tab') return
+      const card = cardRef.current
+      if (!card) return
+      const list = Array.from(card.querySelectorAll<HTMLElement>(FOCUSABLE))
+      if (list.length === 0) {
+        e.preventDefault()
+        card.focus()
+        return
+      }
+      const first = list[0]
+      const last = list[list.length - 1]
+      const active = document.activeElement as HTMLElement | null
+      if (!active || !card.contains(active)) {
+        e.preventDefault()
+        ;(e.shiftKey ? last : first).focus()
+      } else if (e.shiftKey && active === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    document.addEventListener('keydown', onKey, true)
+    return () => document.removeEventListener('keydown', onKey, true)
+  }, [open, onResolve])
+
+  if (!open) return null
+
+  return createPortal(
+    <div
+      className={['cfm-scrim', reduced ? 'still' : ''].filter(Boolean).join(' ')}
+      // A click on the field around the plate means "not now". Mousedown (not
+      // click) so a text selection dragged out of the plate can't dismiss it.
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onResolve(false)
+      }}
+    >
+      <div
+        className={`cfm-card tone-${tone}`}
+        ref={cardRef}
+        tabIndex={-1}
+        role="alertdialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        aria-describedby={body != null ? bodyId : undefined}
+      >
+        <i className="screw tl" aria-hidden="true" />
+        <i className="screw tr" aria-hidden="true" />
+        <i className="screw bl" aria-hidden="true" />
+        <i className="screw br" aria-hidden="true" />
+
+        {/* Lamp first, then the engraved label — the way a real panel reads, and
+            it keeps the LED off the corner screw. */}
+        <div className="cfm-hd">
+          <Led variant={tone === 'crit' ? 'crit' : 'amber'} />
+          <span className="cfm-label">{label ?? (tone === 'crit' ? 'Confirm delete' : 'Confirm')}</span>
+        </div>
+
+        <h2 className="cfm-title" id={titleId}>
+          {title}
+        </h2>
+        {body != null && (
+          <p className="cfm-body" id={bodyId}>
+            {body}
+          </p>
+        )}
+
+        <div className="cfm-actions">
+          <Button ref={cancelRef} onClick={() => onResolve(false)}>
+            {cancelLabel}
+          </Button>
+          <Button variant={tone === 'crit' ? 'crit' : 'primary'} onClick={() => onResolve(true)}>
+            {confirmLabel}
+          </Button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}
+
+// ---- provider + hook --------------------------------------------------------
+
+interface Request extends ConfirmOptions {
+  id: number
+  resolve: (v: boolean) => void
+}
+
+const ConfirmCtx = createContext<((o: ConfirmOptions) => Promise<boolean>) | null>(null)
+
+/**
+ * Mount once at the app root. Everything below can then ask a question and await
+ * the answer.
+ */
+export function ConfirmProvider({ children }: { children: ReactNode }) {
+  const [req, setReq] = useState<Request | null>(null)
+  const pending = useRef<Request | null>(null)
+  const seq = useRef(0)
+
+  const confirm = useCallback(
+    (opts: ConfirmOptions) =>
+      new Promise<boolean>((resolve) => {
+        // A second question while one is open answers the first with "no" rather
+        // than leaving its promise — and its caller — hanging forever.
+        pending.current?.resolve(false)
+        seq.current += 1
+        const next: Request = { ...opts, id: seq.current, resolve }
+        pending.current = next
+        setReq(next)
+      }),
+    [],
+  )
+
+  const settle = useCallback((confirmed: boolean) => {
+    const open = pending.current
+    pending.current = null
+    setReq(null)
+    open?.resolve(confirmed)
+  }, [])
+
+  // Teardown must not strand a caller mid-await.
+  useEffect(
+    () => () => {
+      pending.current?.resolve(false)
+      pending.current = null
+    },
+    [],
+  )
+
+  // A question belongs to the page that asked it. The provider outlives the
+  // hash router, so a navigation would otherwise leave a stale plate floating
+  // over a page it has nothing to do with — answer it "no" and clear it.
+  useEffect(() => {
+    const onNav = () => {
+      if (pending.current) settle(false)
+    }
+    window.addEventListener('hashchange', onNav)
+    return () => window.removeEventListener('hashchange', onNav)
+  }, [settle])
+
+  return (
+    <ConfirmCtx.Provider value={confirm}>
+      {children}
+      {req !== null && <ConfirmDialog key={req.id} open onResolve={settle} {...req} />}
+    </ConfirmCtx.Provider>
+  )
+}
+
+/**
+ * Ask the operator, get a definite answer:
+ *
+ *   const confirm = useConfirm()
+ *   if (!(await confirm({ title: 'Delete rule "x"?', body: '…' }))) return
+ *
+ * The returned function is stable, so it is safe in a useCallback dep list. It
+ * always settles — cancel, Esc, click-outside and teardown all resolve `false`;
+ * only the confirming button resolves `true`.
+ *
+ * Name it `confirm` at the call site on purpose: the local binding shadows the
+ * global one inside that component, so an accidental bare `confirm(...)` cannot
+ * reach the suppressible native dialog.
+ */
+export function useConfirm(): (o: ConfirmOptions) => Promise<boolean> {
+  const ctx = useContext(ConfirmCtx)
+  if (!ctx) {
+    // Loud on purpose. A fallback that quietly resolved false would rebuild the
+    // exact bug this component exists to kill.
+    throw new Error('useConfirm() needs <ConfirmProvider> above it (mounted in main.tsx)')
+  }
+  return ctx
+}

panel/src/components/index.ts

@@ -17,6 +17,8 @@ export { Button } from './Button'
 export type { ButtonProps } from './Button'
 export { Select } from './Select'
 export type { SelectProps, SelectOption } from './Select'
+export { ConfirmDialog, ConfirmProvider, useConfirm } from './ConfirmDialog'
+export type { ConfirmDialogProps, ConfirmOptions, ConfirmTone } from './ConfirmDialog'
 export { Clock } from './Clock'
 export { CatSuggest } from './CatSuggest'
 export { SrcPicker } from './SrcPicker'

panel/src/main.tsx

@@ -2,12 +2,17 @@ import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import './tokens.css'
 import { App } from './App'
+import { ConfirmProvider } from './components'
 
 const rootEl = document.getElementById('root')
 if (!rootEl) throw new Error('#root not found')
 
+// ConfirmProvider sits ABOVE <App> so it survives App's early returns (the
+// unauth / no-link plates) — useConfirm() can never find itself without a host.
 createRoot(rootEl).render(
   <StrictMode>
-    <App />
+    <ConfirmProvider>
+      <App />
+    </ConfirmProvider>
   </StrictMode>,
 )

panel/src/mock.ts

@@ -6,7 +6,7 @@
 // state mutates in-memory so the Apply / Confirm / Rollback flow is exercisable.
 //
 // Type-only imports from api.ts (erased at build) keep this free of a runtime cycle.
-import type { ApplyResult, ChainHealth, ConnLogEntry, DiscoveredDevice, GroupHealth, GroupMemberHealth, GroupsHealth, GroupTestResult, GroupTestStart, GroupTestStatus, Interface, Model, QueryLogEntry, RulesetCategories, RulesetCheck, RulesetStatus, Stats, StatsLogPage, StatsLogQuery, Status, StatusWarning } from './api'
+import type { ApplyResult, ChainHealth, ChainHopHealth, ConnLogEntry, DiscoveredDevice, GroupHealth, GroupMemberHealth, GroupsHealth, GroupTestResult, GroupTestStart, GroupTestStatus, Interface, Model, Profile, QueryLogEntry, RuleReach, RulesReachability, RulesetCategories, RulesetCheck, RulesetStatus, Stats, StatsLogPage, StatsLogQuery, Status, StatusWarning, Traffic } from './api'
 
 let armed = false // a pending commit-confirm auto-rollback
 let hasLastGood = false // a predecessor config exists to roll back to (post-apply)
@@ -129,9 +129,25 @@ const CONFIG: Model = {
     { Name: 'via-tunnel', Source: 'subscription', Subscription: 'primary', Strategy: 'leastping', Egress: 'awg' },
     { Name: 'fallback', Source: 'subscription', Subscription: 'backup', Strategy: 'roundrobin', Egress: '' },
   ],
-  // One multi-hop chain so `?mock` exercises the chain card's Test button and
-  // its result readout: enters through the awg tunnel, exits via the auto group.
-  Chains: [{ Name: 'relay', Hops: ['egress:awg', 'group:auto'] }],
+  // Three chains, one per state the hop readout has to render.
+  Chains: [
+    // The owner's real production shape: leave through a WAN interface, cross an
+    // AmneziaWG node, then three subscription groups in series. The leading
+    // `egress:` is NOT a numbered hop — the daemon lifts it into hop 1's entry
+    // detour — so this reports FOUR hops, and hop 3 is dead while its neighbours
+    // answer. That single red notch in the middle of a live path is the entire
+    // reason per-hop health exists, so `?mock` must show it at a glance.
+    {
+      Name: 'ewan-wg-subs',
+      Hops: ['egress:wan', 'node:home-wg', 'group:auto', 'group:stealth', 'group:via-tunnel'],
+    },
+    // Used, but the observatory hasn't come round yet — every hop untested. Not
+    // dead and not healthy: the state the panel most easily renders as a fault.
+    { Name: 'sub-fresh', Hops: ['node:home-wg', 'group:fallback'] },
+    // No enabled rule targets it, so the observatory skips it entirely and the
+    // daemon never materialises its hops: `used:false` and NO `hops` key.
+    { Name: 'relay', Hops: ['egress:awg', 'group:auto'] },
+  ],
   Egresses: [
     { Name: 'wan', Type: 'interface', Interface: 'wan' },
     // An AmneziaWG tunnel — the whole point of a group-level egress binding.
@@ -145,7 +161,20 @@ const CONFIG: Model = {
   Rules: [
     { Name: 'block-ads', Enabled: true, Order: 10, DstRuleset: ['ad-hosts'], Target: 'block' },
     { Name: 'ru-bypass', Enabled: true, Order: 20, DstRuleset: ['ru-inside'], Target: 'direct' },
+    // These two are what make the chains USED — the observatory probes only the
+    // paths an enabled rule can reach, so without them every chain card would
+    // read "not routed" and the hop rail would never appear in `?mock`. Kept
+    // ABOVE the condition-less rule at Order 40, which would otherwise swallow
+    // everything below it and mark them "never applies".
+    { Name: 'media-via-chain', Enabled: true, Order: 22, DstRuleset: ['yt-geosite'], Target: 'chain:ewan-wg-subs' },
+    { Name: 'spare-via-chain', Enabled: true, Order: 24, DstRuleset: ['ad-hosts'], Target: 'chain:sub-fresh' },
     { Name: 'private-direct', Enabled: true, Order: 30, DstRuleset: ['private-nets'], Target: 'direct' },
+    // A SECOND condition-less rule, above the real default. It reads like a working
+    // rule and does nothing: a rule with no conditions becomes the router's default,
+    // and the last such rule by Order wins — so this one never applies. It is in the
+    // fixture on purpose, to exercise the "never applies" badge; the field config
+    // that prompted it had two rules BOTH named `default` (orders 20 and 100).
+    { Name: 'default-bypass', Enabled: true, Order: 40, Target: 'direct' },
     { Name: 'default-tunnel', Enabled: true, Order: 900, Target: 'group:auto' },
   ],
   // Named match-lists a rule points DstRuleset at. url + geosite + geoip are remote
@@ -296,6 +325,96 @@ const RULESET_STATUS: RulesetStatus[] = [
   { tag: 'rs-ru-geoip-ru', name: 'ru-geoip', category: 'ru', kind: 'ruleset', remote: true, last_updated: '', interval_seconds: 86_400, rule_count: 0 },
 ]
 
+/** GET /api/rules/reachability. Mirrors the daemon's analysis over CONFIG.Rules:
+ *  a rule with no conditions is the router's default, and the LAST such rule by
+ *  Order wins — every earlier one can never apply. It reads the live CONFIG so
+ *  edits made in `?mock` keep the badge honest.
+ *
+ *  It also mirrors model.ResolveActiveProfile + ApplyProfileRuleOverrides, because
+ *  `effective_enabled` is the whole point of the endpoint: CONFIG's `mobile-uplink`
+ *  is active and both enables and disables rules, so `?mock` shows the same
+ *  desired-vs-effective split the field config does. */
+export async function getRulesReachability(): Promise<RulesReachability> {
+  await wait(60)
+  const rules = CONFIG.Rules ?? []
+
+  // A pin naming an existing, ENABLED profile wins outright. Otherwise auto-select:
+  // highest Priority among enabled profiles, ties by Name, skipping any with an
+  // iface condition (the WAN watcher owns those and expresses its verdict as the pin).
+  const profiles = CONFIG.Profiles ?? []
+  const pinned = String(CONFIG.Globals?.ActiveProfile ?? '').trim()
+  let prof: Profile | null = profiles.find((p) => p.Enabled && p.Name === pinned) ?? null
+  if (!prof) {
+    for (const p of profiles) {
+      if (!p.Enabled || (p.MatchIface ?? []).length > 0) continue
+      const pp = p.Priority ?? 0
+      const bp = prof?.Priority ?? 0
+      if (!prof || pp > bp || (pp === bp && p.Name < prof.Name)) prof = p
+    }
+  }
+  // Enable first, then Disable, so a name in both ends up disabled (Disable wins).
+  const effective = rules.map((r) => Boolean(r.Enabled))
+  if (prof) {
+    const force = (names: string[] | null | undefined, on: boolean) => {
+      for (const raw of names ?? []) {
+        const n = raw.trim()
+        rules.forEach((r, i) => {
+          if (r.Name === n) effective[i] = on
+        })
+      }
+    }
+    force(prof.EnableRules, true)
+    force(prof.DisableRules, false)
+  }
+  const activeProfile = prof
+
+  const out: RuleReach[] = rules.map((r, index) => ({
+    index,
+    name: String(r.Name ?? ''),
+    order: Number(r.Order ?? 0),
+    unreachable: false,
+    shadowed_by_index: -1,
+    effective_enabled: effective[index],
+    // Annotate only where the profile actually FLIPPED the outcome — a profile that
+    // disables an already-off rule has overridden nothing the operator can see.
+    ...(activeProfile && effective[index] !== Boolean(r.Enabled)
+      ? {
+          overridden_by: activeProfile.Name,
+          override: effective[index] ? ('enabled' as const) : ('disabled' as const),
+        }
+      : {}),
+  }))
+  const conditionless = (r: (typeof rules)[number]): boolean =>
+    !(r.Src ?? []).length &&
+    !(r.DstRuleset ?? []).length &&
+    !String(r.DstPort ?? '').trim() &&
+    !String(r.Proto ?? '').trim()
+  const target = (r: (typeof rules)[number]): string =>
+    String(r.Target ?? '').trim() || (r.Egress ? `egress:${String(r.Egress).trim()}` : '')
+  const defaults = rules
+    .map((r, index) => ({ r, index }))
+    // The EFFECTIVE flag, not the configured one: a rule the active profile
+    // switched off is not in force and cannot retire anything (model's
+    // RuleReachability runs over the effective set for the same reason).
+    .filter(({ r, index }) => effective[index] && conditionless(r) && target(r))
+    .sort((a, b) => Number(a.r.Order ?? 0) - Number(b.r.Order ?? 0) || a.index - b.index)
+  const winner = defaults[defaults.length - 1]
+  if (winner) {
+    for (const { index } of defaults.slice(0, -1)) {
+      out[index].unreachable = true
+      out[index].shadowed_by = String(winner.r.Name ?? '')
+      out[index].shadowed_by_index = winner.index
+      out[index].shadowed_by_order = Number(winner.r.Order ?? 0)
+      out[index].reason =
+        `this rule has no conditions, so it sets the default for all traffic — but rule ` +
+        `"${winner.r.Name}" (order ${winner.r.Order}) has none either and comes after it, so ` +
+        `"${target(winner.r)}" is the default the router uses and this rule's target ` +
+        `"${target(rules[index])}" is never applied`
+    }
+  }
+  return { rules: out }
+}
+
 export async function getRulesetStatus(): Promise<RulesetStatus[]> {
   await wait(90)
   return RULESET_STATUS.map((r) => ({ ...r }))
@@ -357,6 +476,11 @@ export async function getRulesetCategories(source: string): Promise<RulesetCateg
 //   ?mock&warn=1     → a full warning set (critical + warning + info) on top
 //   ?mock&ks=open    → healthy plane but a FAIL-OPEN kill-switch, which is what
 //                      makes the untunnelable policy inert (F8 case 4)
+//   ?mock&traffic=…  → with the plane FULL, where the traffic actually ends up:
+//                      split | direct | blocked | blackout | unknown. `direct` is
+//                      the field case the readout used to call "Protected" (one
+//                      rule, `default → direct`); `unknown` is a daemon too old to
+//                      report. Default: tunnel.
 function mockPlane(): { plane: 'full' | 'hold' | 'none'; engine: boolean; killSwitch: string } {
   const q = typeof location === 'undefined' ? '' : location.search
   const params = new URLSearchParams(q)
@@ -368,6 +492,30 @@ function mockPlane(): { plane: 'full' | 'hold' | 'none'; engine: boolean; killSw
   return { plane: 'full', engine: true, killSwitch }
 }
 
+// The daemon's verdict on where traffic goes (apply.Status.traffic). Only
+// meaningful with the plane installed: with the engine down there is no running
+// config to judge, and the daemon reports the unknown/zero value — so do the same
+// here rather than leaving a stale "tunnel" behind a dead engine.
+function mockTraffic(plane: 'full' | 'hold' | 'none'): Traffic | undefined {
+  if (plane !== 'full') return { verdict: '', default: '', tunnel_rules: 0 }
+  const params = new URLSearchParams(typeof location === 'undefined' ? '' : location.search)
+  switch (params.get('traffic')) {
+    case 'split':
+      return { verdict: 'split', default: 'direct', tunnel_rules: 3 }
+    case 'direct':
+      return { verdict: 'direct', default: 'direct', tunnel_rules: 0 }
+    case 'blocked':
+      return { verdict: 'blocked', default: 'block', tunnel_rules: 2 }
+    case 'blackout':
+      return { verdict: 'blocked', default: 'block', tunnel_rules: 0 }
+    case 'unknown':
+      // A daemon that predates the field sends no `traffic` at all.
+      return undefined
+    default:
+      return { verdict: 'tunnel', default: 'auto', tunnel_rules: 1 }
+  }
+}
+
 const MOCK_WARNINGS: StatusWarning[] = [
   {
     severity: 'critical',
@@ -470,6 +618,7 @@ export async function getStatus(): Promise<Status> {
     can_rollback: armed || hasLastGood,
     engine_running: engine,
     plane,
+    traffic: mockTraffic(plane),
     warnings: mockWarnings(killSwitch),
     // Process uptime. Anchored to when this tab loaded plus a fixed head start, so
     // the reading ticks forward across polls exactly like the real daemon's does.
@@ -1046,20 +1195,59 @@ function healthList(): GroupHealth[] {
   return (CONFIG.Groups ?? []).map((g) => summarise(g.Name, GROUP_MEMBERS.get(g.Name) ?? []))
 }
 
-/** Per-chain reachability for the Targets page's "unused" badge (plan §5.E) — the
- *  chain analogue of healthList's `used` field. The mock's single chain `relay` is
- *  NOT referenced by any rule in CONFIG.Rules (they target group:auto / block /
- *  direct), so it reads used=false and its card renders "unused" — exactly the case
- *  the badge exists to surface. A stopped engine reports no chains. */
+/**
+ * Per-hop health, keyed by chain name — what the observatory measured at each
+ * position of the path, in WIRE order.
+ *
+ * `ewan-wg-subs` is the fixture that matters, and it encodes the ORDERED WALK.
+ * Hop 1 is the WireGuard node and answers; hop 2 is a subscription group whose
+ * copies answer THROUGH it — 119 of 122 tested alive, which is the reading only a
+ * per-hop probe can produce, since the same members are dialled differently on
+ * their own card. Hop 3 is a group whose members all time out at that position,
+ * and the walk STOPS there: hop 4 is dialled through hop 3, so it was never
+ * dialled at all. It comes back `untested` with `blocked_by` naming hop 3, its
+ * counters zeroed, and `selected` still set — the wrapper has a pick, nothing
+ * crossed it to measure. A dead hop with a live hop under it is not in this
+ * fixture because the daemon can no longer produce one.
+ *
+ * `sub-fresh` is used but never yet reached: every hop untested, nothing dead,
+ * no block — the other reason a lamp is unlit, and the one that fixes itself.
+ * `relay` is absent from this map on purpose — an unused chain is never
+ * materialised, so the daemon sends no `hops` key at all, which is "nothing
+ * measured", not "no hops".
+ */
+const CHAIN_HOPS: Record<string, ChainHopHealth[]> = {
+  'ewan-wg-subs': [
+    { index: 1, tag: 'chain-ewan-wg-subs-h1', kind: 'node', exit: false, state: 'alive', delay_ms: 41, age_seconds: 22, selected: '', total: 1, tested: 1, alive: 1, dead: 0, untested: 0 },
+    { index: 2, tag: 'chain-ewan-wg-subs-h2', kind: 'group', exit: false, state: 'alive', delay_ms: 96, age_seconds: 18, selected: '🇳🇱 Amsterdam-01', total: 298, tested: 122, alive: 119, dead: 3, untested: 176 },
+    { index: 3, tag: 'chain-ewan-wg-subs-h3', kind: 'group', exit: false, state: 'dead', delay_ms: 0, age_seconds: 15, selected: '', total: 2, tested: 2, alive: 0, dead: 2, untested: 0 },
+    { index: 4, tag: 'chain-ewan-wg-subs-h4', kind: 'group', exit: true, state: 'untested', delay_ms: 0, age_seconds: -1, selected: '🇸🇬 Singapore-09', total: 6, tested: 0, alive: 0, dead: 0, untested: 6, blocked_by: { index: 3, tag: 'chain-ewan-wg-subs-h3' } },
+  ],
+  'sub-fresh': [
+    { index: 1, tag: 'chain-sub-fresh-h1', kind: 'node', exit: false, state: 'untested', delay_ms: 0, age_seconds: -1, selected: '', total: 1, tested: 0, alive: 0, dead: 0, untested: 1 },
+    { index: 2, tag: 'chain-sub-fresh-h2', kind: 'group', exit: true, state: 'untested', delay_ms: 0, age_seconds: -1, selected: '', total: 24, tested: 0, alive: 0, dead: 0, untested: 24 },
+  ],
+}
+
+/** Per-chain reachability plus per-hop health for the Targets page. `used` is the
+ *  chain analogue of healthList's field; `hops` is OMITTED (never null, never []),
+ *  exactly like the daemon, for a chain the engine never materialised. A stopped
+ *  engine reports no chains at all. */
 function chainHealthList(): ChainHealth[] {
   if (!mockPlane().engine) return []
-  return (CONFIG.Chains ?? []).map((c) => ({ name: c.Name, used: chainUsed(c.Name) }))
+  return (CONFIG.Chains ?? []).map((c) => {
+    const hops = CHAIN_HOPS[c.Name]
+    const h: ChainHealth = { name: c.Name, used: chainUsed(c.Name) }
+    if (hops) h.hops = hops.map((x) => ({ ...x }))
+    return h
+  })
 }
 
 /** A chain is "used" when some enabled routing rule (or Final, or a DNS detour)
  *  targets `chain:<name>` — the same reachability the daemon's observatory derives.
- *  The mock's rules never target a chain, so every chain reads used=false; a real
- *  config would mark the ones rules point at used=true. */
+ *  Two of the mock's rules do (`media-via-chain` → ewan-wg-subs, `spare-via-chain`
+ *  → sub-fresh), so those two chains read used=true and get a hop rail; `relay`
+ *  is targeted by nothing and reads used=false, which is the unused note. */
 function chainUsed(name: string): boolean {
   const target = `chain:${name}`
   return (CONFIG.Rules ?? []).some(
@@ -1111,15 +1299,23 @@ class ApiErrorLike extends Error {
   }
 }
 
-// Mock group/chain test. Deliberately covers every state the UI has to render,
-// one per target, so a single offline run exercises all of them:
-//   auto     → ok WITH an exit address
-//   stealth  → ok WITHOUT one (delay measured, address undeterminable) — a
-//              SUCCESS, and the case the UI most easily gets wrong
-//   relay    → the chain: same wire shape, `group` carries the CHAIN's name and
-//              `selected` the node its exit group picked
-//   fallback → a failure carrying a human reason
-// Results land one per GET poll, so the running/progress state is visible too.
+// Mock refresh results. The endpoint no longer dials anything: it asks the
+// observatory to measure out of turn and reports what the observatory found, so
+// every row here is a READ of a background measurement. Deliberately covers every
+// state the UI has to render, one per target, so a single offline run exercises
+// all of them:
+//   auto         → ok WITH an exit address
+//   stealth      → ok WITHOUT one (delay measured, address undeterminable) — a
+//                  SUCCESS, and the case the UI most easily gets wrong
+//   ewan-wg-subs → the chain: same wire shape, `group` carries the CHAIN's name
+//                  and `selected` the node its exit hop picked
+//   via-tunnel   → the one honest health FAILURE: a probe that ran and failed
+//   fallback,
+//   relay        → not routed at all, so no measurement exists to report
+//   sub-fresh    → routed, but the observatory hasn't come round yet
+// The last three are absence of measurement, not a broken target, and the copy
+// has to keep them apart. Results land one per GET poll, so the running/progress
+// state is visible too.
 const GROUP_TEST_SHAPE: Record<string, Omit<GroupTestResult, 'group' | 'tested_unix'>> = {
   auto: {
     selected: 'nl-reality-2',
@@ -1137,32 +1333,60 @@ const GROUP_TEST_SHAPE: Record<string, Omit<GroupTestResult, 'group' | 'tested_u
     ok: true,
     error: '',
   },
-  // The chain — Selected is the node the chain's exit group (auto) picked.
-  relay: {
-    selected: 'nl-reality-2',
-    delay_ms: 61,
-    exit_ip: '185.12.34.56',
-    exit_country: 'NL',
-    ok: true,
-    error: '',
+  // The chain, and the pairing that makes the whole feature worth building. A
+  // chain is one series path, so with hop 3 dead the end-to-end probe is never
+  // even attempted — the daemon stops walking there. This row and the hop rail
+  // therefore have to tell one story, not two: both name hop 3, and neither
+  // offers hop 4 as a second suspect. Note the row does NOT say "the probe
+  // failed" — no probe of this chain's exit ran at all — which is why the daemon
+  // has a separate message for it.
+  'ewan-wg-subs': {
+    selected: '',
+    delay_ms: 0,
+    exit_ip: '',
+    exit_country: '',
+    ok: false,
+    error:
+      'hop 3 of this chain was probed and did not answer, so nothing reaches the exit through it — fix that hop first',
   },
-  // Dead through its tunnel, exactly as its membership health says — the exit
-  // test and the member health tell the same story about the same group.
+  // The one real health failure in the fixture: the observatory's probe ran along
+  // this path and did not come back.
   'via-tunnel': {
     selected: '',
     delay_ms: 0,
     exit_ip: '',
     exit_country: '',
     ok: false,
-    error: 'no member answered through egress awg (6 of 6 timed out)',
+    error: 'the observatory’s probe through this path failed',
   },
+  // Not a health verdict — nothing routes here, so no measurement of it exists.
   fallback: {
     selected: '',
     delay_ms: 0,
     exit_ip: '',
     exit_country: '',
     ok: false,
-    error: 'no reachable node in the group (all 3 members timed out)',
+    error:
+      'not routed by any enabled rule, so nothing measures it — the observatory only probes paths the rules use',
+  },
+  relay: {
+    selected: '',
+    delay_ms: 0,
+    exit_ip: '',
+    exit_country: '',
+    ok: false,
+    error:
+      'not routed by any enabled rule, so nothing measures it — the observatory only probes paths the rules use',
+  },
+  // Routed, materialised, simply not reached yet. Untested is not dead.
+  'sub-fresh': {
+    selected: '',
+    delay_ms: 0,
+    exit_ip: '',
+    exit_country: '',
+    ok: false,
+    error:
+      'the observatory has not reached this target yet — it refreshes on the global probe interval',
   },
 }
 

panel/src/pages/DNS.tsx

@@ -1,6 +1,6 @@
 import './DNS.css'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Button, CatSuggest, Led, SrcPicker, Toggle } from '../components'
+import { Button, CatSuggest, Led, SrcPicker, Toggle, useConfirm } from '../components'
 import { apply as apiApply, getConfig, putConfig, ApiError } from '../api'
 import type { Alert, DNSRule, Model, Resolver } from '../api'
 
@@ -220,6 +220,7 @@ function describeDetour(
 // ---- page ------------------------------------------------------------------
 
 export default function DNS() {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<DNSModel | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
 
@@ -422,15 +423,19 @@ export default function DNS() {
   )
 
   const removeBlocklist = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = blocklists[idx]
-      if (!window.confirm(`Delete blocklist “${target.Name}”? This removes it from the config.`))
-        return
+      const ok = await confirm({
+        label: 'Delete blocklist',
+        title: `Delete blocklist “${target.Name}”?`,
+        body: 'This removes it from the config.',
+      })
+      if (!ok) return
       const next = blocklists.filter((_, i) => i !== idx)
       void save({ ...config, Blocklists: next }, `Deleted ${target.Name}`)
     },
-    [config, blocklists, save],
+    [config, blocklists, save, confirm],
   )
 
   // ---- allowlist mutations --------------------------------------------------
@@ -457,15 +462,19 @@ export default function DNS() {
   )
 
   const removeAllowlist = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = allowlists[idx]
-      if (!window.confirm(`Delete allowlist “${target.Name}”? This removes it from the config.`))
-        return
+      const ok = await confirm({
+        label: 'Delete allowlist',
+        title: `Delete allowlist “${target.Name}”?`,
+        body: 'This removes it from the config.',
+      })
+      if (!ok) return
       const next = allowlists.filter((_, i) => i !== idx)
       void save({ ...config, Allowlists: next }, `Deleted ${target.Name}`)
     },
-    [config, allowlists, save],
+    [config, allowlists, save, confirm],
   )
 
   // ---- resolver mutations ---------------------------------------------------
@@ -492,11 +501,15 @@ export default function DNS() {
   )
 
   const removeResolver = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = resolvers[idx]
-      if (!window.confirm(`Delete resolver “${target.Name}”? This removes it from the config.`))
-        return
+      const ok = await confirm({
+        label: 'Delete resolver',
+        title: `Delete resolver “${target.Name}”?`,
+        body: 'This removes it from the config.',
+      })
+      if (!ok) return
       const next = resolvers.filter((_, i) => i !== idx)
       // Don't leave default/fallback pointing at a resolver that no longer exists.
       const g = { ...config.Globals }
@@ -578,15 +591,19 @@ export default function DNS() {
   )
 
   const removeDNSRule = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = dnsRules[idx]
-      if (!window.confirm(`Delete this DNS rule? Matching queries fall back to the default resolver.`))
-        return
+      const ok = await confirm({
+        label: 'Delete DNS rule',
+        title: 'Delete this DNS rule?',
+        body: 'Matching queries fall back to the default resolver.',
+      })
+      if (!ok) return
       const next = dnsRules.filter((_, i) => i !== idx)
       void save({ ...config, DNSRules: next }, `Deleted DNS rule → ${target.Resolver}`)
     },
-    [config, dnsRules, save],
+    [config, dnsRules, save, confirm],
   )
 
   // ---- alert mutations ------------------------------------------------------
@@ -610,14 +627,19 @@ export default function DNS() {
   )
 
   const removeAlert = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = alerts[idx]
-      if (!window.confirm(`Delete alert “${target.Name}”? This removes it from the config.`)) return
+      const ok = await confirm({
+        label: 'Delete alert',
+        title: `Delete alert “${target.Name}”?`,
+        body: 'This removes it from the config.',
+      })
+      if (!ok) return
       const next = alerts.filter((_, i) => i !== idx)
       void save({ ...config, Alerts: next }, `Deleted ${target.Name}`)
     },
-    [config, alerts, save],
+    [config, alerts, save, confirm],
   )
 
   const setAlertVia = useCallback(

panel/src/pages/Devices.css

@@ -138,57 +138,9 @@
 
 /* inline rename: a quiet pencil affordance beside the name, and the mono input
    it swaps to — in the same sink/groove tone as the domain editors. */
-.dev-rename {
-  flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 22px;
-  height: 22px;
-  padding: 0;
-  border: 1px solid transparent;
-  border-radius: 5px;
-  background: none;
-  color: var(--faint);
-  font-size: 12px;
-  line-height: 1;
-  cursor: pointer;
-  transition: color 0.15s, background 0.15s, border-color 0.15s;
-}
-.dev-rename:hover:not(:disabled) {
-  color: var(--accent);
-  background: color-mix(in srgb, var(--accent) 12%, transparent);
-}
-.dev-rename:focus-visible {
-  color: var(--accent);
-  border-color: var(--accent);
-  outline: 2px solid var(--accent);
-  outline-offset: 1px;
-}
-.dev-rename:disabled {
-  opacity: 0.5;
-  cursor: default;
-}
-.dev-name-input {
-  min-width: 0;
-  max-width: 24ch;
-  padding: 4px 8px;
-  border: 1px solid var(--accent);
-  border-radius: 6px;
-  background: var(--sink);
-  color: var(--ink);
-  font-size: 13px;
-  font-weight: 600;
-  letter-spacing: 0.01em;
-  box-shadow: 0 1px 2px var(--shadow) inset;
-}
-.dev-name-input:focus-visible {
-  outline: 2px solid var(--accent);
-  outline-offset: 1px;
-}
-.dev-name-input:disabled {
-  opacity: 0.55;
-}
+/* The pencil button and the name input now live in App.css as .inline-rename /
+   .inline-rename-input — Nodes grew the same affordance and the two pages must
+   not drift. */
 .dev-id-l2 {
   display: flex;
   align-items: center;

panel/src/pages/Devices.tsx

@@ -1,6 +1,6 @@
 import './Devices.css'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Button, Led, Module, Toggle } from '../components'
+import { Button, Led, Module, Toggle, useConfirm } from '../components'
 import type { LedVariant } from '../components'
 import { apply as apiApply, getConfig, getDevices, putConfig, ApiError } from '../api'
 import type { Device, DiscoveredDevice, Model } from '../api'
@@ -81,6 +81,7 @@ function networkLabel(row: DeviceRow): string {
 // ---- page ------------------------------------------------------------------
 
 export default function Devices() {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<Model | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
 
@@ -251,17 +252,22 @@ export default function Devices() {
   const nameOf = (row: DeviceRow) => row.cfg?.Name || row.hostname || row.ip || 'device'
 
   const removeControl = useCallback(
-    (row: DeviceRow) => {
+    async (row: DeviceRow) => {
       if (!config) return
       const devs = asArray(config.Devices)
       const idx = matchDevice(devs, row.mac, row.ip)
       if (idx < 0) return
       const nm = devs[idx].Name || nameOf(row)
-      if (!window.confirm(`Stop managing “${nm}”? Its per-device rules are removed; it falls back to network defaults.`))
-        return
+      const ok = await confirm({
+        label: 'Stop managing device',
+        title: `Stop managing “${nm}”?`,
+        body: 'Its per-device rules are removed; it falls back to network defaults.',
+        confirmLabel: 'Stop managing',
+      })
+      if (!ok) return
       void save({ ...config, Devices: devs.filter((_, i) => i !== idx) }, `Removed control for ${nm}`)
     },
-    [config, save],
+    [config, save, confirm],
   )
 
   const loading = config === null && loadError === null && devices === null && devError === null
@@ -471,7 +477,7 @@ function DeviceCard({
             {renaming ? (
               <input
                 ref={nameInput}
-                className="dev-name-input mono"
+                className="inline-rename-input mono"
                 type="text"
                 spellCheck={false}
                 autoComplete="off"
@@ -497,7 +503,7 @@ function DeviceCard({
                 </span>
                 <button
                   type="button"
-                  className="dev-rename"
+                  className="inline-rename"
                   onClick={beginRename}
                   disabled={busy}
                   aria-label={`Rename ${name}`}

panel/src/pages/Networks.tsx

@@ -1,6 +1,6 @@
 import './Networks.css'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Button, Led, Select, Toggle } from '../components'
+import { Button, Led, Select, Toggle, useConfirm } from '../components'
 import { apply as apiApply, getConfig, putConfig, ApiError } from '../api'
 import type { Inbound, Interface, Model, Status } from '../api'
 import { isLanNetwork, isWanNetwork, useInterfaces } from '../srcOptions'
@@ -242,6 +242,7 @@ function computeWarnings(inbounds: Inbound[], ifaces: Interface[]): Warning[] {
 // ---- page ------------------------------------------------------------------
 
 export default function Networks({ status }: { status?: Status | null }) {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<Model | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
   const ifaces = useInterfaces()
@@ -392,23 +393,21 @@ export default function Networks({ status }: { status?: Status | null }) {
   )
 
   const removeInbound = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = inbounds[idx]
-      if (
-        !window.confirm(
-          `Delete inbound “${target.Name}”?${
-            intercepts(target)
-              ? ` ${target.Network || 'Its network'} stops going through the tunnel.`
-              : ''
-          }`,
-        )
-      )
-        return
+      const ok = await confirm({
+        label: 'Delete inbound',
+        title: `Delete inbound “${target.Name}”?`,
+        body: intercepts(target)
+          ? `${target.Network || 'Its network'} stops going through the tunnel.`
+          : undefined,
+      })
+      if (!ok) return
       const next = inbounds.filter((_, i) => i !== idx)
       void save({ ...config, Inbounds: next }, `Deleted ${target.Name}`)
     },
-    [config, inbounds, save],
+    [config, inbounds, save, confirm],
   )
 
   return (

panel/src/pages/Nodes.css

@@ -727,3 +727,53 @@ select.fp-input {
     width: 9rem;
   }
 }
+
+/* ---- inline node rename ----
+   The pencil / input pair itself is shared (.inline-rename[-input] in App.css);
+   only the row-local sizing and the refusal message live here. A node name is
+   longer than a device name (it carries a protocol and a host), so the field is
+   given more room than the shared 24ch default. */
+.node-name-input {
+  max-width: 32ch;
+  font-family: var(--font-mono);
+  font-size: 12.5px;
+}
+/* Why a rename was refused, pinned under the row it was typed in. Semantic crit:
+   the name did not change, and that must not be mistaken for a saved edit. */
+.row-err {
+  margin: 2px 0 0;
+  font-size: 11.5px;
+  line-height: 1.45;
+  color: var(--crit);
+  max-width: 68ch;
+}
+/* Stated once per subscription bucket: the same rule the locked control in every
+   row carries, so the absent rename is explained before it is looked for. */
+.group-note {
+  margin: 0;
+  padding: 8px 12px;
+  border: 1px solid var(--groove);
+  border-top: 0;
+  background: color-mix(in srgb, var(--sink) 25%, transparent);
+  font-size: 11.5px;
+  line-height: 1.5;
+  color: var(--faint);
+}
+/* The optional name sits beside the link input on a wide row and drops onto its
+   own line when the row can no longer hold both. */
+.add-name {
+  flex: 0 1 22ch;
+  min-width: 12ch;
+}
+.add-row--conf .add-name {
+  flex: none;
+  align-self: stretch;
+}
+@media (max-width: 640px) {
+  .add-row {
+    flex-wrap: wrap;
+  }
+  .add-name {
+    flex: 1 1 100%;
+  }
+}

panel/src/pages/Nodes.tsx

@@ -2,7 +2,7 @@ import './Nodes.css'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import type { LedVariant } from '../components'
-import { Button, Led, Toggle } from '../components'
+import { Button, Led, Toggle, useConfirm } from '../components'
 import {
   apply as apiApply,
   getConfig,
@@ -158,6 +158,219 @@ function uniqueName(base: string, taken: Set<string>): string {
   return `${seed}-${i}`
 }
 
+// ---- node names are identity, not a caption --------------------------------
+//
+// A node's Name IS its sing-box outbound tag and the only thing every reference
+// to it spells: a rule target `node:<name>`, a chain hop, a manual group's member
+// list, a resolver detour, an alert delivery, a subscription fetch detour. Rename
+// the node alone and every one of those points at nothing — and an unresolved
+// target does NOT fall back to the default route, the daemon BLOCKS that traffic.
+// So the rename either carries every reference with it, or it is refused.
+
+/** Reserved outbound tags. A node called this is skipped by the generator entirely. */
+const RESERVED_TAGS = ['direct', 'block']
+
+/**
+ * Prefixes that `model.SplitTarget` reads as a KIND, not as part of a name. A
+ * name starting with one of them makes every bare reference to it ambiguous with
+ * a real `kind:name` reference, so it is refused rather than half-supported.
+ */
+const KIND_PREFIXES = ['node', 'group', 'egress', 'chain', 'direct', 'block']
+
+/** Names are rendered into a line-oriented `uci export`; control chars are stripped there. */
+function hasControlChar(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c < 0x20 || c === 0x7f) return true
+  }
+  return false
+}
+
+/**
+ * Why `name` cannot be a node name here, or null if it can.
+ *
+ * Every rule mirrors something the daemon actually does with the name, not a
+ * house style: reserved tags make generate skip the node; a duplicate makes two
+ * outbounds share a tag and the manager silently keeps the last one; a group of
+ * the same name is dropped by buildGroups ("rename the group"); an
+ * `egress-<name>` collision takes over a real egress outbound; and a control
+ * character is rewritten to a space by sanitizeUCIValue on write, so the saved
+ * name would not be the one you typed.
+ */
+function nodeNameError(
+  raw: string,
+  m: Model | null,
+  self: string | null,
+): string | null {
+  const name = raw.trim()
+  if (!name) return 'A node needs a name.'
+  if (hasControlChar(name))
+    return 'Names can’t contain line breaks or control characters — they’re stripped when the config is written.'
+  if (RESERVED_TAGS.some((t) => t.toLowerCase() === name.toLowerCase()))
+    return `“${name}” is a reserved target name — a node called that is skipped by the engine. Pick another.`
+  const head = name.includes(':') ? name.slice(0, name.indexOf(':')).toLowerCase() : ''
+  if (head && KIND_PREFIXES.includes(head))
+    return `A name starting with “${head}:” reads as a ${head} reference everywhere it’s used. Pick another.`
+  if (!m) return null
+
+  const clash = asArray(m.Nodes).find((n) => n.Name === name && n.Name !== self)
+  if (clash)
+    return clash.FromSub
+      ? `“${name}” is already a node from subscription “${clash.FromSub}”. Two nodes with one name share a single outbound — pick another.`
+      : `“${name}” is already another node. Pick another.`
+  if (asArray(m.Groups).some((g) => g.Name === name))
+    return `A group is already named “${name}”. The engine drops the group when a node takes its name — pick another.`
+  const egressClash = asArray(m.Egresses).find((e) => `egress-${e.Name}` === name)
+  if (egressClash)
+    return `“${name}” is the outbound tag of egress “${egressClash.Name}”. Pick another.`
+  return null
+}
+
+/** One place a node name is written, as a short label for the rename summary. */
+interface NodeRefSite {
+  /** Which section — drives the "N rules, M groups" count. */
+  kind: 'rule' | 'group' | 'chain' | 'resolver' | 'alert' | 'subscription' | 'egress'
+  label: string
+}
+
+/** A target/detour string naming this node in its prefixed form (`node:<name>`). */
+const isNodeRef = (v: string | undefined | null, name: string): boolean =>
+  (v ?? '') === `node:${name}`
+
+/** …or in the bare form the engine also resolves (a group member, a bare hop/target). */
+const isBareRef = (v: string | undefined | null, name: string): boolean => (v ?? '') === name
+
+/**
+ * Every place `name` is written outside the node itself. Both spellings count:
+ * `resolveTarget` falls through to a bare node lookup, and a manual group's
+ * member list is bare by contract.
+ */
+function findNodeReferences(m: Model, name: string): NodeRefSite[] {
+  const out: NodeRefSite[] = []
+  for (const r of asArray(m.Rules)) {
+    if (isNodeRef(r.Target, name) || isBareRef(r.Target, name))
+      out.push({ kind: 'rule', label: `rule “${r.Name}” target` })
+  }
+  for (const g of asArray(m.Groups)) {
+    if (asArray(g.Nodes).some((n) => n === name))
+      out.push({ kind: 'group', label: `group “${g.Name}” member` })
+  }
+  for (const c of asArray(m.Chains)) {
+    if (asArray(c.Hops).some((h) => isNodeRef(h, name) || isBareRef(h, name)))
+      out.push({ kind: 'chain', label: `chain “${c.Name}” hop` })
+  }
+  for (const r of asArray(m.Resolvers)) {
+    if (isNodeRef(r.Detour, name)) out.push({ kind: 'resolver', label: `resolver “${r.Name}” DNS path` })
+  }
+  for (const a of asArray(m.Alerts)) {
+    if (isNodeRef(a.Via, name)) out.push({ kind: 'alert', label: `alert “${a.Name}” delivery` })
+  }
+  for (const s of asArray(m.Subscriptions)) {
+    if (isNodeRef(s.FetchDetour, name))
+      out.push({ kind: 'subscription', label: `subscription “${s.Name}” fetch` })
+  }
+  for (const e of asArray(m.Egresses)) {
+    if (isNodeRef(e.Target, name)) out.push({ kind: 'egress', label: `egress “${e.Name}” target` })
+  }
+  return out
+}
+
+/**
+ * What makes a rename impossible to carry rather than merely wide.
+ *
+ * A BARE reference is just a name; the engine resolves it node-first, then group.
+ * If something else already answers to the old name, we cannot tell which object
+ * a bare reference meant, and rewriting it would move a reference the operator
+ * never pointed at this node. That is a half-done cascade, so the rename is
+ * refused instead — with the collision named, so it can be fixed.
+ */
+function bareAmbiguity(m: Model, name: string): string | null {
+  const group = asArray(m.Groups).find((g) => g.Name === name)
+  if (!group) return null
+  const bare = [
+    ...asArray(m.Rules)
+      .filter((r) => isBareRef(r.Target, name))
+      .map((r) => `rule “${r.Name}”`),
+    ...asArray(m.Chains)
+      .filter((c) => asArray(c.Hops).some((h) => isBareRef(h, name)))
+      .map((c) => `chain “${c.Name}”`),
+  ]
+  if (bare.length === 0) return null
+  return `A group is also named “${name}”, and ${bare.join(', ')} point${bare.length === 1 ? 's' : ''} at that bare name — there is no way to tell which of the two is meant. Rename the group first, then this node.`
+}
+
+/**
+ * Rewrite every reference from `from` to `to`. Returns a NEW Model with only the
+ * touched sections replaced; the Nodes section is the caller's business.
+ *
+ * Bare references are rewritten too — that is the whole point for a manual
+ * group's member list — which is safe only because `bareAmbiguity` has already
+ * refused the one case where a bare name could mean something else.
+ */
+function renameNodeReferences(m: Model, from: string, to: string): Model {
+  if (from === to) return m
+  /** Prefixed-only sites (a detour is never spelled bare). */
+  const pfx = (v: string | undefined) => (isNodeRef(v, from) ? `node:${to}` : v)
+  /** Sites that accept either spelling — each is rewritten in the spelling it already uses. */
+  const either = (v: string | undefined) => {
+    if (isNodeRef(v, from)) return `node:${to}`
+    if (isBareRef(v, from)) return to
+    return v
+  }
+
+  const next: Model = { ...m }
+  if (m.Rules) next.Rules = m.Rules.map((r) => ({ ...r, Target: either(r.Target) }))
+  if (m.Groups)
+    next.Groups = m.Groups.map((g) => ({
+      ...g,
+      Nodes: g.Nodes ? g.Nodes.map((n) => (n === from ? to : n)) : g.Nodes,
+    }))
+  if (m.Chains)
+    next.Chains = m.Chains.map((c) => ({
+      ...c,
+      Hops: c.Hops ? c.Hops.map((h) => either(h) ?? h) : c.Hops,
+    }))
+  if (m.Resolvers) next.Resolvers = m.Resolvers.map((r) => ({ ...r, Detour: pfx(r.Detour) }))
+  if (m.Alerts) next.Alerts = m.Alerts.map((a) => ({ ...a, Via: pfx(a.Via) }))
+  if (m.Subscriptions)
+    next.Subscriptions = m.Subscriptions.map((s) => ({ ...s, FetchDetour: pfx(s.FetchDetour) }))
+  if (m.Egresses) next.Egresses = m.Egresses.map((e) => ({ ...e, Target: pfx(e.Target) }))
+  return next
+}
+
+/** "3 rules, 1 group and 2 chains" — what the rename is about to rewrite. */
+function refSummary(refs: NodeRefSite[]): string {
+  const plural: Record<NodeRefSite['kind'], [string, string]> = {
+    rule: ['rule', 'rules'],
+    group: ['group', 'groups'],
+    chain: ['chain', 'chains'],
+    resolver: ['resolver', 'resolvers'],
+    alert: ['alert', 'alerts'],
+    subscription: ['subscription', 'subscriptions'],
+    egress: ['egress', 'egresses'],
+  }
+  const order: NodeRefSite['kind'][] = [
+    'rule', 'group', 'chain', 'resolver', 'alert', 'subscription', 'egress',
+  ]
+  const parts = order
+    .map((k) => [k, refs.filter((r) => r.kind === k).length] as const)
+    .filter(([, n]) => n > 0)
+    .map(([k, n]) => `${n} ${plural[k][n === 1 ? 0 : 1]}`)
+  if (parts.length === 1) return parts[0]
+  return `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`
+}
+
+/**
+ * The name a rename just committed to, waiting for its row to come back.
+ *
+ * A row is keyed by the node's NAME, so committing a rename unmounts the row and
+ * mounts a different one — carrying the focused element away with it. This baton
+ * survives that remount: the row that reappears under the new name claims it and
+ * puts the keyboard back on its own rename button, instead of dropping the user
+ * on <body> halfway down a list of 300 nodes.
+ */
+let pendingRenameFocus: string | null = null
+
 // A subscription with more than this many nodes starts collapsed so the list
 // doesn't become one endless scroll; an active search overrides it.
 const LARGE_GROUP = 20
@@ -289,6 +502,7 @@ function DetourSelect({
 // ---- page ------------------------------------------------------------------
 
 export default function Nodes() {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<Model | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
 
@@ -385,6 +599,9 @@ export default function Nodes() {
   const [nodeInput, setNodeInput] = useState('')
   const [nodeErr, setNodeErr] = useState<string | null>(null)
   const [addMode, setAddMode] = useState<'link' | 'conf'>('link')
+  // Optional. Empty keeps the old behaviour (a name derived from the server
+  // address), so "paste a link, press Add" stays a two-step path.
+  const [nodeName, setNodeName] = useState('')
   const [importing, setImporting] = useState(false)
 
   // ---- node search + collapsible grouping -----------------------------------
@@ -445,8 +662,12 @@ export default function Nodes() {
       try {
         const { uri, name } = await importWg(conf)
         const taken = new Set(nodes.map((n) => n.Name))
+        // A typed name is used AS TYPED — uniqueName would silently turn a
+        // collision into "name-2", which is the confusion this field exists to
+        // end. It is validated instead, and a clash is refused out loud above.
+        const wanted = nodeName.trim()
         const node: NodeCfg = {
-          Name: uniqueName(name || 'wireguard', taken),
+          Name: wanted || uniqueName(name || 'wireguard', taken),
           Enabled: true,
           URI: uri,
           FromSub: '',
@@ -455,6 +676,7 @@ export default function Nodes() {
         const ok = await save({ ...config, Nodes: [...nodes, node] }, `Added ${node.Name}`)
         if (ok) {
           setNodeInput('')
+          setNodeName('')
           setAddMode('link')
         }
       } catch (e) {
@@ -463,11 +685,20 @@ export default function Nodes() {
         setImporting(false)
       }
     },
-    [config, nodes, save, flash],
+    [config, nodes, nodeName, save, flash],
   )
 
   const addNode = useCallback(async () => {
     if (!config) return
+    // The name is checked BEFORE the import round-trip, so a bad name costs
+    // nothing and the message lands in the form next to the field.
+    if (nodeName.trim()) {
+      const bad = nodeNameError(nodeName, config, null)
+      if (bad) {
+        setNodeErr(bad)
+        return
+      }
+    }
     // Auto-detect a pasted config, whichever input it landed in.
     if (nodeInput.includes(WG_MARKER)) {
       await addWgConf(nodeInput)
@@ -486,10 +717,20 @@ export default function Nodes() {
     const parsed = parseShareLink(uri)
     const taken = new Set(nodes.map((n) => n.Name))
     const base = parsed.suggested || `${parsed.proto.toLowerCase()}-${parsed.host}`.replace(/[^\w.:-]+/g, '-')
-    const node: NodeCfg = { Name: uniqueName(base, taken), Enabled: true, URI: uri, FromSub: '', Egress: '' }
+    const wanted = nodeName.trim()
+    const node: NodeCfg = {
+      Name: wanted || uniqueName(base, taken),
+      Enabled: true,
+      URI: uri,
+      FromSub: '',
+      Egress: '',
+    }
     const ok = await save({ ...config, Nodes: [...nodes, node] }, `Added ${node.Name}`)
-    if (ok) setNodeInput('')
-  }, [config, nodeInput, nodes, save, addMode, addWgConf])
+    if (ok) {
+      setNodeInput('')
+      setNodeName('')
+    }
+  }, [config, nodeInput, nodeName, nodes, save, addMode, addWgConf])
 
   const toggleNode = useCallback(
     (idx: number, on: boolean) => {
@@ -501,14 +742,88 @@ export default function Nodes() {
   )
 
   const removeNode = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = nodes[idx]
-      if (!window.confirm(`Delete node “${target.Name}”? This removes it from the config.`)) return
+      const ok = await confirm({
+        label: 'Delete node',
+        title: `Delete node “${target.Name}”?`,
+        body: 'This removes it from the config.',
+      })
+      if (!ok) return
       const next = nodes.filter((_, i) => i !== idx)
       void save({ ...config, Nodes: next }, `Deleted ${target.Name}`)
     },
-    [config, nodes, save],
+    [config, nodes, save, confirm],
+  )
+
+  /**
+   * Rename a manual node, carrying every reference with it.
+   *
+   * The name is this node's identity: its outbound tag, and the exact string a
+   * rule target, a chain hop, a manual group's member list, a resolver detour, an
+   * alert delivery and a subscription fetch detour all spell. So the rename is one
+   * atomic save of the Nodes section AND every referencing section, or it does not
+   * happen at all:
+   *
+   *   - an invalid or colliding name is refused with the reason (`nodeNameError`);
+   *   - a name a GROUP also answers to, with bare references pointing at it, is
+   *     refused too — there is no way to know which object those meant, and
+   *     guessing would move a reference the operator never pointed here;
+   *   - anything else is shown exactly what it will rewrite, and only then saved.
+   *
+   * Errors surface through `onError` so they land in the row that was edited.
+   */
+  const renameNode = useCallback(
+    async (idx: number, raw: string, onError: (msg: string) => void): Promise<boolean> => {
+      if (!config) return false
+      const target = nodes[idx]
+      const from = target.Name
+      const to = raw.trim()
+      if (to === from) return true
+      // Subscription names come back from the feed on the next update; renaming
+      // one would be undone without warning, so this path is manual-only.
+      if (target.FromSub) {
+        onError(`“${from}” is named by subscription “${target.FromSub}” — the feed rewrites it on the next update.`)
+        return false
+      }
+      const bad = nodeNameError(to, config, from)
+      if (bad) {
+        onError(bad)
+        return false
+      }
+      const blocked = bareAmbiguity(config, from)
+      if (blocked) {
+        onError(blocked)
+        return false
+      }
+
+      const refs = findNodeReferences(config, from)
+      if (refs.length > 0) {
+        const shown = refs.slice(0, 4).map((r) => r.label)
+        const more = refs.length - shown.length
+        const ok = await confirm({
+          tone: 'neutral',
+          label: 'Rename node',
+          title: `Rename “${from}” to “${to}”?`,
+          body: `This also updates ${refSummary(refs)} that point at it — ${shown.join(', ')}${more > 0 ? `, and ${more} more` : ''}. They are saved together, so nothing is left pointing at the old name.`,
+          confirmLabel: 'Rename',
+        })
+        if (!ok) return false
+      }
+
+      // One PUT: the node and every reference move in the same write, so no
+      // intermediate state exists where a reference dangles.
+      const carried = renameNodeReferences(config, from, to)
+      const next = asArray(carried.Nodes).map((n, i) => (i === idx ? { ...n, Name: to } : n))
+      return save(
+        { ...carried, Nodes: next },
+        refs.length > 0
+          ? `Renamed to ${to} — updated ${refs.length} reference${refs.length === 1 ? '' : 's'}`
+          : `Renamed to ${to}`,
+      )
+    },
+    [config, nodes, save, confirm],
   )
 
   // Pin (or clear) one node's dial egress. Same optimistic save→apply path as
@@ -563,16 +878,20 @@ export default function Nodes() {
   )
 
   const removeSub = useCallback(
-    (idx: number) => {
+    async (idx: number) => {
       if (!config) return
       const target = subs[idx]
       const hasCache = nodes.some((n) => n.FromSub === target.Name)
-      const extra = hasCache ? ' Its cached nodes stay until you next apply.' : ''
-      if (!window.confirm(`Delete subscription “${target.Name}”?${extra}`)) return
+      const ok = await confirm({
+        label: 'Delete subscription',
+        title: `Delete subscription “${target.Name}”?`,
+        body: hasCache ? 'Its cached nodes stay until you next apply.' : undefined,
+      })
+      if (!ok) return
       const next = subs.filter((_, i) => i !== idx)
       void save({ ...config, Subscriptions: next }, `Deleted ${target.Name}`)
     },
-    [config, subs, nodes, save],
+    [config, subs, nodes, save, confirm],
   )
 
   // Commit an options edit for one subscription. The editor hands back a fully
@@ -736,6 +1055,20 @@ export default function Nodes() {
                 disabled={busy || importing || !config}
               />
             )}
+            <input
+              className="fp-input add-name"
+              type="text"
+              spellCheck={false}
+              autoComplete="off"
+              placeholder="Name (optional)"
+              aria-label="Node name — optional"
+              value={nodeName}
+              onChange={(e) => {
+                setNodeName(e.target.value)
+                if (nodeErr) setNodeErr(null)
+              }}
+              disabled={busy || importing || !config}
+            />
             <Button type="submit" variant="primary" disabled={busy || importing || !config}>
               {importing ? 'Importing…' : saving ? 'Saving…' : addMode === 'conf' ? 'Import' : 'Add node'}
             </Button>
@@ -743,7 +1076,8 @@ export default function Nodes() {
           <p className="add-hint">
             {addMode === 'conf'
               ? 'Paste a wg-quick / AmneziaWG .conf — it starts with [Interface].'
-              : 'vless://, ss://, trojan://, hysteria2://… A pasted [Interface] config is imported automatically.'}
+              : 'vless://, ss://, trojan://, hysteria2://… A pasted [Interface] config is imported automatically.'}{' '}
+            Leave the name empty and it’s taken from the server address; you can rename it later.
           </p>
         </div>
         {nodeErr && (
@@ -800,6 +1134,7 @@ export default function Nodes() {
                 onToggle={() => toggleGroup(g)}
                 onToggleNode={toggleNode}
                 onRemoveNode={removeNode}
+                onRenameNode={renameNode}
                 onSetEgress={setNodeEgress}
               />
             ))}
@@ -911,6 +1246,7 @@ function NodeGroup({
   onToggle,
   onToggleNode,
   onRemoveNode,
+  onRenameNode,
   onSetEgress,
 }: {
   group: NodeGroupData
@@ -920,6 +1256,7 @@ function NodeGroup({
   onToggle: () => void
   onToggleNode: (idx: number, on: boolean) => void
   onRemoveNode: (idx: number) => void
+  onRenameNode: (idx: number, name: string, onError: (msg: string) => void) => Promise<boolean>
   onSetEgress: (idx: number, egress: string) => Promise<boolean>
 }) {
   const panelId = `node-group-${group.key || 'manual'}`
@@ -940,6 +1277,12 @@ function NodeGroup({
           <span className="group-count mono">{count}</span>
         </button>
       </h3>
+      {open && group.key !== '' && (
+        <p className="group-note">
+          Names come from the subscription feed and are rewritten on every update, so nodes in this
+          list can’t be renamed here.
+        </p>
+      )}
       {open && (
         <ul id={panelId} className="rows-list group-rows">
           {group.items.map(({ node, idx }) => (
@@ -950,6 +1293,7 @@ function NodeGroup({
               egressNames={egressNames}
               onToggle={(on) => onToggleNode(idx, on)}
               onDelete={() => onRemoveNode(idx)}
+              onRename={(name, onError) => onRenameNode(idx, name, onError)}
               onSetEgress={(egress) => onSetEgress(idx, egress)}
             />
           ))}
@@ -965,6 +1309,7 @@ function NodeRow({
   egressNames,
   onToggle,
   onDelete,
+  onRename,
   onSetEgress,
 }: {
   node: NodeCfg
@@ -972,6 +1317,7 @@ function NodeRow({
   egressNames: string[]
   onToggle: (on: boolean) => void
   onDelete: () => void
+  onRename: (name: string, onError: (msg: string) => void) => Promise<boolean>
   onSetEgress: (egress: string) => Promise<boolean>
 }) {
   const { proto, host, hasCreds } = useMemo(() => parseShareLink(node.URI), [node.URI])
@@ -982,6 +1328,68 @@ function NodeRow({
   const [open, setOpen] = useState(false)
   const panelId = `node-egress-${node.FromSub || 'manual'}-${node.Name}`
 
+  // ---- inline rename (same interaction as a device row) ---------------------
+  // Enter commits, Esc cancels, blur commits; a ref-guard keeps Esc-then-blur
+  // from committing twice. Unlike a device, the commit can be REFUSED (a name
+  // collision, or references that can't be carried), so the input stays open
+  // with the reason under it instead of closing on a change that never happened.
+  const [renaming, setRenaming] = useState(false)
+  const [draft, setDraft] = useState(node.Name)
+  const [renameErr, setRenameErr] = useState<string | null>(null)
+  const nameInput = useRef<HTMLInputElement>(null)
+  const renameBtn = useRef<HTMLButtonElement>(null)
+  const finished = useRef(false)
+
+  const beginRename = () => {
+    setDraft(node.Name)
+    setRenameErr(null)
+    finished.current = false
+    setRenaming(true)
+  }
+  const finishRename = async (commit: boolean) => {
+    if (finished.current) return
+    finished.current = true
+    const nm = draft.trim()
+    if (!commit || !nm || nm === node.Name) {
+      setRenaming(false)
+      setRenameErr(null)
+      return
+    }
+    // Armed BEFORE the save: the renamed row remounts the moment the config
+    // state lands, which is before this await resolves. Arming afterwards would
+    // always miss it.
+    pendingRenameFocus = nm
+    const ok = await onRename(nm, (msg) => setRenameErr(msg))
+    if (ok) {
+      setRenaming(false)
+      setRenameErr(null)
+    } else {
+      if (pendingRenameFocus === nm) pendingRenameFocus = null
+      // Refused — hold the field open on the rejected text so it can be fixed.
+      finished.current = false
+      nameInput.current?.focus()
+    }
+  }
+
+  useEffect(() => {
+    if (renaming) {
+      nameInput.current?.focus()
+      nameInput.current?.select()
+    }
+  }, [renaming])
+
+  // Claim the baton if this row is the one the rename produced. The row remounts
+  // while the PUT is still in flight, so on that first pass the button is still
+  // disabled and focus() would be a silent no-op — the baton is held until the
+  // save settles and this effect re-runs with a focusable button.
+  useEffect(() => {
+    if (pendingRenameFocus !== node.Name) return
+    const btn = renameBtn.current
+    if (!btn || btn.disabled) return
+    pendingRenameFocus = null
+    btn.focus()
+  }, [node.Name, busy])
+
   return (
     <li className={`row-item node-row${open ? ' node-row--open' : ''}`}>
       <div className="row-head">
@@ -993,10 +1401,73 @@ function NodeRow({
         />
         <div className="row-main">
           <div className="row-line1">
-            <span className="row-name">{node.Name}</span>
+            {renaming ? (
+              <input
+                ref={nameInput}
+                className="inline-rename-input node-name-input mono"
+                type="text"
+                spellCheck={false}
+                autoComplete="off"
+                value={draft}
+                aria-label={`Rename node ${node.Name}`}
+                aria-invalid={renameErr ? true : undefined}
+                onChange={(e) => {
+                  setDraft(e.target.value)
+                  if (renameErr) setRenameErr(null)
+                }}
+                onBlur={() => void finishRename(true)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    e.preventDefault()
+                    void finishRename(true)
+                  } else if (e.key === 'Escape') {
+                    e.preventDefault()
+                    void finishRename(false)
+                  }
+                }}
+                disabled={busy}
+              />
+            ) : (
+              <>
+                <span className="row-name" title={node.Name}>
+                  {node.Name}
+                </span>
+                {managed ? (
+                  // Not hidden — withheld, with the reason attached. A control
+                  // that quietly isn't there reads as a bug; this one states the
+                  // rule, and the same sentence is on the group header above.
+                  <button
+                    type="button"
+                    className="inline-rename inline-rename--locked"
+                    disabled
+                    aria-label={`Can’t rename ${node.Name} — its name comes from subscription “${node.FromSub}” and is rewritten on the next update`}
+                    title={`Named by subscription “${node.FromSub}” — the feed rewrites this name on the next update. Rename it in the subscription, or add the node manually.`}
+                  >
+                    🔒
+                  </button>
+                ) : (
+                  <button
+                    ref={renameBtn}
+                    type="button"
+                    className="inline-rename"
+                    onClick={beginRename}
+                    disabled={busy}
+                    aria-label={`Rename node ${node.Name}`}
+                    title="Rename"
+                  >
+                    ✎
+                  </button>
+                )}
+              </>
+            )}
             <span className="badge">{proto}</span>
             {node.Stale && <span className="badge badge--warn">stale</span>}
           </div>
+          {renameErr && (
+            <p className="row-err" role="alert">
+              {renameErr}
+            </p>
+          )}
           <div className="row-line2 mono">
             <span className="row-host">{host}</span>
             {hasCreds && (

panel/src/pages/Overview.tsx

@@ -341,7 +341,7 @@ export function Overview({
           led={{ variant: len(config?.Rules) ? 'on' : 'amber' }}
           rows={[
             { k: 'egresses', v: String(len(config?.Egresses)) },
-            { k: 'default', v: defaultTarget(config), hot: true },
+            { k: 'default', v: defaultTarget(status, config), hot: true },
           ]}
         />
 
@@ -563,12 +563,20 @@ const NAV_LABEL: Record<Route, string> = {
 // for the apply/rollback flow, where the individual flags are the actual
 // subject of the page.)
 
-function defaultTarget(config: Model | null): string {
-  const rules = config?.Rules ?? []
-  if (rules.length === 0) return '—'
-  // The highest Order enabled rule is the effective catch-all.
-  const enabled = rules.filter((r) => r.Enabled)
-  if (enabled.length === 0) return 'none'
-  const last = enabled.reduce((a, b) => (b.Order >= a.Order ? b : a))
-  return last.Target || last.Egress || last.Name
+/** Where everything not matched by a rule goes — the engine's route `final`.
+ *
+ *  Taken from the daemon (status.traffic.default), which reads it off the config
+ *  it is running. The guess this replaced was "the highest-Order enabled rule",
+ *  and that is not what the default is: a rule only becomes the default by having
+ *  NO conditions at all, whatever its Order (model.IsCatchAll), so a specific
+ *  high-Order rule was routinely printed here as the router's default. It also
+ *  described the config on disk rather than the one running, and could not see a
+ *  target that failed to resolve and fell back.
+ *
+ *  Falls back to the rule count only when the daemon has not reported — never to
+ *  a guess about where traffic goes. */
+function defaultTarget(status: Status | null, config: Model | null): string {
+  const d = status?.traffic?.default
+  if (d) return d
+  return len(config?.Rules) === 0 ? '—' : 'not reported'
 }

panel/src/pages/Profiles.tsx

@@ -1,6 +1,6 @@
 import './Profiles.css'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Button, Led, Toggle } from '../components'
+import { Button, Led, Toggle, useConfirm } from '../components'
 import { apply as apiApply, getConfig, getInterfaces, putConfig, ApiError } from '../api'
 import type { Interface, Model, Profile } from '../api'
 
@@ -36,6 +36,7 @@ function namesOf(v: unknown): string[] {
 // ---- page ------------------------------------------------------------------
 
 export default function Profiles() {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<Model | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
 
@@ -192,9 +193,14 @@ export default function Profiles() {
   )
 
   const deleteProfile = useCallback(
-    (name: string) => {
+    async (name: string) => {
       if (!config) return
-      if (!window.confirm(`Delete profile “${name}”? Its overrides stop applying.`)) return
+      const ok = await confirm({
+        label: 'Delete profile',
+        title: `Delete profile “${name}”?`,
+        body: 'Its overrides stop applying.',
+      })
+      if (!ok) return
       const next = profiles.filter((p) => p.Name !== name)
       const g =
         config.Globals.ActiveProfile === name
@@ -202,7 +208,7 @@ export default function Profiles() {
           : config.Globals
       void save({ ...config, Profiles: next, Globals: g }, `Deleted ${name}`)
     },
-    [config, profiles, save],
+    [config, profiles, save, confirm],
   )
 
   // ---- expansion (only one profile editor open at a time) -------------------

panel/src/pages/Routing.css

@@ -58,6 +58,45 @@
   color: var(--ink);
 }
 
+/* ---- active-profile banner ----
+ *
+ * Deliberately NOT the accent plate the save→apply bar wears above. Orange is
+ * "there is something for you to do" on this faceplate, and an active WAN profile
+ * is a standing condition, not a pending action. A quiet plate with an amber tag
+ * reads as "note the state" — and it is the SAME amber the overridden rows below
+ * carry, so the banner and its rows are visibly one story rather than two
+ * unrelated oddities. */
+.rt-prof-banner {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  margin: 0 0 calc(var(--u, 8px) * 2.5);
+  padding: 10px 14px;
+  border: 1px solid color-mix(in srgb, var(--amber) 35%, var(--groove));
+  border-radius: 8px;
+  background: color-mix(in srgb, var(--amber) 7%, transparent);
+  font-family: var(--font-sans);
+  font-size: 12px;
+  line-height: 1.55;
+  color: var(--dim);
+}
+.rt-prof-banner strong {
+  color: var(--ink);
+  font-weight: 600;
+}
+.rt-prof-tag {
+  flex: none;
+  margin-top: 1px;
+  padding: 2px 7px;
+  border: 1px solid color-mix(in srgb, var(--amber) 55%, var(--groove));
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--amber) 12%, transparent);
+  font-size: 9px;
+  letter-spacing: var(--track-label);
+  text-transform: uppercase;
+  color: var(--amber);
+}
+
 /* ---- empty state ---- */
 .rt-empty {
   padding: calc(var(--u, 8px) * 4) 0 calc(var(--u, 8px) * 3);
@@ -252,6 +291,88 @@
   color: var(--faint);
 }
 
+/* ---- a rule that can never fire (superseded by a later condition-less rule) ----
+ *
+ * Warn semantics only: --amber, never --accent. Orange is the ACTIVE state on this
+ * faceplate, and a rule the router ignores is the opposite of active — painting it
+ * orange is what made two `default` rows look equally live. It is a dashed amber
+ * frame, an amber order chip, and a dimmed target, so the row reads as "wired but
+ * not connected" without shouting: nothing is broken, one setting is just inert. */
+.rt-rule.dead {
+  border-style: dashed;
+  border-color: color-mix(in srgb, var(--amber) 55%, var(--groove));
+  background: var(--panel);
+  box-shadow: none;
+}
+.rt-ord.dead {
+  color: var(--amber);
+  border-color: color-mix(in srgb, var(--amber) 45%, var(--groove));
+}
+.rt-badge.dead {
+  padding: 1px 7px;
+  border: 1px solid color-mix(in srgb, var(--amber) 55%, var(--groove));
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--amber) 12%, transparent);
+  color: var(--amber);
+}
+.rt-dead-note {
+  font-family: var(--font-sans);
+  font-size: 11.5px;
+  line-height: 1.45;
+  color: var(--dim);
+}
+/* The target is still what the operator asked for, so it stays readable — just
+ * quiet, because the router is not using it. */
+.rt-rule.dead .rt-target {
+  border-style: dashed;
+  opacity: 0.62;
+}
+
+/* ---- a rule the active WAN profile overrides ----
+ *
+ * The row itself needs no new paint: an overridden-off rule already wears `.off`
+ * (it is off, whatever its switch says) and an overridden-on rule wears nothing
+ * (it is on). What was missing was never colour — it was the sentence naming who
+ * decided. So this is the per-row twin of the banner and borrows .rt-dead-note's
+ * type wholesale: same voice, same size, one <p> margin to reset. */
+/* The same pill as .rt-badge.dead, so the two override states read as one pair,
+ * but in accent — a rule the profile forces ON is active, and active is orange on
+ * this faceplate. The pill is also what keeps it from running into the plain
+ * "default route · final" badge beside it, where "final on · by profile" read as
+ * one phrase. */
+.rt-badge.prof-on {
+  padding: 1px 7px;
+  border: 1px solid var(--accent-soft);
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+}
+
+.rt-prof-note {
+  margin: 0;
+}
+.rt-prof-note strong {
+  color: var(--ink);
+  font-weight: 600;
+}
+
+/* Switch + its legend. The caption shows ONLY while a profile overrides the rule,
+ * and it is what keeps the control honest: the plate says what the router is
+ * doing, this says the switch is about the saved setting. A legend under the
+ * control it names is the faceplate's own idiom. */
+.rt-switch {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+}
+.rt-switch-note {
+  font-family: var(--font-mono);
+  font-size: 8.5px;
+  letter-spacing: var(--track-label);
+  text-transform: uppercase;
+  color: var(--faint);
+}
+
 /* ---- target chip (styled like the artifact's group:auto mono chips) ---- */
 .rt-target {
   display: inline-flex;
@@ -359,9 +480,6 @@
   gap: 5px;
   min-width: 0;
 }
-.rt-field-wide {
-  grid-column: span 2;
-}
 .rt-flabel {
   font-family: var(--font-mono);
   font-size: 9px;
@@ -478,6 +596,8 @@ select.rt-input {
   border-color: var(--accent);
   box-shadow: 0 1px 0 var(--edge) inset, 0 0 0 1px var(--accent-soft);
 }
+/* "no matchers" flag in the plate foot — shared by BOTH rule forms (add and
+ * edit), so the same non-blocking warning reads identically in either. */
 .rt-edit-warn {
   font-family: var(--font-mono);
   font-size: 11.5px;
@@ -800,9 +920,6 @@ select.rt-input {
     justify-content: flex-start;
     align-self: start;
   }
-  .rt-field-wide {
-    grid-column: auto;
-  }
   .rt-rs-row {
     grid-template-columns: 1fr;
     row-gap: 10px;

panel/src/pages/Routing.tsx

@@ -1,16 +1,17 @@
 import './Routing.css'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { FormEvent, ReactNode } from 'react'
-import { Button, CatSuggest, SrcPicker, Toggle } from '../components'
+import { Button, CatSuggest, SrcPicker, Toggle, useConfirm } from '../components'
 import {
   apply as apiApply,
   getConfig,
   putConfig,
+  getRulesReachability,
   getRulesetStatus,
   updateRuleset as apiUpdateRuleset,
   ApiError,
 } from '../api'
-import type { Model, Rule, Ruleset, RulesetStatus } from '../api'
+import type { Model, Rule, RuleReach, Ruleset, RulesetStatus } from '../api'
 
 // ---------------------------------------------------------------------------
 // The api.ts `Rule` is a deliberately thin subset (Name/Enabled/Order/Target/
@@ -21,9 +22,7 @@ import type { Model, Rule, Ruleset, RulesetStatus } from '../api'
 // ---------------------------------------------------------------------------
 type RRule = Rule & {
   Src?: string[] | null
-  DstDomain?: string[] | null
   DstRuleset?: string[] | null
-  DstIP?: string[] | null
   DstPort?: string
   Proto?: string
   Kill?: string
@@ -34,6 +33,29 @@ type RRule = Rule & {
   // Minutes east of UTC anchoring the schedule's wall-clock times; captured
   // from the editing browser on save (the router has no tzdata). 0 ⇒ UTC.
   SchedUTCOffset?: number
+  // The daemon's unmigrated-rule tripwire (model.Rule.LegacyDst), read-only here.
+  // Non-empty ⇒ the config STILL carries the schema-v1 `dst_domain`/`dst_ip` that
+  // schema v2 removed, i.e. `shaterd migrate` never ran or could not commit. Each
+  // element is the raw `<option>=<value>` text so the panel can quote what was
+  // found. The daemon holds such a rule disabled; the panel only reports it (it
+  // is never rendered back to UCI, so a config write from here drains it out).
+  // Field name is the Go one: model.Rule has no json tags.
+  LegacyDst?: string[] | null
+}
+
+/**
+ * Whether a rule is in force, kept strictly apart from whether it is switched on.
+ *
+ * `on` is the EFFECTIVE state — what the router is actually doing — and every mark
+ * on the row is drawn from it. `profile`/`dir` are set only when the active WAN
+ * profile is the reason the two differ, so the row can name who overrode the
+ * saved setting instead of leaving the operator to guess why a switch that reads
+ * "on" routes nothing.
+ */
+type RuleForce = {
+  on: boolean
+  profile: string | null
+  dir: 'enabled' | 'disabled' | null
 }
 
 /**
@@ -96,7 +118,6 @@ function ProtoOptions({ value }: { value: string }) {
 
 const len = (a: unknown[] | null | undefined): number => (a ? a.length : 0)
 const byOrder = (a: RRule, b: RRule): number => a.Order - b.Order
-const csv = (s: string): string[] => s.split(',').map((x) => x.trim()).filter(Boolean)
 
 // --- ruleset helpers --------------------------------------------------------
 // A `config ruleset` (api.ts Ruleset) is a named domain/ipcidr list a rule
@@ -212,18 +233,59 @@ function everyLabel(sec: number): string {
   return `every ${sec}s`
 }
 
-/** A rule with no matcher of any kind is the effective catch-all (route Final). */
+/** A rule with no matcher of any kind is the effective catch-all (route Final).
+ *  Mirrors model.IsCatchAll on the daemon side — the two must agree or the
+ *  "never applies" badge lands on a different row than the apply warning.
+ *
+ *  AN UNMIGRATED RULE IS NEVER A CATCH-ALL, and that is the first thing checked
+ *  here, exactly as on the Go side (model/reachability.go). When LegacyDst is
+ *  non-empty the rule's destination is still written in the schema-v1 options
+ *  the parser no longer reads, so its lack of matchers means "the destination is
+ *  unreadable", not "matches everything" — reading it the other way is precisely
+ *  what turned an uncommitted `shaterd migrate` into route Final for the whole
+ *  router. The daemon holds such a rule disabled and reports false here; if this
+ *  copy disagreed, the panel would paint the row "default route · final" while
+ *  the daemon routes nothing through it. */
 function isCatchAll(r: RRule): boolean {
+  if (len(r.LegacyDst) > 0) return false
   return (
     len(r.Src) === 0 &&
-    len(r.DstDomain) === 0 &&
     len(r.DstRuleset) === 0 &&
-    len(r.DstIP) === 0 &&
     !(r.DstPort && r.DstPort.trim()) &&
     !(r.Proto && r.Proto.trim())
   )
 }
 
+/** isCatchAll's twin for a form still being edited: the live fields of either
+ *  rule form with no matcher left in them.
+ *
+ *  Such a rule is not "matches all" in the ordinary sense — the engine emits it
+ *  as route.Final, and among several the LAST one in rule order owns it. So what
+ *  saving one actually does depends on what is last right now, and there are
+ *  three cases:
+ *    - no rules at all, or the last rule is a conditional one → the new rule
+ *      lands last and TAKES the default, silently retargeting every otherwise
+ *      unmatched flow (e.g. the whole LAN to `direct`, past the tunnel);
+ *    - the last rule is already a catch-all → nextOrder() deliberately inserts
+ *      the new one BEFORE it (and bumps the old one up), so the existing default
+ *      keeps route.Final and the new rule is dead on arrival — the daemon
+ *      reports it as shadowed and the row renders as such.
+ *  Both outcomes are worth a warning, and neither form knows which it will be
+ *  (the add form has no rule list), so the shared text says only what is certain:
+ *  the rule has no matchers. It is a legal configuration either way, so neither
+ *  form blocks it — they warn, from this one predicate, so the flag cannot drift
+ *  out of sync between add and edit. */
+function formHasNoMatchers(f: {
+  src: string[]
+  port: string
+  rulesets: string[]
+  proto: string
+}): boolean {
+  return (
+    f.src.length === 0 && f.port.trim() === '' && f.rulesets.length === 0 && f.proto.trim() === ''
+  )
+}
+
 /** Effective routing target for a rule (Target wins; a bare Egress is a target too). */
 function effectiveTarget(r: RRule): string {
   if (r.Target && r.Target.trim()) return r.Target.trim()
@@ -262,16 +324,19 @@ interface TargetGroups {
   nodes: TargetOpt[] // node:<n> (huge — rendered last)
 }
 
-// Free-text destination matchers offered by the ADD form. Domains are NOT one of
-// them (the user's call): domain matching goes through named rulesets — that's
-// what they exist for. 'none' = the rule matches by rulesets/source/proto alone.
-// (Legacy rules that already carry DstDomain stay editable in the edit form.)
-type MatchKind = 'none' | 'ip' | 'port'
+// The add form's fields. WHERE traffic is going is a ruleset choice and nothing
+// else — a rule has no inline domain or address list any more, so the old
+// Match-kind picker (rulesets / ip / port) collapsed into a plain Port field
+// beside the ruleset picker. The cost is real and accepted: routing a single
+// domain is no longer done here — you leave for the Rulesets panel, create the
+// list, fill it, and come back to check it. A "create a list from here" shortcut
+// was proposed and rejected (DECISIONS.md D21): a second place to author a list
+// is a second place for its entry semantics and duplicate-name rules to drift,
+// which is the exact thing D21 removed.
 interface AddForm {
   name: string
   src: string[]
-  matchKind: MatchKind
-  matchValue: string
+  port: string
   rulesets: string[]
   proto: string
   target: string
@@ -283,8 +348,7 @@ interface AddForm {
 const EMPTY_FORM: AddForm = {
   name: '',
   src: [],
-  matchKind: 'none',
-  matchValue: '',
+  port: '',
   rulesets: [],
   proto: '',
   target: 'direct',
@@ -317,6 +381,7 @@ const browserTZName = (): string => {
 }
 
 export default function Routing() {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<Model | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
   const [actionError, setActionError] = useState<string | null>(null)
@@ -334,6 +399,22 @@ export default function Routing() {
     toastTimer.current = window.setTimeout(() => setToast(null), 2600)
   }, [])
 
+  // Which rules can never fire, keyed by their position in the model's Rules array
+  // — NOT by name. The config that made this necessary had two rules both called
+  // `default`, which is exactly when a name-keyed verdict badges the wrong row.
+  const [reach, setReach] = useState<Map<number, RuleReach>>(new Map())
+  const loadReach = useCallback(async () => {
+    try {
+      const { rules } = await getRulesReachability()
+      setReach(new Map(rules.map((r) => [r.index, r])))
+    } catch {
+      // An older daemon has no such endpoint, and a stopped one answers nothing.
+      // Drop the verdicts rather than keep stale ones: no badge is honest, a badge
+      // about the previous config is not.
+      setReach(new Map())
+    }
+  }, [])
+
   const load = useCallback(async () => {
     try {
       setLoadError(null)
@@ -341,7 +422,8 @@ export default function Routing() {
     } catch (e) {
       setLoadError(errMsg(e))
     }
-  }, [])
+    void loadReach()
+  }, [loadReach])
   useEffect(() => {
     void load()
   }, [load])
@@ -407,6 +489,71 @@ export default function Routing() {
   // Every rule name, for the edit form's duplicate-name guard (it excludes self).
   const ruleNames = useMemo(() => new Set(rules.map((r) => r.Name)), [rules])
 
+  // Each rule's position in the model's Rules array — the key the daemon's
+  // reachability verdicts use. `rules` above is a sorted COPY of the same object
+  // references, so identity survives the sort and this map stays valid.
+  const modelIndex = useMemo(() => {
+    const m = new Map<RRule, number>()
+    ;((config?.Rules as RRule[] | null | undefined) ?? []).forEach((r, i) => m.set(r, i))
+    return m
+  }, [config])
+
+  /**
+   * The daemon's verdict for one rule, or null when we have none that describes it.
+   *
+   * Verdicts are fetched separately from the config, so between an optimistic edit
+   * and the refetch they can describe the PREVIOUS rule list. Re-checking the
+   * echoed name and order is what stops that window from putting a "never applies"
+   * badge on a working rule: a mismatch means the verdict is not about this row,
+   * and no badge is the honest answer.
+   */
+  const verdictOf = useCallback(
+    (r: RRule): RuleReach | null => {
+      const i = modelIndex.get(r)
+      if (i === undefined) return null
+      const v = reach.get(i)
+      if (!v || v.name !== r.Name || v.order !== r.Order) return null
+      return v
+    },
+    [modelIndex, reach],
+  )
+
+  const shadowOf = useCallback(
+    (r: RRule): { by: string; byOrder: number; reason: string } | null => {
+      const v = verdictOf(r)
+      if (!v || !v.unreachable || !v.shadowed_by) return null
+      return { by: v.shadowed_by, byOrder: v.shadowed_by_order ?? 0, reason: v.reason ?? '' }
+    },
+    [verdictOf],
+  )
+
+  /**
+   * Whether a rule is IN FORCE, and who decided that — the two states this page
+   * used to conflate.
+   *
+   * `Rule.Enabled` from /api/config is the DESIRED state: what the operator saved,
+   * what the switch edits, what gets PUT back. The active WAN profile can override
+   * it in either direction, and then the desired state is no longer what the router
+   * is doing. Drawing the row from `Enabled` is what let a config with two rules
+   * `enabled '1'` show two live switches while the engine ran one chain.
+   *
+   * With no verdict — an older daemon, a stopped one, or one still describing the
+   * previous config — the desired state is all we know, so the row falls back to it
+   * and claims no profile rather than inventing one. The `typeof` guard is for the
+   * older daemon specifically: it answers without `effective_enabled` at all, and
+   * reading `undefined` as false would gray out every rule on the page.
+   */
+  const forceOf = useCallback(
+    (r: RRule): RuleForce => {
+      const v = verdictOf(r)
+      if (!v || typeof v.effective_enabled !== 'boolean') {
+        return { on: !!r.Enabled, profile: null, dir: null }
+      }
+      return { on: v.effective_enabled, profile: v.overridden_by ?? null, dir: v.override ?? null }
+    },
+    [verdictOf],
+  )
+
   // Rulesets are named domain/IP lists rules match against (rule.DstRuleset).
   const rulesets = useMemo<Ruleset[]>(
     () => [...((config?.Rulesets as Ruleset[] | null | undefined) ?? [])],
@@ -458,6 +605,10 @@ export default function Routing() {
         await putConfig(next)
         setSavedPending(true)
         flash(okMsg)
+        // The verdicts describe the config on disk, which just changed — re-ask.
+        // Adding or moving a rule is precisely what turns a working default into a
+        // superseded one, and vice versa.
+        void loadReach()
       } catch (e) {
         setConfig(prev)
         setActionError(errMsg(e))
@@ -466,7 +617,7 @@ export default function Routing() {
         setSaving(false)
       }
     },
-    [config, flash],
+    [config, flash, loadReach],
   )
 
   const commitRules = useCallback(
@@ -503,13 +654,17 @@ export default function Routing() {
   // Delete the ruleset AND strip its name from any rule that referenced it, so no
   // rule is left pointing at a matcher that no longer exists (one atomic persist).
   const deleteRuleset = useCallback(
-    (name: string) => {
+    async (name: string) => {
       if (!config) return
       const used = rulesetUsage.get(name) ?? 0
-      const warn = used
-        ? `Delete ruleset "${name}"? It'll be removed from ${used} rule${used === 1 ? '' : 's'} that match it.`
-        : `Delete ruleset "${name}"?`
-      if (!window.confirm(warn)) return
+      const ok = await confirm({
+        label: 'Delete ruleset',
+        title: `Delete ruleset "${name}"?`,
+        body: used
+          ? `It'll be removed from ${used} rule${used === 1 ? '' : 's'} that match it.`
+          : undefined,
+      })
+      if (!ok) return
       const nextRulesets = rulesets.filter((r) => r.Name !== name)
       const nextRules = rules.map((r) => {
         const cur = r.DstRuleset ?? []
@@ -520,7 +675,7 @@ export default function Routing() {
         `ruleset ${name} deleted`,
       )
     },
-    [config, rules, rulesets, rulesetUsage, persist],
+    [config, rules, rulesets, rulesetUsage, persist, confirm],
   )
 
   const onToggle = useCallback(
@@ -560,17 +715,26 @@ export default function Routing() {
   )
 
   const onDelete = useCallback(
-    (name: string) => {
-      if (!window.confirm(`Delete rule "${name}"? Traffic it matched will fall through to the next rule.`)) return
+    async (name: string) => {
+      const ok = await confirm({
+        label: 'Delete rule',
+        title: `Delete rule "${name}"?`,
+        body: 'Traffic it matched will fall through to the next rule.',
+      })
+      if (!ok) return
       commitRules(
         rules.filter((r) => r.Name !== name),
         `${name} deleted`,
       )
     },
-    [rules, commitRules],
+    [rules, commitRules, confirm],
   )
 
   // Insert a new rule just above the catch-all (so a specific rule can actually match).
+  // isCatchAll() is false for an unmigrated rule, which is the right answer here too:
+  // such a rule is held disabled and owns no default route, so there is nothing to
+  // insert ahead of — the new rule simply goes last, where a rule with no matchers
+  // does become the default.
   const nextOrder = useCallback((): { order: number; bumpCatchAll?: { name: string; order: number } } => {
     if (rules.length === 0) return { order: 10 }
     const last = rules[rules.length - 1]
@@ -622,18 +786,15 @@ export default function Routing() {
         return
       }
       setFormError(null)
-      const mv = form.matchValue.trim()
       const rule: RRule = {
         Name: name,
         Enabled: true,
         Order: 0,
         Src: form.src,
-        // Domains are matched via rulesets only — the add form has no free-text
-        // domain matcher by design.
-        DstDomain: [],
+        // Destination = rulesets, always. Domains and addresses live in a
+        // `config ruleset` so one list serves every rule that needs it.
         DstRuleset: form.rulesets,
-        DstIP: form.matchKind === 'ip' ? csv(mv) : [],
-        DstPort: form.matchKind === 'port' ? mv : '',
+        DstPort: form.port.trim(),
         Proto: form.proto,
         Target: form.target,
         Egress: '',
@@ -704,7 +865,14 @@ export default function Routing() {
     )
   }
 
-  const enabledCount = rules.filter((r) => r.Enabled).length
+  // One force verdict per displayed rule, computed once and handed down — the row,
+  // the counter and the banner must all be reading the SAME answer.
+  const force = rules.map((r) => forceOf(r))
+  // EFFECTIVE, not configured. A counter that added up saved switches said "2 / 2
+  // active" for a config the router was running one rule of.
+  const enabledCount = force.filter((f) => f.on).length
+  const overridden = force.filter((f) => f.profile !== null)
+  const overrideProfile = overridden[0]?.profile ?? null
 
   return (
     <section className="page" aria-label="Routing rules">
@@ -713,12 +881,28 @@ export default function Routing() {
           Rules run top to bottom on the bus — the <strong>first match wins</strong>. Traffic that
           reaches the bottom follows the default route.
         </p>
-        <span className="rt-count mono" aria-label={`${enabledCount} of ${rules.length} rules active`}>
+        <span className="rt-count mono" aria-label={`${enabledCount} of ${rules.length} rules in force`}>
           {enabledCount}
-          <small> / {rules.length} active</small>
+          <small> / {rules.length} in force</small>
         </span>
       </div>
 
+      {/* Said once at the top, so the per-row badges below read as consequences of
+          one thing rather than as N unrelated oddities. Only shown when a profile
+          actually changed something: a router that uses no profiles, or one whose
+          profile agrees with every saved switch, gets no banner at all. */}
+      {overrideProfile && (
+        <p className="rt-prof-banner" role="status">
+          <span className="rt-prof-tag mono">profile</span>
+          <span>
+            <strong className="mono">{overrideProfile}</strong> is the active WAN profile and is
+            overriding {overridden.length === 1 ? '1 rule' : `${overridden.length} rules`} below. The
+            switches keep showing what you saved; the rows show what the router is running. Change
+            which rules a profile forces on the <strong>Profiles</strong> page.
+          </span>
+        </p>
+      )}
+
       {actionError && (
         <p className="page-error" role="alert">
           {actionError}
@@ -737,14 +921,18 @@ export default function Routing() {
       {rules.length === 0 ? (
         <div className="rt-empty">
           <p>No rules — all traffic follows the default route.</p>
-          <p className="rt-empty-sub">Add a rule below to steer a domain, address, or port.</p>
+          <p className="rt-empty-sub">Add a rule below to steer a destination list, source, or port.</p>
         </div>
       ) : (
         <ol className="rt-list" aria-label="Routing rules in first-match order">
           {rules.map((r, i) =>
             editingRule === r.Name ? (
               <RuleEditForm
-                key={r.Name}
+                // Rule names are NOT unique in the wild — the config that prompted
+                // the never-applies badge had two rules called `default`, and a
+                // duplicate React key makes the second row shadow the first. The
+                // model index disambiguates without changing row identity.
+                key={`${modelIndex.get(r) ?? i}:${r.Name}`}
                 initial={r}
                 names={ruleNames}
                 targets={targets}
@@ -755,12 +943,14 @@ export default function Routing() {
               />
             ) : (
               <RuleRow
-                key={r.Name}
+                key={`${modelIndex.get(r) ?? i}:${r.Name}`}
                 rule={r}
                 index={i}
                 total={rules.length}
                 busy={saving}
                 editingOther={editingRule !== null}
+                shadow={shadowOf(r)}
+                force={force[i]}
                 onEdit={onEditRule}
                 onToggle={onToggle}
                 onMove={onMove}
@@ -810,6 +1000,8 @@ function RuleRow({
   total,
   busy,
   editingOther,
+  shadow,
+  force,
   onEdit,
   onToggle,
   onMove,
@@ -820,6 +1012,11 @@ function RuleRow({
   total: number
   busy: boolean
   editingOther: boolean
+  /** Set when the daemon reports this rule can never fire; null when it can. */
+  shadow: { by: string; byOrder: number; reason: string } | null
+  /** Whether the rule is IN FORCE, and which profile decided that (see RuleForce).
+   *  Every mark on this row comes from here; `rule.Enabled` drives only the switch. */
+  force: RuleForce
   onEdit: (name: string) => void
   onToggle: (name: string) => void
   onMove: (name: string, dir: 'up' | 'down') => void
@@ -829,16 +1026,32 @@ function RuleRow({
   // the first-match order can't shift under the open form. Edit itself stays live —
   // clicking it just swaps which row is being edited.
   const frozen = busy || editingOther
-  const isDefault = isCatchAll(rule)
+  // A rule with no conditions is the router's default — but only ONE of them can
+  // be, and the daemon says which. A superseded one must not wear the default's
+  // marks (the dashed accent frame, the "· final" order chip, the "everything not
+  // matched above" line): those are the claim that made two `default` rules
+  // indistinguishable in the first place.
+  const dead = shadow !== null
+  // The unmigrated-rule tripwire (see RRule.LegacyDst / model.IsCatchAll): this
+  // rule's destination is still in the removed schema-v1 options, so the daemon
+  // holds it disabled. It is NOT an ordinary disabled rule — nobody switched it
+  // off — so it gets the same "wired but not connected" amber treatment as a
+  // shadowed rule, plus a badge and a line saying what to run. isCatchAll()
+  // already refuses to call it the default, so `final` marks cannot land here.
+  const legacyDst = (rule.LegacyDst ?? []).filter(Boolean)
+  const unmigrated = legacyDst.length > 0
+  const inert = dead || unmigrated
+  const isDefault = isCatchAll(rule) && !dead
   const target = effectiveTarget(rule)
   const tone = targetTone(target)
-  const cls = [
-    'rt-rule',
-    rule.Enabled ? '' : 'off',
-    isDefault ? 'final' : '',
-  ]
+  // Dimmed by the EFFECTIVE state, never by the saved one. A rule the active
+  // profile switched off is not in force, and the row has to read that way even
+  // though its switch — which edits the saved setting — is still on.
+  const cls = ['rt-rule', force.on ? '' : 'off', isDefault ? 'final' : '', inert ? 'dead' : '']
     .filter(Boolean)
     .join(' ')
+  // What the switch says, spelled out, for the moment the two disagree.
+  const savedState = rule.Enabled ? 'on' : 'off'
 
   return (
     <li className={cls}>
@@ -852,7 +1065,7 @@ function RuleRow({
         >
           ▲
         </button>
-        <span className={isDefault ? 'rt-ord final' : 'rt-ord'}>
+        <span className={isDefault ? 'rt-ord final' : inert ? 'rt-ord dead' : 'rt-ord'}>
           {isDefault ? '·' : rule.Order}
         </span>
         <button
@@ -870,14 +1083,56 @@ function RuleRow({
         <div className="rt-head">
           <span className="rt-name">{rule.Name}</span>
           {isDefault && <span className="rt-badge">default route · final</span>}
+          {unmigrated && <span className="rt-badge dead">held off · not migrated</span>}
+          {dead && <span className="rt-badge dead">never applies</span>}
+          {/* Amber for the rule the profile switched OFF (warn semantics: wired but
+              not connected), accent for the one it switched ON — orange is the
+              faceplate's active state, and a force-enabled rule is exactly that. */}
+          {force.dir === 'disabled' && <span className="rt-badge dead">off · by profile</span>}
+          {force.dir === 'enabled' && <span className="rt-badge prof-on">on · by profile</span>}
         </div>
         <div className="rt-match">
-          {isDefault ? (
+          {unmigrated ? (
+            // Why the rule is off and what fixes it. Same voice as the shadow note:
+            // state, cause, one command. The daemon says the same thing through the
+            // apply warnings (model.ValidateRules); this puts it on the row it is about.
+            <span className="rt-dead-note">
+              Destination still written the old way (<span className="mono">{legacyDst.join(', ')}</span>
+              ) — this config was never migrated, so shaterd cannot read where this rule sends
+              traffic and holds it disabled. Run <span className="mono">shaterd migrate</span> on the
+              router to turn those entries into a ruleset, then enable the rule again.
+            </span>
+          ) : dead ? (
+            // The badge says it never fires; this line says what beat it and what to
+            // do. Visible text, not a tooltip — the operator has to be able to find
+            // the other rule, and two rows can carry the same name.
+            <span className="rt-dead-note" title={shadow.reason}>
+              “{shadow.by}” (order {shadow.byOrder}) has no conditions either and runs after this
+              one, so it is the default the router uses. Give this rule a condition, or delete one
+              of the two.
+            </span>
+          ) : isDefault ? (
             <span className="rt-nomatch">everything not matched above</span>
           ) : (
             <Matchers rule={rule} />
           )}
         </div>
+        {/* Added BELOW the matchers, not instead of them: the rule's conditions are
+            still worth reading — the operator is deciding whether to change the
+            profile or the rule.
+            Two clauses only. The banner at the top of the page already carries the
+            general explanation and the way to change it, and a profile that
+            overrides several rules would otherwise repeat that paragraph on every
+            one of them. What is left is the part only this row can say: whether it
+            is in force, and what its own switch is showing instead. */}
+        {force.profile && (
+          <p className="rt-dead-note rt-prof-note">
+            {force.dir === 'disabled' ? 'Not in force' : 'In force'} — profile{' '}
+            <strong className="mono">{force.profile}</strong> switches this rule{' '}
+            {force.dir === 'disabled' ? 'off' : 'on'}. The switch still reads{' '}
+            <strong>{savedState}</strong>: that is the saved setting.
+          </p>
+        )}
       </div>
 
       <div className={`rt-target ${tone}`} title={`target: ${target}`}>
@@ -897,12 +1152,40 @@ function RuleRow({
         >
           Edit
         </button>
-        <Toggle
-          pressed={rule.Enabled}
-          onChange={() => onToggle(rule.Name)}
-          label={`${rule.Enabled ? 'Disable' : 'Enable'} rule ${rule.Name}`}
-          disabled={frozen}
-        />
+        {/* An unmigrated rule cannot be switched on from here, and the switch says
+            so rather than pretending: the daemon holds it disabled, but a config
+            write from the panel DROPS the unreadable legacy options (render.go
+            emits neither), so enabling it here would save a live rule with no
+            destination left at all — the catch-all this tripwire exists to
+            prevent. `shaterd migrate` clears LegacyDst and the switch comes back. */}
+        {/* The switch edits the SAVED setting and nothing else, so it keeps showing
+            rule.Enabled even while the active profile forces the opposite. Mirroring
+            the effective state here would be worse than the bug it replaces: the
+            operator would flip a switch that was never theirs, and the PUT would
+            write the profile's decision into UCI as if they had chosen it. The row
+            above says what the router is doing; the "saved" caption says what this
+            control is for. */}
+        <span className="rt-switch">
+          <Toggle
+            pressed={rule.Enabled}
+            onChange={() => onToggle(rule.Name)}
+            label={
+              unmigrated
+                ? `Rule ${rule.Name} is held disabled until the config is migrated`
+                : force.profile
+                  ? `Saved setting for rule ${rule.Name} is ${savedState}; profile ${force.profile} is forcing it ${
+                      force.dir === 'disabled' ? 'off' : 'on'
+                    }. This switch changes the saved setting only.`
+                  : `${rule.Enabled ? 'Disable' : 'Enable'} rule ${rule.Name}`
+            }
+            disabled={frozen || unmigrated}
+          />
+          {force.profile && (
+            <span className="rt-switch-note" aria-hidden="true">
+              saved
+            </span>
+          )}
+        </span>
         <button
           type="button"
           className="rt-del"
@@ -935,9 +1218,7 @@ function Matchers({ rule }: { rule: RRule }): ReactNode {
     )
   }
   listChip('src', rule.Src, 'src')
-  listChip('dns', rule.DstDomain, 'dom')
   listChip('ruleset', rule.DstRuleset, 'rs')
-  listChip('ip', rule.DstIP, 'ip')
   if (rule.DstPort && rule.DstPort.trim()) {
     chips.push(
       <span className="rt-chip" key="port">
@@ -1053,7 +1334,16 @@ function TargetOptions({ targets, current }: { targets: TargetGroups; current?:
   )
 }
 
-/** The dst_ruleset checkbox group. Renders nothing when no rulesets exist. */
+/**
+ * The destination picker: which rulesets this rule matches (dst_ruleset).
+ *
+ * Checkboxes and nothing else. This is the ONLY way a rule names a destination,
+ * so it renders even when the config has no lists yet — an empty picker that says
+ * where lists come from is the honest answer, and hiding it would leave the rule
+ * form with no destination control at all. Building and filling a list is the
+ * Rulesets panel's job, deliberately kept out of the rule editor so a list is
+ * created in exactly one place.
+ */
 function RulesetPicker({
   options,
   selected,
@@ -1065,24 +1355,26 @@ function RulesetPicker({
   busy: boolean
   onToggle: (name: string) => void
 }): ReactNode {
-  if (options.length === 0) return null
   return (
     <div className="rt-rsel">
-      <span className="rt-flabel">Match rulesets — dst_ruleset</span>
-      <div className="rt-rsel-opts" role="group" aria-label="Match these rulesets">
-        {options.map((n) => {
-          const on = selected.includes(n)
-          return (
-            <label key={n} className={on ? 'rt-rsel-opt on' : 'rt-rsel-opt'}>
-              <input type="checkbox" checked={on} onChange={() => onToggle(n)} disabled={busy} />
-              <span className="mono">{n}</span>
-            </label>
-          )
-        })}
-      </div>
+      <span className="rt-flabel">Destination — dst_ruleset</span>
+      {options.length > 0 && (
+        <div className="rt-rsel-opts" role="group" aria-label="Match these rulesets">
+          {options.map((n) => {
+            const on = selected.includes(n)
+            return (
+              <label key={n} className={on ? 'rt-rsel-opt on' : 'rt-rsel-opt'}>
+                <input type="checkbox" checked={on} onChange={() => onToggle(n)} disabled={busy} />
+                <span className="mono">{n}</span>
+              </label>
+            )
+          })}
+        </div>
+      )}
       <p className="rt-rsel-hint">
-        The rule also matches any traffic in the checked list(s). Combine with a domain, address, or
-        port, or use a ruleset on its own.
+        {options.length === 0
+          ? 'No rulesets yet. Add one under Rulesets below, then come back and check it here — a rule matches a destination through a ruleset only.'
+          : 'The rule matches traffic in ANY checked list. Narrow it further with a source, port or protocol.'}
       </p>
     </div>
   )
@@ -1208,7 +1500,14 @@ function AddRule({
     set('rulesets', form.rulesets.includes(n) ? form.rulesets.filter((x) => x !== n) : [...form.rulesets, n])
   const toggleDay = (d: string) =>
     set('schedDays', form.schedDays.includes(d) ? form.schedDays.filter((x) => x !== d) : [...form.schedDays, d])
-  const matchPlaceholder = form.matchKind === 'ip' ? '10.0.0.0/8, 100.64.0.0/10' : '443, 8080-8090'
+
+  // Same flag as the edit form, from the same predicate: no matcher = this rule
+  // asks to be route.Final. Whether it wins depends on what is last — it takes
+  // the default when there is no catch-all yet (or the last rule is conditional),
+  // and lands dead when there is one, because nextOrder() inserts ahead of it.
+  // Both are worth flagging, so the text states the fact and not the outcome.
+  // Shown, never blocking: a default route is a legal thing to write.
+  const noMatchers = formHasNoMatchers(form)
 
   return (
     <form className="rt-add" onSubmit={onSubmit} aria-label="Add a routing rule">
@@ -1241,32 +1540,17 @@ function AddRule({
         </label>
 
         <label className="rt-field">
-          <span className="rt-flabel">Match</span>
-          <select
+          <span className="rt-flabel">Port(s)</span>
+          <input
             className="rt-input mono"
-            value={form.matchKind}
-            onChange={(e) => set('matchKind', e.target.value as MatchKind)}
-          >
-            <option value="none">rulesets only</option>
-            <option value="ip">ip / cidr</option>
-            <option value="port">port</option>
-          </select>
+            value={form.port}
+            onChange={(e) => set('port', e.target.value)}
+            placeholder="443, 8080-8090"
+            autoComplete="off"
+            spellCheck={false}
+          />
         </label>
 
-        {form.matchKind !== 'none' && (
-          <label className="rt-field rt-field-wide">
-            <span className="rt-flabel">{form.matchKind === 'port' ? 'Port(s)' : 'Address(es)'}</span>
-            <input
-              className="rt-input mono"
-              value={form.matchValue}
-              onChange={(e) => set('matchValue', e.target.value)}
-              placeholder={matchPlaceholder}
-              autoComplete="off"
-              spellCheck={false}
-            />
-          </label>
-        )}
-
         <label className="rt-field">
           <span className="rt-flabel">Proto</span>
           <select
@@ -1313,6 +1597,9 @@ function AddRule({
         <Button type="submit" variant="primary" disabled={busy}>
           {busy ? 'Saving…' : 'Add rule'}
         </Button>
+        {noMatchers && !error && (
+          <span className="rt-edit-warn">no matchers — matches everything</span>
+        )}
         {error && (
           <span className="rt-add-error" role="alert">
             {error}
@@ -1324,11 +1611,11 @@ function AddRule({
 }
 
 // --- edit-a-rule plate (inline, replaces the row it edits) ------------------
-// Unlike AddRule, editing exposes all three destination matchers at once
-// (Domain(s) / IP-CIDR(s) / Port) rather than a single Match picker — a real rule
-// can carry several matcher kinds simultaneously and none may be silently dropped.
-// The full original rule is spread into the result on save, so Order / Enabled /
-// Kill / Egress (and anything else off-form) survive untouched.
+// Same fields as AddRule, on purpose: a rule carries exactly one destination
+// mechanism (rulesets) plus port/proto/source, so there is nothing an edit can
+// reveal that the add form hides. The full original rule is spread into the
+// result on save, so Order / Enabled / Kill / Egress (and anything else off-form)
+// survive untouched.
 function RuleEditForm({
   initial,
   names,
@@ -1348,8 +1635,6 @@ function RuleEditForm({
 }) {
   const [name, setName] = useState(initial.Name)
   const [src, setSrc] = useState<string[]>([...(initial.Src ?? [])])
-  const [domain, setDomain] = useState((initial.DstDomain ?? []).join(', '))
-  const [ip, setIp] = useState((initial.DstIP ?? []).join(', '))
   const [port, setPort] = useState(initial.DstPort ?? '')
   const [proto, setProto] = useState(initial.Proto ?? '')
   const [target, setTarget] = useState(effectiveTarget(initial))
@@ -1365,14 +1650,15 @@ function RuleEditForm({
   const toggleDay = (d: string) =>
     setSchedDays((cur) => (cur.includes(d) ? cur.filter((x) => x !== d) : [...cur, d]))
 
+  // This rule's destination may still be in the schema-v1 options (RRule.LegacyDst).
+  // The form cannot show or edit them — they are not fields any more — and saving
+  // writes the model back through render.go, which does not emit them. So a save
+  // here silently DISCARDS that destination. Say so before it happens; the fix is
+  // `shaterd migrate`, which converts them into a ruleset this form can check.
+  const legacyDst = (initial.LegacyDst ?? []).filter(Boolean)
+
   // A rule with no matcher of any kind is a catch-all — legal, but worth flagging.
-  const noMatchers =
-    src.length === 0 &&
-    csv(domain).length === 0 &&
-    csv(ip).length === 0 &&
-    port.trim() === '' &&
-    rulesets.length === 0 &&
-    proto.trim() === ''
+  const noMatchers = formHasNoMatchers({ src, port, rulesets, proto })
 
   const submit = (e: FormEvent) => {
     e.preventDefault()
@@ -1394,8 +1680,6 @@ function RuleEditForm({
       ...initial,
       Name: nm,
       Src: src,
-      DstDomain: csv(domain),
-      DstIP: csv(ip),
       DstPort: port.trim(),
       DstRuleset: rulesets,
       Proto: proto,
@@ -1414,7 +1698,15 @@ function RuleEditForm({
       <form className="rt-add rt-edit-form" onSubmit={submit} aria-label={`Edit rule ${initial.Name}`}>
         <div className="rt-add-hd">
           <span className="rt-add-title">Edit {initial.Name}</span>
-          <span className="rt-add-sub">Empty a field to drop that matcher. Save, then Apply.</span>
+          <span className="rt-add-sub">
+            Uncheck a list or clear a field to drop that matcher. Save, then Apply.
+          </span>
+          {legacyDst.length > 0 && (
+            <span className="rt-edit-warn">
+              not migrated — saving discards its old destination ({legacyDst.join(', ')}); run
+              shaterd migrate first
+            </span>
+          )}
         </div>
 
         <div className="rt-fields">
@@ -1444,37 +1736,6 @@ function RuleEditForm({
             />
           </label>
 
-          {/* Domains are matched via rulesets by design — this legacy field only
-              appears when the rule ALREADY carries free-text domains, so they
-              stay visible and clearable rather than silently preserved. */}
-          {(initial.DstDomain ?? []).length > 0 && (
-            <label className="rt-field rt-field-wide">
-              <span className="rt-flabel">Domain(s) — legacy</span>
-              <input
-                className="rt-input mono"
-                value={domain}
-                onChange={(e) => setDomain(e.target.value)}
-                placeholder="youtube.com, *.googlevideo.com"
-                autoComplete="off"
-                spellCheck={false}
-                disabled={busy}
-              />
-            </label>
-          )}
-
-          <label className="rt-field rt-field-wide">
-            <span className="rt-flabel">IP / CIDR(s)</span>
-            <input
-              className="rt-input mono"
-              value={ip}
-              onChange={(e) => setIp(e.target.value)}
-              placeholder="10.0.0.0/8, 100.64.0.0/10"
-              autoComplete="off"
-              spellCheck={false}
-              disabled={busy}
-            />
-          </label>
-
           <label className="rt-field">
             <span className="rt-flabel">Port(s)</span>
             <input

panel/src/pages/Targets.css

@@ -704,6 +704,13 @@
 .tg-test--bad .tg-test-msg {
   color: var(--crit);
 }
+/* "Nothing measured this" is not a failure and must never be dressed as one: an
+   unlit lamp and the faintest text on the card, the same register the group
+   readout uses for its unmeasured state. */
+.tg-test--none .tg-test-msg {
+  font-family: var(--font-sans);
+  color: var(--faint);
+}
 .tg-test--wait .tg-test-msg {
   color: var(--amber);
 }
@@ -1038,6 +1045,235 @@
 }
 
 /* ---- responsive ---- */
+/* ---- chain hop rail ----
+ * The chain section's signature, and the one place this card spends any
+ * boldness: the path is drawn as a CONDUCTOR with a numbered lamp at each hop,
+ * and the conductor is SEVERED below the first hop that was probed and did not
+ * answer. A chain is a single series path, so the question is never "how many
+ * hops are green", it is "where does my traffic stop" — and a broken line answers
+ * that before a word has been read.
+ *
+ * The two marks carry two different facts and must not be conflated:
+ *   - the LAMP is that hop's own measurement (good / warn / crit / unlit). Below
+ *     the break there is no measurement to draw: the daemon stops walking at the
+ *     first dead hop, so those lamps are UNLIT and the row says which hop stopped
+ *     the walk. Unlit is never a shade of red — it claims nothing, which is the
+ *     truth about a hop nobody dialled;
+ *   - the CONDUCTOR is reachability through the path, which really does stop.
+ *
+ * Orange is untouched here. Semantics carry every colour, and everything that is
+ * not a lamp is groove-grey. No transitions and no animation anywhere in the
+ * rail, so there is nothing for reduced-motion to switch off. */
+.ch-rail {
+  gap: 8px;
+}
+.ch-eyebrow {
+  font-family: var(--font-mono);
+  font-size: 9px;
+  letter-spacing: var(--track-label);
+  text-transform: uppercase;
+  color: var(--faint);
+}
+.ch-hops {
+  --ch-num: 1.8ch; /* the engraved hop number's gutter */
+  --ch-gap: 8px;
+  --ch-led: 10px; /* must match .led's width */
+  --ch-lampy: 14px; /* row top → lamp centre; the conductor's anchor */
+  /* x of the conductor: the number gutter, one gap, then the lamp's centre */
+  --ch-spine: calc(var(--ch-num) + var(--ch-gap) + var(--ch-led) / 2);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.ch-hop {
+  position: relative;
+  display: grid;
+  grid-template-columns: var(--ch-num) var(--ch-led) minmax(0, 1fr);
+  column-gap: var(--ch-gap);
+  align-items: start;
+}
+
+/* the conductor — two halves per row, so a break lands on one link only */
+.ch-hop::before,
+.ch-hop::after {
+  content: '';
+  position: absolute;
+  left: var(--ch-spine);
+  width: 2px;
+  margin-left: -1px;
+  /* Brighter than a plain groove: this line IS the readout, and at groove
+     strength it disappeared into the panel and took the whole idea with it. */
+  background: color-mix(in srgb, var(--dim) 55%, var(--groove));
+}
+.ch-hop::before {
+  top: 0;
+  height: calc(var(--ch-lampy) - var(--ch-led) / 2 - 3px);
+}
+.ch-hop::after {
+  top: calc(var(--ch-lampy) + var(--ch-led) / 2 + 3px);
+  bottom: 0;
+}
+/* Nothing feeds hop 1 from above, and nothing leaves the exit downward — the
+   path starts and ends inside this rail. */
+.ch-hop--first::before {
+  display: none;
+}
+.ch-hop--exit::after {
+  bottom: auto;
+  height: 9px;
+}
+/* …the exit ends on a crossbar instead of trailing off: end of line. */
+.ch-hop--exit .ch-socket {
+  position: relative;
+}
+.ch-hop--exit .ch-socket::after {
+  content: '';
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  top: calc(var(--ch-lampy) + var(--ch-led) / 2 + 12px);
+  width: 11px;
+  height: 2px;
+  background: color-mix(in srgb, var(--dim) 55%, var(--groove));
+}
+
+/* THE SEVER. Everything from the dead hop's outgoing link downward is drawn as a
+   broken conductor: unmistakably not-a-line at a glance, and unmistakably not a
+   colour, because a colour here would compete with the lamps that carry health. */
+.ch-hop--dead::after,
+.ch-hop--severed::before,
+.ch-hop--severed::after {
+  background: repeating-linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--dim) 45%, var(--groove)) 0 3px,
+    transparent 3px 7px
+  );
+}
+
+.ch-num {
+  font-size: 10px;
+  line-height: calc(var(--ch-lampy) * 2);
+  text-align: right;
+  color: var(--faint);
+}
+.ch-socket {
+  display: flex;
+  align-items: center;
+  height: calc(var(--ch-lampy) * 2);
+}
+.ch-body {
+  min-width: 0;
+  /* Separates one hop from the next. The conductor runs through this space, so
+     too little of it and two hops read as one wrapped row. */
+  padding-bottom: 8px;
+}
+.ch-l1 {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  min-height: calc(var(--ch-lampy) * 2);
+}
+.ch-name {
+  font-size: 12px;
+  color: var(--ink);
+  overflow-wrap: anywhere;
+}
+.ch-hop--untested .ch-name {
+  color: var(--dim);
+}
+/* The exit marker is NEUTRAL on purpose. The config path above this rail tags its
+   exit green, which is free there — but in here green means "answering", and a
+   green badge on the last hop would read as a health claim about it. */
+.ch-tag {
+  font-family: var(--font-mono);
+  font-size: 8.5px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--faint);
+}
+.ch-delay {
+  font-size: 11.5px;
+  font-weight: 700;
+  color: var(--ink);
+}
+.ch-quiet {
+  font-family: var(--font-sans);
+  font-size: 12px;
+  color: var(--faint);
+}
+/* A blocked hop's phrase carries a tooltip with the blocking hop's engine
+   outbound, so it takes the same help cursor as .ch-dead. No colour of its own:
+   the finding is red once, on the hop that actually failed. */
+.ch-blocked {
+  cursor: help;
+}
+.ch-age {
+  margin-left: auto;
+  font-size: 10.5px;
+  color: var(--faint);
+  white-space: nowrap;
+}
+
+/* The counters read exactly as they do on a group card — alive out of TESTED,
+   with the untested remainder as a quiet aside only when there is one. Same
+   register, same weights, deliberately not a second dialect. */
+.ch-l2 {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 1px;
+  font-size: 11.5px;
+  letter-spacing: 0.02em;
+  color: var(--dim);
+}
+.ch-count {
+  font-size: 12px;
+  color: var(--dim);
+  white-space: nowrap;
+}
+.ch-count b {
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--ink);
+}
+.ch-hop--dead .ch-count b {
+  color: var(--crit);
+}
+.ch-word {
+  font-size: 10.5px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--faint);
+}
+.ch-dead {
+  padding: 1px 6px;
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--crit) 12%, transparent);
+  font-size: 10.5px;
+  color: var(--crit);
+  white-space: nowrap;
+  cursor: help;
+}
+.ch-rest {
+  font-size: 10.5px;
+  color: var(--faint);
+}
+/* On a blocked hop this chip says "set to", not "now": a pick nothing crossed.
+   It steps back to faint so it can't be mistaken for a live reading. */
+.ch-hop--blocked .ch-now {
+  color: var(--faint);
+}
+.ch-now {
+  max-width: 28ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 10.5px;
+  color: var(--dim);
+}
+
 @media (max-width: 640px) {
   .tg-sec-hd {
     flex-wrap: wrap;
@@ -1060,6 +1296,20 @@
   .gh-now {
     max-width: 100%;
   }
+  /* On a phone the age stamp stops being pushed to a lonely right edge and just
+     joins the end of the hop's line; the selected node gets the full width
+     instead of an ellipsis it doesn't need. */
+  .ch-age {
+    margin-left: 0;
+  }
+  .ch-now {
+    max-width: 100%;
+  }
+  /* Every field of a hop wraps onto its own line at this width, so the gap
+     between hops has to grow with them or the rail reads as one block of text. */
+  .ch-body {
+    padding-bottom: 12px;
+  }
   .gh-mems {
     max-height: 260px;
   }

panel/src/pages/Targets.tsx

@@ -1,6 +1,6 @@
 import './Targets.css'
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Button, Led, Toggle } from '../components'
+import { Button, Led, Toggle, useConfirm } from '../components'
 import type { LedVariant } from '../components'
 import {
   apply as apiApply,
@@ -22,6 +22,8 @@ import type {
   GroupTestResult,
   GroupTestStatus,
   Chain,
+  ChainHealth,
+  ChainHopHealth,
   Egress,
   Interface,
   Node,
@@ -161,18 +163,18 @@ function renameReferences(m: Model, kind: RefKind, from: string, to: string): Mo
 }
 
 /**
- * The sentence a delete confirmation appends: what still points at this target,
- * and what happens to it. Empty list ⇒ an explicit "nothing references it", so
- * the operator can delete a stray with confidence instead of guessing.
+ * The body of a delete confirmation: what still points at this target, and what
+ * happens to it. Empty list ⇒ an explicit "nothing references it", so the
+ * operator can delete a stray with confidence instead of guessing.
  */
 function refWarning(refs: RefSite[]): string {
-  if (refs.length === 0) return ' Nothing references it.'
+  if (refs.length === 0) return 'Nothing references it.'
   const shown = refs.slice(0, 4).map((r) => r.label)
   const more = refs.length - shown.length
   const list = `${shown.join(', ')}${more > 0 ? `, and ${more} more` : ''}`
   return refs.length === 1
-    ? ` It is referenced by ${list}, whose traffic will be blocked (an unresolved target never falls through to the default route).`
-    : ` It is referenced by ${refs.length} places — ${list} — whose traffic will be blocked (an unresolved target never falls through to the default route).`
+    ? `It is referenced by ${list}, whose traffic will be blocked (an unresolved target never falls through to the default route).`
+    : `It is referenced by ${refs.length} places — ${list} — whose traffic will be blocked (an unresolved target never falls through to the default route).`
 }
 
 /**
@@ -436,14 +438,14 @@ const normalizeTest = (st: GroupTestStatus): GroupTestStatus => ({
 })
 
 /**
- * How the header names the reach of a running exit test. The name matters more
+ * How the header names the reach of a running refresh pass. The name matters more
  * than the number when there is only one: "auto" tells the operator which button
  * they pressed; "1 target" tells them nothing they didn't already know.
  */
 function scopeLabel(scope: string[], targetCount: number): string {
   if (scope.length === 1) return scope[0]
-  if (scope.length === 0) return 'exits' // pre-scope daemon — say nothing false
-  return scope.length >= targetCount ? 'every exit' : `${scope.length} exits`
+  if (scope.length === 0) return 'targets' // pre-scope daemon — say nothing false
+  return scope.length >= targetCount ? 'every target' : `${scope.length} targets`
 }
 
 /** Which editor (add or edit-by-name) is open within a section. */
@@ -457,6 +459,7 @@ interface Opt {
 // ---- page ------------------------------------------------------------------
 
 export default function Targets() {
+  const confirm = useConfirm()
   const [config, setConfig] = useState<Model | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
 
@@ -589,10 +592,12 @@ export default function Targets() {
     [health],
   )
 
-  // ---- group/chain exit test: how fast, through which node, out which address --
-  // The POST only kicks a run off, and a 2 s poll of the GET carries progress
-  // plus every result so far. One endpoint covers groups and chains alike:
-  // POST with a group or chain name tests that one; an empty name tests them all.
+  // ---- out-of-turn refresh: how fast, through which node, out which address ----
+  // The POST does NOT dial. It asks the observatory — the only thing in the daemon
+  // that measures anything, and it measures along the real dial path — to come
+  // round out of turn; a 2 s poll of the GET carries progress plus every reading
+  // so far. One endpoint covers groups and chains alike: POST with a name refreshes
+  // that one, an empty name refreshes them all.
   const [gtest, setGtest] = useState<GroupTestStatus>(IDLE_TEST)
   const [gtestErr, setGtestErr] = useState<string | null>(null)
   const [polling, setPolling] = useState(false)
@@ -635,7 +640,7 @@ export default function Targets() {
       void readTest().then((st) => {
         if (!alive || !st || st.running) return
         setPolling(false)
-        flash('Group test complete')
+        flash('Readings refreshed')
       })
     }, 2000)
     return () => {
@@ -651,16 +656,16 @@ export default function Targets() {
         if (r.started) {
           setGtestErr(null)
           setPolling(true)
-          flash(name ? `Testing ${name}…` : 'Testing every exit…')
+          flash(name ? `Refreshing ${name}…` : 'Refreshing every reading…')
           void readTest()
         } else if (r.reason === 'already running') {
-          setPolling(true) // pick up the run someone else started
-          flash('A group test is already running')
+          setPolling(true) // pick up the pass someone else started
+          flash('The prober is already refreshing')
         } else {
-          flash(`Couldn’t start the test — ${r.reason || 'the daemon refused it'}`)
+          flash(`Couldn’t ask for a refresh — ${r.reason || 'the daemon refused it'}`)
         }
       } catch (e) {
-        flash(`Couldn’t start the test — ${errText(e)}`)
+        flash(`Couldn’t ask for a refresh — ${errText(e)}`)
       }
     },
     [flash, readTest],
@@ -787,13 +792,18 @@ export default function Targets() {
   )
 
   const removeGroup = useCallback(
-    (name: string) => {
+    async (name: string) => {
       if (!config) return
       const refs = findReferences(config, 'group', name)
-      if (!window.confirm(`Delete group “${name}”?${refWarning(refs)}`)) return
+      const ok = await confirm({
+        label: 'Delete group',
+        title: `Delete group “${name}”?`,
+        body: refWarning(refs),
+      })
+      if (!ok) return
       void save({ ...config, Groups: groups.filter((g) => g.Name !== name) }, `Deleted ${name}`)
     },
-    [config, groups, save],
+    [config, groups, save, confirm],
   )
 
   // ---- chain mutations ------------------------------------------------------
@@ -820,13 +830,18 @@ export default function Targets() {
   )
 
   const removeChain = useCallback(
-    (name: string) => {
+    async (name: string) => {
       if (!config) return
       const refs = findReferences(config, 'chain', name)
-      if (!window.confirm(`Delete chain “${name}”?${refWarning(refs)}`)) return
+      const ok = await confirm({
+        label: 'Delete chain',
+        title: `Delete chain “${name}”?`,
+        body: refWarning(refs),
+      })
+      if (!ok) return
       void save({ ...config, Chains: chains.filter((c) => c.Name !== name) }, `Deleted ${name}`)
     },
-    [config, chains, save],
+    [config, chains, save, confirm],
   )
 
   // ---- egress mutations -----------------------------------------------------
@@ -853,13 +868,18 @@ export default function Targets() {
   )
 
   const removeEgress = useCallback(
-    (name: string) => {
+    async (name: string) => {
       if (!config) return
       const refs = findReferences(config, 'egress', name)
-      if (!window.confirm(`Delete egress “${name}”?${refWarning(refs)}`)) return
+      const ok = await confirm({
+        label: 'Delete egress',
+        title: `Delete egress “${name}”?`,
+        body: refWarning(refs),
+      })
+      if (!ok) return
       void save({ ...config, Egresses: egresses.filter((e) => e.Name !== name) }, `Deleted ${name}`)
     },
-    [config, egresses, save],
+    [config, egresses, save, confirm],
   )
 
   const busy = saving || applying
@@ -894,10 +914,11 @@ export default function Targets() {
           <h2 className="tg-sec-title">Groups</h2>
           <span className="tg-sec-count mono">{groups.length} configured</span>
           {/* The observatory's background probing is invisible by design — it
-              keeps every used group's and chain's numbers fresh on its own. The
-              one manual run left is the exit test: it is scoped to the groups
-              and chains it names, so its progress says WHICH, and its badge
-              lands only on those cards. */}
+              keeps every used group's and chain's numbers fresh on its own, along
+              the path traffic actually takes. The one manual control left does
+              not measure anything itself: it asks that prober to come round out
+              of turn. It is scoped to the groups and chains it names, so its
+              progress says WHICH, and its badge lands only on those cards. */}
           <div className="tg-sec-ctl">
             {groupHealthOn && (
              <>
@@ -905,11 +926,11 @@ export default function Targets() {
               <span
                 className="tg-run tg-run--exit"
                 role="status"
-                title="An exit test sends one connection through each group or chain it covers and reports the delay and the address the internet sees."
+                title="The background prober is measuring the targets this refresh covers, along the path each one's traffic really takes."
               >
                 <Led variant="amber" pulse />
                 <span className="tg-run-what">
-                  exit test · {scopeLabel(asArray(gtest.scope), groups.length + chains.length)}
+                  refreshing · {scopeLabel(asArray(gtest.scope), groups.length + chains.length)}
                 </span>
                 <span className="tg-run-n mono">
                   {gtest.done}/{gtest.total}
@@ -919,9 +940,9 @@ export default function Targets() {
             <Button
               onClick={() => void runTest()}
               disabled={busy || !config || (groups.length === 0 && chains.length === 0) || gtest.running}
-              title="Send one connection through each group and chain and report the delay and the exit address the internet sees"
+              title="Ask the background prober to measure every group and chain out of turn, then show what it measured. The panel opens no connection of its own."
             >
-              {gtest.running ? 'Testing…' : 'Test every exit'}
+              {gtest.running ? 'Refreshing…' : 'Refresh every reading'}
             </Button>
              </>
             )}
@@ -941,6 +962,13 @@ export default function Targets() {
           dials out through a tunnel measures them through that tunnel, so the same node can be alive
           in one group and dead in another.
         </p>
+        <p className="tg-sec-note">
+          One thing measures, and the panel is not it. A background prober walks every path your
+          rules use — hop by hop, exactly as traffic goes — and every number on this page is a read
+          of what it found. <strong>Refresh every reading</strong> asks it to come round out of turn
+          instead of waiting for the next pass; it opens no connection of its own, so a target no
+          rule routes through has nothing to report and says so.
+        </p>
 
         {groupHealthOn && healthErr && (
           <p className="tg-test-err" role="alert">
@@ -951,7 +979,7 @@ export default function Targets() {
 
         {groupHealthOn && gtestErr && (
           <p className="tg-test-err" role="alert">
-            Couldn’t read the test results — {gtestErr}.{' '}
+            Couldn’t read the refreshed numbers — {gtestErr}.{' '}
             <button className="linkish" onClick={() => void readTest()}>
               Retry
             </button>
@@ -1094,7 +1122,9 @@ export default function Targets() {
                   chain={c}
                   busy={busy}
                   showHealth={groupHealthOn}
-                  used={healthByChain.get(c.Name)?.used}
+                  // The whole chain health record, not just `.used` — the card
+                  // renders the observatory's per-hop measurements from it.
+                  health={healthByChain.get(c.Name)}
                   test={testByGroup.get(c.Name)}
                   // The badge is this card's business only when the run names it.
                   testing={gtest.running && testScope.has(c.Name)}
@@ -1216,7 +1246,7 @@ function GroupRow({
   group: Group
   busy: boolean
   /** Group health checks are on (Settings). When false, the card drops its health
-   *  readout, its exit-test readout and its Test button — it is config only. */
+   *  readout, its end-to-end reading and its Refresh button — it is config only. */
   showHealth: boolean
   /** This group's membership health, or undefined when the engine hasn't built
    *  it (not applied yet, or dropped for having no usable members). */
@@ -1226,14 +1256,14 @@ function GroupRow({
   healthKnown: boolean
   test?: GroupTestResult
   /**
-   * A group exit test covering THIS group is in flight.
+   * A refresh pass covering THIS group is in flight.
    *
    * Deliberately not "a test is running": the caller resolves it against the run's
    * scope. There is no per-card equivalent for the health run — that one measures
    * every group at once and is reported once, in the section header.
    */
   testing: boolean
-  /** Any exit test is in flight; the daemon runs one at a time. */
+  /** Any refresh pass is in flight; the daemon runs one at a time. */
   testBusy: boolean
   onTest: () => void
   onEdit: () => void
@@ -1293,7 +1323,11 @@ function GroupRow({
               health={health}
               healthKnown={healthKnown}
             />
-            <GroupTestReadout test={test} pending={testing && !test} />
+            <GroupTestReadout
+              test={test}
+              pending={testing && !test}
+              hideAbsence={health?.used === false}
+            />
           </>
         )}
       </div>
@@ -1304,7 +1338,7 @@ function GroupRow({
         editLabel={`Edit group ${group.Name}`}
         deleteLabel={`Delete group ${group.Name}`}
         onTest={showHealth ? onTest : undefined}
-        testLabel={showHealth ? `Test the exit of group ${group.Name}` : undefined}
+        testLabel={showHealth ? `Refresh the reading for group ${group.Name}` : undefined}
         testDisabled={testBusy}
       />
     </li>
@@ -1363,21 +1397,7 @@ function GroupHealthReadout({
   // its members would stay "untested" forever. That is a fact about the ROUTING
   // CONFIG, not about the members — so instead of counters that could only ever
   // read as a permanent unknown, the card says so, quietly: unused, not unwell.
-  if (!health.used) {
-    return (
-      <div className="gh gh--unused">
-        <div className="gh-line">
-          <span
-            className="gh-unused"
-            title="No enabled rule routes through this group, so its members are not probed. Add it to a rule to see health."
-          >
-            unused
-          </span>
-          <span className="gh-quiet">not probed — no enabled rule routes through this group</span>
-        </div>
-      </div>
-    )
-  }
+  if (!health.used) return <NotRoutedNote kind="group" />
 
   const v = verdictOf(health)
   const { total, tested, alive, dead, untested } = health
@@ -1540,6 +1560,56 @@ function GroupHealthReadout({
   )
 }
 
+/**
+ * The card's answer when NOTHING ROUTES THROUGH THIS TARGET. Shared by the group
+ * card and the chain card, because it is the same misunderstanding on both.
+ *
+ * It has to carry two statements, and the old one-liner ("not probed — no enabled
+ * rule routes through this group") only carried the first. Read fast it still
+ * landed as a verdict: a card that normally shows health and today shows a grey
+ * pill reads as "the health is bad". So the two meanings are now separated, on
+ * purpose and in this order:
+ *
+ *   1. the ROUTING FACT — nothing routes here, so nothing measures it;
+ *   2. the NON-FACT — this is not a health reading at all. Absent numbers are
+ *      absence of measurement, never failure.
+ *
+ * For a GROUP there is a third line, and it is the confusion this whole change
+ * exists to end: a group used only as a hop inside a chain is never routed to
+ * DIRECTLY, so it correctly reads unused here while carrying real traffic as a
+ * hop. Its health is measured at that hop, on the chain's card.
+ *
+ * Unused is neutral — groove-grey, never amber, never crit. It is a state of the
+ * config, and the config is not sick.
+ */
+function NotRoutedNote({ kind }: { kind: 'group' | 'chain' }) {
+  return (
+    <div className="gh gh--unused">
+      <div className="gh-line">
+        <span className="gh-unused">unused</span>
+        <span className="gh-quiet">
+          No enabled rule routes through this {kind}, so the observatory never probes it.
+        </span>
+      </div>
+      <p className="gh-say">
+        That is a routing fact, not a health reading. There are no numbers here because nothing
+        measured this {kind} — not because it failed.
+      </p>
+      {kind === 'group' ? (
+        <p className="gh-say">
+          A group used only as a hop inside a chain reads unused here on purpose: the rules point at
+          the chain, not at the group. Its members are measured at that hop, so its real health is on
+          that chain’s card, hop by hop.
+        </p>
+      ) : (
+        <p className="gh-say">
+          Point a rule at this chain and the observatory starts measuring every hop within seconds.
+        </p>
+      )}
+    </div>
+  )
+}
+
 /**
  * One group's member rows, fetched on demand.
  *
@@ -1645,7 +1715,9 @@ function MemberRow({ member }: { member: GroupMemberHealth }) {
 }
 
 /**
- * What a group test found, in the four states it actually has.
+ * What the OBSERVATORY measured for this target end to end, in the four states it
+ * actually has. Nothing here was dialled by the panel — it is a read of the
+ * background prober's own measurement along the real path.
  *
  * The one worth spelling out: `ok` with an EMPTY `exit_ip` is a SUCCESS. The
  * delay was measured; only the address lookup came back empty. Rendering that as
@@ -1653,15 +1725,45 @@ function MemberRow({ member }: { member: GroupMemberHealth }) {
  * traffic, so it reads as a result with the address slot marked unknown — dim,
  * not red, and the LED stays green.
  */
-function GroupTestReadout({ test, pending }: { test?: GroupTestResult; pending: boolean }) {
+/**
+ * Errors that mean NO MEASUREMENT EXISTS, as opposed to "this target is broken".
+ *
+ * Three of the observatory's four failure reasons are about the observatory, not
+ * about the path: nothing routes here, nothing has reached it yet, or background
+ * probing is switched off. Painting those crit-red — which is what `ok:false`
+ * used to buy you — reports a fault that nobody has found, on a target that may
+ * be carrying traffic perfectly. Only "the observatory's probe through this path
+ * failed" is a health finding, and it is deliberately NOT in this list.
+ *
+ * Matched on a stable fragment rather than the whole sentence, so a daemon that
+ * rewords the tail still classifies. An error we don't recognise stays red: an
+ * unknown failure is likelier to be real than not, and that is the safe default.
+ */
+const NO_MEASUREMENT = [
+  'not routed by any enabled rule',
+  'has not reached this target yet',
+  'background probing is disabled',
+]
+const isAbsence = (err: string): boolean => NO_MEASUREMENT.some((frag) => err.includes(frag))
+
+function GroupTestReadout({
+  test,
+  pending,
+  hideAbsence,
+}: {
+  test?: GroupTestResult
+  pending: boolean
+  /** The card already explains why nothing measures this target (the unused
+   *  note), so an absence error here would just say it a second time. */
+  hideAbsence?: boolean
+}) {
   if (pending) {
-    // "testing", never "measuring": the health run owns that word and covers every
-    // group at once. Two runs that read the same on a card is how one group's test
-    // came to look like all four were busy.
+    // Names who is working and on what: the prober, on this target. The badge is
+    // scoped to the cards the run covers, so it can say "this one" honestly.
     return (
       <div className="tg-test tg-test--wait" role="status">
         <Led variant="amber" pulse />
-        <span className="tg-test-msg">testing this exit…</span>
+        <span className="tg-test-msg">waiting for the prober to measure this…</span>
       </div>
     )
   }
@@ -1670,10 +1772,22 @@ function GroupTestReadout({ test, pending }: { test?: GroupTestResult; pending:
   const at = test.tested_unix ? fmtClock(test.tested_unix) : ''
 
   if (!test.ok) {
+    // No measurement exists. Unlit lamp, quiet text: this panel's way of saying
+    // "no verdict", which is precisely the state — never a red one.
+    if (isAbsence(test.error)) {
+      if (hideAbsence) return null
+      return (
+        <div className="tg-test tg-test--none" role="status">
+          <Led variant="off" />
+          <span className="tg-test-msg">{test.error}</span>
+          {at && <span className="tg-test-at mono">{at}</span>}
+        </div>
+      )
+    }
     return (
       <div className="tg-test tg-test--bad" role="status">
         <Led variant="crit" />
-        <span className="tg-test-msg">{test.error || 'the test failed'}</span>
+        <span className="tg-test-msg">{test.error || 'the probe failed'}</span>
         {at && <span className="tg-test-at mono">{at}</span>}
       </div>
     )
@@ -2098,7 +2212,7 @@ function ChainRow({
   chain,
   busy,
   showHealth,
-  used,
+  health,
   test,
   testing,
   testBusy,
@@ -2109,19 +2223,19 @@ function ChainRow({
   chain: Chain
   busy: boolean
   /** Group health checks are on (Settings). When false, the card drops its
-   *  exit-test readout and Test button — it is config only. */
+   *  health readout and Refresh button — it is config only. */
   showHealth: boolean
-  /** This chain's reachability (GroupHealth.Used's chain analogue, plan §5.E).
-   *  undefined ⇒ the health endpoint hasn't reported this chain (not applied yet, or
-   *  a daemon version without chains): no badge. false ⇒ no enabled rule routes
-   *  through the chain, so the observatory never probes it and the card renders
-   *  "unused" instead of an exit-test readout. */
-  used?: boolean
+  /** Everything the observatory knows about this chain: whether any enabled rule
+   *  routes through it, and the per-hop measurements along it.
+   *  undefined ⇒ the health endpoint hasn't reported this chain at all (not
+   *  applied yet, or a daemon version without chains): the card says nothing
+   *  rather than guessing. */
+  health?: ChainHealth
   test?: GroupTestResult
-  /** An exit test covering THIS chain is in flight (the caller resolves it
+  /** A refresh pass covering THIS chain is in flight (the caller resolves it
    *  against the run's scope, exactly as for a group card). */
   testing: boolean
-  /** Any exit test is in flight; the daemon runs one at a time. */
+  /** Any refresh pass is in flight; the daemon runs one at a time. */
   testBusy: boolean
   onTest: () => void
   onEdit: () => void
@@ -2165,25 +2279,21 @@ function ChainRow({
         {showHealth && (
           <>
             {/* A chain no enabled rule routes through is never probed (the
-                observatory walks only reachable paths), so instead of an exit-test
-                readout the card says so, quietly — the same "unused" pattern the
-                group card uses (GroupHealthReadout), not a new design. `used` is
-                undefined until the health endpoint reports this chain (or from a
-                daemon version without chains): no badge then. */}
-            {used === false && (
-              <div className="gh gh--unused">
-                <div className="gh-line">
-                  <span
-                    className="gh-unused"
-                    title="No enabled rule routes through this chain, so its exit is not probed. Add it to a rule to see health."
-                  >
-                    unused
-                  </span>
-                  <span className="gh-quiet">not probed — no enabled rule routes through this chain</span>
-                </div>
-              </div>
-            )}
-            <GroupTestReadout test={test} pending={testing && !test} />
+                observatory walks only reachable paths), so instead of a health
+                readout the card says so — the same "unused" note the group card
+                uses, not a new design. `health` is undefined until the endpoint
+                reports this chain (or on a daemon without chains): say nothing
+                then rather than guess. */}
+            {health?.used === false ? (
+              <NotRoutedNote kind="chain" />
+            ) : health?.used ? (
+              <ChainHopRail chain={chain.Name} defs={hops} hops={health.hops} />
+            ) : null}
+            <GroupTestReadout
+              test={test}
+              pending={testing && !test}
+              hideAbsence={health?.used === false}
+            />
           </>
         )}
       </div>
@@ -2194,13 +2304,250 @@ function ChainRow({
         editLabel={`Edit chain ${chain.Name}`}
         deleteLabel={`Delete chain ${chain.Name}`}
         onTest={showHealth ? onTest : undefined}
-        testLabel={showHealth ? `Test the exit of chain ${chain.Name}` : undefined}
+        testLabel={showHealth ? `Refresh the reading for chain ${chain.Name}` : undefined}
         testDisabled={testBusy}
       />
     </li>
   )
 }
 
+// ---- chain hop rail --------------------------------------------------------
+
+/**
+ * The API gives hops an index and no name. The page already knows the names — the
+ * model's own `Hops` strings ("egress:ewan", "node:awgout", "group:sub0") — so
+ * zip the two by POSITION.
+ *
+ * Two things make that safe rather than clever. A LEADING `egress:` is not a
+ * numbered hop: the daemon lifts it into hop 1's entry detour, so it is dropped
+ * before counting. And if the counts still disagree — a chain that splices
+ * sub-chains gets FLATTENED by the daemon, producing more wire hops than the
+ * config lists — every label is dropped. A hop labelled with its neighbour's name
+ * is worse than a hop with no name at all: it would send someone to fix the wrong
+ * target.
+ */
+function hopLabels(defs: string[], hops: ChainHopHealth[]): (string | undefined)[] {
+  const numbered = defs.length > 0 && defs[0].startsWith('egress:') ? defs.slice(1) : defs
+  if (numbered.length !== hops.length) return hops.map(() => undefined)
+  return hops.map((h) => (h.index >= 1 && h.index <= numbered.length ? numbered[h.index - 1] : undefined))
+}
+
+/**
+ * One hop's lamp.
+ *
+ * `dead` is crit and `untested` is an UNLIT socket — never red, because nothing
+ * has been measured and an unlit lamp is this panel's way of saying "no verdict".
+ * That covers a hop the walk never reached (`blocked_by`) too: it is neither
+ * healthy nor broken, and unlit is the only mark that claims neither.
+ * The fourth case is the page's existing house reading, applied here for
+ * consistency rather than invented: a group hop that is carrying traffic but has
+ * confirmed failures on its board is amber. `state` stays the daemon's word for
+ * "can this hop carry traffic"; the amber only qualifies HOW WELL.
+ */
+function hopLed(h: ChainHopHealth): LedVariant {
+  if (h.state === 'dead') return 'crit'
+  if (h.state === 'untested') return 'off'
+  return h.dead > 0 ? 'amber' : 'on'
+}
+
+/**
+ * What the observatory measured at each position of a chain — the reading the
+ * daemon always took and the panel never showed.
+ *
+ * THE DESIGN RISK, and the one place this card spends any boldness: the rail
+ * draws the CONDUCTOR as well as the lamps, and severs it below the first dead
+ * hop. A chain is a single series path, so the operator's real question is never
+ * "how many hops are green" — it is "where does my traffic stop". Four lamps in a
+ * column answer the first question and leave the second to arithmetic. A broken
+ * conductor answers the second one before you have read a single word, which is
+ * the whole reason this feature exists.
+ *
+ * It stays honest by keeping two different facts on two different marks. The
+ * CONDUCTOR is reachability through the path, and that genuinely does stop at the
+ * break. The LAMPS are measurements — and there are none below the break to show:
+ * the daemon walks the path in order and stops at the first hop that does not
+ * answer, because every later hop is dialled THROUGH that one. Those hops arrive
+ * `untested` with `blocked_by` naming the hop that stopped the walk, so their
+ * lamps stay UNLIT: not a soft red, not a pale green, just this panel's way of
+ * saying no verdict exists about a hop nobody reached. The row says so in words
+ * too, naming that hop, because "why is this row empty" is the question the shape
+ * alone cannot answer.
+ *
+ * Nothing here is re-derived from the daemon's counters — the block, the zeroed
+ * numbers and the state all come off the wire. The only thing the panel adds is
+ * what a chain structurally is.
+ *
+ * Everything around the rail is deliberately quiet: no colour but the semantic
+ * lamps, no motion at all, the orange accent untouched.
+ */
+function ChainHopRail({
+  chain,
+  defs,
+  hops,
+}: {
+  chain: string
+  /** The chain's configured hops, straight off the model — the only source of names. */
+  defs: string[]
+  /** Absent ⇒ the engine never materialised per-hop outbounds. NOT "no hops". */
+  hops?: ChainHopHealth[]
+}) {
+  const ordered = useMemo(() => [...asArray(hops)].sort((a, b) => a.index - b.index), [hops])
+  const labels = useMemo(() => hopLabels(defs, ordered), [defs, ordered])
+
+  // The first hop that was probed and did not answer. Everything after it is
+  // unreachable THROUGH THIS CHAIN, whatever its own lamp says. `untested` is
+  // never a break: nothing was measured, so nothing is known to be severed.
+  const breakAt = ordered.findIndex((h) => h.state === 'dead')
+
+  if (ordered.length === 0) {
+    // Say why, in one line, instead of an empty rail. The daemon collapses a
+    // single-target chain into a plain alias and never builds copies to measure,
+    // so we can tell the two absences apart from the config alone.
+    const numbered = defs.filter((d, i) => !(i === 0 && d.startsWith('egress:')))
+    return (
+      <div className="gh gh--absent">
+        <span className="gh-absent-msg">
+          {numbered.length <= 1
+            ? 'This chain has a single hop, so the engine points traffic straight at that target instead of building a path to measure. Its health is on that target’s own card.'
+            : 'The engine hasn’t built this chain’s hops yet, so there is nothing measured per hop. They appear once it is running with this config applied.'}
+        </span>
+      </div>
+    )
+  }
+
+  return (
+    <div className="gh ch-rail">
+      <span className="ch-eyebrow">measured, hop by hop</span>
+      <ol className="ch-hops">
+        {ordered.map((h, i) => {
+          const label = labels[i]
+          const severed = breakAt >= 0 && i > breakAt
+          // Straight off the wire: present ⇒ the walk never reached this hop, so
+          // there is nothing measured here and the daemon has already named the
+          // hop that stopped it. Never inferred from the counters.
+          const blocked = h.blocked_by
+          const cls = [
+            'ch-hop',
+            `ch-hop--${h.state}`,
+            blocked ? 'ch-hop--blocked' : '',
+            severed ? 'ch-hop--severed' : '',
+            h.exit ? 'ch-hop--exit' : '',
+            i === 0 ? 'ch-hop--first' : '',
+          ]
+            .filter(Boolean)
+            .join(' ')
+          const age = fmtAge(h.age_seconds)
+          return (
+            <li key={h.tag || h.index} className={cls}>
+              <span className="ch-num mono" aria-hidden="true">
+                {h.index}
+              </span>
+              <span className="ch-socket">
+                <Led variant={hopLed(h)} />
+              </span>
+              <div className="ch-body">
+                <div className="ch-l1">
+                  <span className="ch-name mono" title={`engine outbound ${h.tag}`}>
+                    {label ?? (h.kind === 'group' ? 'a group hop' : 'a node hop')}
+                  </span>
+                  {h.exit && <span className="ch-tag">exit</span>}
+                  {h.state === 'alive' && h.delay_ms > 0 && (
+                    <span className="ch-delay mono">{h.delay_ms} ms</span>
+                  )}
+                  {/* Two different silences. A plain untested hop is a timing
+                      gap that fills in by itself; a BLOCKED one never will,
+                      because the walk stopped above it — so it says which hop
+                      stopped it instead of implying someone should wait. */}
+                  {blocked ? (
+                    <span
+                      className="ch-quiet ch-blocked"
+                      title={`hop ${blocked.index} did not answer, so nothing was dialled through it (engine outbound ${blocked.tag})`}
+                    >
+                      no reading — the probe stopped at hop {blocked.index}
+                    </span>
+                  ) : (
+                    h.state === 'untested' && <span className="ch-quiet">not measured yet</span>
+                  )}
+                  {age && <span className="ch-age mono">{age}</span>}
+                </div>
+
+                {/* A node hop IS its own measurement (total 1), so counters would
+                    only restate the lamp. A group hop rolls up its per-hop member
+                    copies, and those read exactly as they do everywhere else in
+                    this app: alive out of TESTED, with the untested remainder as a
+                    quiet aside only when there is one. A blocked hop has those
+                    counters zeroed by the daemon, so it lands in the tested === 0
+                    branch — and there it must say the members were never REACHED,
+                    not that they are still waiting their turn. */}
+                {h.kind === 'group' && h.total > 0 && (
+                  <div className="ch-l2">
+                    {h.tested === 0 ? (
+                      <span className="ch-rest mono">
+                        {h.total} member{h.total === 1 ? '' : 's'},{' '}
+                        {blocked ? 'none of them reached' : 'none measured'}
+                      </span>
+                    ) : (
+                      <>
+                        <span className="ch-count mono">
+                          <b>{h.alive}</b> / {h.tested}
+                        </span>
+                        <span className="ch-word">alive</span>
+                        {h.dead > 0 && (
+                          <span
+                            className="ch-dead mono"
+                            title={`${h.dead} member${h.dead === 1 ? '' : 's'} were probed at this hop and did not answer`}
+                          >
+                            {h.dead} not answering
+                          </span>
+                        )}
+                        {h.untested > 0 && (
+                          <span className="ch-rest mono">
+                            tested {h.tested} of {h.total}
+                          </span>
+                        )}
+                      </>
+                    )}
+                    {/* The wrapper keeps its pick even when nothing crossed it,
+                        so on a blocked hop this is the node it WOULD use — say
+                        that, rather than "now", which claims live traffic. */}
+                    {h.selected && (
+                      <span
+                        className="ch-now mono"
+                        title={
+                          blocked
+                            ? `Hop ${h.index} of “${chain}” is set to ${h.selected}; nothing crossed it to measure`
+                            : `Traffic crossing hop ${h.index} of “${chain}” is on ${h.selected}`
+                        }
+                      >
+                        {blocked ? 'set to' : 'now'} → {h.selected}
+                      </span>
+                    )}
+                  </div>
+                )}
+              </div>
+            </li>
+          )
+        })}
+      </ol>
+
+      {/* The sentence the rail's shape implies, written out — because the break is
+          the answer someone came here for, and a graphic alone should never be the
+          only place a finding exists. It names the dead hop, since that is the one
+          thing here anybody can act on. */}
+      {breakAt >= 0 && (
+        <p className="gh-say gh-say--bad">
+          Hop {ordered[breakAt].index}
+          {labels[breakAt] ? ` (${labels[breakAt]})` : ''} was probed and did not answer, so traffic
+          stops there
+          {breakAt < ordered.length - 1
+            ? ' — and the hops below it are dialled through it, so nothing reached them and nothing is known about them.'
+            : '.'}
+        </p>
+      )}
+    </div>
+  )
+}
+
 function ChainEditor({
   initial,
   hopOptions,
@@ -2675,8 +3022,8 @@ function RowActions({
   busy: boolean
   editLabel: string
   deleteLabel: string
-  // Only groups and chains can be tested, so the control is optional and absent
-  // everywhere else rather than a disabled stub on every row.
+  // Only groups and chains are probed, so the refresh control is optional and
+  // absent everywhere else rather than a disabled stub on every row.
   onTest?: () => void
   testLabel?: string
   testDisabled?: boolean
@@ -2689,8 +3036,9 @@ function RowActions({
           onClick={onTest}
           disabled={busy || testDisabled}
           aria-label={testLabel}
+          title="Ask the background prober to measure this target out of turn. It does not open a connection from the panel."
         >
-          Test
+          Refresh
         </Button>
       )}
       <Button className="tg-act" onClick={onEdit} disabled={busy} aria-label={editLabel}>

panel/src/planeState.test.ts

@@ -0,0 +1,150 @@
+// protectionState — the one sentence the whole panel shows about "am I protected".
+//
+// Run with `npm test` (node's built-in test runner + native TypeScript stripping;
+// no test dependency is added to the SPA, which ships inside the daemon binary).
+//
+// The case this file was written for is "plane full, traffic direct": the exact
+// state of a live router — one enabled rule, `default → direct`, no groups, no
+// rule-sets — where every part of the data plane was installed and the readout
+// therefore said "Protected — traffic from your network is going through the
+// tunnel", under a green LED, while the whole LAN went out the plain WAN.
+//
+// planeState.ts has no runtime imports (both of its imports are `import type`),
+// so this runs against the real module with nothing stubbed.
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { protectionState } from './planeState.ts'
+import type { Status, Traffic } from './api.ts'
+
+/** A healthy, fully-installed router; `traffic` is what each case varies. */
+function status(over: Partial<Status> = {}): Status {
+  return {
+    running: true,
+    enabled: true,
+    active: true,
+    table: true,
+    hash: 'abc',
+    version: '1.11.0-shater',
+    kill_switch: 'closed',
+    engine_running: true,
+    plane: 'full',
+    warnings: [],
+    ...over,
+  }
+}
+
+function withTraffic(traffic: Traffic | undefined): Status {
+  return status({ traffic })
+}
+
+// --- the field case ---------------------------------------------------------
+
+test('plane full + default direct is NOT reported as protected', () => {
+  const s = protectionState(withTraffic({ verdict: 'direct', default: 'direct', tunnel_rules: 0 }))
+  assert.notEqual(s.headline, 'Protected')
+  assert.equal(s.variant, 'crit')
+  assert.equal(s.alarm, true)
+  // The claim that was false must not survive anywhere in the copy.
+  assert.doesNotMatch(s.detail, /going through the tunnel/)
+  // ...and the honest consequence must be stated, not implied.
+  assert.match(s.detail, /real address/)
+})
+
+// --- the other verdicts under a full plane ----------------------------------
+
+test('plane full + default into a tunnel is protected', () => {
+  const s = protectionState(withTraffic({ verdict: 'tunnel', default: 'auto', tunnel_rules: 1 }))
+  assert.equal(s.variant, 'on')
+  assert.equal(s.headline, 'Protected')
+  assert.equal(s.alarm, false)
+})
+
+test('plane full + direct default with tunnelling rules is split, not protected', () => {
+  const s = protectionState(withTraffic({ verdict: 'split', default: 'direct', tunnel_rules: 3 }))
+  assert.equal(s.variant, 'amber')
+  assert.notEqual(s.headline, 'Protected')
+  // Says how much is protected, and that the default is not.
+  assert.match(s.detail, /3 rules/)
+  assert.match(s.detail, /normal internet connection/)
+  // A working selective setup must not raise a banner on every other page.
+  assert.equal(s.alarm, false)
+})
+
+test('split names a single rule in the singular', () => {
+  const s = protectionState(withTraffic({ verdict: 'split', default: 'direct', tunnel_rules: 1 }))
+  assert.match(s.detail, /^One rule sends traffic/)
+})
+
+test('plane full + blocked default with rules leaks nothing and is never crit', () => {
+  const s = protectionState(withTraffic({ verdict: 'blocked', default: 'block', tunnel_rules: 2 }))
+  assert.equal(s.variant, 'amber')
+  assert.equal(s.alarm, false)
+  assert.match(s.detail, /nothing is leaving unprotected/)
+})
+
+test('plane full + blocked default with no rules says the network has no way out', () => {
+  const s = protectionState(withTraffic({ verdict: 'blocked', default: 'block', tunnel_rules: 0 }))
+  assert.equal(s.variant, 'amber')
+  assert.equal(s.alarm, true)
+  assert.doesNotMatch(s.detail, /going through the tunnel/)
+})
+
+test('plane full with no verdict claims nothing either way', () => {
+  for (const t of [undefined, { verdict: '' as const }]) {
+    const s = protectionState(withTraffic(t))
+    assert.notEqual(s.headline, 'Protected')
+    assert.equal(s.variant, 'amber')
+    assert.equal(s.alarm, false)
+  }
+})
+
+// --- the branches that were already correct ---------------------------------
+
+test('no status yet', () => {
+  const s = protectionState(null)
+  assert.equal(s.variant, 'off')
+  assert.equal(s.alarm, false)
+})
+
+test('service switched off is a deliberate state, not a fault', () => {
+  const s = protectionState(status({ enabled: false }))
+  assert.equal(s.variant, 'amber')
+  assert.equal(s.headline, 'Turned off')
+  assert.equal(s.alarm, false)
+})
+
+test('hold: the kill-switch caught it — protected, offline', () => {
+  const s = protectionState(status({ plane: 'hold', engine_running: false, active: false }))
+  assert.equal(s.variant, 'amber')
+  assert.equal(s.alarm, true)
+  assert.match(s.headline, /blocked/)
+})
+
+test('none + fail-closed is the leak, and it is crit', () => {
+  const s = protectionState(status({ plane: 'none', table: false, engine_running: false }))
+  assert.equal(s.variant, 'crit')
+  assert.equal(s.alarm, true)
+})
+
+test('none + fail-open is the operator’s documented choice, stated not alarmed at', () => {
+  const s = protectionState(
+    status({ plane: 'none', table: false, engine_running: false, kill_switch: 'open' }),
+  )
+  assert.equal(s.variant, 'amber')
+  assert.equal(s.alarm, true)
+})
+
+test('daemon too old to send `plane` keeps its own fallback', () => {
+  // Nothing here may depend on `traffic`: a daemon with no `plane` has no
+  // `traffic` either, and this branch reads what it can observe instead.
+  const { plane, ...noPlane } = status()
+  void plane
+  assert.equal(protectionState(noPlane as Status).headline, 'Protected')
+  assert.equal(protectionState({ ...noPlane, running: false } as Status).headline, 'Service stopped')
+  assert.equal(
+    protectionState({ ...noPlane, active: false } as Status).headline,
+    'Starting up',
+  )
+})

panel/src/planeState.ts

@@ -11,7 +11,7 @@
 // same router differently.
 
 import type { LedVariant } from './components'
-import type { Status } from './api'
+import type { Status, Traffic } from './api'
 
 export interface ProtectionState {
   variant: LedVariant
@@ -31,6 +31,24 @@ export interface ProtectionState {
  *   hold — the kill-switch caught it. Protected, but offline.
  *   none (fail-closed) — there is no protection at all. Online, and exposed.
  * Collapsing them would erase the only difference that matters.
+ *
+ * PLANE IS NOT THE WHOLE ANSWER, AND THAT USED TO BE A LIE. `plane: 'full'`
+ * returned "Protected — traffic from your network is going through the tunnel",
+ * which is a claim `plane` cannot support: it only says the nft table, the policy
+ * routing and the engine are all installed. Where the diverted packets go once the
+ * engine has them is decided by the engine's default route, and a router in the
+ * field ran with one rule — `default → direct`, no groups, no rule-sets. Fully
+ * installed plane, zero tunnel, whole LAN out the plain WAN with its real address,
+ * green LED, "Protected".
+ *
+ * So `full` now branches on `status.traffic`, the daemon's verdict on the config
+ * it is actually running (see api.ts TrafficVerdict). It is computed on the daemon
+ * because only the daemon knows what was GENERATED and STARTED: the panel's
+ * /api/config is desired state, which diverges from the running one whenever edits
+ * are unapplied or a rollback is pending, and re-deriving the default route from it
+ * would mean a second implementation of the generator's rule loop — schedules,
+ * shadowed catch-alls, targets that failed to resolve and fell back to direct —
+ * drifting against the first.
  */
 export function protectionState(status: Status | null): ProtectionState {
   if (!status) {
@@ -56,12 +74,7 @@ export function protectionState(status: Status | null): ProtectionState {
 
   switch (status.plane) {
     case 'full':
-      return {
-        variant: 'on',
-        headline: 'Protected',
-        detail: 'Traffic from your network is going through the tunnel.',
-        alarm: false,
-      }
+      return fullPlaneState(status.traffic)
     case 'hold':
       return {
         variant: 'amber',
@@ -112,3 +125,87 @@ export function protectionState(status: Status | null): ProtectionState {
     alarm: false,
   }
 }
+
+/**
+ * The plane is fully installed — now say where the traffic it carries ends up.
+ *
+ * Only `tunnel` earns "Protected". The other verdicts each describe a real router
+ * someone can be sitting in front of, and they are kept apart because the thing to
+ * DO about them differs:
+ *
+ *   split   — deliberate for most people who reach it, accidental for the rest
+ *             (a default rule that was never pointed anywhere). Amber, but no
+ *             alarm: raising a banner on every page of a working selective setup
+ *             is how a banner stops being read.
+ *   direct  — the engine is running and forwarding every connection out the plain
+ *             WAN. The traffic outcome is identical to `plane: 'none'` under a
+ *             closed kill-switch, so it gets the same weight: crit, and it
+ *             interrupts. The wording differs because the fix does — nothing
+ *             failed here, the routing simply says "direct".
+ *   blocked — the fail-closed default. Nothing is leaking, so this is never crit;
+ *             with no tunnelling rules at all it means the network has no way out
+ *             and someone should be told why.
+ *   unknown — an older daemon, or the seconds between this daemon starting and its
+ *             first apply. We do not know, so we do not claim. Saying "Protected"
+ *             here is the exact bug being removed.
+ */
+function fullPlaneState(traffic: Traffic | undefined): ProtectionState {
+  const tunnelRules = traffic?.tunnel_rules ?? 0
+
+  switch (traffic?.verdict) {
+    case 'tunnel':
+      return {
+        variant: 'on',
+        headline: 'Protected',
+        detail: 'Traffic from your network is going through the tunnel.',
+        alarm: false,
+      }
+    case 'split':
+      return {
+        variant: 'amber',
+        headline: 'Partly protected — the rest goes out directly',
+        detail: `${ruleCount(tunnelRules)} through the tunnel. Everything they don’t match leaves through your normal internet connection, with your real address.`,
+        alarm: false,
+      }
+    case 'direct':
+      return {
+        variant: 'crit',
+        headline: 'Not protected — nothing is going through the tunnel',
+        detail:
+          'The service is running, but your routing sends every connection straight out your normal internet connection, with your real address. On the Routing page, point the default rule at a group or a node.',
+        alarm: true,
+      }
+    case 'blocked':
+      return tunnelRules > 0
+        ? {
+            variant: 'amber',
+            headline: 'Partly protected — everything else is blocked',
+            detail: `${ruleCount(tunnelRules)} through the tunnel. Anything they don’t match is blocked instead of being let out, so nothing is leaving unprotected.`,
+            alarm: false,
+          }
+        : {
+            variant: 'amber',
+            headline: 'Nothing is getting out',
+            detail:
+              'No rule sends traffic anywhere, so every connection from your network is being blocked rather than let out unprotected. Add a default rule on the Routing page.',
+            alarm: true,
+          }
+    default:
+      return {
+        variant: 'amber',
+        headline: 'Checking where traffic goes',
+        detail:
+          'The router is up and handling your traffic. It hasn’t reported yet whether that traffic is going through the tunnel.',
+        alarm: false,
+      }
+  }
+}
+
+/** "One rule sends traffic" / "4 rules send traffic", so the detail lines above
+ *  can name a number the operator can go and count on the Routing page. Falls
+ *  back to the vague form only if the daemon sent a verdict without a count. */
+function ruleCount(n: number): string {
+  if (n <= 0) return 'Some traffic goes'
+  if (n === 1) return 'One rule sends traffic'
+  return `${n} rules send traffic`
+}

panel/tsconfig.json

@@ -18,5 +18,10 @@
     "noFallthroughCasesInSwitch": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "vite.config.ts"],
+  // *.test.ts runs under node's built-in test runner (`npm test`), which strips
+  // types rather than checking them. They are excluded here because they import
+  // node:test / node:assert, and the SPA deliberately carries no @types/node — it
+  // is embedded in the daemon binary, so every devDependency is weight on a router.
+  "exclude": ["src/**/*.test.ts"]
 }

protocol/group/urltest.go

@@ -44,6 +44,20 @@ type URLTest struct {
 	group                        *URLTestGroup
 	interruptExternalConnections bool
 	balancer                     *balancer // lx: SPEC 019 — nil for least_test (default)
+	// lx: health board §5.C — true when options.SelfCheck == false: the group's
+	// OWN probing schedule (PostStart warm-up + Touch ticker) is stood down and
+	// the observatory is the only thing that measures its members. Stored
+	// INVERTED so the zero value keeps today's behaviour for every construction
+	// path that does not go through NewURLTest (hand-built groups in tests).
+	// See option.URLTestOutboundOptions.SelfCheck for the full reasoning.
+	selfCheckDisabled bool
+	// lx: health board §5.C — the RUNTIME half of the same question, read from
+	// the context registry at construction. selfCheckDisabled above says "this
+	// group is not used by the config"; this says "this group cannot be reached
+	// right now", which changes while the box runs and is therefore asked
+	// afresh at every scheduled check rather than stored. nil = no gate.
+	// See urltest.ProbeGate for why the two must stay separate.
+	probeGate urltest.ProbeGate
 }
 
 func NewURLTest(ctx context.Context, router adapter.Router, logger log.ContextLogger, tag string, options option.URLTestOutboundOptions) (adapter.Outbound, error) {
@@ -71,6 +85,12 @@ func NewURLTest(ctx context.Context, router adapter.Router, logger log.ContextLo
 		idleTimeout:                  time.Duration(options.IdleTimeout),
 		interruptExternalConnections: options.InterruptExistConnections,
 		balancer:                     balancer,
+		// nil/absent means true (self-check on) — the documented default, so a
+		// config written before the flag existed behaves exactly as it always has.
+		selfCheckDisabled: options.SelfCheck != nil && !*options.SelfCheck,
+		// Absent from the registry (plain sing-box, tests) yields nil, which
+		// means "no gate" — every scheduled probe proceeds, as before.
+		probeGate: service.FromContext[urltest.ProbeGate](ctx),
 	}
 	if len(outbound.tags) == 0 {
 		return nil, E.New("missing tags")
@@ -92,6 +112,13 @@ func (s *URLTest) Start() error {
 		return err
 	}
 	group.balancer = s.balancer // lx: SPEC 019 v2 — health-check drives the pool through it
+	// lx: health board §5.C — carry the stand-down flag onto the group the same
+	// way the balancer travels: set after construction, immutable from then on.
+	group.selfCheckDisabled = s.selfCheckDisabled
+	// The gate and the tag to ask it about travel together: the gate answers
+	// per-outbound, and the group is the thing whose schedule is being gated.
+	group.probeGate = s.probeGate
+	group.tag = s.Tag()
 	if s.balancer != nil {
 		// lx: health board §5.B — slot liveness reads through the board verdict, so a
 		// death recorded by any prober or a failed dial takes effect on the next pick,
@@ -319,6 +346,80 @@ type URLTestGroup struct {
 	lastActive                   common.TypedValue[time.Time]
 	lastSelected                 common.TypedValue[string] // lx: SPEC 019 — Now() in balanced modes
 	balancer                     *balancer                 // lx: SPEC 019 v2 — round_robin pool; nil for least_test
+	// lx: health board §5.C — mirrors URLTest.selfCheckDisabled (set by Start,
+	// immutable afterwards, zero value = probing on). Guards ONLY the group's
+	// own schedule: the PostStart warm-up sweep and the Touch ticker. An
+	// explicit CheckOutbounds/URLTest call is untouched — the flag stands down
+	// the schedule, not the capability.
+	selfCheckDisabled bool
+	// lx: health board §5.C — the runtime gate and the tag it is asked about.
+	// Both mirror URLTest's fields (set by Start, immutable afterwards); nil
+	// gate or empty tag means every scheduled check proceeds. Consulted only
+	// through selfCheckAllowed, and only on the SCHEDULE.
+	probeGate urltest.ProbeGate
+	tag       string
+}
+
+// selfCheckAllowed reports whether the group's OWN probing schedule may dial
+// right now. lx: health board §5.C.
+//
+// Two independent refusals, in the order they can be answered cheapest first:
+//
+//	selfCheckDisabled — the config says no rule reaches this group. Fixed for
+//	                    the life of the box; see standDownUnusedSelfCheck.
+//	probeGate         — the world says this group cannot be reached right now,
+//	                    typically a chain hop sitting behind a dead hop. Asked
+//	                    fresh EVERY time, which is the entire mechanism by which
+//	                    a recovered hop resumes probing: there is no state here
+//	                    to reset, so there is none to get stuck.
+//
+// Neither refusal touches an explicit CheckOutbounds/URLTest — a deliberate
+// request is never a scheduled one.
+func (g *URLTestGroup) selfCheckAllowed() bool {
+	if g.selfCheckDisabled {
+		return false
+	}
+	if g.probeGate == nil || g.tag == "" {
+		return true
+	}
+	return g.probeGate.ProbeAllowed(g.tag)
+}
+
+// scheduledCheck is one firing of the group's own schedule — the warm-up sweep
+// and every ticker tick go through here, and nothing else does. Having exactly
+// one gated entry point is what keeps the two callers from drifting apart, and
+// it is the seam the tests drive to assert that a gated group makes no dial
+// attempt at all.
+func (g *URLTestGroup) scheduledCheck() {
+	if !g.selfCheckAllowed() {
+		return
+	}
+	g.CheckOutbounds(false)
+}
+
+// keepWarm reports whether this group must keep measuring with no traffic
+// flowing through it. lx: health board §5.C — see urltest.ProbeGate.ProbeWhenIdle.
+//
+// The default is NO, in every direction: no gate, no tag, or a group whose
+// self-check is stood down anyway. Only a gate that positively says "the routing
+// config reaches this group" turns the idle timeout off, so plain sing-box and
+// every hand-built group keep the lifecycle they have always had.
+func (g *URLTestGroup) keepWarm() bool {
+	if g.selfCheckDisabled || g.probeGate == nil || g.tag == "" {
+		return false
+	}
+	return g.probeGate.ProbeWhenIdle(g.tag)
+}
+
+// startTickerLocked arms the group's own probing ticker. g.access MUST be held
+// and g.ticker MUST be nil. Extracted so PostStart and Touch arm it identically
+// — two ways in, one construction, no chance of one of them forgetting the pause
+// registration.
+func (g *URLTestGroup) startTickerLocked() {
+	ticker := time.NewTicker(g.interval)
+	g.ticker = ticker
+	g.pauseCallback = pause.RegisterTicker(g.pause, ticker, g.interval, nil)
+	go g.loopCheck(ticker, g.close)
 }
 
 func NewURLTestGroup(ctx context.Context, outboundManager adapter.OutboundManager, logger log.Logger, outbounds []adapter.Outbound, link string, interval time.Duration, tolerance uint16, idleTimeout time.Duration, interruptExternalConnections bool) (*URLTestGroup, error) {
@@ -362,24 +463,67 @@ func (g *URLTestGroup) PostStart() {
 	g.lastActive.Store(time.Now())
 	// lx: SPEC 019 v2 — seed the pool so round_robin can route from the first connection,
 	// before the first health-check completes (history-warm nodes first, else config order).
+	// The seed only READS the board, so it runs even with the self-check stood down.
 	g.seedPool()
-	go g.CheckOutbounds(false)
+	// lx: health board §5.C — the warm-up sweep is the first half of the group's
+	// own probing schedule, and it fires for EVERY group at box start, including
+	// groups no routing rule reaches. For those, the sweep dials every member
+	// directly from the router — a path nothing uses — and records the outcome
+	// under the members' base tags, forging the board reading the observatory
+	// exists to keep honest. A stood-down group therefore skips it entirely; the
+	// observatory (or nothing, for a truly unused group) is what measures its
+	// members.
+	//
+	// The same call is now also where a chain hop behind a DEAD hop declines to
+	// sweep: every member of such a group dials through the broken hop, so the
+	// sweep would measure that hop once per member and file the result against
+	// this one. selfCheckAllowed keeps both refusals in one place.
+	go g.scheduledCheck()
+	// A group the routing config REACHES keeps measuring whether or not anybody
+	// dials it, so its ticker is armed here instead of waiting for a Touch that
+	// may never come. Without this, a used group with no traffic gets this one
+	// warm-up sweep and then nothing: its members age past the verdict TTL and
+	// the panel reports "untested" about a rule that is in force, while the first
+	// real request pays a cold probe. Nothing else would fill the gap — the
+	// observatory stands off a urltest group's members entirely (probeplan.go
+	// SelfChecked), which is the whole point of one dialler per target.
+	//
+	// lastActive was stored a moment ago, so loopCheck's opening "idle longer
+	// than the interval" check does not fire and this cannot double up with the
+	// sweep above.
+	if g.keepWarm() && g.ticker == nil {
+		g.startTickerLocked()
+	}
 }
 
 func (g *URLTestGroup) Touch() {
 	if !g.started {
 		return
 	}
+	// lx: health board §5.C — Touch's only job is to keep the group's OWN
+	// probing ticker alive while traffic flows. With the self-check stood down
+	// there is deliberately no ticker to start or feed: the observatory owns the
+	// schedule, and a stray dial through an unused group (a stale rule cache, a
+	// manual pin) must not arm 30 minutes of direct probing under the members'
+	// base tags. Checked before the lock because the flag is immutable after
+	// Start, exactly like the started fast-path above.
+	//
+	// The runtime gate is deliberately NOT consulted here. Touch only arms the
+	// ticker; refusing to arm it would mean a hop that recovers has no ticker
+	// left to notice — the block would outlive the failure, which is the one
+	// outcome this must never have. The ticker runs and each tick re-asks the
+	// gate (loopCheck -> scheduledCheck), so a blocked hop costs a predicate
+	// call per interval and resumes the moment the hop in front answers.
+	if g.selfCheckDisabled {
+		return
+	}
 	g.access.Lock()
 	defer g.access.Unlock()
 	if g.ticker != nil {
 		g.lastActive.Store(time.Now())
 		return
 	}
-	ticker := time.NewTicker(g.interval)
-	g.ticker = ticker
-	g.pauseCallback = pause.RegisterTicker(g.pause, ticker, g.interval, nil)
-	go g.loopCheck(ticker, g.close)
+	g.startTickerLocked()
 }
 
 func (g *URLTestGroup) Close() error {
@@ -405,10 +549,15 @@ func (g *URLTestGroup) Select(network string) (adapter.Outbound, bool) {
 	return g.selectExcluding(network, nil)
 }
 
+// loopCheck is the group's own schedule. lx: health board §5.C — every probe it
+// fires goes through scheduledCheck, so a stood-down or currently-unreachable
+// group ticks without dialling. The ticker's LIFECYCLE (the idle timeout below)
+// is deliberately left alone: a gated group keeps its ticker exactly as long as
+// an ungated one would, because the ticker is what will notice the recovery.
 func (g *URLTestGroup) loopCheck(ticker *time.Ticker, closeChan <-chan struct{}) {
 	if time.Since(g.lastActive.Load()) > g.interval {
 		g.lastActive.Store(time.Now())
-		g.CheckOutbounds(false)
+		g.scheduledCheck()
 	}
 	for {
 		select {
@@ -416,7 +565,13 @@ func (g *URLTestGroup) loopCheck(ticker *time.Ticker, closeChan <-chan struct{})
 			return
 		case <-ticker.C:
 		}
-		if time.Since(g.lastActive.Load()) > g.idleTimeout {
+		// The idle timeout retires the ticker of a group nobody is dialling —
+		// unless the routing config reaches it, in which case its health is a
+		// live question whether or not traffic is flowing and the ticker must
+		// outlive the silence. Asked here rather than remembered from PostStart
+		// so it tracks the running config, and asked OUTSIDE g.access because the
+		// answer comes from the engine, which has locks of its own.
+		if !g.keepWarm() && time.Since(g.lastActive.Load()) > g.idleTimeout {
 			g.access.Lock()
 			if g.ticker == ticker {
 				g.ticker.Stop()
@@ -427,7 +582,7 @@ func (g *URLTestGroup) loopCheck(ticker *time.Ticker, closeChan <-chan struct{})
 			g.access.Unlock()
 			return
 		}
-		g.CheckOutbounds(false)
+		g.scheduledCheck()
 	}
 }
 

protocol/group/urltest_health_lx_test.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"net"
+	"sync"
 	"testing"
 	"time"
 
@@ -32,10 +33,31 @@ type healthNode struct {
 func (n *healthNode) Tag() string       { return n.tag }
 func (n *healthNode) Network() []string { return []string{N.NetworkTCP, N.NetworkUDP} }
 
-func (n *healthNode) DialContext(ctx context.Context, network string, destination M.Socksaddr) (net.Conn, error) {
-	if n.dialed != nil {
-		*n.dialed = append(*n.dialed, n.tag)
+// healthDialMu guards the shared dialed slice. testNodes probes a group's
+// members CONCURRENTLY (a batch of 10), so two nodes pointing at one slice
+// append from two goroutines; the append is what the -race build trips on, not
+// the code under test.
+var healthDialMu sync.Mutex
+
+func (n *healthNode) record() {
+	if n.dialed == nil {
+		return
 	}
+	healthDialMu.Lock()
+	*n.dialed = append(*n.dialed, n.tag)
+	healthDialMu.Unlock()
+}
+
+// dialsOf reads a dial log under the same lock. Every assertion on a log a
+// concurrent sweep may still be writing must go through it.
+func dialsOf(dialed *[]string) []string {
+	healthDialMu.Lock()
+	defer healthDialMu.Unlock()
+	return append([]string(nil), *dialed...)
+}
+
+func (n *healthNode) DialContext(ctx context.Context, network string, destination M.Socksaddr) (net.Conn, error) {
+	n.record()
 	if n.fail {
 		return nil, errors.New("dial refused")
 	}
@@ -45,9 +67,7 @@ func (n *healthNode) DialContext(ctx context.Context, network string, destinatio
 }
 
 func (n *healthNode) ListenPacket(ctx context.Context, destination M.Socksaddr) (net.PacketConn, error) {
-	if n.dialed != nil {
-		*n.dialed = append(*n.dialed, n.tag)
-	}
+	n.record()
 	if n.fail {
 		return nil, errors.New("listen refused")
 	}

protocol/group/urltest_selfcheck_lx_test.go

@@ -0,0 +1,272 @@
+package group
+
+// lx: health board §5.C tests — SelfCheck stands the group's OWN probing
+// schedule down: no PostStart warm-up sweep, no Touch ticker. The explicit
+// CheckOutbounds path stays available, and the nil default keeps probing.
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sagernet/sing-box/common/urltest"
+	"github.com/sagernet/sing-box/log"
+	"github.com/sagernet/sing-box/option"
+	"github.com/sagernet/sing/service/pause"
+)
+
+// waitForHistory polls until the store holds an entry for tag or the deadline
+// passes; reports whether it appeared. PostStart's sweep runs on its own
+// goroutine, so both directions of the assertion need a bounded wait.
+func waitForHistory(hist *urltest.HistoryStorage, tag string, deadline time.Duration) bool {
+	stop := time.Now().Add(deadline)
+	for time.Now().Before(stop) {
+		if hist.LoadURLTestHistory(tag) != nil {
+			return true
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	return false
+}
+
+// A group with the self-check stood down writes NOTHING to the history storage
+// on PostStart: the warm-up sweep — which would dial the member directly from
+// the router and mark the failure under its base tag — must not fire. And
+// Touch, the other half of the schedule, must not start a ticker either.
+func TestSelfCheckDisabledPostStartWritesNothing(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	a := &healthNode{tag: "a", fail: true}
+	manager := managerOf(a)
+	g := healthTestGroup(hist, manager, a)
+	g.selfCheckDisabled = true
+
+	g.PostStart()
+	// The absence of a write is the assertion, so give the (non-existent) sweep
+	// real time to have happened before declaring victory.
+	if waitForHistory(hist, "a", 150*time.Millisecond) {
+		t.Fatal("a stood-down group's PostStart wrote to the board; the warm-up sweep must not fire")
+	}
+
+	g.Touch()
+	g.access.Lock()
+	ticker := g.ticker
+	g.access.Unlock()
+	if ticker != nil {
+		t.Fatal("Touch armed the probing ticker on a stood-down group")
+	}
+}
+
+// The default (SelfCheck nil, i.e. the zero-value field on a hand-built group)
+// keeps today's behaviour: PostStart's warm-up sweep runs and records the
+// failing member on the board.
+func TestSelfCheckDefaultStillProbesOnPostStart(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	a := &healthNode{tag: "a", fail: true}
+	manager := managerOf(a)
+	g := healthTestGroup(hist, manager, a)
+
+	g.PostStart()
+	if !waitForHistory(hist, "a", 5*time.Second) {
+		t.Fatal("default group's PostStart never probed; the self-check must stay on unless stood down")
+	}
+	if v := hist.Verdict("a", 10*time.Minute); v != urltest.VerdictDead {
+		t.Fatalf("verdict(a) = %v, want dead from the warm-up sweep", v)
+	}
+}
+
+// An EXPLICIT CheckOutbounds still probes a stood-down group: the flag
+// suppresses the group's own schedule, never a deliberate request (the adapter
+// interface a human or an API invokes on purpose).
+func TestSelfCheckDisabledExplicitCheckStillProbes(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	a := &healthNode{tag: "a", fail: true}
+	manager := managerOf(a)
+	g := healthTestGroup(hist, manager, a)
+	g.selfCheckDisabled = true
+
+	g.CheckOutbounds(true)
+	if hist.LoadURLTestHistory("a") == nil {
+		t.Fatal("an explicit CheckOutbounds(true) did not probe; the flag must only stand down the schedule")
+	}
+}
+
+// The option → outbound plumbing: nil/absent means on, an explicit false means
+// stood down, an explicit true means on. NewURLTest is the only place the
+// option is read, so this is where a plumbing regression would hide.
+func TestSelfCheckOptionPlumbing(t *testing.T) {
+	build := func(selfCheck *bool) *URLTest {
+		t.Helper()
+		opts := option.URLTestOutboundOptions{Outbounds: []string{"a"}}
+		opts.SelfCheck = selfCheck
+		ob, err := NewURLTest(context.Background(), nil, log.NewNOPFactory().Logger(), "t", opts)
+		if err != nil {
+			t.Fatalf("NewURLTest: %v", err)
+		}
+		return ob.(*URLTest)
+	}
+	if build(nil).selfCheckDisabled {
+		t.Fatal("nil SelfCheck must keep the self-check ON (the compatibility default)")
+	}
+	on, off := true, false
+	if build(&on).selfCheckDisabled {
+		t.Fatal("SelfCheck=true must keep the self-check on")
+	}
+	if !build(&off).selfCheckDisabled {
+		t.Fatal("SelfCheck=false must stand the self-check down")
+	}
+}
+
+// lx: health board §5.C — the RUNTIME gate (urltest.ProbeGate). The self-check
+// flag above says "the config reaches nothing here"; the gate says "the path in
+// front of this group is down right now". Both stand the SCHEDULE down; neither
+// touches an explicit check; and only the gate is allowed to change its mind
+// while the box runs.
+
+// fakeGate answers from a mutable set of blocked tags, so one test can watch a
+// group stop dialling and start again without rebuilding anything.
+type fakeGate struct {
+	mu      sync.Mutex
+	blocked map[string]bool
+	warm    map[string]bool
+	asked   int
+}
+
+func (g *fakeGate) ProbeAllowed(tag string) bool {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	g.asked++
+	return !g.blocked[tag]
+}
+
+func (g *fakeGate) ProbeWhenIdle(tag string) bool {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.warm[tag]
+}
+
+func (g *fakeGate) set(tag string, blocked bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	g.blocked[tag] = blocked
+}
+
+func (g *fakeGate) asks() int {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.asked
+}
+
+// A gated group makes NO DIAL ATTEMPT on its own schedule — the assertion is on
+// the attempt log, not on the board, because a probe that ran and failed leaves
+// the same "nothing useful known" as one that never ran, and only the attempt
+// log tells them apart. This is the waste half of the chain-hop fix: a hop
+// sitting behind a dead hop would otherwise spend one probe timeout per member
+// rediscovering the same broken hop.
+func TestProbeGateBlocksScheduledDials(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	defer hist.Close()
+	var dialed []string
+	a := &healthNode{tag: "chain-c-h3-a", fail: true, dialed: &dialed}
+	b := &healthNode{tag: "chain-c-h3-b", fail: true, dialed: &dialed}
+	gate := &fakeGate{blocked: map[string]bool{"chain-c-h3": true}}
+
+	g := healthTestGroup(hist, managerOf(a, b), a, b)
+	g.tag = "chain-c-h3"
+	g.probeGate = gate
+	// Touch arms a real ticker, so this group needs the two things
+	// healthTestGroup leaves out because nothing else in that suite starts one:
+	// a pause manager to register the ticker with, and the close channel Close
+	// shuts the loop down through.
+	g.pause = pause.ManagerFromContext(pause.WithDefaultManager(context.Background()))
+	g.close = make(chan struct{})
+
+	// The warm-up sweep: gated, so nothing is dialled. Give the (non-existent)
+	// sweep real time to have happened — the absence is the assertion.
+	g.PostStart()
+	if waitForHistory(hist, "chain-c-h3-a", 150*time.Millisecond) {
+		t.Fatal("a gated group's PostStart wrote to the board")
+	}
+	// A ticker tick, driven directly: this is the exact call loopCheck makes.
+	g.scheduledCheck()
+	if got := dialsOf(&dialed); len(got) != 0 {
+		t.Fatalf("gated group dialled %v; a hop behind a dead hop must not dial at all", got)
+	}
+
+	// Touch still arms the ticker. Refusing to arm it would leave a recovered
+	// hop with nothing to notice — the block would outlive the failure.
+	g.Touch()
+	g.access.Lock()
+	ticker := g.ticker
+	g.access.Unlock()
+	if ticker == nil {
+		t.Fatal("Touch did not arm the ticker on a gated group; nothing would be left to spot the recovery")
+	}
+	_ = g.Close()
+
+	// The hop in front comes back. Nothing is reset, nothing is reapplied — the
+	// next scheduled check simply asks again and gets a different answer.
+	gate.set("chain-c-h3", false)
+	before := gate.asks()
+	g.scheduledCheck()
+	if gate.asks() <= before {
+		t.Error("scheduledCheck did not re-ask the gate; a cached answer is a block that outlives its cause")
+	}
+	if len(dialsOf(&dialed)) == 0 {
+		t.Fatal("the group did not resume dialling after the hop in front recovered")
+	}
+}
+
+// An EXPLICIT check is a deliberate request and is never gated — the same rule
+// SelfCheck already follows. The gate stands down the schedule, not the
+// capability.
+func TestProbeGateDoesNotBlockExplicitCheck(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	defer hist.Close()
+	var dialed []string
+	a := &healthNode{tag: "chain-c-h3-a", fail: true, dialed: &dialed}
+	g := healthTestGroup(hist, managerOf(a), a)
+	g.tag = "chain-c-h3"
+	g.probeGate = &fakeGate{blocked: map[string]bool{"chain-c-h3": true}}
+
+	g.CheckOutbounds(true)
+	if len(dialsOf(&dialed)) == 0 {
+		t.Fatal("an explicit CheckOutbounds was refused by the gate")
+	}
+}
+
+// The two refusals are independent and compose the obvious way; and the absent
+// cases (no gate at all, an ungated tag) leave today's behaviour untouched,
+// which is what every plain sing-box config and every hand-built group relies
+// on.
+func TestSelfCheckAllowedCombinations(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	defer hist.Close()
+	a := &healthNode{tag: "a"}
+	base := func() *URLTestGroup { return healthTestGroup(hist, managerOf(a), a) }
+
+	if g := base(); !g.selfCheckAllowed() {
+		t.Error("a plain group with no gate must probe (the zero value is the compatibility default)")
+	}
+	g := base()
+	g.selfCheckDisabled = true
+	g.tag, g.probeGate = "chain-c-h3", &fakeGate{blocked: map[string]bool{}}
+	if g.selfCheckAllowed() {
+		t.Error("an UNUSED group must stay down even when the path in front is fine")
+	}
+	g = base()
+	g.tag, g.probeGate = "chain-c-h3", &fakeGate{blocked: map[string]bool{"chain-c-h3": true}}
+	if g.selfCheckAllowed() {
+		t.Error("a group behind a dead hop must not run its schedule")
+	}
+	g = base()
+	g.tag, g.probeGate = "auto", &fakeGate{blocked: map[string]bool{"chain-c-h3": true}}
+	if !g.selfCheckAllowed() {
+		t.Error("an unrelated group was gated by another tag's block")
+	}
+	g = base()
+	g.probeGate = &fakeGate{blocked: map[string]bool{"": true}}
+	if !g.selfCheckAllowed() {
+		t.Error("a group with no tag must not be gated; there is nothing to ask about")
+	}
+}

protocol/redirect/tproxy.go

@@ -16,6 +16,7 @@ import (
 	"github.com/sagernet/sing/common"
 	"github.com/sagernet/sing/common/buf"
 	"github.com/sagernet/sing/common/control"
+	E "github.com/sagernet/sing/common/exceptions" // lx:tproxy_writeback_connect
 	M "github.com/sagernet/sing/common/metadata"
 	N "github.com/sagernet/sing/common/network"
 	"github.com/sagernet/sing/common/udpnat2"
@@ -68,7 +69,26 @@ func (t *TProxy) Start(stage adapter.StartStage) error {
 }
 
 func (t *TProxy) Close() error {
-	return t.listener.Close()
+	err := t.listener.Close()
+	// lx:begin tproxy_writeback_connect
+	// Closing the listener stops INGRESS but leaves every live UDP NAT session in
+	// the cache, and each session holds a write-back socket bound to its original
+	// destination. Nothing else ever wakes those sessions: the cache evicts
+	// lazily (on the next Get/Add), and after this inbound is gone there is no
+	// next Get. For a DNS session answered in-engine by hijack-dns there is not
+	// even an outbound connection whose failure could unwind it, so its socket
+	// survives until a GC finalizer happens to reach it.
+	//
+	// That is invisible upstream, where an inbound is closed once at shutdown. On
+	// this fork the engine is REBUILT on every config apply, so each apply would
+	// strand another generation of sockets on the router's own LAN :53. Purge
+	// evicts every session; the cache's OnEvict closes the conn, which unblocks
+	// the session's routing goroutine and runs its onClose — the one place the
+	// write-back socket is actually closed. Purge AFTER the listener so a packet
+	// arriving mid-teardown cannot re-create a session behind us.
+	t.udpNat.Purge()
+	// lx:end tproxy_writeback_connect
+	return err
 }
 
 func (t *TProxy) NewConnection(ctx context.Context, conn net.Conn, metadata adapter.InboundContext, onClose N.CloseHandlerFunc) {
@@ -121,18 +141,92 @@ type tproxyPacketWriter struct {
 	conn        *net.UDPConn
 }
 
+// lx:begin tproxy_writeback_connect
+//
+// The TPROXY UDP write-back socket is bound to the ORIGINAL DESTINATION, so the
+// client sees the reply coming from the address it addressed. Upstream leaves
+// that socket UNCONNECTED (net.ListenPacket + WriteToUDPAddrPort), and that is
+// the bug this block exists for.
+//
+// An unconnected socket bound to <addr>:<port> is, as far as the kernel is
+// concerned, a RECEIVER for that address:port — and because the socket also
+// carries SO_REUSEADDR it silently joins the UDP demultiplex set of whatever
+// else is bound there. Nothing ever reads from it: this writer only sends. So
+// every datagram the kernel happens to hand it is lost.
+//
+// On a router that transparently intercepts LAN DNS towards its OWN address
+// (`nft ... udp dport 53 tproxy ...`) the original destination IS the router's
+// LAN address, so each intercepted DNS session parks another silent receiver on
+// <router-lan-ip>:53 right next to dnsmasq's socket — observed on the stand:
+// 33 such sockets against dnsmasq's one, several with a growing Recv-Q. The
+// host's own queries to that address take the loopback path, are never diverted,
+// and are therefore demultiplexed among all of them: they land in one of the
+// silent sockets at random and time out, permanently and unpredictably, while
+// every other DNS path on the box keeps working.
+//
+// Connecting the socket fixes it at the root. compute_score() in the kernel's
+// UDP lookup REJECTS a connected socket for any peer other than the connected
+// one, so a write-back socket can no longer be handed a datagram it will not
+// read. Nothing about the reply changes — same spoofed source address, same
+// single peer, one Write instead of one WriteTo.
+//
+// The unconnected path is kept verbatim for a destination that cannot be bound
+// (a domain socksaddr), so no existing case regresses.
+
+// newTProxyWriteBack creates the connected write-back socket: local address =
+// the original destination (transparent bind), peer = the client. A package
+// variable so the behaviour can be tested without CAP_NET_ADMIN.
+var newTProxyWriteBack = func(w *tproxyPacketWriter, destination M.Socksaddr) (*net.UDPConn, error) {
+	var dialer net.Dialer
+	dialer.LocalAddr = destination.UDPAddr()
+	dialer.Control = control.Append(dialer.Control, control.ReuseAddr())
+	dialer.Control = control.Append(dialer.Control, redir.TProxyWriteBack())
+	conn, err := w.listener.DialContext(dialer, w.ctx, "udp", w.source.String())
+	if err != nil {
+		return nil, err
+	}
+	udpConn, loaded := conn.(*net.UDPConn)
+	if !loaded {
+		conn.Close()
+		return nil, E.New("tproxy write back: unexpected connection type ", conn)
+	}
+	return udpConn, nil
+}
+
+// lx:end tproxy_writeback_connect
+
 func (w *tproxyPacketWriter) WritePacket(buffer *buf.Buffer, destination M.Socksaddr) error {
 	defer buffer.Release()
 	if w.listener.ListenOptions().NetNs == "" {
 		conn := w.conn
 		if w.destination == destination && conn != nil {
-			_, err := conn.WriteToUDPAddrPort(buffer.Bytes(), w.source)
+			// lx:begin tproxy_writeback_connect
+			// The cached socket is CONNECTED to the client, so this is a plain
+			// Write. A failed write also closes it: upstream only dropped the
+			// reference, leaving the fd to the GC finalizer.
+			_, err := conn.Write(buffer.Bytes())
 			if err != nil {
+				conn.Close()
 				w.conn = nil
 			}
 			return err
+			// lx:end tproxy_writeback_connect
 		}
 	}
+	// lx:begin tproxy_writeback_connect
+	if destination.IsIP() {
+		udpConn, err := newTProxyWriteBack(w, destination)
+		if err != nil {
+			return err
+		}
+		if w.listener.ListenOptions().NetNs == "" && w.destination == destination {
+			w.conn = udpConn
+		} else {
+			defer udpConn.Close()
+		}
+		return common.Error(udpConn.Write(buffer.Bytes()))
+	}
+	// lx:end tproxy_writeback_connect
 	var listenConfig net.ListenConfig
 	listenConfig.Control = control.Append(listenConfig.Control, control.ReuseAddr())
 	listenConfig.Control = control.Append(listenConfig.Control, redir.TProxyWriteBack())

protocol/redirect/tproxy_writeback_lx_test.go

@@ -0,0 +1,234 @@
+package redirect
+
+// Regression cover for the lx:tproxy_writeback_connect block in tproxy.go.
+//
+// The failure it guards against, seen on a live BPi-R3 Mini: `shaterd` held 33
+// UNCONNECTED UDP sockets on the router's own LAN address :53 — the write-back
+// sockets of intercepted DNS sessions — alongside dnsmasq's single socket on the
+// same address:port. Nothing reads a write-back socket, so every host-originated
+// query that the kernel demultiplexed into one of them was silently dropped
+// (Recv-Q climbing, sender timing out). Connecting the socket to the one peer it
+// ever talks to removes it from the demultiplex set for everybody else.
+//
+// The real socket needs CAP_NET_ADMIN (IP_TRANSPARENT) and a foreign bind, so
+// these tests drive the seam (newTProxyWriteBack) with an ordinary connected
+// loopback socket. That is enough to pin both properties that actually broke:
+//
+//   - the write path uses the CONNECTED form. If WritePacket ever goes back to
+//     WriteToUDPAddrPort, Go returns ErrWriteToConnected on a connected socket
+//     and these tests fail — i.e. the test cannot pass with an unconnected
+//     write-back socket, which is exactly the regression.
+//   - repeated writes to the same destination REUSE one socket instead of
+//     accumulating a new one per packet.
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/sagernet/sing-box/common/listener"
+	"github.com/sagernet/sing-box/option"
+
+	"github.com/sagernet/sing/common/buf"
+	M "github.com/sagernet/sing/common/metadata"
+	N "github.com/sagernet/sing/common/network"
+	"github.com/sagernet/sing/common/udpnat2"
+)
+
+// writeBackHarness stands up a loopback "client" socket and a tproxyPacketWriter
+// whose socket factory returns a plain connected UDP socket aimed at it. It
+// returns the writer, the client socket and a pointer to the factory call count.
+func writeBackHarness(t *testing.T) (*tproxyPacketWriter, *net.UDPConn, *int) {
+	t.Helper()
+
+	client, err := net.ListenUDP("udp", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1)})
+	if err != nil {
+		t.Fatalf("client socket: %v", err)
+	}
+	t.Cleanup(func() { client.Close() })
+
+	source := netip.MustParseAddrPort(client.LocalAddr().String())
+	w := &tproxyPacketWriter{
+		ctx:    context.Background(),
+		source: source,
+		// A listener with empty options is enough: WritePacket only reads
+		// ListenOptions().NetNs, and the factory is stubbed below.
+		listener: listener.New(listener.Options{
+			Context: context.Background(),
+			Listen:  option.ListenOptions{},
+		}),
+		destination: M.SocksaddrFrom(netip.MustParseAddr("127.0.0.1"), 53),
+	}
+
+	calls := 0
+	orig := newTProxyWriteBack
+	t.Cleanup(func() { newTProxyWriteBack = orig })
+	newTProxyWriteBack = func(w *tproxyPacketWriter, destination M.Socksaddr) (*net.UDPConn, error) {
+		calls++
+		// The real implementation binds the ORIGINAL DESTINATION transparently
+		// and connects to w.source; here we only reproduce the connect half,
+		// which is the property under test.
+		conn, err := net.DialUDP("udp", nil, net.UDPAddrFromAddrPort(w.source))
+		if err != nil {
+			return nil, err
+		}
+		return conn, nil
+	}
+	return w, client, &calls
+}
+
+// readOne reads one datagram from the client socket with a short deadline.
+func readOne(t *testing.T, client *net.UDPConn) string {
+	t.Helper()
+	_ = client.SetReadDeadline(time.Now().Add(2 * time.Second))
+	b := make([]byte, 512)
+	n, _, err := client.ReadFrom(b)
+	if err != nil {
+		t.Fatalf("client read: %v", err)
+	}
+	return string(b[:n])
+}
+
+// TestWriteBackUsesConnectedSocket: the reply must go out over a CONNECTED
+// socket. On the pre-fix code the write is WriteToUDPAddrPort, which Go refuses
+// on a connected socket ("use of WriteTo with pre-connected connection"), so
+// this test is red for exactly the shape that caused the outage.
+func TestWriteBackUsesConnectedSocket(t *testing.T) {
+	w, client, calls := writeBackHarness(t)
+
+	if err := w.WritePacket(buf.As([]byte("first")).ToOwned(), w.destination); err != nil {
+		t.Fatalf("WritePacket: %v", err)
+	}
+	if got := readOne(t, client); got != "first" {
+		t.Fatalf("client got %q, want %q", got, "first")
+	}
+	if *calls != 1 {
+		t.Fatalf("expected one write-back socket, got %d", *calls)
+	}
+}
+
+// TestWriteBackReusesOneSocket: a session that keeps answering the same client
+// must keep ONE socket, not open a fresh one per datagram. The live box carried
+// one socket per intercepted DNS session already; one per PACKET would turn a
+// nuisance into an fd exhaustion.
+func TestWriteBackReusesOneSocket(t *testing.T) {
+	w, client, calls := writeBackHarness(t)
+
+	for i, payload := range []string{"a", "b", "c", "d"} {
+		if err := w.WritePacket(buf.As([]byte(payload)).ToOwned(), w.destination); err != nil {
+			t.Fatalf("WritePacket %d: %v", i, err)
+		}
+		if got := readOne(t, client); got != payload {
+			t.Fatalf("packet %d: client got %q, want %q", i, got, payload)
+		}
+	}
+	if *calls != 1 {
+		t.Fatalf("four packets to one destination must share one socket, got %d sockets", *calls)
+	}
+	if w.conn == nil {
+		t.Fatalf("the write-back socket must be cached on the writer for reuse")
+	}
+}
+
+// TestWriteBackClosesSocketOnWriteFailure: upstream dropped the reference to a
+// failed socket without closing it, leaving the fd to the GC finalizer. On a box
+// that already parks one socket per DNS session that is the wrong direction.
+func TestWriteBackClosesSocketOnWriteFailure(t *testing.T) {
+	w, client, _ := writeBackHarness(t)
+
+	if err := w.WritePacket(buf.As([]byte("warm")).ToOwned(), w.destination); err != nil {
+		t.Fatalf("WritePacket: %v", err)
+	}
+	readOne(t, client)
+
+	cached := w.conn
+	if cached == nil {
+		t.Fatalf("expected a cached socket after the first write")
+	}
+	// Close it behind WritePacket's back so the next write fails, exactly as a
+	// dead peer or a torn-down plane would make it fail.
+	cached.Close()
+
+	if err := w.WritePacket(buf.As([]byte("boom")).ToOwned(), w.destination); err == nil {
+		t.Fatalf("a write on a closed socket must report the failure")
+	}
+	if w.conn != nil {
+		t.Fatalf("a failed write must drop the cached socket")
+	}
+	// A second Close on an already-closed conn is an error, which is how we know
+	// WritePacket closed it rather than merely forgetting it.
+	if err := cached.Close(); err == nil {
+		t.Fatalf("WritePacket must CLOSE the failed socket, not just nil the field")
+	}
+}
+
+// --- Close() must release the UDP NAT sessions --------------------------------
+
+// natSessionHandler stands in for the router: it drains the session conn until
+// it errors (which is what Close does to it) and then reports onClose, exactly
+// as the real routing goroutine does. onClose is where the write-back socket is
+// closed, so "onClose fired" is the observable proof the socket was released.
+type natSessionHandler struct {
+	released chan error
+}
+
+func (h *natSessionHandler) NewPacketConnectionEx(ctx context.Context, conn N.PacketConn, source M.Socksaddr, destination M.Socksaddr, onClose N.CloseHandlerFunc) {
+	go func() {
+		for {
+			buffer := buf.NewSize(1024)
+			_, err := conn.ReadPacket(buffer)
+			buffer.Release()
+			if err != nil {
+				if onClose != nil {
+					onClose(err)
+				}
+				h.released <- err
+				return
+			}
+		}
+	}()
+}
+
+// TestTProxyCloseReleasesNatSessions pins the apply-level half of the leak.
+//
+// Closing the inbound used to close the listener only. The NAT cache evicts
+// lazily, so after the inbound is gone nothing ever touches it again and every
+// live session — with the write-back socket it holds on the router's own
+// LAN :53 — was left to a GC finalizer. On this fork the engine is rebuilt on
+// every config apply, so that is one stranded generation of sockets per apply.
+func TestTProxyCloseReleasesNatSessions(t *testing.T) {
+	handler := &natSessionHandler{released: make(chan error, 1)}
+	tp := &TProxy{
+		ctx: context.Background(),
+		listener: listener.New(listener.Options{
+			Context: context.Background(),
+			Listen:  option.ListenOptions{},
+		}),
+	}
+	prepared := 0
+	tp.udpNat = udpnat.New(handler, func(source M.Socksaddr, destination M.Socksaddr, userData any) (bool, context.Context, N.PacketWriter, N.CloseHandlerFunc) {
+		prepared++
+		return true, context.Background(), nil, func(error) {}
+	}, time.Minute, false)
+
+	tp.udpNat.NewPacket(
+		[][]byte{{0x00}},
+		M.SocksaddrFrom(netip.MustParseAddr("10.67.0.2"), 40000),
+		M.SocksaddrFrom(netip.MustParseAddr("10.67.0.1"), 53),
+		nil,
+	)
+	if prepared != 1 {
+		t.Fatalf("expected one NAT session, got %d", prepared)
+	}
+
+	if err := tp.Close(); err != nil {
+		t.Fatalf("Close: %v", err)
+	}
+	select {
+	case <-handler.released:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Close must release every live NAT session (and with it the write-back socket it holds)")
+	}
+}

scripts/build-shaterd.sh

@@ -18,17 +18,21 @@
 #      OpenWrt package can $(INSTALL_BIN) the arch-matched artifact.
 #   5. Prints a size table + a per-arch static check (ELF type / no PT_INTERP).
 #
-# Router build tag set = D9 (musl-static). We deliberately DROP with_purego and
-# with_naive_outbound: they pull cronet-go, which forces a glibc PT_INTERP even
-# with CGO_ENABLED=0, making the binary unusable on musl OpenWrt.
+# Router build tag set = D9/D23 (musl-static). It is DEFINED IN, and only in,
+# scripts/router-tags.sh (sourced below) — that file documents every tag and is
+# machine-checked against the declared feature list by shater/buildtags's test.
+# Run scripts/check-router-tags.sh after touching it.
 #
 # Usage:
 #   scripts/build-shaterd.sh [VERSION] [--fast]
 #
 #   VERSION   Version string stamped into constant.Version. Resolution order:
 #               1) this positional arg, if given
-#               2) $SHATER_VERSION, if set
-#               3) `git describe --tags` (nearest tag + commit)
+#               2) $SHATER_VERSION, if set (CI sets it from ci/version.sh)
+#               3) `ci/version.sh --binary` — THE single source of truth shared
+#                  with the package version (vX.Y.Z-rR[-g<sha>], derived from
+#                  the git tag exactly like PKG_VERSION/PKG_RELEASE), so the
+#                  string the panel shows always matches `apk info shaterd`
 #               4) fallback: v0.2.0-dev
 #   --fast    Skip `npm ci` when panel/node_modules already exists (dev speed-up).
 #
@@ -69,24 +73,25 @@ if [ -n "$VERSION_ARG" ]; then
 	VERSION="$VERSION_ARG"
 elif [ -n "${SHATER_VERSION:-}" ]; then
 	VERSION="$SHATER_VERSION"
-elif VERSION="$(git -C "$REPO" describe --tags 2>/dev/null)"; then
-	: # git describe succeeded
+elif VERSION="$(sh "$REPO/ci/version.sh" --binary)"; then
+	# Same computation the PACKAGE version comes from (ci/version.sh), so the
+	# binary's constant.Version and the .ipk/.apk version can never drift apart.
+	: # ci/version.sh always succeeds (it falls back to 0.0.0 without git)
 else
 	VERSION="v0.2.0-dev"
 fi
 [ -n "$VERSION" ] || VERSION="v0.2.0-dev"
 
 # --- config -----------------------------------------------------------------
-# D9 router tag set (musl-static). Keep in sync with docs-shater/DECISIONS.md D9.
-# No with_gvisor: the data plane is tproxy/redirect (netplane), generate never
-# emits a tun inbound, so the userspace gvisor stack was 3.6 MB of dead weight
-# (tun would fall back to the system stack anyway).
-# No with_clash_api: the panel is shater's own; generate never emits a clash_api
-# service ("the shater generator emits none of those" — shater/engine/engine.go).
-# No with_dhcp: shater resolvers are udp/tcp/doh/dot/local/fakeip — no "dhcp://"
-# DNS transport is ever generated, and the slim registry never registers it.
-ROUTER_TAGS="with_quic,with_wireguard,with_utls,badlinkname,tfogo_checklinkname0,with_xhttp,with_awg,with_lx_command"
-LDFLAGS="-X github.com/sagernet/sing-box/constant.Version=${VERSION} -checklinkname=0 -s -w -buildid="
+# D9/D23 router tag set (musl-static). The set itself lives in ONE place —
+# scripts/router-tags.sh — because it is also parsed by shater/buildtags's test,
+# which proves it still covers every feature docs-shater/FEATURES.md declares.
+# Do not re-inline it here: that split is exactly how `with_gvisor` went missing
+# while `with_wireguard` stayed (D23).
+# shellcheck source=router-tags.sh
+. "$SCRIPT_DIR/router-tags.sh"
+ROUTER_TAGS="$SHATER_ROUTER_TAGS"
+LDFLAGS="-X github.com/sagernet/sing-box/constant.Version=${VERSION} ${SHATER_ROUTER_LDFLAGS} -s -w -buildid="
 
 UPX_BIN="${UPX:-upx}"
 # UPX itself treats the environment variable UPX as extra command-line options, so
@@ -106,6 +111,20 @@ echo "  version : $VERSION"
 echo "  tags    : $ROUTER_TAGS"
 echo "  upx     : $UPX_BIN"
 echo "  go      : $(go version)"
+
+# --- gate: does this tag set still support what we declare? (D23) ------------
+# Cheap (one tiny tag-less package, no network, ~1 s) and it travels with the
+# BUILD rather than with a CI config, so an artifact produced by hand on a
+# developer's machine gets the same guarantee. The heavier half — actually
+# constructing every declared protocol under these tags — is
+# scripts/check-router-tags.sh, which CI runs before this script.
+if ! (cd "$REPO" && go test -count=1 ./shater/buildtags/ >/dev/null); then
+	echo >&2
+	echo "  ABORT: the router tag set no longer covers a declared feature." >&2
+	echo "         Details: go test ./shater/buildtags/" >&2
+	echo "         Full check: scripts/check-router-tags.sh" >&2
+	exit 1
+fi
 echo
 
 # --- step 1: build the SPA --------------------------------------------------

scripts/check-router-tags.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+#
+# check-router-tags.sh — prove the SHIPPED build-tag set still supports every
+# feature shater declares (D23).
+#
+# WHY (2026-07-25): the router tag set is a trimmed subset of upstream's, but the
+# test suite builds with the FULL upstream set — so the one combination we
+# actually ship was never exercised. `with_gvisor` got trimmed while
+# `with_wireguard` stayed, and every shipped binary answered a WireGuard node
+# with "gVisor is not included in this build". Compiling is not evidence.
+#
+# WHAT IT RUNS
+#   1. shater/buildtags, TAG-LESS — reads scripts/router-tags.sh and fails if a
+#      declared feature (buildtags.Features) lost a build tag it needs. Cheap,
+#      hostable anywhere, catches the trim at the moment it happens.
+#   2. shater/generate + shater/buildtags, WITH THE SHIPPED TAG SET on linux —
+#      constructs one node of every declared protocol through box.New+Start, and
+#      cross-checks that the tag detectors match the set the compiler was given.
+#      This is the half that catches "the tag is there but insufficient".
+#
+# The run is unprivileged (no tproxy inbound is built) and offline apart from Go
+# module downloads.
+#
+# Usage:
+#   scripts/check-router-tags.sh
+#
+# Env:
+#   SHATER_GO_IMAGE   docker image used to reach linux from a non-linux host
+#                     (default golang:1.26 — keep it >= go.mod's toolchain).
+#   SHATER_NO_DOCKER=1  fail instead of falling back to docker.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$REPO"
+
+# shellcheck source=router-tags.sh
+. "$SCRIPT_DIR/router-tags.sh"
+
+echo "== router build-tag check =="
+echo "  tags   : $SHATER_ROUTER_TAGS"
+echo "  ldflags: $SHATER_ROUTER_LDFLAGS"
+echo
+
+# --- 1. static: does the set still cover the declared features? --------------
+# No tags, no OS constraint: this is the check that would have caught the outage
+# on the developer's own machine.
+echo "== [1/2] declared features vs. the shipped tag set (no tags needed) =="
+go test -count=1 ./shater/buildtags/
+echo
+
+# --- 2. behavioural: does the shipped combination actually construct? --------
+# The protocol-construction test is linux-only (box.New validates the loop-guard
+# routing_mark only there). From a non-linux host, re-exec this script inside a
+# golang container rather than silently skipping — a skipped guard is no guard.
+if [ "$(go env GOOS)" != "linux" ] && [ "${SHATER_TAGCHECK_IN_DOCKER:-0}" != "1" ]; then
+	if [ "${SHATER_NO_DOCKER:-0}" = "1" ] || ! command -v docker >/dev/null 2>&1; then
+		echo "  ERROR: step 2 needs linux (GOOS=$(go env GOOS)) and docker is unavailable/disabled." >&2
+		echo "         Run this script on the linux CI runner or the OpenWrt VM." >&2
+		exit 1
+	fi
+	image="${SHATER_GO_IMAGE:-golang:1.26}"
+	echo "== [2/2] re-exec on linux via docker ($image) =="
+	host_repo="$REPO"
+	command -v cygpath >/dev/null 2>&1 && host_repo="$(cygpath -w "$REPO")"
+	# Named volumes keep the module/build cache warm between runs; MSYS2_ARG_CONV_EXCL
+	# stops Git Bash from rewriting the container-side paths into windows ones.
+	MSYS2_ARG_CONV_EXCL='*' MSYS_NO_PATHCONV=1 docker run --rm \
+		-v "$host_repo":/src \
+		-v shater-tagcheck-gomod:/go/pkg/mod \
+		-v shater-tagcheck-gocache:/root/.cache/go-build \
+		-w /src \
+		-e SHATER_TAGCHECK_IN_DOCKER=1 \
+		"$image" bash scripts/check-router-tags.sh
+	exit $?
+fi
+
+echo "== [2/2] every declared protocol constructs under the SHIPPED tags =="
+out="$(mktemp)"
+trap 'rm -f "$out"' EXIT
+set +e
+SHATER_ROUTER_TAG_CHECK=1 go test -count=1 -v \
+	-tags "$SHATER_ROUTER_TAGS" -ldflags "$SHATER_ROUTER_LDFLAGS" \
+	-run 'TestShippedTagSetConstructsDeclaredProtocols|TestEveryTagGatedFeatureIsProbed' \
+	./shater/generate/ >"$out" 2>&1
+rc_gen=$?
+set -e
+sed 's/^/    /' "$out"
+
+set +e
+SHATER_ROUTER_TAG_CHECK=1 go test -count=1 -v \
+	-tags "$SHATER_ROUTER_TAGS" -ldflags "$SHATER_ROUTER_LDFLAGS" \
+	-run 'TestCompiledTagsMatchTheShippedSet' \
+	./shater/buildtags/ >"$out" 2>&1
+rc_tags=$?
+set -e
+sed 's/^/    /' "$out"
+
+if [ "$rc_gen" -ne 0 ] || [ "$rc_tags" -ne 0 ]; then
+	echo
+	echo "  FAILED: the tag set we SHIP cannot do what we declare." >&2
+	exit 1
+fi
+
+# A guard that silently runs nothing is worse than no guard: prove the tests were
+# actually compiled in and executed (build tags / file renames could exclude them).
+for want in TestShippedTagSetConstructsDeclaredProtocols TestCompiledTagsMatchTheShippedSet; do
+	if ! SHATER_ROUTER_TAG_CHECK=1 go test -count=1 -v \
+		-tags "$SHATER_ROUTER_TAGS" -ldflags "$SHATER_ROUTER_LDFLAGS" \
+		-run "$want" ./shater/generate/ ./shater/buildtags/ 2>&1 | grep -q -- "--- PASS: $want"; then
+		echo "  FAILED: $want did not run (build-tag/file-name drift?)" >&2
+		exit 1
+	fi
+done
+
+echo
+echo "== OK: the shipped tag set covers every declared feature, and every =="
+echo "==     declared protocol constructs through box.New under it.      =="

scripts/router-tags.sh

@@ -0,0 +1,78 @@
+# shellcheck shell=sh
+#
+# router-tags.sh — THE build-tag set of the shipped `shaterd` router binary.
+#
+# This file is DATA, not a program: it is `.`-sourced by
+#   - scripts/build-shaterd.sh     (the ship build)
+#   - scripts/check-router-tags.sh (the guard that proves the set is complete)
+# and it is PARSED by shater/buildtags/buildtags_test.go, which asserts that
+# every feature docs-shater/FEATURES.md declares supported has its build tags
+# present here. Change the set here and nowhere else.
+#
+# WHY A TRIMMED SET AT ALL (D9): upstream's DEFAULT_BUILD_TAGS registers the
+# whole sing-box zoo. We drop what shater/generate can never emit, because a
+# router binary pays for every tag twice — flash and (UPX unpacks into anonymous
+# pages) resident RAM. We do NOT drop what a declared feature needs to run.
+#
+# WHY THIS FILE EXISTS (the 2026-07-25 WireGuard outage): the set used to be a
+# string literal inside build-shaterd.sh, with nothing connecting it to the
+# feature list. `with_gvisor` was trimmed as "unreachable code" while
+# `with_wireguard` stayed — so every shipped binary answered a WireGuard node
+# with "gVisor is not included in this build". No test caught it: the test suite
+# builds with the FULL upstream tag set, so the SHIPPED combination was never
+# exercised. One file + one test now hold the two halves together (D23).
+#
+# ---- the set -----------------------------------------------------------------
+#   with_gvisor            userspace netstack. REQUIRED BY with_wireguard: both
+#                          transport/wireguard device constructors
+#                          (newStackDevice AND newSystemStackDevice) are stubs
+#                          returning tun.ErrGVisorNotIncluded without it, so
+#                          box.New dies at "create WireGuard device". Not
+#                          optional as long as we ship WireGuard/AmneziaWG.
+#   with_quic              hysteria2 + tuic outbounds, QUIC/HTTP3 DNS
+#                          transports, and the vless/vmess `type=quic` transport
+#                          (shater/registry/registry_quic.go).
+#   with_wireguard         registers the wireguard endpoint
+#                          (shater/registry/registry_wireguard.go).
+#   with_awg               AmneziaWG obfuscation params (jc/jmin/jmax, s1-s4,
+#                          h1-h4, i1-i5) actually reach the device
+#                          (transport/wireguard/device_awg.go). A driving
+#                          product requirement — FEATURES.md marks it [MVP].
+#   with_utls              uTLS fingerprints AND REALITY: common/tls/
+#                          reality_client.go is itself `//go:build with_utls`.
+#   with_xhttp             the XHTTP/SplitHTTP v2ray transport
+#                          (shater/parse emits type=xhttp).
+#   badlinkname            badtls fast path (common/badtls/*.go are
+#                          `go1.25 && badlinkname`). Needs -checklinkname=0 in
+#                          SHATER_ROUTER_LDFLAGS below or the LINK step fails.
+#   tfogo_checklinkname0   same deal for tfo-go's linkname use.
+#   with_lx_command        lx daemon command server. Inert for shaterd (nothing
+#                          under shater/ imports sing-box/daemon or libbox —
+#                          `go list -deps ./shater/cmd/shaterd` links neither),
+#                          kept only so the router set stays a subset of the lx
+#                          desktop set. Costs nothing; safe to drop later.
+#
+# Deliberately NOT here (each is unreachable for shater, not merely unused):
+#   with_purego,with_naive_outbound  cronet-go forces a glibc PT_INTERP even at
+#                                    CGO_ENABLED=0 -> will not run on musl (D9).
+#   with_clash_api                   the panel is shater's own web server;
+#                                    generate emits no clash_api service.
+#   with_dhcp                        resolver types are udp/tcp/doh/dot/local/
+#                                    fakeip; no dhcp:// transport is generated.
+#   with_tailscale,with_acme,with_ech,with_usbip,with_cloudflared,with_ocm,
+#   with_ccm,with_v2ray_api,with_reality_server
+#                                    nothing in shater/parse or shater/generate
+#                                    can produce them; hysteria2 `ech=` is
+#                                    refused with a warning in the parser.
+#
+# Adding a tag here is cheap. REMOVING one is a product decision: run
+# `scripts/check-router-tags.sh` — it fails if the set no longer covers a
+# declared feature, and it fails if the shipped combination cannot construct
+# every protocol through box.New.
+
+SHATER_ROUTER_TAGS="with_gvisor,with_quic,with_wireguard,with_utls,badlinkname,tfogo_checklinkname0,with_xhttp,with_awg,with_lx_command"
+
+# Linker flags the tag set REQUIRES (they are not optional trimming: `badlinkname`
+# without -checklinkname=0 fails at link time with
+# "invalid reference to crypto/tls.(*Conn).handlePostHandshakeMessage").
+SHATER_ROUTER_LDFLAGS="-checklinkname=0"

shater/apply/apply.go

@@ -74,6 +74,19 @@ type Applier struct {
 	stateMu sync.RWMutex
 	holding bool
 
+	// traffic is WHERE THE TRAFFIC GOES under the config that is currently running:
+	// tunnelled, split, straight out, or blocked (see generate.TrafficOf). It is
+	// computed from the generated option.Options at the moment they are handed to
+	// the engine, so it describes what runs rather than what is on disk.
+	//
+	// Deliberately separate from `holding` and from Plane, which answer "how much of
+	// the data plane is installed". The panel used to read Plane == "full" as
+	// "protected" and said so under a green LED on a router whose only rule was
+	// `default -> direct`; the plane really was fully installed, and the whole LAN
+	// really was going out the plain WAN. Zero value = not known (no successful
+	// apply in this process yet), which is NOT the same as "tunnel".
+	traffic generate.Traffic // guarded by stateMu
+
 	// lastWarnings is the normalised warning set from the last SUCCESSFUL apply,
 	// published through Status so the panel can show fail-open degradations
 	// (a blocklist that did not load, a DoH host left reachable) instead of
@@ -192,11 +205,15 @@ func (a *Applier) configureObservatory(m *model.Model, opts option.Options) {
 	})
 }
 
-// TestGroups launches the engine's one-shot exit test (delay + exit address, F2)
-// of the named groups/chains, returning started=false when a run is already in
-// flight or the engine is absent. names empty/nil = every group and every chain.
-// It takes NEITHER the apply mutex nor the flock, so kicking off a test never
-// blocks behind an Apply.
+// TestGroups launches the engine's one-shot group/chain test (F2): the engine
+// asks its observatory for an out-of-turn pass and reports what it measured,
+// plus the exit address for alive rule-routed targets — it no longer dials
+// health probes of its own. Returns started=false when a run is already in
+// flight or the engine is absent. names empty/nil = every group and every
+// chain. probeURL is passed through for signature stability and IGNORED by the
+// engine (the probe URL is a global observatory setting now). It takes NEITHER
+// the apply mutex nor the flock, so kicking off a test never blocks behind an
+// Apply.
 func (a *Applier) TestGroups(names []string, probeURL string) (started bool) {
 	if a.eng == nil {
 		return false
@@ -488,6 +505,23 @@ func (a *Applier) applyLocked(m *model.Model) (bool, error) {
 		return changed, err
 	}
 
+	// The plane is COMPLETE only here: table + policy routing + sysctls. ApplyNft
+	// already flushed the DNS conntrack when it loaded the ruleset, but that is
+	// one step too early — ApplyRouting is idempotent BY del-then-add, so it opens
+	// a window in which the fwmark rule is momentarily absent, and any DNS flow
+	// that crosses that window is tracked against a plane that is still being
+	// assembled. Flushing once more now that every piece is in place is what makes
+	// "no entry survives the transition" actually true. Only on a real change (the
+	// fast path assembled nothing), best-effort, and cheap: the :53 entry count is
+	// bounded by the number of clients.
+	if !nftCurrent {
+		if n, ferr := netplane.FlushDNSConntrack(); ferr != nil {
+			a.log.Debug("flush DNS conntrack after plane change: ", ferr)
+		} else if n > 0 {
+			a.log.Debug("plane changed: dropped ", n, " stale DNS conntrack entries")
+		}
+	}
+
 	// (4) success. Bump the effective-state generation ONLY when something really
 	// moved: a no-op reconcile must not invalidate an armed commit-confirm window
 	// (cron reconciles every minute — counting those would cancel every rollback
@@ -497,6 +531,12 @@ func (a *Applier) applyLocked(m *model.Model) (bool, error) {
 	}
 	a.setHolding(false)
 	a.lastGood = m
+	// Publish where this config actually sends traffic, read off the very options
+	// the engine was just handed (a.eng.Apply above). The engine's hash fast-path
+	// may have skipped a swap, in which case these options are hash-equal to what is
+	// already running — either way they are the running config, which is the only
+	// config this verdict may describe.
+	a.setTraffic(generate.TrafficOf(opts))
 	// Publish the warnings of THIS successful apply, in one normalised set, and log
 	// them in one consistent format. Status carries them to the panel so a
 	// fail-open degradation is visible in the UI instead of only in logread.
@@ -540,6 +580,11 @@ func (a *Applier) applyLocked(m *model.Model) (bool, error) {
 // With the kill-switch OPEN nothing is installed — fail-open is the operator's
 // documented choice and this must not quietly override it.
 func (a *Applier) holdLocked(m *model.Model, cause error) {
+	// The engine is not carrying anything, so whatever the last running config did
+	// with traffic is no longer true of this router. Forget it either way — a stale
+	// "tunnel" verdict left behind by a config that is no longer running is the same
+	// reassuring lie in a different place.
+	a.setTraffic(generate.Traffic{})
 	if !killSwitchClosed(m.Globals) {
 		a.log.Warn("engine is down and kill_switch=open: LAN traffic is NOT protected (documented fail-open): ", cause)
 		return
@@ -623,24 +668,52 @@ func (a *Applier) setHolding(v bool) {
 	a.stateMu.Unlock()
 }
 
+// Traffic returns where the traffic of the CURRENTLY RUNNING config goes. The
+// zero value means no config of this process's is running (nothing applied yet,
+// or the plane was torn down / put on hold), and callers must render that as
+// "unknown", never as protected.
+func (a *Applier) Traffic() generate.Traffic {
+	a.stateMu.RLock()
+	defer a.stateMu.RUnlock()
+	return a.traffic
+}
+
+func (a *Applier) setTraffic(t generate.Traffic) {
+	a.stateMu.Lock()
+	a.traffic = t
+	a.stateMu.Unlock()
+}
+
 func (a *Applier) setWarnings(ws []Warning) {
 	a.stateMu.Lock()
 	a.lastWarnings = ws
 	a.stateMu.Unlock()
 }
 
-// Warnings returns the normalised warning set from the last successful apply.
-// Never nil: an empty slice means "the last apply was clean", which the panel
-// must render differently from "no apply has run yet" (Active/Plane cover that).
+// Warnings returns the normalised warning set from the last successful apply,
+// PLUS whatever is wrong right now that no apply can describe. Never nil: an
+// empty slice means "the last apply was clean", which the panel must render
+// differently from "no apply has run yet" (Active/Plane cover that).
+//
+// The live half is currently the engine's abandoned generations
+// (engineTeardownWarnings). It is computed at READ time rather than folded into
+// lastWarnings on purpose: a superseded box that will not shut down is a
+// condition of the process, not a property of a config. Folding it in would make
+// it appear only after the NEXT successful apply and then stay published long
+// after the shutdown finally completed — reporting a leak that is over, and
+// staying silent about one that is not. Read-time means it shows up the instant
+// it happens and clears itself the instant it resolves.
 func (a *Applier) Warnings() []Warning {
+	var out []Warning
+	if a.eng != nil {
+		out = engineTeardownWarnings(a.eng.PendingCloses())
+	}
 	a.stateMu.RLock()
 	defer a.stateMu.RUnlock()
-	if a.lastWarnings == nil {
+	if out == nil && a.lastWarnings == nil {
 		return []Warning{}
 	}
-	out := make([]Warning, len(a.lastWarnings))
-	copy(out, a.lastWarnings)
-	return out
+	return append(out, a.lastWarnings...)
 }
 
 // Reconcile re-reads UCI and either tears down (disabled) or re-applies (enabled).
@@ -706,6 +779,7 @@ func (a *Applier) Teardown() error {
 	a.lastGood = nil
 	a.lastNft = ""
 	a.setHolding(false)
+	a.setTraffic(generate.Traffic{})
 	a.setWarnings(nil)
 	// The plane is gone, so the logged set no longer describes anything. Forget it,
 	// and the next apply re-announces its warnings in full rather than staying
@@ -986,6 +1060,20 @@ type Status struct {
 	//	         say so rather than looking healthy.
 	Plane string `json:"plane"`
 
+	// Traffic is WHERE THE TRAFFIC GOES under the running config — tunnelled, split,
+	// straight out, or blocked (see generate.Traffic).
+	//
+	// Plane does NOT answer this, and reading it as if it did is the defect this
+	// field exists for. Plane == "full" only means the table, the policy routing and
+	// the engine are all in place; a router whose one rule is `default -> direct` has
+	// all three and sends every packet out the plain WAN with its real address. The
+	// panel showed that as "Protected — traffic is going through the tunnel".
+	//
+	// Zero value (Verdict == "") means unknown: no successful apply has run in this
+	// daemon process yet, or the plane is on hold / torn down. A consumer must render
+	// that as unknown and never as protected.
+	Traffic generate.Traffic `json:"traffic"`
+
 	// Warnings is the normalised warning set from the last successful apply:
 	// everything that was skipped, degraded or left un-applied while the apply
 	// still succeeded. Always non-nil so the panel can map over it unconditionally.
@@ -1065,6 +1153,7 @@ func (a *Applier) Status() Status {
 		Hash:          a.eng.Hash(),
 		CanRollback:   a.canRollback(),
 		EngineRunning: a.eng.Running(),
+		Traffic:       a.Traffic(),
 		Warnings:      a.Warnings(),
 	}
 	s.StartedUnix, s.UptimeSeconds = processUptime(time.Now())

shater/apply/teardown_test.go

@@ -0,0 +1,283 @@
+package apply
+
+// Regression cover for the leaked-engine-generation defect.
+//
+// Observed on the router: one shaterd process was carrying up to FOUR sing-box
+// instances at once. sing-box stamps every log line with the elapsed seconds of
+// ITS OWN instance, so the same process printed `ERROR[2015]` and `ERROR[0129]`
+// in the same second — two engines half an hour apart in age, both alive, both
+// dialling, both holding WireGuard devices built from the same private keys. A
+// full daemon stop+start collapsed it back to one generation, which places the
+// leak squarely on the config re-apply path rather than on startup.
+//
+// The tests below pin the two halves of the fix:
+//
+//	TestApplySwapsLeaveExactlyOneEngineGeneration — the healthy path really
+//	  retires the old instance (its listener is provably gone), N times in a row.
+//	TestStuckEngineCloseDoesNotBlockTheApply     — a shutdown that never returns
+//	  is bounded, does not stall the apply, and is REPORTED as a critical warning
+//	  for exactly as long as it is true.
+
+import (
+	"io"
+	"net"
+	"net/netip"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	C "github.com/sagernet/sing-box/constant"
+	"github.com/sagernet/sing-box/option"
+	"github.com/sagernet/sing-box/shater/engine"
+	"github.com/sagernet/sing/common/json/badoption"
+)
+
+// mixedOn builds a minimal but REAL engine config: a mixed inbound bound to
+// 127.0.0.1:port plus a direct outbound. Two configs with different ports hash
+// differently, so each Apply is a genuine swap rather than a hash-gate no-op —
+// and the bound port is the observable that proves whether the old instance
+// actually died.
+func mixedOn(port uint16) option.Options {
+	listen := badoption.Addr(netip.MustParseAddr("127.0.0.1"))
+	return option.Options{
+		Log: &option.LogOptions{Level: "error"},
+		Inbounds: []option.Inbound{{
+			Type: C.TypeMixed,
+			Tag:  "mixed-in",
+			Options: &option.HTTPMixedInboundOptions{
+				ListenOptions: option.ListenOptions{Listen: &listen, ListenPort: port},
+			},
+		}},
+		Outbounds: []option.Outbound{{
+			Type:    C.TypeDirect,
+			Tag:     "direct-out",
+			Options: &option.DirectOutboundOptions{},
+		}},
+	}
+}
+
+// portFree reports whether 127.0.0.1:port can be bound right now — i.e. whether
+// the instance that used to listen there is really gone. Retried briefly because
+// a listener is released by Close, not by the return of Close's caller.
+func portFree(port uint16) bool {
+	deadline := time.Now().Add(3 * time.Second)
+	for {
+		ln, err := net.Listen("tcp", net.JoinHostPort("127.0.0.1", strconv.Itoa(int(port))))
+		if err == nil {
+			_ = ln.Close()
+			return true
+		}
+		if time.Now().After(deadline) {
+			return false
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+}
+
+// TestApplySwapsLeaveExactlyOneEngineGeneration is the core regression: after N
+// sequential applies the process must be carrying ONE engine, not N.
+//
+// "Carrying" is checked two ways on purpose. Generations() is the engine's own
+// accounting (running instance + every retirement still in flight) and would
+// catch a retirement that silently never completes. The port check is
+// independent of that accounting: if the superseded instance were still alive it
+// would still hold its listener, and the bind would fail. A fix that only
+// reset a pointer would pass the first check and fail the second.
+func TestApplySwapsLeaveExactlyOneEngineGeneration(t *testing.T) {
+	const (
+		firstPort = 18801
+		applies   = 5
+	)
+
+	a := New(engine.New(), nil)
+	t.Cleanup(func() { _ = a.eng.Close() })
+
+	for i := 0; i < applies; i++ {
+		port := uint16(firstPort + i)
+		changed, err := a.eng.Apply(mixedOn(port))
+		if err != nil {
+			t.Fatalf("apply #%d (port %d): %v", i+1, port, err)
+		}
+		if !changed {
+			t.Fatalf("apply #%d: every config here differs, so the swap must be real", i+1)
+		}
+		if got := a.eng.Generations(); got != 1 {
+			t.Fatalf("after apply #%d the process carries %d engine instances, want exactly 1 — "+
+				"a superseded generation is still alive (this is the four-generations-in-one-process leak)",
+				i+1, got)
+		}
+		if stuck := a.eng.PendingCloses(); len(stuck) != 0 {
+			t.Fatalf("after apply #%d: %d generation(s) abandoned, want none: %+v", i+1, len(stuck), stuck)
+		}
+		if i > 0 {
+			prev := uint16(firstPort + i - 1)
+			if !portFree(prev) {
+				t.Fatalf("after apply #%d the PREVIOUS generation still holds 127.0.0.1:%d — "+
+					"the old engine was replaced in the field but never actually stopped", i+1, prev)
+			}
+		}
+		// The warning set must stay clean while teardown is healthy: a critical
+		// warning that cries wolf on every apply is worse than none.
+		for _, w := range a.Warnings() {
+			if w.Section == "engine" {
+				t.Fatalf("after apply #%d a healthy swap produced an engine warning: %+v", i+1, w)
+			}
+		}
+	}
+
+	if err := a.eng.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+	if got := a.eng.Generations(); got != 0 {
+		t.Fatalf("after Close the process carries %d engine instances, want 0", got)
+	}
+	if !portFree(firstPort + applies - 1) {
+		t.Fatalf("after Close the last generation still holds its listener")
+	}
+}
+
+// hangingCloser returns a box closer that BLOCKS the first close it is handed
+// until release() is called, and performs every later close normally. That is the
+// shape of the real fault: one subsystem of one generation (a WireGuard endpoint)
+// refuses to come down, while the rest of the process is fine.
+func hangingCloser() (closer func(io.Closer) error, release func()) {
+	gate := make(chan struct{})
+	first := make(chan struct{}, 1)
+	first <- struct{}{}
+	return func(c io.Closer) error {
+			select {
+			case <-first:
+				<-gate      // the stuck generation: never returns until released
+				return c.Close() // ...and then really does close, so the port frees
+			default:
+				return c.Close()
+			}
+		}, func() {
+			close(gate)
+		}
+}
+
+// TestStuckEngineCloseDoesNotBlockTheApply pins all four requirements of the
+// bounded teardown at once:
+//
+//	1. the apply COMPLETES — a shutdown that never returns must not hold the
+//	   control plane (and therefore the panel) hostage;
+//	2. the new engine is running afterwards — fail-closed semantics are unchanged,
+//	   the swap succeeded;
+//	3. the abandoned generation is REPORTED as a critical warning, by name, for as
+//	   long as it is still running — it is not silently swallowed;
+//	4. generations do not stack: a further apply while the leak persists leaves
+//	   one live instance plus the one abandoned one, not three.
+func TestStuckEngineCloseDoesNotBlockTheApply(t *testing.T) {
+	const budget = 200 * time.Millisecond
+	restoreBudget := engine.SetCloseBudget(budget)
+	defer restoreBudget()
+
+	a := New(engine.New(), nil)
+
+	// Generation 1 comes up with the REAL closer still installed.
+	if _, err := a.eng.Apply(mixedOn(18811)); err != nil {
+		t.Fatalf("apply #1: %v", err)
+	}
+
+	closer, release := hangingCloser()
+	restoreCloser := engine.SetBoxCloser(closer)
+	released := false
+	defer func() {
+		if !released {
+			release()
+		}
+		restoreCloser()
+		_ = a.eng.Close()
+	}()
+
+	// (1) Generation 2: the retirement of generation 1 will never return.
+	start := time.Now()
+	changed, err := a.eng.Apply(mixedOn(18812))
+	elapsed := time.Since(start)
+	if err != nil {
+		t.Fatalf("apply #2 must SUCCEED despite the stuck teardown: %v", err)
+	}
+	if !changed {
+		t.Fatalf("apply #2: expected a real swap")
+	}
+	// Generously bounded: the budget plus box.New+Start. The point is that it
+	// returned at all — before the fix this waited on Box.Close forever.
+	if elapsed > budget+20*time.Second {
+		t.Fatalf("apply #2 took %s: a stuck teardown must not stall the apply", elapsed)
+	}
+
+	// (2) fail-closed semantics unchanged: the new engine really is up.
+	if !a.eng.Running() {
+		t.Fatalf("apply #2: the new engine must be running")
+	}
+
+	// (3) the leak is visible, named, and critical.
+	stuck := a.eng.PendingCloses()
+	if len(stuck) != 1 {
+		t.Fatalf("PendingCloses() = %+v, want exactly the one abandoned generation", stuck)
+	}
+	if stuck[0].Generation != 1 {
+		t.Errorf("abandoned generation = %d, want 1", stuck[0].Generation)
+	}
+	ws := a.Status().Warnings // the exact set `shaterd status` and the panel read
+	var found *Warning
+	for i := range ws {
+		if ws[i].Section == "engine" {
+			found = &ws[i]
+			break
+		}
+	}
+	if found == nil {
+		t.Fatalf("a superseded engine that will not shut down produced NO warning; "+
+			"Status would show a healthy router: %+v", ws)
+	}
+	if found.Severity != SeverityCritical {
+		t.Errorf("stuck-teardown warning severity = %q, want %q", found.Severity, SeverityCritical)
+	}
+	if !strings.Contains(found.Name, "generation 1") {
+		t.Errorf("stuck-teardown warning must name the generation, got Name=%q", found.Name)
+	}
+	if !strings.Contains(found.Message, "STILL RUNNING") {
+		t.Errorf("stuck-teardown warning must say the instance is still running, got %q", found.Message)
+	}
+	if got := a.eng.Generations(); got != 2 {
+		t.Fatalf("Generations() = %d, want 2 (one live + one abandoned)", got)
+	}
+
+	// (4) another apply while the leak persists must not add a THIRD generation:
+	// with a generation abandoned the swap goes close-old-then-start-new, so the
+	// process still holds one live instance plus the one that will not die.
+	if _, err := a.eng.Apply(mixedOn(18813)); err != nil {
+		t.Fatalf("apply #3: %v", err)
+	}
+	if got := a.eng.Generations(); got != 2 {
+		t.Fatalf("Generations() = %d after a third apply, want 2 — generations are stacking, "+
+			"which is exactly the four-live-engines fault", got)
+	}
+	if stuck := a.eng.PendingCloses(); len(stuck) != 1 || stuck[0].Generation != 1 {
+		t.Fatalf("PendingCloses() = %+v, want only the original abandoned generation 1", stuck)
+	}
+
+	// (5) and it CLEARS: when the shutdown finally completes the warning goes away
+	// on its own. A leak report that outlives the leak trains the operator to
+	// ignore the panel.
+	release()
+	released = true
+	deadline := time.Now().Add(5 * time.Second)
+	for len(a.eng.PendingCloses()) > 0 && time.Now().Before(deadline) {
+		time.Sleep(10 * time.Millisecond)
+	}
+	if got := a.eng.PendingCloses(); len(got) != 0 {
+		t.Fatalf("the finished shutdown is still reported as abandoned: %+v", got)
+	}
+	for _, w := range a.Warnings() {
+		if w.Section == "engine" {
+			t.Fatalf("the engine warning outlived the leak it describes: %+v", w)
+		}
+	}
+	if got := a.eng.Generations(); got != 1 {
+		t.Fatalf("Generations() = %d after the stuck shutdown completed, want 1", got)
+	}
+}

shater/apply/traffic_status_test.go

@@ -0,0 +1,47 @@
+package apply
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/sagernet/sing-box/shater/engine"
+	"github.com/sagernet/sing-box/shater/generate"
+	"github.com/sagernet/sing-box/shater/model"
+)
+
+// TestStatusReportsTraffic pins the wiring the panel's headline depends on.
+//
+// Plane says how much of the data plane is installed; it does NOT say where the
+// traffic goes, and reading it as if it did put "Protected — traffic is going
+// through the tunnel" on a router whose only rule was `default -> direct`. The
+// verdict that answers the real question travels in Status.Traffic, so it must
+// (a) start unknown, (b) surface what the last successful apply published, and
+// (c) go back to unknown the moment the engine stops carrying that config.
+func TestStatusReportsTraffic(t *testing.T) {
+	a := New(engine.New(), nil)
+
+	// A fresh applier has applied nothing, so it knows nothing. The zero value must
+	// NOT read as any verdict — least of all "tunnel".
+	if got := a.Status().Traffic; got.Verdict != "" {
+		t.Fatalf("fresh applier: Traffic.Verdict = %q, want \"\" (unknown)", got.Verdict)
+	}
+
+	a.setTraffic(generate.Traffic{Verdict: generate.VerdictTunnel, Default: "auto", TunnelRules: 2})
+	got := a.Status().Traffic
+	if got.Verdict != generate.VerdictTunnel || got.Default != "auto" || got.TunnelRules != 2 {
+		t.Fatalf("Status().Traffic = %+v, want the verdict the last apply published", got)
+	}
+
+	// The engine is down and the config it was running is no longer in force. A
+	// verdict left over from it would be the same reassuring lie, one layer down.
+	// (kill_switch=open takes holdLocked's early return, which is precisely the path
+	// that must still forget the verdict.)
+	g := model.DefaultGlobals()
+	g.KillSwitch = "open"
+	a.mu.Lock()
+	a.holdLocked(&model.Model{Globals: g}, errors.New("engine start failed"))
+	a.mu.Unlock()
+	if got := a.Status().Traffic; got.Verdict != "" {
+		t.Fatalf("after hold: Traffic.Verdict = %q, want \"\" (unknown) — the engine is not carrying that config", got.Verdict)
+	}
+}

shater/apply/untunnelable.go

@@ -20,6 +20,7 @@ import (
 	"net/netip"
 	"strings"
 
+	C "github.com/sagernet/sing-box/constant"
 	"github.com/sagernet/sing-box/option"
 	"github.com/sagernet/sing-box/shater/model"
 	"github.com/sagernet/sing-box/shater/netplane"
@@ -30,6 +31,110 @@ import (
 // engine.RuleSetIPCIDRs).
 type ruleSetCIDRs func(tag string) ([]netip.Prefix, bool)
 
+// SCHEMA v2 MOVED A RULE'S DESTINATION OUT OF THE RULE, AND THIS FILE HAD TO FOLLOW.
+//
+// Until D21 a routing rule spelled its destination inline: `dst_domain` became
+// DefaultRule.Domain*, `dst_ip` became DefaultRule.IPCIDR. Both were visible right
+// on the rule, so matchesUntunnelable could read them off it and the ADDRESS half
+// could only ever be resolved through the engine for the rare geosite/geoip case.
+//
+// Since v2 a rule names a `config ruleset` and generate materialises it into
+// Route.RuleSet, so BOTH halves arrive by reference. That broke two things at once,
+// in opposite directions:
+//
+//   - DOMAINS WENT INVISIBLE. A v1 rule `dst_domain=[bank.ru] dst_ip=[10/8]` ANDed
+//     its matchers, so it could not match an ICMP packet (no domain in one) and this
+//     file skipped it. After migration the same rule reads `rule_set: [rule-x,
+//     rule-x-ip]`, whose two sets are ORed — so the address set alone would make the
+//     rule look applicable, and the plan would start emitting an ALLOW (target
+//     direct) or a DENY (target block) for 10/8 that the operator never asked for.
+//     The ALLOW is the dangerous half: it sends previously-tunnelled ICMP out with
+//     the client's real address, i.e. an upgrade silently opening a leak. So a rule
+//     whose rule-sets are KNOWN to carry domain matchers is treated exactly as its
+//     v1 form was: inapplicable to untunnelable traffic. (The OR is deliberate and
+//     documented in D21 for the ENGINE's TCP/UDP path; it does not follow that a
+//     leak-guard should widen itself during an upgrade without a word.)
+//   - ADDRESSES WENT ENGINE-ONLY. `rule-x-ip` is an INLINE rule-set: its prefixes
+//     are sitting right there in the generated options. Asking the engine for them
+//     — and, when the engine is not up, truncating the whole walk and denying
+//     everything — was needless. Inline sets are now read from the options, so an
+//     engine that has not started yet no longer costs the operator their ping.
+//
+// Both come from the same index, built once per plan: what the CONFIG ITSELF can
+// say about each rule-set. Remote/local sets stay the engine's business.
+
+// ruleSetFacts is what the generated options alone reveal about one rule-set.
+//
+// opaque means "not knowable from here" — a local/remote set (only the engine has
+// its contents) or an inline set with a rule shape this code does not model. An
+// opaque set is never used to conclude anything; it falls through to the engine
+// lookup exactly as before.
+type ruleSetFacts struct {
+	opaque    bool
+	hasDomain bool           // carries a matcher only a NAMED destination can satisfy
+	cidrs     []netip.Prefix // addresses, when they are knowable here
+}
+
+// indexRuleSets summarises every rule-set in the generated options by tag.
+func indexRuleSets(sets []option.RuleSet) map[string]ruleSetFacts {
+	out := make(map[string]ruleSetFacts, len(sets))
+	for _, rs := range sets {
+		var f ruleSetFacts
+		// option.RuleSet leaves Type empty for inline in some marshalled forms; the
+		// generator always sets it, and both spellings mean the same thing here.
+		if rs.Type != C.RuleSetTypeInline && rs.Type != "" {
+			f.opaque = true
+			out[rs.Tag] = f
+			continue
+		}
+		for _, hr := range rs.InlineOptions.Rules {
+			if hr.Type != C.RuleTypeDefault && hr.Type != "" {
+				// A logical headless rule, or a shape sing-box adds later. Never guessed
+				// at — the same rule the walk itself follows for a logical route rule.
+				f = ruleSetFacts{opaque: true}
+				break
+			}
+			d := hr.DefaultOptions
+			if headlessNeedsUnavailableMatcher(d) {
+				f.hasDomain = true
+			}
+			f.cidrs = append(f.cidrs, parsePrefixes(d.IPCIDR)...)
+		}
+		out[rs.Tag] = f
+	}
+	return out
+}
+
+// headlessNeedsUnavailableMatcher is matchesUntunnelable's predicate for the
+// HEADLESS rule shape a rule-set carries. It reports whether the rule demands
+// something a packet with no domain, no ports, no sniffed protocol and no process
+// identity cannot supply — in which case that rule-set cannot claim such a packet.
+//
+// The generator only ever emits domain matchers or ip_cidr into an inline routing
+// rule-set, so in practice this is the domain test; the rest is there so a future
+// matcher is refused rather than silently ignored.
+func headlessNeedsUnavailableMatcher(d option.DefaultHeadlessRule) bool {
+	switch {
+	case len(d.Domain) > 0, len(d.DomainSuffix) > 0, len(d.DomainKeyword) > 0,
+		len(d.DomainRegex) > 0, len(d.AdGuardDomain) > 0:
+		return true // no domain in an ICMP/ESP/GRE packet
+	case len(d.Port) > 0, len(d.PortRange) > 0, len(d.SourcePort) > 0, len(d.SourcePortRange) > 0:
+		return true
+	case len(d.Network) > 0, len(d.QueryType) > 0:
+		return true
+	case len(d.ProcessName) > 0, len(d.ProcessPath) > 0, len(d.ProcessPathRegex) > 0,
+		len(d.PackageName) > 0, len(d.PackageNameRegex) > 0:
+		return true
+	case len(d.WIFISSID) > 0, len(d.WIFIBSSID) > 0:
+		return true
+	case d.Invert:
+		// Same reasoning as the route-rule case: inverting flips every conservative
+		// assumption, so the set may only ever withhold, never grant.
+		return true
+	}
+	return false
+}
+
 // buildUntunnelablePlan reduces the resolved routing rules to the first-match
 // walk the nft forward chain can evaluate for a packet that has no domain, no
 // ports and no sniffable protocol.
@@ -57,6 +162,9 @@ func buildUntunnelablePlan(opts option.Options, lookup ruleSetCIDRs) *netplane.U
 		// No routing at all: nothing is provably direct.
 		return plan
 	}
+	// Since schema v2 a rule's destination lives in a rule-set, so the rule-sets
+	// have to be read alongside the rules. See the block above ruleSetFacts.
+	sets := indexRuleSets(opts.Route.RuleSet)
 
 	for _, r := range opts.Route.Rules {
 		if r.Type == "logical" {
@@ -78,7 +186,10 @@ func buildUntunnelablePlan(opts option.Options, lookup ruleSetCIDRs) *netplane.U
 		// and the destination logic never allowed anything. Its `protocol: dns`
 		// matcher makes it inapplicable to a packet with no stream to sniff, which
 		// is the correct and obvious reading once the checks are in this order.
-		if !matchesUntunnelable(d) {
+		if !matchesUntunnelable(d, sets) {
+			if note, ok := namedDestinationNote(d, sets); ok {
+				plan.Warnings = append(plan.Warnings, note)
+			}
 			continue // needs a domain/port/protocol: cannot apply to this traffic
 		}
 
@@ -96,21 +207,28 @@ func buildUntunnelablePlan(opts option.Options, lookup ruleSetCIDRs) *netplane.U
 		mt := netplane.UntunnelableMatch{Allow: verdict}
 
 		// Destination predicate: explicit ip_cidr plus every rule-set's addresses.
+		// An INLINE rule-set is answered straight out of the config — it is fully
+		// present there — so a rule whose lists are all inline no longer depends on
+		// the engine being up. Only local/remote sets still have to be asked for.
 		dst := parsePrefixes(d.IPCIDR)
-		resolvable := true
+		var unresolved string
 		for _, tag := range d.RuleSet {
+			if f, known := sets[tag]; known && !f.opaque {
+				dst = append(dst, f.cidrs...)
+				continue
+			}
 			prefixes, ok := lookup(tag)
 			if !ok {
-				resolvable = false
+				unresolved = tag
 				break
 			}
 			dst = append(dst, prefixes...)
 		}
-		if !resolvable {
+		if unresolved != "" {
 			plan.Warnings = append(plan.Warnings, fmt.Sprintf(
 				"list %q is not loaded yet, so ping/IPTV/VPN passthrough stays blocked for the "+
 					"addresses it covers (it resolves itself once the list downloads)",
-				strings.Join(d.RuleSet, ", ")))
+				unresolved))
 			return plan
 		}
 		hasDstMatcher := len(d.IPCIDR) > 0 || len(d.RuleSet) > 0
@@ -198,7 +316,20 @@ func classifyAction(a option.RuleAction) (isDirect bool, class int) {
 // Every matcher listed here is one the packet cannot satisfy, so a rule carrying
 // any of them is inapplicable rather than universally matching. Matchers ANDed
 // within a rule mean one unsatisfiable matcher makes the whole rule unsatisfiable.
-func matchesUntunnelable(d option.DefaultRule) bool {
+//
+// sets carries the same test for the matchers that are no longer written on the
+// rule: since schema v2 a destination is a rule-set reference, so a rule's domains
+// live in Route.RuleSet rather than in d.Domain*. A rule referencing a set that is
+// KNOWN to match by name is inapplicable here for exactly the reason a d.Domain
+// rule is — the packet has no name to match. Sets whose contents this code cannot
+// see (local/remote) say nothing either way; the address walk below already refuses
+// to conclude anything from them.
+func matchesUntunnelable(d option.DefaultRule, sets map[string]ruleSetFacts) bool {
+	for _, tag := range d.RuleSet {
+		if sets[tag].hasDomain {
+			return false
+		}
+	}
 	switch {
 	case len(d.Domain) > 0, len(d.DomainSuffix) > 0, len(d.DomainKeyword) > 0,
 		len(d.DomainRegex) > 0, len(d.Geosite) > 0:
@@ -229,6 +360,41 @@ func matchesUntunnelable(d option.DefaultRule) bool {
 	return true
 }
 
+// namedDestinationNote explains the one skip an operator can actually be
+// surprised by: a rule that names BOTH a domain list and an address list.
+//
+// A domain-only rule contributes nothing here and always has, so saying so would be
+// noise. A mixed rule is different — its addresses look like something this plan
+// could act on, and it is precisely the shape `shaterd migrate` produces from a v1
+// rule that carried dst_domain and dst_ip together. The rule is skipped so the
+// upgrade cannot quietly change what ping does (see the block above ruleSetFacts);
+// that decision is worth one line in the operator's warning list rather than none.
+//
+// ok=false when there is nothing surprising to report.
+func namedDestinationNote(d option.DefaultRule, sets map[string]ruleSetFacts) (string, bool) {
+	var named []string
+	addressed := len(d.IPCIDR) > 0
+	for _, tag := range d.RuleSet {
+		f, known := sets[tag]
+		if known && f.hasDomain {
+			named = append(named, tag)
+			continue
+		}
+		// An unknown/opaque set may well hold addresses; so may a knowable one.
+		if !known || f.opaque || len(f.cidrs) > 0 {
+			addressed = true
+		}
+	}
+	if len(named) == 0 || !addressed {
+		return "", false
+	}
+	return fmt.Sprintf(
+		"a routing rule matches by name (%s) as well as by address, and ping/IPTV/VPN-passthrough traffic "+
+			"carries no name — so that rule is left out of the ping/IPTV decision entirely and later rules "+
+			"decide those addresses. Split it into a name rule and an address rule if you want the addresses "+
+			"decided here", strings.Join(named, ", ")), true
+}
+
 // parsePrefixes converts CIDR/bare-address strings to prefixes, dropping anything
 // unparseable (it cannot be matched on, so it must not silently widen a set).
 func parsePrefixes(in []string) []netip.Prefix {

shater/apply/untunnelable_test.go

@@ -22,6 +22,16 @@ func tunnelModel() *model.Model {
 	return m
 }
 
+// pinnedIPSet declares the inline `type=ipcidr` rule-set a rule pins its
+// destination addresses with. Since schema v2 a routing rule has no dst_ip of its
+// own: addresses are a `config ruleset`, so the generated rule carries a rule_set
+// reference and the plan resolves the actual prefixes through the lookup below —
+// i.e. through the RUNNING engine in production (engine.RuleSetIPCIDRs), not out
+// of the config text. planFor's table stands in for that.
+func pinnedIPSet(name string, cidrs ...string) model.Ruleset {
+	return model.Ruleset{Name: name, Type: "ipcidr", Source: "inline", Entries: cidrs}
+}
+
 // planFor generates m and builds the untunnelable plan, resolving rule-set tags
 // from the supplied table. A tag absent from the table reports "not loaded".
 func planFor(t *testing.T, m *model.Model, sets map[string][]string) *netplane.UntunnelablePlan {
@@ -58,11 +68,12 @@ func renderPlan(t *testing.T, m *model.Model, plan *netplane.UntunnelablePlan) s
 // only 8.8.8.8 may be un-pingable and the rest of the internet must answer.
 func TestOnlyPinnedAddressIsTunnelled(t *testing.T) {
 	m := tunnelModel()
+	m.Rulesets = []model.Ruleset{pinnedIPSet("pin", "8.8.8.8/32")}
 	m.Rules = []model.Rule{
-		{Name: "pin", Enabled: true, Order: 10, DstIP: []string{"8.8.8.8/32"}, Target: "group:auto"},
+		{Name: "pin", Enabled: true, Order: 10, DstRuleset: []string{"pin"}, Target: "group:auto"},
 		{Name: "rest", Enabled: true, Order: 99, Target: "direct"},
 	}
-	plan := planFor(t, m, nil)
+	plan := planFor(t, m, map[string][]string{"rs-pin": {"8.8.8.8/32"}})
 
 	if !plan.DefaultAllow {
 		t.Fatalf("a catch-all `direct` rule must make the default ALLOW; plan=%+v", plan)
@@ -221,14 +232,148 @@ func TestDomainRuleDoesNotAffectUntunnelable(t *testing.T) {
 	}
 }
 
-// TestBlockedRuleDenies: an explicitly blocked destination stays dropped.
-func TestBlockedRuleDenies(t *testing.T) {
+// --- schema v2: the destination moved into rule-sets, and so did the analysis ---
+
+// migratedRule reproduces exactly what `shaterd migrate` makes of a v1 rule that
+// carried BOTH lists: `dst_domain=[bank.ru] dst_ip=[203.0.113.0/24]` becomes two
+// inline rule-sets, `rule-x` and `rule-x-ip`, and the rule references both.
+func migratedRule(target string) *model.Model {
 	m := tunnelModel()
+	m.Rulesets = []model.Ruleset{
+		{Name: "rule-x", Type: "domain", Source: "inline", Entries: []string{"full:bank.ru"}},
+		pinnedIPSet("rule-x-ip", "203.0.113.0/24"),
+	}
 	m.Rules = []model.Rule{
-		{Name: "bad", Enabled: true, Order: 10, DstIP: []string{"203.0.113.0/24"}, Target: "block"},
+		{Name: "x", Enabled: true, Order: 10,
+			DstRuleset: []string{"rule-x", "rule-x-ip"}, Target: target},
+		{Name: "dflt", Enabled: true, Order: 99, Target: "group:auto"},
+	}
+	return m
+}
+
+// TestMigratedDomainAndIPRuleStaysOutOfTheUntunnelablePlan is the upgrade
+// regression. In v1 the rule ANDed its domain and its addresses, so it could never
+// claim a packet that carries no domain and this plan skipped it. After the
+// migration the same rule reads `rule_set: [rule-x, rule-x-ip]`, and rule_set
+// entries are ORed — so the address set alone made the rule look applicable and the
+// plan started emitting a verdict for 203.0.113.0/24 that nobody asked for.
+//
+// With target=direct that verdict is an ALLOW, i.e. an upgrade quietly sending
+// previously-tunnelled ICMP out with the client's real source address. That is the
+// half that makes this a leak and not just a surprise, so it is checked first.
+func TestMigratedDomainAndIPRuleStaysOutOfTheUntunnelablePlan(t *testing.T) {
+	// Both engine states, because they fail differently: with the engine UP the old
+	// code emitted a live verdict for the addresses, and with it DOWN the same
+	// mistake hid behind the unresolvable-list truncation. Neither may happen.
+	for _, target := range []string{"direct", "block", "group:auto"} {
+		for _, engine := range []string{"up", "down"} {
+			t.Run(target+"/engine-"+engine, func(t *testing.T) {
+				m := migratedRule(target)
+				var loaded map[string][]string
+				if engine == "up" {
+					loaded = map[string][]string{"rs-rule-x": {}, "rs-rule-x-ip": {"203.0.113.0/24"}}
+				}
+				plan := planFor(t, m, loaded)
+
+				if len(plan.Matches) != 0 {
+					t.Fatalf("a rule that matches by NAME as well as by address must contribute no "+
+						"address step (it cannot match a packet that carries no name): %+v", plan.Matches)
+				}
+				if plan.DefaultAllow {
+					t.Errorf("the catch-all routes into the tunnel, so the default must still deny")
+				}
+				fwd := renderPlan(t, m, plan)
+				if strings.Contains(fwd, "203.0.113.0/24") {
+					t.Errorf("the migrated address list must not reach the data plane through the "+
+						"untunnelable policy:\n%s", fwd)
+				}
+			})
+		}
+	}
+}
+
+// TestMigratedDomainAndIPRuleSaysWhyItWasSkipped: skipping is the safe answer, but
+// a silently different ping after an upgrade is the complaint this whole change
+// exists to answer. The mixed rule — the exact shape migration produces — is named.
+func TestMigratedDomainAndIPRuleSaysWhyItWasSkipped(t *testing.T) {
+	plan := planFor(t, migratedRule("direct"), nil)
+	var seen bool
+	for _, w := range plan.Warnings {
+		if strings.Contains(w, "matches by name") && strings.Contains(w, "rs-rule-x") {
+			seen = true
+		}
+	}
+	if !seen {
+		t.Fatalf("the skip must be explained and the list named; warnings=%v", plan.Warnings)
+	}
+}
+
+// TestDomainOnlyRuleSetIsQuiet: a rule whose only destination is a NAME list has
+// always contributed nothing here and is not a surprise, so it must not produce a
+// note. Only the mixed shape is worth a line.
+func TestDomainOnlyRuleSetIsQuiet(t *testing.T) {
+	m := tunnelModel()
+	m.Rulesets = []model.Ruleset{
+		{Name: "names", Type: "domain", Source: "inline", Entries: []string{"full:bank.ru"}},
+	}
+	m.Rules = []model.Rule{
+		{Name: "names", Enabled: true, Order: 10, DstRuleset: []string{"names"}, Target: "group:auto"},
 		{Name: "rest", Enabled: true, Order: 99, Target: "direct"},
 	}
 	plan := planFor(t, m, nil)
+	if !plan.DefaultAllow {
+		t.Errorf("a name-only rule must not withhold the catch-all allow; plan=%+v", plan)
+	}
+	for _, w := range plan.Warnings {
+		if strings.Contains(w, "matches by name") {
+			t.Errorf("a name-only rule is not a surprise and needs no note: %q", w)
+		}
+	}
+}
+
+// TestInlineRuleSetNeedsNoEngine: an inline rule-set's addresses are sitting in the
+// generated config. Asking the engine for them — and, while it is down, truncating
+// the whole walk so ping/IPTV/VPN passthrough dies everywhere — was a conservative
+// answer to a question that did not have to be asked. The verdict must now be the
+// same whether or not the engine is up.
+func TestInlineRuleSetNeedsNoEngine(t *testing.T) {
+	m := tunnelModel()
+	m.Rulesets = []model.Ruleset{pinnedIPSet("pin", "8.8.8.8/32")}
+	m.Rules = []model.Rule{
+		{Name: "pin", Enabled: true, Order: 10, DstRuleset: []string{"pin"}, Target: "group:auto"},
+		{Name: "rest", Enabled: true, Order: 99, Target: "direct"},
+	}
+
+	down := planFor(t, m, nil)                                         // engine not up
+	up := planFor(t, m, map[string][]string{"rs-pin": {"8.8.8.8/32"}}) // engine up
+
+	for name, plan := range map[string]*netplane.UntunnelablePlan{"engine-down": down, "engine-up": up} {
+		if !plan.DefaultAllow {
+			t.Fatalf("%s: the catch-all direct must allow the rest of the internet; plan=%+v", name, plan)
+		}
+		if len(plan.Matches) != 1 || plan.Matches[0].Allow {
+			t.Fatalf("%s: the tunnelled address must produce one DENY step, got %+v", name, plan.Matches)
+		}
+		if got := plan.Matches[0].Dst4; len(got) != 1 || got[0] != "8.8.8.8/32" {
+			t.Fatalf("%s: step destinations = %v, want [8.8.8.8/32]", name, got)
+		}
+	}
+	for _, w := range down.Warnings {
+		if strings.Contains(w, "not loaded yet") {
+			t.Errorf("an inline list is never 'not loaded': %q", w)
+		}
+	}
+}
+
+// TestBlockedRuleDenies: an explicitly blocked destination stays dropped.
+func TestBlockedRuleDenies(t *testing.T) {
+	m := tunnelModel()
+	m.Rulesets = []model.Ruleset{pinnedIPSet("bad", "203.0.113.0/24")}
+	m.Rules = []model.Rule{
+		{Name: "bad", Enabled: true, Order: 10, DstRuleset: []string{"bad"}, Target: "block"},
+		{Name: "rest", Enabled: true, Order: 99, Target: "direct"},
+	}
+	plan := planFor(t, m, map[string][]string{"rs-bad": {"203.0.113.0/24"}})
 	if len(plan.Matches) != 1 || plan.Matches[0].Allow {
 		t.Fatalf("a blocked destination must deny untunnelable traffic too: %+v", plan.Matches)
 	}
@@ -361,11 +506,12 @@ func TestPlanNeverAcceptsTCPOrUDP(t *testing.T) {
 			m := tunnelModel()
 			m.Globals.IPv6 = true
 			m.Globals.Untunnelable = policy
+			m.Rulesets = []model.Ruleset{pinnedIPSet("pin", "8.8.8.8/32")}
 			m.Rules = []model.Rule{
-				{Name: "pin", Enabled: true, Order: 10, DstIP: []string{"8.8.8.8/32"}, Target: "group:auto"},
+				{Name: "pin", Enabled: true, Order: 10, DstRuleset: []string{"pin"}, Target: "group:auto"},
 				{Name: "rest", Enabled: true, Order: 99, Target: "direct"},
 			}
-			fwd := renderPlan(t, m, planFor(t, m, nil))
+			fwd := renderPlan(t, m, planFor(t, m, map[string][]string{"rs-pin": {"8.8.8.8/32"}}))
 
 			// Only the lines the untunnelable policy emits are in scope: the tproxy
 			// diverts in prerouting legitimately match TCP/UDP, which is their job.
@@ -424,12 +570,13 @@ func TestLocalPlaneSurvivesEveryPlan(t *testing.T) {
 // only grant those clients, not everyone.
 func TestSourceScopedRuleNarrowsTheAllow(t *testing.T) {
 	m := tunnelModel()
+	m.Rulesets = []model.Ruleset{pinnedIPSet("lab", "198.51.100.0/24")}
 	m.Rules = []model.Rule{
 		{Name: "lab", Enabled: true, Order: 10, Src: []string{"192.168.9.0/24"},
-			DstIP: []string{"198.51.100.0/24"}, Target: "direct"},
+			DstRuleset: []string{"lab"}, Target: "direct"},
 		{Name: "dflt", Enabled: true, Order: 99, Target: "group:auto"},
 	}
-	plan := planFor(t, m, nil)
+	plan := planFor(t, m, map[string][]string{"rs-lab": {"198.51.100.0/24"}})
 	if len(plan.Matches) != 1 {
 		t.Fatalf("expected one step, got %+v", plan.Matches)
 	}

shater/apply/warnings.go

@@ -24,7 +24,9 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"time"
 
+	"github.com/sagernet/sing-box/shater/engine"
 	"github.com/sagernet/sing-box/shater/model"
 	"github.com/sagernet/sing-box/shater/netplane"
 )
@@ -91,6 +93,15 @@ var criticalMarkers = []string{
 	"not covered",     // an interface outside the fail-closed guard
 	"fail-closed",     //  ''
 	"REJECTED",        // an unusable interface name
+	// A condition-less rule retired by a later condition-less rule whose target is
+	// `direct` (generate/route.go warnUnreachableRules): the operator's default
+	// policy — a tunnel, or a block — is not the one the router uses, so everything
+	// unmatched leaves on the plain WAN. The marker is the full clause, not the
+	// shorter "leaves over the plain WAN" that ruleKillFallback's kill=open note
+	// also contains: that one is a DELIBERATE per-rule bypass the operator asked
+	// for, and grading it critical here would be a different decision made by
+	// accident.
+	"leaves over the plain WAN with your real IP address",
 }
 
 // protectionSections are entity kinds whose whole purpose is to block or divert
@@ -260,6 +271,50 @@ func untunnelablePolicyWarnings(g model.Globals, planNotes []string) []Warning {
 	}
 }
 
+// engineTeardownWarnings turns the engine's ABANDONED generations — superseded
+// sing-box instances whose shutdown overran the hard close budget and are still
+// running inside this process — into operator-facing warnings.
+//
+// Critical, without hesitation. A leaked generation is not untidiness:
+//
+//   - it still holds its WireGuard devices, and two devices built from the same
+//     private key evict each other at the peer (one session per public key), so
+//     the leak reproduces BETWEEN generations exactly the fault
+//     generate/wgdedup.go removes WITHIN a config — the tunnel flaps and neither
+//     end can say why;
+//   - it still holds its outbound connections and keeps probing nodes, so the
+//     log fills with errors attributed to a config that is no longer applied;
+//   - on a 512 MiB router each one costs real memory that is never returned.
+//
+// The generation number is carried in Name so two consecutive status reads can
+// tell "the same stuck generation" from "another one just leaked", and the
+// elapsed time is in the message because a shutdown at 8s and one at 40 minutes
+// are different problems.
+func engineTeardownWarnings(stuck []engine.StuckClose) []Warning {
+	if len(stuck) == 0 {
+		return nil
+	}
+	out := make([]Warning, 0, len(stuck))
+	for _, s := range stuck {
+		config := "unknown config"
+		if len(s.Hash) >= 12 {
+			config = "config " + s.Hash[:12]
+		}
+		out = append(out, Warning{
+			Severity: SeverityCritical,
+			Section:  "engine",
+			Name:     fmt.Sprintf("generation %d", s.Generation),
+			Message: fmt.Sprintf(
+				"a superseded engine instance (%s) has been shutting down for %s and is STILL RUNNING: "+
+					"it keeps its outbound connections and its WireGuard devices, so it can evict the "+
+					"live tunnel at the peer and it keeps writing to the log. The current configuration "+
+					"is applied and running; restart shaterd if this does not clear.",
+				config, s.Elapsed.Round(time.Second)),
+		})
+	}
+	return out
+}
+
 func severityRank(s string) int {
 	switch s {
 	case SeverityCritical:

shater/apply/warnings_test.go

@@ -240,3 +240,45 @@ func blockGlobals() model.Globals {
 	g.Untunnelable = netplane.UntunnelableBlock
 	return g
 }
+
+// TestCollectWarningsGradesUnreachableRules (B1): a condition-less rule retired by
+// a later condition-less one is graded by CONSEQUENCE, not by the mere fact that a
+// setting is dead.
+//
+//   - the surviving default is `direct` while the retired one wanted a tunnel:
+//     the operator's default policy is not in effect and everything unmatched
+//     leaves on the plain WAN — critical, the panel must show it loudly;
+//   - the surviving default is the tunnel and the dead one was `direct`: a dead
+//     knob, nothing is leaking — warning.
+//
+// Both must be attributed to section "rule" + the rule's name, so the panel can
+// deep-link to the offending row instead of printing prose.
+func TestCollectWarningsGradesUnreachableRules(t *testing.T) {
+	const leak = `rule "default": it has no conditions, so it sets the default for ALL traffic — ` +
+		`but rule "fallback" (order 100) has none either and comes after it, so "direct" wins and ` +
+		`this rule's target "group:auto" is never applied. Everything no other rule matches leaves ` +
+		`over the plain WAN with your real IP address. Delete one of the two, or give this one a condition`
+	const dead = `rule "default": it has no conditions, so it sets the default for ALL traffic — ` +
+		`but rule "default" (order 100) has none either and comes after it, so the default the ` +
+		`router uses is "group:auto" and this rule's target "direct" is never applied. Delete one ` +
+		`of the two, or give this one a condition so it can match something`
+
+	check := func(text, wantSeverity string) {
+		t.Helper()
+		found := false
+		for _, w := range collectWarnings(blockGlobals(), []string{text}, nil, nil) {
+			if w.Section != "rule" || w.Name != "default" {
+				continue
+			}
+			found = true
+			if w.Severity != wantSeverity {
+				t.Errorf("severity = %q, want %q for: %s", w.Severity, wantSeverity, text)
+			}
+		}
+		if !found {
+			t.Fatalf("never-applied warning not attributed to rule %q: %s", "default", text)
+		}
+	}
+	check(leak, SeverityCritical)
+	check(dead, SeverityWarning)
+}

shater/buildtags/buildtags.go

@@ -0,0 +1,206 @@
+// Package buildtags is the contract between what shater DECLARES it supports
+// and the build tags the shipped router binary is actually compiled with.
+//
+// # Why this package exists
+//
+// The router binary is built with a deliberately trimmed tag set (D9/D23,
+// scripts/router-tags.sh) — upstream's full set registers a zoo shater/generate
+// can never emit, and a router pays for every tag in flash and in RAM. Trimming
+// is right; trimming BLIND is not. On 2026-07-25 a production router answered a
+// configured WireGuard node with
+//
+//	create instance: initialize endpoint[0]: create WireGuard device:
+//	gVisor is not included in this build, rebuild with -tags with_gvisor
+//
+// because `with_gvisor` had been trimmed as "unreachable code" (true for the tun
+// inbound we never emit — false for the WireGuard endpoint we ship and declare
+// [MVP]) while `with_wireguard` stayed. Nothing caught it: the test suite builds
+// with the FULL upstream tag set, so the SHIPPED tag combination was, at that
+// point, the one configuration nothing in the repo ever exercised.
+//
+// # What holds it together now
+//
+//  1. Features below names each declared feature and the build tags it needs to
+//     RUN (not merely to compile). shater/buildtags's own test parses
+//     scripts/router-tags.sh and fails if the shipped set does not cover them —
+//     it needs no tags, no Linux and no network, so it runs in every plain
+//     `go test ./...`.
+//  2. shater/generate's TestShippedTagSetConstructsDeclaredProtocols drives one
+//     node of every declared protocol through box.New under whatever tags the
+//     test binary was built with, skipping only what is genuinely not compiled
+//     in. scripts/check-router-tags.sh runs it with the SHIPPED set, so the
+//     combination we ship is proven to construct, not merely to link.
+//
+// (1) catches a trimmed dependency the moment it is trimmed; (2) catches the
+// class of failure (1) cannot model — a tag that is present but insufficient.
+//
+// Adding a protocol to shater/parse + shater/generate means adding a row here.
+package buildtags
+
+import "sort"
+
+// Feature is one capability the product declares, together with the build tags
+// the binary must carry for it to work at runtime.
+type Feature struct {
+	// Name is the feature as a user would name it.
+	Name string
+	// Declared points at where we promise it (docs-shater/FEATURES.md section,
+	// or the generator/registry that emits it).
+	Declared string
+	// Tags are ALL build tags required for the feature to work — including
+	// transitive ones (with_awg alone is useless without with_wireguard, which
+	// is useless without with_gvisor). Listing them transitively is deliberate:
+	// the check must not depend on a dependency graph nobody maintains.
+	Tags []string
+	// Why explains what breaks without those tags, with the code anchor. It is
+	// printed by the failing test, so a future trimmer reads the reason instead
+	// of rediscovering it on a router.
+	Why string
+}
+
+// Features is the authoritative list. Only tag-GATED capabilities belong here:
+// tproxy, routing rules, rule-sets, the DNS filter, nft/policy routing and the
+// panel are compiled unconditionally and cannot be lost to a tag trim.
+var Features = []Feature{
+	{
+		Name:     "WireGuard nodes (wg:// / wireguard:// links, wg-quick .conf import)",
+		Declared: "FEATURES.md §Proxy engine — “VLESS, VMess, Trojan, Shadowsocks, WireGuard” [MVP]",
+		Tags:     []string{"with_wireguard", "with_gvisor"},
+		Why: "with_wireguard registers the endpoint (shater/registry/registry_wireguard.go); " +
+			"with_gvisor supplies the userspace netstack EVERY WireGuard device needs — without it " +
+			"transport/wireguard/device_stack_stub.go returns tun.ErrGVisorNotIncluded from BOTH " +
+			"newStackDevice and newSystemStackDevice, so box.New fails with " +
+			"\"create WireGuard device: gVisor is not included in this build\" and the node is dead. " +
+			"system_interface=true is not an escape hatch: it hits the same stub.",
+	},
+	{
+		Name:     "AmneziaWG obfuscation (awg:// links; jc/jmin/jmax, s1-s4, h1-h4, i1-i5)",
+		Declared: "FEATURES.md §Proxy engine — “AmneziaWG 2.0 … a driving requirement” [MVP]",
+		Tags:     []string{"with_awg", "with_wireguard", "with_gvisor"},
+		Why: "with_awg makes the AWG params reach the device (transport/wireguard/device_awg.go); " +
+			"without it they parse and are silently ignored (option/wireguard.go). It rides on the " +
+			"WireGuard endpoint, so it needs that feature's tags too.",
+	},
+	{
+		Name:     "Hysteria2 nodes (hysteria2:// / hy2://)",
+		Declared: "FEATURES.md §Proxy engine [T1]; shater/registry registerQUICOutbounds",
+		Tags:     []string{"with_quic"},
+		Why:      "hysteria2.RegisterOutbound is compiled only under with_quic (shater/registry/registry_quic.go); without it box.New rejects the outbound as an unknown type.",
+	},
+	{
+		Name:     "TUIC nodes (tuic://)",
+		Declared: "FEATURES.md §Proxy engine [T1]; shater/registry registerQUICOutbounds",
+		Tags:     []string{"with_quic"},
+		Why:      "tuic.RegisterOutbound is compiled only under with_quic (shater/registry/registry_quic.go).",
+	},
+	{
+		Name:     "VLESS/VMess over the QUIC v2ray transport (type=quic)",
+		Declared: "FEATURES.md §Proxy engine — “Transports: TCP/WS/gRPC/HTTPUpgrade/H2/QUIC” [MVP]",
+		Tags:     []string{"with_quic"},
+		Why:      "transport/v2rayquic registers its constructor from an init() blank-imported only under with_quic; without it NewQUICClient returns os.ErrInvalid at dial time.",
+	},
+	{
+		Name:     "QUIC / HTTP3 DNS transports (quic://, h3://)",
+		Declared: "shater/registry registerQUICTransports",
+		Tags:     []string{"with_quic"},
+		Why:      "dns/transport/quic is registered only under with_quic (shater/registry/registry_quic.go).",
+	},
+	{
+		Name:     "REALITY (vless security=reality, pbk/sid)",
+		Declared: "FEATURES.md §Proxy engine — “Reality/XTLS” [MVP]; shater/parse security=reality",
+		Tags:     []string{"with_utls"},
+		Why:      "the REALITY client lives in common/tls/reality_client.go, which is itself `//go:build with_utls`; without the tag a reality config is rejected by the TLS layer.",
+	},
+	{
+		Name:     "uTLS ClientHello fingerprints (fp=chrome/firefox/safari/…)",
+		Declared: "shater/generate/outbound.go TLS mapping (UTLS options)",
+		Tags:     []string{"with_utls"},
+		Why:      "common/tls/utls_client.go is `//go:build with_utls`; the stub (utls_stub.go) refuses a config that sets a fingerprint.",
+	},
+	{
+		Name:     "XHTTP / SplitHTTP transport (type=xhttp, type=splithttp)",
+		Declared: "FEATURES.md §Proxy engine [T1]; shater/parse/sharelink.go case \"xhttp\"",
+		Tags:     []string{"with_xhttp"},
+		Why:      "transport/v2rayxhttp registers the \"xhttp\" transport from an init() blank-imported only under with_xhttp (shater/registry/registry_xhttp.go); without it the transport type is unknown at box.New.",
+	},
+	{
+		Name:     "badtls fast path (zero-copy TLS read-wait / ktls, used by every TLS outbound)",
+		Declared: "common/badtls — linked unconditionally by the TLS client",
+		Tags:     []string{"badlinkname", "tfogo_checklinkname0"},
+		Why: "common/badtls/*.go are `go1.25 && badlinkname`; without the tag the package degrades to read_wait_stub.go. " +
+			"These two tags additionally REQUIRE -checklinkname=0 in the linker flags — the build fails at link time otherwise " +
+			"(\"invalid reference to crypto/tls.(*Conn).handlePostHandshakeMessage\"), which is why " +
+			"scripts/router-tags.sh carries SHATER_ROUTER_LDFLAGS next to the tag set.",
+	},
+}
+
+// RequiredTags is the union of every declared feature's tags, sorted.
+func RequiredTags() []string {
+	seen := map[string]bool{}
+	for _, f := range Features {
+		for _, t := range f.Tags {
+			seen[t] = true
+		}
+	}
+	return sortedKeys(seen)
+}
+
+// Compiled reports the shater-relevant build tags THIS binary was compiled with,
+// sorted. It is populated by the one-line tag_*.go twins in this package; a tag
+// with no file here is simply not tracked (and must not appear in Features).
+func Compiled() []string { return sortedKeys(compiled) }
+
+// Has reports whether this binary was compiled with tag.
+func Has(tag string) bool { return compiled[tag] }
+
+// MissingTags returns the tags f needs that this binary lacks, sorted. Empty
+// means the feature is fully compiled in.
+func MissingTags(f Feature) []string {
+	missing := map[string]bool{}
+	for _, t := range f.Tags {
+		if !compiled[t] {
+			missing[t] = true
+		}
+	}
+	return sortedKeys(missing)
+}
+
+// Tracked reports whether tag has a detector file (tag_*.go) in this package.
+// Features must only reference tracked tags — an untracked tag would silently
+// read as "not compiled" and turn a real check into a skip. TestFeatureTagsAreTracked
+// enforces that, and scripts/check-router-tags.sh additionally proves the
+// detectors match the tag set the compiler was actually handed.
+func Tracked(tag string) bool { return tracked[tag] }
+
+// TrackedTags is every tag this package can observe, i.e. exactly the tags with
+// a tag_*.go detector. Keep the two in sync — the check script fails loudly if
+// they drift.
+func TrackedTags() []string { return sortedKeys(tracked) }
+
+var tracked = map[string]bool{
+	"with_gvisor":          true,
+	"with_quic":            true,
+	"with_wireguard":       true,
+	"with_awg":             true,
+	"with_utls":            true,
+	"with_xhttp":           true,
+	"with_lx_command":      true,
+	"badlinkname":          true,
+	"tfogo_checklinkname0": true,
+}
+
+// compiled is filled by the tag_*.go detectors' init(). A tag with no detector
+// file compiled in is absent from the map, which reads as "not compiled".
+var compiled = map[string]bool{}
+
+// mark records that tag is compiled into this binary.
+func mark(tag string) { compiled[tag] = true }
+
+func sortedKeys(m map[string]bool) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}

shater/buildtags/buildtags_test.go

@@ -0,0 +1,175 @@
+package buildtags
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+)
+
+// repoFile reads a file relative to the repo root (this package sits at
+// <repo>/shater/buildtags).
+func repoFile(t *testing.T, rel string) string {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("..", "..", filepath.FromSlash(rel)))
+	if err != nil {
+		t.Fatalf("read %s: %v", rel, err)
+	}
+	return string(b)
+}
+
+// shVar pulls VAR="…" out of a POSIX sh fragment.
+func shVar(t *testing.T, script, name string) string {
+	t.Helper()
+	re := regexp.MustCompile(`(?m)^` + regexp.QuoteMeta(name) + `="([^"]*)"`)
+	m := re.FindStringSubmatch(script)
+	if m == nil {
+		t.Fatalf("scripts/router-tags.sh: %s=\"…\" not found (single line, double quotes)", name)
+	}
+	return m[1]
+}
+
+// routerTagSet returns the shipped tag set as a set, read from the ONE file that
+// defines it.
+func routerTagSet(t *testing.T) map[string]bool {
+	t.Helper()
+	set := map[string]bool{}
+	for _, tag := range strings.Split(shVar(t, repoFile(t, "scripts/router-tags.sh"), "SHATER_ROUTER_TAGS"), ",") {
+		if tag = strings.TrimSpace(tag); tag != "" {
+			set[tag] = true
+		}
+	}
+	if len(set) == 0 {
+		t.Fatal("SHATER_ROUTER_TAGS is empty")
+	}
+	return set
+}
+
+// TestRouterTagSetCoversDeclaredFeatures is THE guard the 2026-07-25 WireGuard
+// outage was missing (D23): it reads the tag set the router binary is actually
+// built with and fails if a feature we DECLARE supported has lost the build tag
+// it needs to run.
+//
+// It deliberately needs no build tags, no Linux, no privileges and no network,
+// so it runs in every plain `go test ./...` — including on the Windows dev host,
+// where nothing else can exercise the shipped configuration. The behavioural
+// half (does the shipped combination actually CONSTRUCT?) is
+// shater/generate.TestShippedTagSetConstructsDeclaredProtocols, run with this
+// same set by scripts/check-router-tags.sh.
+func TestRouterTagSetCoversDeclaredFeatures(t *testing.T) {
+	shipped := routerTagSet(t)
+
+	for _, f := range Features {
+		var missing []string
+		for _, tag := range f.Tags {
+			if !shipped[tag] {
+				missing = append(missing, tag)
+			}
+		}
+		if len(missing) > 0 {
+			t.Errorf("the shipped router binary would NOT support a feature we declare.\n"+
+				"  feature : %s\n"+
+				"  declared: %s\n"+
+				"  missing : %s  (not in SHATER_ROUTER_TAGS, scripts/router-tags.sh)\n"+
+				"  why     : %s\n"+
+				"Either add the tag back, or stop declaring the feature — those are the only two honest options.",
+				f.Name, f.Declared, strings.Join(missing, ", "), f.Why)
+		}
+	}
+}
+
+// TestFeatureTagsAreTracked keeps Features honest: every tag it names must have
+// a tag_*.go detector, or Compiled()/MissingTags() would report it absent even
+// when it is compiled in — and the behavioural test would silently SKIP the
+// feature instead of checking it. A false green is worse than a red.
+func TestFeatureTagsAreTracked(t *testing.T) {
+	for _, f := range Features {
+		for _, tag := range f.Tags {
+			if !Tracked(tag) {
+				t.Errorf("feature %q requires tag %q, which has no detector: add shater/buildtags/tag_%s.go and the entry in the tracked map", f.Name, tag, tag)
+			}
+		}
+	}
+}
+
+// TestTrackedTagsHaveDetectorFiles pairs the tracked map with the files on disk,
+// so a renamed/deleted detector cannot quietly make a tag read as absent.
+func TestTrackedTagsHaveDetectorFiles(t *testing.T) {
+	for _, tag := range TrackedTags() {
+		name := "tag_" + tag + ".go"
+		body, err := os.ReadFile(name)
+		if err != nil {
+			t.Errorf("tracked tag %q has no detector file %s: %v", tag, name, err)
+			continue
+		}
+		if !strings.Contains(string(body), "//go:build "+tag) || !strings.Contains(string(body), `mark("`+tag+`")`) {
+			t.Errorf("%s must be `//go:build %s` and call mark(%q)", name, tag, tag)
+		}
+	}
+	files, err := filepath.Glob("tag_*.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range files {
+		tag := strings.TrimSuffix(strings.TrimPrefix(f, "tag_"), ".go")
+		if !Tracked(tag) {
+			t.Errorf("detector %s exists but %q is not in the tracked map", f, tag)
+		}
+	}
+}
+
+// TestBuildScriptUsesTheSharedTagSet stops the split that caused the outage from
+// coming back: the ship build must SOURCE scripts/router-tags.sh, not carry its
+// own copy of the tag list. A second copy is a second truth, and the second one
+// is the one nobody checks.
+func TestBuildScriptUsesTheSharedTagSet(t *testing.T) {
+	build := repoFile(t, "scripts/build-shaterd.sh")
+	if !strings.Contains(build, "router-tags.sh") {
+		t.Fatal("scripts/build-shaterd.sh must source scripts/router-tags.sh")
+	}
+	if regexp.MustCompile(`(?m)^\s*ROUTER_TAGS="with_`).MatchString(build) {
+		t.Fatal("scripts/build-shaterd.sh re-inlines a literal tag list; the set must come from scripts/router-tags.sh only")
+	}
+}
+
+// TestRouterLdflagsSatisfyTagRequirements: `badlinkname` is not self-contained —
+// the LINK step fails without -checklinkname=0. The flag therefore belongs to
+// the tag set, and lives beside it; assert the pair never separates.
+func TestRouterLdflagsSatisfyTagRequirements(t *testing.T) {
+	script := repoFile(t, "scripts/router-tags.sh")
+	ldflags := shVar(t, script, "SHATER_ROUTER_LDFLAGS")
+	if routerTagSet(t)["badlinkname"] && !strings.Contains(ldflags, "-checklinkname=0") {
+		t.Fatalf("SHATER_ROUTER_TAGS carries badlinkname but SHATER_ROUTER_LDFLAGS (%q) lacks -checklinkname=0: the build will fail at link time", ldflags)
+	}
+	if !strings.Contains(repoFile(t, "scripts/build-shaterd.sh"), "SHATER_ROUTER_LDFLAGS") {
+		t.Fatal("scripts/build-shaterd.sh must use $SHATER_ROUTER_LDFLAGS, not a hand-copied -checklinkname=0")
+	}
+}
+
+// TestCompiledTagsMatchTheShippedSet proves the DETECTORS are telling the truth:
+// when the test binary is compiled with exactly the shipped tag set, Compiled()
+// must equal that set (restricted to tracked tags). Without this, a typo'd or
+// deleted detector would make the behavioural test skip a protocol and pass.
+//
+// It only runs under scripts/check-router-tags.sh (which compiles with that very
+// set and exports SHATER_ROUTER_TAG_CHECK=1); a plain `go test ./...` compiles
+// with no tags at all, where the comparison is meaningless.
+func TestCompiledTagsMatchTheShippedSet(t *testing.T) {
+	if os.Getenv("SHATER_ROUTER_TAG_CHECK") != "1" {
+		t.Skip("not a router-tag-set run; use scripts/check-router-tags.sh")
+	}
+	var want []string
+	for tag := range routerTagSet(t) {
+		if Tracked(tag) {
+			want = append(want, tag)
+		}
+	}
+	sort.Strings(want)
+	got := Compiled()
+	if strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("compiled tags do not match the shipped set\n  compiled: %v\n  shipped : %v\n"+
+			"Either the build ran with the wrong -tags, or a tag_*.go detector is broken.", got, want)
+	}
+}

shater/buildtags/tag_badlinkname.go

@@ -0,0 +1,7 @@
+//go:build badlinkname
+
+package buildtags
+
+// Detector for the badlinkname build tag — see buildtags.go. There is no !badlinkname twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("badlinkname") }

shater/buildtags/tag_tfogo_checklinkname0.go

@@ -0,0 +1,7 @@
+//go:build tfogo_checklinkname0
+
+package buildtags
+
+// Detector for the tfogo_checklinkname0 build tag — see buildtags.go. There is no !tfogo_checklinkname0 twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("tfogo_checklinkname0") }

shater/buildtags/tag_with_awg.go

@@ -0,0 +1,7 @@
+//go:build with_awg
+
+package buildtags
+
+// Detector for the with_awg build tag — see buildtags.go. There is no !with_awg twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_awg") }

shater/buildtags/tag_with_gvisor.go

@@ -0,0 +1,7 @@
+//go:build with_gvisor
+
+package buildtags
+
+// Detector for the with_gvisor build tag — see buildtags.go. There is no !with_gvisor twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_gvisor") }

shater/buildtags/tag_with_lx_command.go

@@ -0,0 +1,7 @@
+//go:build with_lx_command
+
+package buildtags
+
+// Detector for the with_lx_command build tag — see buildtags.go. There is no !with_lx_command twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_lx_command") }

shater/buildtags/tag_with_quic.go

@@ -0,0 +1,7 @@
+//go:build with_quic
+
+package buildtags
+
+// Detector for the with_quic build tag — see buildtags.go. There is no !with_quic twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_quic") }

shater/buildtags/tag_with_utls.go

@@ -0,0 +1,7 @@
+//go:build with_utls
+
+package buildtags
+
+// Detector for the with_utls build tag — see buildtags.go. There is no !with_utls twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_utls") }

shater/buildtags/tag_with_wireguard.go

@@ -0,0 +1,7 @@
+//go:build with_wireguard
+
+package buildtags
+
+// Detector for the with_wireguard build tag — see buildtags.go. There is no !with_wireguard twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_wireguard") }

shater/buildtags/tag_with_xhttp.go

@@ -0,0 +1,7 @@
+//go:build with_xhttp
+
+package buildtags
+
+// Detector for the with_xhttp build tag — see buildtags.go. There is no !with_xhttp twin:
+// an absent detector means "not compiled in", which is exactly the truth.
+func init() { mark("with_xhttp") }

shater/cmd/shaterd/logsetup.go

@@ -0,0 +1,27 @@
+package main
+
+// Control-plane log formatting (the IO-free half, so it is unit-testable on any
+// dev host — same split as profilewatch.go).
+//
+// The daemon's own logger used to be built with a bare log.Formatter, whose
+// DisableColors zero value is false: every control-plane line went to procd's
+// stderr — i.e. straight into syslog — carrying aurora escape sequences. See
+// shater/logsink/color.go for why that is a defect and not a cosmetic.
+
+import (
+	"os"
+	"time"
+
+	"github.com/sagernet/sing-box/log"
+	"github.com/sagernet/sing-box/shater/logsink"
+)
+
+// controlLogFormatter builds the control-plane logger's formatter. out is the
+// process's real stderr (the sink's syslog half): colours are emitted only when
+// that is a terminal, never when it is procd/syslog or a log file.
+func controlLogFormatter(baseTime time.Time, out *os.File) log.Formatter {
+	return log.Formatter{
+		BaseTime:      baseTime,
+		DisableColors: !logsink.IsTTY(out),
+	}
+}

shater/cmd/shaterd/logsetup_test.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sagernet/sing-box/log"
+)
+
+// TestControlLogFormatterNoANSIOffTTY pins the control-plane half of the syslog
+// colour leak: when the daemon's stderr is not a terminal — which is ALWAYS the
+// case under procd, where stderr is the pipe procd relays to syslog — no line
+// the daemon formats may contain an ESC (0x1b).
+func TestControlLogFormatterNoANSIOffTTY(t *testing.T) {
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close(); _ = w.Close() })
+
+	f := controlLogFormatter(time.Now(), w)
+	if !f.DisableColors {
+		t.Fatalf("colours enabled for a non-terminal stderr")
+	}
+	// A context ID exercises the second colouring branch of log/format.go (the
+	// 256-colour connection id), which is what produced ESC[38;5;193m on the router.
+	ctx := log.ContextWithNewID(context.Background())
+	for _, level := range []log.Level{log.LevelError, log.LevelWarn, log.LevelInfo, log.LevelDebug, log.LevelTrace} {
+		line := f.Format(ctx, level, "dns", "exchange failed for example.com. IN AAAA: unexpected EOF", time.Now())
+		if i := strings.IndexByte(line, 0x1b); i >= 0 {
+			t.Errorf("level %v: formatted line carries an ANSI escape at byte %d: %q", level, i, line)
+		}
+	}
+}

shater/cmd/shaterd/main.go

@@ -79,7 +79,7 @@ func dispatch(args []string) int {
 	case "mint-token":
 		return cmdMintToken()
 	case "nodes":
-		return cmdReadStub("nodes", "[]")
+		return cmdNodes()
 	case "stats":
 		return cmdReadStub("stats", "{}")
 	case "blocklist":
@@ -124,7 +124,7 @@ usage: shaterd <verb>
   rollback               roll back to the last-good config
   status                 print daemon/data-plane status as JSON
   mint-token             mint a single-use panel handoff token (JSON) via the daemon
-  nodes                  print nodes as JSON
+  nodes                  print the configured nodes as JSON (manual + subscription)
   stats                  print stats as JSON
   blocklist update       force a DNS-filter blocklist refresh (reconcile; no-op if down)
   schedule due           re-evaluate time-scheduled rules now (reconcile; no-op if down)
@@ -158,8 +158,11 @@ func cmdRun() int {
 	// The level starts at trace (nothing read yet) and is corrected from
 	// Globals.LogLevel as soon as UCI is read — the control plane now RESPECTS
 	// the configured level instead of the old unconditional trace.
+	// The formatter colours only when stderr is a real terminal
+	// (controlLogFormatter -> logsink.IsTTY): under procd stderr IS syslog, and
+	// ANSI escapes there break `logread | grep ERROR` and every log collector.
 	logFactory := log.NewDefaultFactory(context.Background(),
-		log.Formatter{BaseTime: time.Now()}, sink, "", nil, false)
+		controlLogFormatter(time.Now(), os.Stderr), sink, "", nil, false)
 	log.SetStdLogger(logFactory.Logger())
 	logger := log.StdLogger()
 
@@ -172,10 +175,23 @@ func cmdRun() int {
 		logFactory.SetLevel(controlLogLevel(g.LogLevel))
 	}
 
-	// Refuse to start a second daemon (race-safe single-owner guard). procd's
-	// term_timeout ensures the previous instance exits before reload restarts us.
-	if pid, ok := daemonAlive(); ok && pid != os.Getpid() {
-		logger.Error("another shaterd is already running (pid ", pid, ") — refusing to start")
+	// Single-owner guard: never run two daemons at once. On a `restart` procd's
+	// `service delete` is ASYNCHRONOUS — the ubus call returns immediately while
+	// the outgoing instance is still running its honest teardown — and the
+	// following `service add` starts us straight away, so a predecessor being
+	// alive here is the NORMAL restart case, not an error.
+	//
+	// This used to exit(1) on the spot and lean on procd's `respawn ... 5 ...` to
+	// try again five seconds later. That is a blind retry, not synchronisation:
+	// it neither knows nor waits for the predecessor's teardown to finish, and it
+	// turns every restart into at least one logged crash plus a five-second hole
+	// in which the LAN has no plane at all. Waiting for the predecessor to exit
+	// makes `restart` behave exactly like `stop` + pause + `start`: our apply is
+	// then strictly ordered AFTER the previous teardown, which is the whole point
+	// of the guard.
+	if pid, waiting := waitForPredecessor(predecessorBudget, predecessorPoll, logger); waiting {
+		logger.Error("another shaterd is still running (pid ", pid, ") after waiting ",
+			predecessorBudget, " for it to exit — refusing to start")
 		return 1
 	}
 	if err := writePidfile(); err != nil {
@@ -832,6 +848,42 @@ func cmdStatus() int {
 	return 0
 }
 
+// cmdNodes prints the node inventory as a JSON array (see nodes.go for the
+// shape and for why this is a view rather than the raw model.Node).
+//
+// Shape of the call mirrors cmdStatus: ask the RUNNING daemon first — it is the
+// process that owns the engine, so its answer is the inventory the live box was
+// built from — and fall back to reading the same on-disk desired state directly
+// when there is no daemon (or it did not answer). Both sides call the SAME
+// nodesJSON(), so the fallback cannot report something the daemon would not.
+//
+// The one thing it will never do is print `[]` because it could not find out:
+// a read failure goes to stderr and exits non-zero, so "empty" on stdout with
+// exit 0 means "no nodes are configured" and nothing else.
+func cmdNodes() int {
+	if _, ok := daemonAlive(); ok {
+		resp, err := ctlRequest("nodes")
+		switch {
+		case err != nil:
+			fmt.Fprintf(os.Stderr, "shaterd nodes: %v — reading the on-disk config instead\n", err)
+		case strings.HasPrefix(strings.TrimSpace(resp), "["):
+			fmt.Println(strings.TrimSpace(resp))
+			return 0
+		default:
+			// The daemon answered, but with an error object rather than a list.
+			fmt.Fprintf(os.Stderr, "shaterd nodes: daemon: %s\n", strings.TrimSpace(resp))
+		}
+	}
+	b, err := nodesJSON()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "shaterd nodes: %v\n", err)
+		fmt.Println("[]") // stdout stays parseable JSON; the exit code carries the failure
+		return 1
+	}
+	fmt.Println(string(b))
+	return 0
+}
+
 // cmdMintToken asks the RUNNING daemon (over the control socket) for a single-use
 // panel handoff token and prints the daemon's JSON reply verbatim — {"token":"..."}
 // on success, {"error":"..."} otherwise. It is the CLI shim the LuCI/rpcd layer
@@ -869,6 +921,13 @@ func printJSONError(msg string) {
 	fmt.Println(string(b))
 }
 
+// cmdReadStub relays a read-only verb to the daemon and prints def when there is
+// no daemon to ask. It is ONLY valid where def is the truth in the daemon-down
+// case: `stats` counts what the LIVE engine saw, so with no engine there really
+// is nothing counted and `{}` says exactly that. It is NOT a way to make a verb
+// look implemented — `nodes` used to be routed through here with def="[]" while
+// hundreds of nodes sat on disk (see nodes.go). Anything whose data outlives the
+// daemon belongs in its own command that reads that data.
 func cmdReadStub(cmd, def string) int {
 	if _, ok := daemonAlive(); ok {
 		if resp, err := ctlRequest(cmd); err == nil {
@@ -940,7 +999,16 @@ func handleCtl(conn net.Conn, a *apply.Applier, ps *panel.Server, sa stats.Stats
 	case "rollback":
 		writeResult(conn, false, a.Rollback())
 	case "nodes":
-		writeLine(conn, "[]")
+		// Same assembly as the CLI fallback and as GET /api/config: model.ReadUCI
+		// (UCI + the per-subscription caches) projected onto the printable view.
+		b, err := nodesJSON()
+		if err != nil {
+			l.Warn("control socket: nodes: ", err)
+			e, _ := json.Marshal(map[string]string{"error": err.Error()})
+			writeLine(conn, string(e))
+			return
+		}
+		writeLine(conn, string(b))
 	case "stats":
 		if sa == nil {
 			writeLine(conn, "{}")

shater/cmd/shaterd/nodes.go

@@ -0,0 +1,139 @@
+package main
+
+// `shaterd nodes` — the node inventory, as JSON.
+//
+// This verb used to answer `[]` unconditionally (a `cmdReadStub("nodes", "[]")`
+// on the CLI side and a hard-coded `writeLine(conn, "[]")` in the daemon's
+// control-socket handler), while `shaterd --help` advertised "print nodes as
+// JSON". The data was never missing: /etc/shater/subs/*.json holds every
+// subscription-fetched node and `GET /api/config` reports the full merged set —
+// on a live router that is hundreds of nodes answered as "none". An empty list
+// is indistinguishable from a truthful "no nodes are configured", so the verb
+// did not fail loudly, it lied quietly. Same class as the honesty fixes in
+// 9dc954029 / aec82d444; the cure is the same: report what is actually there.
+//
+// # Data path (deliberately the SAME one /api/config uses)
+//
+// model.ReadUCI() = `uci export shater` (manual nodes + everything else) +
+// model.MergeSubCaches (the per-subscription JSON caches). That single call is
+// what the panel's handleConfigGet serves, what generate builds the engine from
+// and what `sub update` writes back — so `shaterd nodes` cannot drift from the
+// panel or from the running engine, because there is no second assembly here to
+// drift. This file only PROJECTS that model onto a small, printable view.
+//
+// # Why a view and not the raw model.Node
+//
+// model.Node carries the share-link URI, and a share link is a credential
+// (uuid/password in the query string). /api/config may return it — that path is
+// session-authenticated and the panel needs the URI to edit a node — but a CLI
+// verb whose output gets piped into support tickets, `logger`, and cron mail
+// must not spray credentials. The view therefore reports the *derived* facts a
+// share link answers (protocol, server, port) and drops the secret-bearing URI.
+// Nodes whose URI does not parse are still listed, with the parse error in
+// `parse_error`: the engine skips exactly those nodes (generate/outbound.go),
+// and a node that is configured-but-unusable is precisely what an operator
+// needs to see — hiding it would be the same lie in a smaller coat.
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/sagernet/sing-box/shater/model"
+	"github.com/sagernet/sing-box/shater/parse"
+)
+
+// nodeView is ONE node as the `nodes` verb reports it. Field set: the model's
+// own facts (name/enabled/sub/egress/stale/fingerprint) plus what the share link
+// decodes to (protocol/server/port). Everything is omitempty-free where a reader
+// would have to distinguish "absent" from "false"/"zero" — `enabled` and `stale`
+// are always present so a consumer never has to guess.
+type nodeView struct {
+	Name    string `json:"name"`
+	Enabled bool   `json:"enabled"`
+	// Sub is the subscription this node came from; "" means a manual node
+	// (model.Node.FromSub semantics, unchanged).
+	Sub string `json:"sub"`
+	// Protocol is the parsed protocol (vless|vmess|trojan|shadowsocks|wireguard…).
+	// When the URI does not parse it falls back to the bare URI scheme so the
+	// operator still sees what kind of thing failed; "" only when the URI is empty.
+	Protocol string `json:"protocol"`
+	Server   string `json:"server,omitempty"`
+	Port     uint16 `json:"port,omitempty"`
+	// Egress is the `config egress` this node's own upstream is bound to
+	// (multi-WAN); "" = default route.
+	Egress string `json:"egress,omitempty"`
+	// Stale marks a cached subscription node whose subscription failed to refresh.
+	Stale       bool   `json:"stale"`
+	Fingerprint string `json:"fingerprint,omitempty"`
+	// ParseError is the reason the engine will SKIP this node, verbatim from
+	// parse.ParseShareLink. Empty on every usable node.
+	ParseError string `json:"parse_error,omitempty"`
+	// ParseWarnings lists what the share link asked for that the engine cannot
+	// do (hysteria2 port hopping, tuic congestion control, …). The node IS
+	// usable — that is the difference from parse_error — but it does not behave
+	// exactly as its link describes, and that gap belongs on screen rather than
+	// in a code comment.
+	ParseWarnings []string `json:"parse_warnings,omitempty"`
+}
+
+// readModel is the model source. A package var so the tests can exercise the
+// assembly without a router's `uci` binary; production always reads the real
+// merged desired state.
+var readModel = model.ReadUCI
+
+// nodesJSON reads the desired state and renders the node inventory as a JSON
+// array. The array is never `null`: an empty configuration marshals to `[]`,
+// which is the ONE case where `[]` is the truth.
+func nodesJSON() ([]byte, error) {
+	m, err := readModel()
+	if err != nil {
+		return nil, err
+	}
+	return json.Marshal(nodeViews(m))
+}
+
+// nodeViews projects the merged model onto the printable view. Pure: no IO, no
+// globals — the whole verb's logic is testable on a dev host.
+func nodeViews(m *model.Model) []nodeView {
+	out := make([]nodeView, 0, len(m.Nodes)) // never nil => never `null`
+	for i := range m.Nodes {
+		n := m.Nodes[i]
+		v := nodeView{
+			Name:        n.Name,
+			Enabled:     n.Enabled,
+			Sub:         n.FromSub,
+			Egress:      n.Egress,
+			Stale:       n.Stale,
+			Fingerprint: n.Fingerprint,
+			Protocol:    uriScheme(n.URI),
+		}
+		// The engine reads a node through exactly this call (generate/outbound.go,
+		// chain.go, group.go); using it here is what makes "protocol" agree with
+		// what will actually be dialled, and the error agree with what will be
+		// skipped.
+		if p, err := parse.ParseShareLink(n.URI); err == nil {
+			if p.Protocol != "" {
+				v.Protocol = p.Protocol
+			}
+			v.Server = p.Server
+			v.Port = p.Port
+			v.ParseWarnings = p.Warnings
+		} else if n.URI != "" {
+			v.ParseError = err.Error()
+		}
+		out = append(out, v)
+	}
+	return out
+}
+
+// uriScheme returns the lower-cased scheme of a share link ("vless://…" ->
+// "vless"), or "" when there is none. It is the fallback protocol for a URI that
+// ParseShareLink refuses, so an unusable node is still described rather than
+// reported as a typeless blank.
+func uriScheme(uri string) string {
+	i := strings.Index(uri, "://")
+	if i <= 0 {
+		return ""
+	}
+	return strings.ToLower(uri[:i])
+}

shater/cmd/shaterd/nodes_test.go

@@ -0,0 +1,146 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/sagernet/sing-box/shater/model"
+)
+
+// vlessURI is a syntactically complete share link (host, port, uuid, fragment)
+// so ParseShareLink really succeeds and the derived fields are exercised.
+const vlessURI = "vless://11111111-2222-3333-4444-555555555555@example.net:443?" +
+	"encryption=none&security=tls&sni=example.net&type=ws&path=%2Fws#NL-vless-1"
+
+// writeSubCache points the subscription cache at a temp dir and persists one
+// subscription's nodes there, the way `sub update` does on the router
+// (/etc/shater/subs/<sub>.json). Returns nothing: the point is the side effect
+// that model.MergeSubCaches will pick up.
+func writeSubCache(t *testing.T, sub string, nodes []model.Node) {
+	t.Helper()
+	t.Setenv("SHATER_SUBS_DIR", t.TempDir())
+	if err := model.SaveSubCache(sub, nodes); err != nil {
+		t.Fatalf("SaveSubCache(%q): %v", sub, err)
+	}
+}
+
+// TestNodesJSONReportsCachedSubscriptionNodes is the regression for the bug this
+// verb had: `shaterd nodes` answered `[]` while the subscription cache held
+// hundreds of nodes. A NON-EMPTY cache must produce a NON-EMPTY list.
+func TestNodesJSONReportsCachedSubscriptionNodes(t *testing.T) {
+	writeSubCache(t, "all-qomar", []model.Node{
+		{Name: "NL-vless-1", Enabled: true, URI: vlessURI, FromSub: "all-qomar", Fingerprint: "66b33"},
+		{Name: "NL-vless-2", Enabled: false, URI: vlessURI, FromSub: "all-qomar"},
+	})
+
+	// The model source stands in for `uci export shater` (absent on a dev host);
+	// the subscription half is the REAL model.MergeSubCaches path.
+	restore := readModel
+	readModel = func() (*model.Model, error) {
+		m := &model.Model{Globals: model.DefaultGlobals()}
+		model.MergeSubCaches(m)
+		return m, nil
+	}
+	t.Cleanup(func() { readModel = restore })
+
+	b, err := nodesJSON()
+	if err != nil {
+		t.Fatalf("nodesJSON: %v", err)
+	}
+	var got []nodeView
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatalf("nodesJSON produced invalid JSON %q: %v", b, err)
+	}
+	if len(got) == 0 {
+		t.Fatalf("nodes reported an EMPTY list while the subscription cache holds 2 nodes: %s", b)
+	}
+	if len(got) != 2 {
+		t.Fatalf("got %d nodes, want 2: %s", len(got), b)
+	}
+	byName := map[string]nodeView{}
+	for _, v := range got {
+		byName[v.Name] = v
+	}
+	first, ok := byName["NL-vless-1"]
+	if !ok {
+		t.Fatalf("cached node NL-vless-1 missing from %s", b)
+	}
+	if !first.Enabled {
+		t.Errorf("NL-vless-1.enabled = false, want true")
+	}
+	if first.Sub != "all-qomar" {
+		t.Errorf("NL-vless-1.sub = %q, want %q", first.Sub, "all-qomar")
+	}
+	if first.Protocol != "vless" {
+		t.Errorf("NL-vless-1.protocol = %q, want %q", first.Protocol, "vless")
+	}
+	if first.Server != "example.net" || first.Port != 443 {
+		t.Errorf("NL-vless-1 server:port = %s:%d, want example.net:443", first.Server, first.Port)
+	}
+	if first.ParseError != "" {
+		t.Errorf("NL-vless-1.parse_error = %q, want empty", first.ParseError)
+	}
+	if byName["NL-vless-2"].Enabled {
+		t.Errorf("NL-vless-2.enabled = true, want false (the model says disabled)")
+	}
+	// The credential-bearing share link must not be printed.
+	if strings.Contains(string(b), "11111111-2222-3333-4444-555555555555") {
+		t.Errorf("nodes output leaks the share-link uuid: %s", b)
+	}
+}
+
+// TestNodeViewsShape pins the projection: manual vs subscription, an unparsable
+// URI still being LISTED (with the reason), and an empty model marshalling to
+// `[]` rather than `null`.
+func TestNodeViewsShape(t *testing.T) {
+	m := &model.Model{Nodes: []model.Node{
+		{Name: "manual-1", Enabled: true, URI: vlessURI, Egress: "wan2"},
+		{Name: "broken", Enabled: true, URI: "nosuch://whatever", FromSub: "qomar", Stale: true},
+		{Name: "no-uri", Enabled: false},
+	}}
+	got := nodeViews(m)
+	if len(got) != 3 {
+		t.Fatalf("nodeViews returned %d views, want 3", len(got))
+	}
+	if got[0].Sub != "" {
+		t.Errorf("manual node sub = %q, want empty", got[0].Sub)
+	}
+	if got[0].Egress != "wan2" {
+		t.Errorf("manual node egress = %q, want wan2", got[0].Egress)
+	}
+	if got[1].ParseError == "" {
+		t.Errorf("unparsable node must carry the reason the engine will skip it")
+	}
+	if got[1].Protocol != "nosuch" {
+		t.Errorf("unparsable node protocol = %q, want the bare scheme %q", got[1].Protocol, "nosuch")
+	}
+	if !got[1].Stale {
+		t.Errorf("stale flag lost")
+	}
+	if got[2].Protocol != "" || got[2].ParseError != "" {
+		t.Errorf("URI-less node: got protocol=%q parse_error=%q, want both empty", got[2].Protocol, got[2].ParseError)
+	}
+
+	b, err := json.Marshal(nodeViews(&model.Model{}))
+	if err != nil {
+		t.Fatalf("marshal empty: %v", err)
+	}
+	if string(b) != "[]" {
+		t.Errorf("empty model marshalled to %q, want []", b)
+	}
+}
+
+func TestURIScheme(t *testing.T) {
+	for _, tc := range []struct{ in, want string }{
+		{"vless://x@h:443", "vless"},
+		{"VMESS://payload", "vmess"},
+		{"", ""},
+		{"not-a-uri", ""},
+		{"://leading", ""},
+	} {
+		if got := uriScheme(tc.in); got != tc.want {
+			t.Errorf("uriScheme(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}

shater/cmd/shaterd/predecessor.go

@@ -0,0 +1,63 @@
+package main
+
+// The startup handshake that stops a restarting daemon from standing a new data
+// plane up on top of the previous one's teardown.
+//
+// Deliberately free of build tags: the logic is pure timing and is exercised by
+// the tests on any host, while the probe it polls (pidfile + kill(pid, 0)) is
+// linux-only and is installed by predecessor_linux.go.
+
+import (
+	"os"
+	"time"
+
+	"github.com/sagernet/sing-box/log"
+)
+
+// predecessorBudget / predecessorPoll bound the wait for an outgoing daemon.
+//
+// The budget must comfortably exceed the slowest honest teardown (engine.Close
+// of a box with a few hundred outbounds plus the cache-file flush to flash, then
+// the nft/ip/sysctl removal) AND the init script's procd term_timeout, which is
+// the hard cap on how long a predecessor can live after its SIGTERM. Overshooting
+// costs nothing on a healthy box — the wait ends the instant the predecessor is
+// gone — while undershooting reintroduces the very overlap this exists to remove.
+//
+// Variables, not constants, so the tests can drive the loop without sleeping.
+var (
+	predecessorBudget = 60 * time.Second
+	predecessorPoll   = 100 * time.Millisecond
+)
+
+// aliveProbe is the seam waitForPredecessor polls. The portable default reports
+// "no predecessor", so a non-linux build (where there is no daemon at all) never
+// waits; predecessor_linux.go replaces it with the real pidfile probe.
+var aliveProbe = func() (int, bool) { return 0, false }
+
+// waitForPredecessor blocks until no OTHER shaterd owns the pidfile, or until the
+// budget runs out.
+//
+// Returns (pid, true) only when a predecessor is STILL alive once the budget
+// expires — the genuine "two daemons" error the caller refuses on. A predecessor
+// that exits within the budget (the restart case) returns (0, false) and startup
+// continues, now guaranteed to be sequenced after its teardown, exactly as it is
+// after a manual `stop` + pause + `start`.
+func waitForPredecessor(budget, poll time.Duration, logger log.ContextLogger) (int, bool) {
+	pid, ok := aliveProbe()
+	if !ok || pid == os.Getpid() {
+		return 0, false
+	}
+	if logger != nil {
+		logger.Info("a previous shaterd (pid ", pid, ") is still shutting down — ",
+			"waiting for its teardown to finish before applying a new data plane")
+	}
+	deadline := time.Now().Add(budget)
+	for time.Now().Before(deadline) {
+		time.Sleep(poll)
+		pid, ok = aliveProbe()
+		if !ok || pid == os.Getpid() {
+			return 0, false
+		}
+	}
+	return pid, true
+}

shater/cmd/shaterd/predecessor_linux.go

@@ -0,0 +1,9 @@
+//go:build linux
+
+package main
+
+// Bind the portable predecessor wait to the real single-owner probe. Split out
+// of main.go so waitForPredecessor itself stays build-tag-free and testable on
+// any developer host.
+
+func init() { aliveProbe = daemonAlive }

shater/cmd/shaterd/predecessor_test.go

@@ -0,0 +1,106 @@
+package main
+
+// B3 regression, daemon half.
+//
+// `/etc/init.d/shater restart` is `stop; start`, and procd's `stop` is
+// asynchronous: the ubus `service delete` returns as soon as SIGTERM has been
+// SENT, so `start` re-adds the instance while the outgoing `shaterd run` is
+// still executing its honest teardown. The startup guard used to exit(1) the
+// moment it saw a live predecessor and rely on procd's `respawn ... 5 ...` to
+// try again later — a blind retry that neither knows nor waits for the teardown
+// to finish, and that turns every restart into a logged crash plus a five-second
+// hole with no data plane.
+//
+// The contract these pin: startup BLOCKS until the predecessor is gone (so our
+// apply is strictly ordered after its teardown, exactly as it is after a manual
+// `stop` + pause + `start`), and only refuses when the predecessor outlives the
+// whole budget.
+
+import (
+	"os"
+	"testing"
+	"time"
+)
+
+// scriptAlive installs an aliveProbe that reports a live predecessor for the
+// first n calls and "gone" afterwards, and restores the real probe.
+func scriptAlive(t *testing.T, pid, n int) *int {
+	t.Helper()
+	orig := aliveProbe
+	t.Cleanup(func() { aliveProbe = orig })
+	calls := 0
+	aliveProbe = func() (int, bool) {
+		calls++
+		if calls <= n {
+			return pid, true
+		}
+		return 0, false
+	}
+	return &calls
+}
+
+// TestWaitForPredecessorWaitsForTeardown: a predecessor that is still tearing
+// the plane down must be WAITED for, not refused. Before the fix this returned
+// "still alive" on the first probe and the daemon exited 1.
+func TestWaitForPredecessorWaitsForTeardown(t *testing.T) {
+	calls := scriptAlive(t, 4242, 3)
+
+	pid, stillAlive := waitForPredecessor(2*time.Second, time.Millisecond, nil)
+	if stillAlive {
+		t.Fatalf("a predecessor that exits within the budget must not be refused (pid %d)", pid)
+	}
+	if *calls < 4 {
+		t.Fatalf("expected the guard to keep probing until the predecessor was gone, got %d probes", *calls)
+	}
+}
+
+// TestWaitForPredecessorRefusesAfterBudget: the single-owner invariant is kept —
+// a predecessor that never dies still ends in a refusal, it is just no longer
+// the FIRST answer.
+func TestWaitForPredecessorRefusesAfterBudget(t *testing.T) {
+	orig := aliveProbe
+	defer func() { aliveProbe = orig }()
+	aliveProbe = func() (int, bool) { return 4242, true }
+
+	start := time.Now()
+	pid, stillAlive := waitForPredecessor(30*time.Millisecond, time.Millisecond, nil)
+	if !stillAlive || pid != 4242 {
+		t.Fatalf("an immortal predecessor must still be refused, got pid=%d alive=%v", pid, stillAlive)
+	}
+	if time.Since(start) < 30*time.Millisecond {
+		t.Fatalf("the guard must exhaust its budget before refusing")
+	}
+}
+
+// TestWaitForPredecessorNoPredecessorIsFree: the boot path must pay nothing —
+// one probe, no sleep. A wait that cost a tick on every clean start would show up
+// as a slower boot for no reason.
+func TestWaitForPredecessorNoPredecessorIsFree(t *testing.T) {
+	orig := aliveProbe
+	defer func() { aliveProbe = orig }()
+	calls := 0
+	aliveProbe = func() (int, bool) { calls++; return 0, false }
+
+	start := time.Now()
+	if _, stillAlive := waitForPredecessor(time.Minute, time.Second, nil); stillAlive {
+		t.Fatalf("no predecessor must not be reported as alive")
+	}
+	if calls != 1 {
+		t.Fatalf("expected exactly one probe when nothing is running, got %d", calls)
+	}
+	if time.Since(start) > 500*time.Millisecond {
+		t.Fatalf("the no-predecessor path must not sleep")
+	}
+}
+
+// TestWaitForPredecessorIgnoresOwnPid: a pidfile naming THIS process (a crashed
+// predecessor whose pid we were handed, or a re-exec) is not a predecessor.
+func TestWaitForPredecessorIgnoresOwnPid(t *testing.T) {
+	orig := aliveProbe
+	defer func() { aliveProbe = orig }()
+	aliveProbe = func() (int, bool) { return os.Getpid(), true }
+
+	if _, stillAlive := waitForPredecessor(time.Minute, time.Second, nil); stillAlive {
+		t.Fatalf("our own pid must never count as a predecessor")
+	}
+}

shater/engine/engine.go

@@ -61,6 +61,25 @@ type Engine struct {
 	current  option.Options // options the running Box was built from
 	hash     string         // stable hash of current (hex sha256 of canonical JSON)
 
+	// instanceCancel cancels the context THIS box was built on — its own
+	// cancellable child of e.ctx, one per box (see newBox). box.New does not
+	// derive a cancellable context of its own, so without this every goroutine
+	// inside a retired box that waits on ctx.Done() waits forever. Upstream's
+	// runner does exactly this and calls cancel before Close
+	// (cmd/sing-box/cmd_run.go). nil when nothing is running.
+	instanceCancel context.CancelFunc
+	// instanceGen is the 1-based sequence number of the running box, bumped on
+	// every adopted swap. It is what names a generation in the log and in
+	// PendingCloses when a shutdown overruns its budget.
+	instanceGen uint64
+
+	// pending holds the retirements in flight (see teardown.go). Its OWN leaf
+	// lock, deliberately not mu: PendingCloses is read by the status path, and
+	// the moment that read matters most is while an apply is holding mu waiting
+	// out a shutdown that will not finish.
+	pendingMu sync.Mutex
+	pending   []*pendingClose
+
 	// defaultLogWriter, when non-nil, is handed to EVERY box.New this engine
 	// performs (box.Options.DefaultLogWriter): the daemon points it at its
 	// long-lived logsink once, and each Apply-swapped box then logs into that
@@ -140,7 +159,21 @@ func New(logger ...log.ContextLogger) *Engine {
 	// URLTestHistory() below. The pointer is stable across Apply swaps, so health
 	// history survives config changes instead of being reset on every apply.
 	ctx = service.ContextWithPtr(ctx, urltest.NewHistoryStorage())
-	return &Engine{ctx: ctx, log: l}
+	// Pre-register the engine itself as the probe GATE, into the same shared
+	// registry and for the same reason as the two above: every urltest group
+	// built by every box.New reads it out of ctx (protocol/group/urltest.go), and
+	// the registration must survive Apply swaps because the question it answers
+	// outlives any single box.
+	//
+	// The gate answers "may this outbound run its own scheduled probe right
+	// now" — see Engine.ProbeAllowed. It is a live call, not a stored flag, so
+	// a chain hop that comes back resumes probing with no reapply. Registering
+	// the Engine here (rather than a snapshot) is what makes that possible;
+	// the struct is built first purely so ctx can point at it.
+	e := &Engine{log: l}
+	ctx = service.ContextWith[urltest.ProbeGate](ctx, e)
+	e.ctx = ctx
+	return e
 }
 
 // Apply installs opts as the running configuration.
@@ -174,6 +207,24 @@ func (e *Engine) Apply(opts option.Options) (changed bool, err error) {
 }
 
 func (e *Engine) applyLocked(opts option.Options) (bool, error) {
+	// Stand down the self-check of urltest groups no rule reaches (see
+	// selfcheck.go for the whole argument). This MUTATES opts in place — the
+	// option structs are pointers behind an `any` — and it must run BEFORE the
+	// hash below, so the hash describes the config that is really built: a rule
+	// change that flips a group used<->unused is then a real change that
+	// triggers a swap, and an unchanged config hashes identically on every
+	// reconcile because the stand-down is deterministic.
+	stood, used := standDownUnusedSelfCheck(opts)
+	if stood > 0 && e.log != nil {
+		e.log.Info("apply: stood down self-check on ", stood, " unused urltest group(s); the observatory is their only prober")
+	}
+	// Publish the same walk's used-set for ProbeWhenIdle BEFORE the new box is
+	// built, because the question is asked during that box's PostStart: a used
+	// group arms its probing ticker there rather than waiting for traffic. The
+	// observatory's own copy is published later, after a SUCCESSFUL swap, which
+	// is too late to be the answer.
+	e.publishKeepWarm(used)
+
 	newHash, err := e.hashOptions(opts)
 	if err != nil {
 		return false, E.Cause(err, "hash options")
@@ -184,12 +235,18 @@ func (e *Engine) applyLocked(opts option.Options) (bool, error) {
 		return false, nil
 	}
 
-	// (2) build + validate. box.New constructs and validates every adapter.
-	nb, err := box.New(box.Options{
-		Context:          e.ctx,
-		Options:          opts,
-		DefaultLogWriter: e.defaultLogWriter,
-	})
+	// (1b) Do not stack generations. A superseded box whose shutdown overran its
+	// budget is still holding its outbound connections and its WireGuard devices;
+	// building another one on top of it is how one process ends up carrying four
+	// live generations. Give any abandoned teardown one more budget to finish
+	// BEFORE we create anything (see teardown.go awaitAbandonedLocked). Placed
+	// after the hash gate on purpose: a no-op reconcile — cron, every minute —
+	// must stay free.
+	stuck := e.awaitAbandonedLocked()
+
+	// (2) build + validate on its OWN cancellable context. box.New constructs and
+	// validates every adapter.
+	nb, nbCancel, err := e.newBox(opts)
 	if err != nil {
 		// Validation failed: keep the running instance, do not swap.
 		return false, E.Cause(err, "create instance")
@@ -211,8 +268,15 @@ func (e *Engine) applyLocked(opts option.Options) (bool, error) {
 	//     close-old-then-start-new DIRECTLY — skipping the stall. (box.New above
 	//     already validated opts, so we never tear the old box down for a config
 	//     that would fail to build.)
-	if e.instance != nil && sharesCacheFileLock(e.current, opts) {
-		return e.closeOldThenStart(nb, opts, newHash)
+	//
+	// A generation that is STILL abandoned after the wait above forces the same
+	// path for a different reason: start-new-first would put a second LIVE box
+	// alongside a third that refuses to die, all three contending for the same
+	// tproxy port, the same cache file and — the expensive one — the same
+	// WireGuard private keys. Closing the current box first keeps the process to
+	// at most one live instance plus the abandoned one.
+	if e.instance != nil && (stuck > 0 || sharesCacheFileLock(e.current, opts)) {
+		return e.closeOldThenStart(nb, nbCancel, opts, newHash)
 	}
 
 	// (3b) start-new-first (zero-downtime when there is no resource conflict).
@@ -223,25 +287,59 @@ func (e *Engine) applyLocked(opts option.Options) (bool, error) {
 		// close-old-then-start-new then. Any OTHER Start failure keeps today's
 		// behavior: discard the new box, keep the old one running.
 		if e.instance == nil || !isSwapConflict(err) {
+			nbCancel()
 			_ = nb.Close()
 			return false, E.Cause(err, "start instance")
 		}
-		return e.closeOldThenStart(nb, opts, newHash)
+		return e.closeOldThenStart(nb, nbCancel, opts, newHash)
 	}
 
 	// Swap succeeded. The previously running config becomes last-good.
-	old := e.instance
-	if old != nil {
+	if e.instance != nil {
 		e.lastGood = e.current
 		e.hasLastGood = true
-		_ = old.Close()
+		// Retire the old generation under the hard budget. Its error — including
+		// ErrCloseTimeout — is deliberately NOT returned: the new box is started
+		// and carrying traffic, so this apply SUCCEEDED, and failing it here would
+		// abort the caller's netplane stage and leave a stale ruleset loaded over a
+		// perfectly healthy engine. An abandoned generation is surfaced through
+		// PendingCloses() (critical warning in `shaterd status` and the panel) and
+		// an ERROR line naming it — visible, but not mistaken for a failed apply.
+		_ = e.retireLocked(e.instance, e.instanceCancel, e.instanceGen, e.hash)
 	}
-	e.instance = nb
-	e.current = opts
-	e.hash = newHash
+	e.adoptLocked(nb, nbCancel, opts, newHash)
 	return true, nil
 }
 
+// newBox builds a box on its OWN cancellable child of the engine context and
+// returns the cancel alongside it. Every goroutine the box starts inherits that
+// context, so cancelling it is what unwinds the ones Close does not reach; see
+// teardown.go for why the shared, never-cancelled context was the defect.
+func (e *Engine) newBox(opts option.Options) (*box.Box, context.CancelFunc, error) {
+	ctx, cancel := context.WithCancel(e.ctx)
+	b, err := box.New(box.Options{
+		Context:          ctx,
+		Options:          opts,
+		DefaultLogWriter: e.defaultLogWriter,
+	})
+	if err != nil {
+		cancel()
+		return nil, nil, err
+	}
+	return b, cancel, nil
+}
+
+// adoptLocked installs a started box as THE running instance and gives it the
+// next generation number. Caller holds e.mu and has already retired whatever was
+// running before.
+func (e *Engine) adoptLocked(b *box.Box, cancel context.CancelFunc, opts option.Options, hash string) {
+	e.instanceGen++
+	e.instance = b
+	e.instanceCancel = cancel
+	e.current = opts
+	e.hash = hash
+}
+
 // closeOldThenStart is the close-old-then-start-new swap. It is taken both
 // proactively (the incoming config shares the running box's cache_file lock, so
 // start-new-first cannot work) and reactively (start-new-first hit a swap
@@ -256,27 +354,36 @@ func (e *Engine) applyLocked(opts option.Options) (bool, error) {
 // already validated by the caller's box.New, so the rebuild below is expected to
 // succeed; the restore path guards the rare case it does not. The caller holds
 // e.mu.
-func (e *Engine) closeOldThenStart(discard *box.Box, opts option.Options, newHash string) (bool, error) {
+func (e *Engine) closeOldThenStart(discard *box.Box, discardCancel context.CancelFunc, opts option.Options, newHash string) (bool, error) {
 	// (a) Drop the pre-built box (a Start-failed box cannot be restarted, and the
 	// proactively-built one must not hold the cache_file lock while we rebuild).
+	// It was never adopted, so it is not a generation — close it inline, but
+	// cancel its context first exactly like a retired one.
+	if discardCancel != nil {
+		discardCancel()
+	}
 	if discard != nil {
 		_ = discard.Close()
 	}
 
-	// (b) Free the port + cache_file lock by closing the old instance. Remember
-	// its config so we can restore it if the fresh box cannot come up.
+	// (b) Free the port + cache_file lock by closing the old instance, under the
+	// hard budget. Remember its config so we can restore it if the fresh box
+	// cannot come up. An overrun here is reported by retireLocked and tracked in
+	// PendingCloses; we still proceed, because the resources it was supposed to
+	// free are exactly what the operator is waiting on.
 	prevOpts := e.current
 	prevHash := e.hash
 	prevLastGood := e.lastGood
 	prevHasLastGood := e.hasLastGood
-	_ = e.instance.Close()
-	e.instance = nil
+	_ = e.retireLocked(e.instance, e.instanceCancel, e.instanceGen, prevHash)
+	e.instance, e.instanceCancel = nil, nil
 
 	// (c) Build a FRESH box for opts (the discarded one cannot be reused).
-	nb2, err := box.New(box.Options{Context: e.ctx, Options: opts, DefaultLogWriter: e.defaultLogWriter})
+	nb2, cancel2, err := e.newBox(opts)
 	if err == nil {
 		err = nb2.Start()
 		if err != nil {
+			cancel2()
 			_ = nb2.Close()
 		}
 	}
@@ -284,28 +391,25 @@ func (e *Engine) closeOldThenStart(discard *box.Box, opts option.Options, newHas
 		// (d) Success: the old config we just closed becomes last-good.
 		e.lastGood = prevOpts
 		e.hasLastGood = true
-		e.instance = nb2
-		e.current = opts
-		e.hash = newHash
+		e.adoptLocked(nb2, cancel2, opts, newHash)
 		return true, nil
 	}
 
 	// (e) The fresh box could not come up and the old one is already closed —
 	// interception is currently down. Try to RESTORE the previous config so we
 	// do not leave the tunnel dead.
-	rb, rerr := box.New(box.Options{Context: e.ctx, Options: prevOpts, DefaultLogWriter: e.defaultLogWriter})
+	rb, rcancel, rerr := e.newBox(prevOpts)
 	if rerr == nil {
 		rerr = rb.Start()
 		if rerr != nil {
+			rcancel()
 			_ = rb.Close()
 		}
 	}
 	if rerr == nil {
 		// Old config restored: keep current/hash/last-good exactly as they were
 		// (do NOT advance them). Report that opts was not applied.
-		e.instance = rb
-		e.current = prevOpts
-		e.hash = prevHash
+		e.adoptLocked(rb, rcancel, prevOpts, prevHash)
 		e.lastGood = prevLastGood
 		e.hasLastGood = prevHasLastGood
 		return false, E.Cause(err, "start instance (config not applied; previous config restored)")
@@ -314,7 +418,7 @@ func (e *Engine) closeOldThenStart(discard *box.Box, opts option.Options, newHas
 	// Restore ALSO failed: the engine is now STOPPED. e.instance stays nil (never
 	// pointing at a closed box). The fail-closed nft kill-switch keeps the LAN
 	// safe (no unproxied leak) even though interception is down.
-	e.instance = nil
+	e.instance, e.instanceCancel = nil, nil
 	e.hash = ""
 	return false, E.Cause(E.Errors(err, rerr), "start instance failed and could not restore previous config; engine stopped")
 }
@@ -410,14 +514,26 @@ func (e *Engine) HasLastGood() bool {
 }
 
 // Close stops the running instance, if any. It is idempotent.
+//
+// Unlike the swap path, this one DOES return ErrCloseTimeout: here the shutdown
+// is the whole operation, so "it did not stop" is the result, not a footnote. The
+// caller (apply.Teardown) records it as the teardown's error while still
+// completing the netplane teardown — the data plane must come down even when a
+// box will not.
 func (e *Engine) Close() error {
 	e.mu.Lock()
 	defer e.mu.Unlock()
 	if e.instance == nil {
+		// Nothing running, but a previously abandoned generation may still be:
+		// give it a last budget so a teardown followed by a restart does not carry
+		// the leak across.
+		if e.awaitAbandonedLocked() > 0 {
+			return ErrCloseTimeout
+		}
 		return nil
 	}
-	err := e.instance.Close()
-	e.instance = nil
+	err := e.retireLocked(e.instance, e.instanceCancel, e.instanceGen, e.hash)
+	e.instance, e.instanceCancel = nil, nil
 	e.hash = ""
 	return err
 }

shater/engine/grouphealth.go

@@ -1,6 +1,7 @@
 package engine
 
 import (
+	"sort"
 	"strings"
 
 	"github.com/sagernet/sing-box/adapter"
@@ -320,11 +321,15 @@ func parseGroupCopyTag(group, tag string) (member string, ok bool) {
 	return member, true
 }
 
-// ChainHealth is one configured chain's reachability, mirroring GroupHealth.Used
-// for the chain card (plan §5.E): a chain no enabled rule routes through is never
-// probed — the observatory walks only reachable paths — and the panel renders it
-// "unused" rather than as a health problem. A chain has no membership counters: it
-// is a fixed path, and its end-to-end health is the exit test's job, not a roll-up.
+// ChainHealth is one configured chain's reachability plus its PER-HOP health,
+// mirroring GroupHealth.Used for the chain card (plan §5.E): a chain no enabled
+// rule routes through is never probed — the observatory walks only reachable
+// paths — and the panel renders it "unused" rather than as a health problem.
+// A chain has no membership counters of its own: it is a fixed path, and its
+// end-to-end health is the exit probe's job. What it DOES have is hops, and
+// since the observatory now probes every hop wrapper (probeplan.go walkDetour),
+// each hop's health is on the board and is projected here so an operator can
+// see WHICH hop died instead of only that the chain did.
 type ChainHealth struct {
 	// Name is the chain's model name (config chain "chain:<name>"), what the Targets
 	// page lists and what a rule targets.
@@ -336,34 +341,284 @@ type ChainHealth struct {
 	// when the observatory is disabled or not yet configured: no badge is better
 	// than a wrong one (the same rule as GroupHealth.Used).
 	Used bool `json:"used"`
+	// Hops is the per-hop health readout, L1..Ln in wire order (see ChainHopHealth).
+	// It is EMPTY for a chain the running box never materialised: a chain no rule
+	// references is resolved lazily and never built, and a 1-hop chain without an
+	// egress entry resolves straight to its target with no wrapper — in both cases
+	// there are no "chain-<name>-h…" outbounds to project. An absent "hops" key
+	// therefore means "nothing materialised to report on", NEVER "this chain has
+	// no hops" — the model, not this projection, knows how many hops were
+	// configured.
+	Hops []ChainHopHealth `json:"hops,omitempty"`
 }
 
-// ChainHealth reports the reachability (used/unused) of every named chain, one row
-// per name, in the order given. It is the chain analogue of GroupHealth.Used: a
-// chain the observatory's used-set does not cover is reported Used=false so the
-// panel can mark it "unused" instead of running an exit test against a path nothing
-// routes through.
+// ChainHopHealth is one hop of one materialised chain, as the health board saw
+// it — a projection, like everything in this file: nothing here dials.
+//
+// A NODE hop is a single measurement: the observatory dials the hop wrapper
+// "chain-<name>-h<i>", which pulls exactly the path prefix up to and including
+// this hop, so Total=1, the counters follow the hop's own state, DelayMs and
+// AgeSeconds are its own observation, and Selected is "" (a fixed hop selects
+// nothing).
+//
+// A GROUP hop rolls up its member copies "chain-<name>-h<i>-<member>", each of
+// which the observatory probes through its own prefix of the chain. The
+// counters obey the same invariants as GroupHealth — Tested == Alive+Dead and
+// Alive+Dead+Untested == Total — so the panel needs no arithmetic of its own.
+// State summarises them: "alive" when at least one member is alive (the hop can
+// carry traffic), "dead" when at least one was tested and none is alive (a
+// positive finding of a dead hop), "untested" when nothing was tested. Selected
+// is the node NAME the wrapper currently picks; DelayMs/AgeSeconds are the
+// SELECTED member's observation, or the freshest ALIVE member's when the
+// selection has no measurement of its own — the number shown must always be a
+// measurement somebody took, never an average nobody did.
+//
+// # The hop nobody reached: BlockedBy
+//
+// The prober walks a chain in wire order and stops at the first dead hop
+// (observatory.go probeChainOrdered), because a probe of hop 3 dials THROUGH
+// hop 2 and a hop 2 with no live member makes that probe a measurement of hop 2.
+// Everything behind the break is therefore not dialled at all, and this struct
+// says so: State is untested — no fresh knowledge, which is the truth — the
+// counters collapse into Untested, and BlockedBy names the hop that stopped the
+// walk. A row like that must never be read as a fault of its own; the fault is
+// at BlockedBy.Index, and that is the hop to go and fix.
+type ChainHopHealth struct {
+	Index      int    `json:"index"`       // 1-based position on the wire, L1..Ln
+	Tag        string `json:"tag"`         // "chain-<name>-h<i>" — the wrapper actually dialled
+	Kind       string `json:"kind"`        // "node" | "group"
+	Exit       bool   `json:"exit"`        // the LAST hop: where traffic leaves to the internet
+	State      string `json:"state"`       // "alive" | "dead" | "untested"
+	DelayMs    int    `json:"delay_ms"`
+	AgeSeconds int64  `json:"age_seconds"` // -1 when unknown
+	Selected   string `json:"selected"`    // group hop: the node NAME it currently selects; "" otherwise
+	Total      int    `json:"total"`
+	Tested     int    `json:"tested"`
+	Alive      int    `json:"alive"`
+	Dead       int    `json:"dead"`
+	Untested   int    `json:"untested"`
+	// BlockedBy is set ONLY on a hop the ordered walk never reached, and names the
+	// dead hop in front of it. Absent (omitted, never null) on every hop that was
+	// itself measured. When it is present State is always "untested" and the
+	// counters are always 0/0/0/Total — see the type comment.
+	BlockedBy *ChainHopBlock `json:"blocked_by,omitempty"`
+}
+
+// ChainHopBlock identifies the hop whose failure stopped a chain's ordered probe
+// walk: its 1-based wire index and the engine outbound tag that was dialled.
+//
+// The index is the field that matters — it is what the operator acts on, and it
+// lines up with ChainHopHealth.Index on the same chain, so a reader can point
+// straight at the offending row. The tag is diagnostic detail (logs, tooltips)
+// and is not a label to put in front of a person: "chain-ewan-wg-subs-h2" is not
+// a name anybody chose.
+type ChainHopBlock struct {
+	Index int    `json:"index"`
+	Tag   string `json:"tag"`
+}
+
+// ChainHealth reports the reachability (used/unused) of every named chain plus
+// the per-hop health of each one the running box materialised, one row per
+// name, in the order given. The Used half is the chain analogue of
+// GroupHealth.Used: a chain the observatory's used-set does not cover is
+// reported Used=false so the panel can mark it "unused" instead of a health
+// readout against a path nothing routes through.
 //
 // names come from the desired-state model, NOT the running box: a chain no rule
 // references is never materialised (generate/chain.go resolveChain is lazy), so it
 // is invisible to a box-only enumeration — yet the panel lists it from the config
-// and must be able to badge it. The engine supplies the only fact a box read can
-// add here, the observatory's published used-set. Pure apart from that read; nil
-// names or a stopped engine (nil used-set) yield an empty/used-everything result.
+// and must be able to badge it. The engine supplies what only it can: the
+// observatory's published used-set, and the running box's outbound/endpoint
+// pool the hop projection reads. Still no dialling anywhere; nil names or a
+// stopped engine (nil used-set, empty pool) yield an empty/used-everything
+// result with no hops.
 func (e *Engine) ChainHealth(names []string) []ChainHealth {
 	out := make([]ChainHealth, 0, len(names))
 	used := e.observatoryUsed()
 	usedChains := usedChainNames(used)
+	pool := e.runningPool()
+	view := e.HealthView()
 	for _, name := range names {
 		name = strings.TrimSpace(name)
 		if name == "" {
 			continue
 		}
-		out = append(out, ChainHealth{Name: name, Used: used == nil || usedChains[name]})
+		out = append(out, ChainHealth{
+			Name: name,
+			Used: used == nil || usedChains[name],
+			Hops: chainHopHealthOf(pool, name, view),
+		})
 	}
 	return out
 }
 
+// runningPool snapshots the running box's outbounds AND endpoints into one
+// list. The endpoints matter: a chain hop rebuilt from a wireguard/AmneziaWG
+// node is an ENDPOINT copy, invisible in Outbounds() — the same trap
+// groupTargets documents — and a hop projection that missed it would silently
+// drop the very hop this feature exists to localise (the production chain's
+// first hop IS an AWG endpoint). Empty (never nil-unsafe) on a stopped engine.
+func (e *Engine) runningPool() []adapter.Outbound {
+	var pool []adapter.Outbound
+	inst := e.Instance()
+	if inst == nil {
+		return pool
+	}
+	if om := inst.Outbound(); om != nil {
+		pool = append(pool, om.Outbounds()...)
+	}
+	if em := inst.Endpoint(); em != nil {
+		for _, ep := range em.Endpoints() {
+			pool = append(pool, ep)
+		}
+	}
+	return pool
+}
+
+// chainHopHealthOf projects one chain's hop wrappers out of an outbound pool
+// against one health view. Pure apart from the view reads — the same
+// unit-testing contract as groupHealthOf: hand it a fake pool and a hand-built
+// store and every branch is reachable without a box.
+//
+// A pool entry belongs to chain <name> when its tag is exactly
+// "chain-<name>-h<digits>" — the hop WRAPPER the observatory dials. Member
+// copies ("chain-<name>-h<i>-<member>") are not hops themselves; they are
+// reached through the wrapper's own member list (adapter.OutboundGroup.All), so
+// the roll-up sees exactly what the wrapper can select, in its order.
+func chainHopHealthOf(pool []adapter.Outbound, name string, view HealthView) []ChainHopHealth {
+	prefix := "chain-" + name + "-h"
+	var hops []ChainHopHealth
+	for _, ob := range pool {
+		tag := ob.Tag()
+		rest, ok := strings.CutPrefix(tag, prefix)
+		if !ok {
+			continue
+		}
+		idx, ok := parseAllDigits(rest)
+		if !ok {
+			continue // a member copy, or another chain sharing the prefix
+		}
+		if g, isGroup := ob.(adapter.OutboundGroup); isGroup {
+			hops = append(hops, chainGroupHop(g, name, idx, view))
+		} else {
+			hops = append(hops, chainNodeHop(tag, idx, view))
+		}
+	}
+	sort.Slice(hops, func(i, j int) bool { return hops[i].Index < hops[j].Index })
+	if len(hops) > 0 {
+		// The largest index is the exit — the wrapper whose probe leaves to the
+		// internet. Marked after sorting so the flag cannot depend on pool order.
+		hops[len(hops)-1].Exit = true
+	}
+	markBlockedHops(hops)
+	return hops
+}
+
+// markBlockedHops applies the ordered walk's outcome to the projection: from the
+// first hop that reads DEAD, every later hop is rewritten as not-reached.
+//
+// This is a rewrite and not an annotation on purpose. The prober stops at the
+// first dead hop, so a hop behind the break has not been dialled since the break
+// appeared — but its board records do not vanish, they age out on the TTL. For
+// as long as that takes, the raw projection would keep publishing a verdict about
+// a hop nothing has attempted, and the most damaging version of that is a stale
+// "dead" pointing the operator at a hop that may be perfectly fine. Untested is
+// the honest reading of "nothing current is known", and BlockedBy is why.
+//
+// The counters collapse the same way, into Untested, so the invariants the whole
+// health surface promises still hold verbatim: Tested == Alive+Dead and
+// Alive+Dead+Untested == Total.
+//
+// Selected SURVIVES. It is not a measurement — it is the member the wrapper would
+// route through — and it stays true (and useful) whether or not anything reached
+// this hop.
+func markBlockedHops(hops []ChainHopHealth) {
+	for i := range hops {
+		if hops[i].State != HealthDead {
+			continue
+		}
+		blocker := &ChainHopBlock{Index: hops[i].Index, Tag: hops[i].Tag}
+		for j := i + 1; j < len(hops); j++ {
+			h := &hops[j]
+			h.State = HealthUntested
+			h.DelayMs, h.AgeSeconds = 0, -1
+			h.Alive, h.Dead, h.Tested = 0, 0, 0
+			h.Untested = h.Total
+			h.BlockedBy = blocker
+		}
+		return // the first break is the only one that can be observed
+	}
+}
+
+// chainNodeHop is the one-measurement hop: the wrapper itself was dialled by
+// the observatory, so its own board state IS the hop's health and the counters
+// degenerate to whichever bucket that state fills.
+func chainNodeHop(tag string, idx int, view HealthView) ChainHopHealth {
+	hop := ChainHopHealth{Index: idx, Tag: tag, Kind: "node", Total: 1}
+	hop.State, hop.DelayMs, hop.AgeSeconds = view.State(tag)
+	switch hop.State {
+	case HealthAlive:
+		hop.Alive = 1
+	case HealthDead:
+		hop.Dead = 1
+	default:
+		hop.Untested = 1
+	}
+	hop.Tested = hop.Alive + hop.Dead
+	return hop
+}
+
+// chainGroupHop rolls a group hop up over its member copies. The counters carry
+// the GroupHealth invariants; the summary State answers the only question a hop
+// row asks — "can this hop carry the chain": alive while anything answers,
+// dead only on a positive all-tested-dead finding, untested when nothing is
+// known (never dead-by-absence, the same honesty rule as everywhere else).
+func chainGroupHop(g adapter.OutboundGroup, chain string, idx int, view HealthView) ChainHopHealth {
+	hop := ChainHopHealth{Index: idx, Tag: g.Tag(), Kind: "group", AgeSeconds: -1}
+	selected := g.Now()
+	if selected != "" {
+		hop.Selected = chainMemberName(selected, chain)
+	}
+
+	// The number a hop row shows must be a real observation: the selected
+	// member's when it has one, else the freshest alive member's.
+	freshDelay, freshAge := 0, int64(-1)
+	selDelay, selAge := 0, int64(-1)
+	for _, tag := range g.All() {
+		state, delayMs, age := view.State(tag)
+		switch state {
+		case HealthAlive:
+			hop.Alive++
+			if age >= 0 && (freshAge < 0 || age < freshAge) {
+				freshDelay, freshAge = delayMs, age
+			}
+		case HealthDead:
+			hop.Dead++
+		default:
+			hop.Untested++
+		}
+		hop.Total++
+		if tag == selected && age >= 0 {
+			selDelay, selAge = delayMs, age
+		}
+	}
+	hop.Tested = hop.Alive + hop.Dead
+	switch {
+	case hop.Alive > 0:
+		hop.State = HealthAlive
+	case hop.Tested > 0:
+		hop.State = HealthDead
+	default:
+		hop.State = HealthUntested
+	}
+	if selAge >= 0 {
+		hop.DelayMs, hop.AgeSeconds = selDelay, selAge
+	} else {
+		hop.DelayMs, hop.AgeSeconds = freshDelay, freshAge
+	}
+	return hop
+}
+
 // usedChainNames recovers the set of chain NAMES the observatory's used-set covers.
 //
 // The used-set is keyed by outbound TAG (the generator's schema, materialised in

shater/engine/grouphealth_test.go

@@ -309,8 +309,167 @@ func TestChainHealthNilUsedSet(t *testing.T) {
 		t.Fatalf("ChainHealth = %+v, want %+v (nil used-set ⇒ all used, blanks dropped)", got, want)
 	}
 	for i, w := range want {
-		if got[i] != w {
+		if got[i].Name != w.Name || got[i].Used != w.Used {
 			t.Errorf("ChainHealth[%d] = %+v, want %+v", i, got[i], w)
 		}
+		// A stopped engine materialised nothing: hops must be empty, and the
+		// contract says empty means "nothing materialised", not "no hops".
+		if len(got[i].Hops) != 0 {
+			t.Errorf("ChainHealth[%d].Hops = %+v, want empty on a stopped engine", i, got[i].Hops)
+		}
+	}
+}
+
+// TestChainHopHealthProjection drives the per-hop readout over a 3-hop chain —
+// node hop L1, group hop L2, group hop L3 (the exit) — with exactly ONE hop's
+// members dead. The dead state must land on THAT hop's index and nowhere else,
+// the counters must obey the GroupHealth invariants on every hop, and the exit
+// flag must sit on the largest index. This is the "which hop died" question the
+// whole hop surface exists to answer.
+//
+// L3 additionally pins the ordered walk's half of the contract: it sits BEHIND
+// the dead L2, so whatever its stale board records say, it is reported untested
+// with L2 named — never as a hop of its own with a verdict nobody took.
+func TestChainHopHealthProjection(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	now := time.Now()
+
+	// L1 (node hop wrapper): alive — the prefix up to hop 1 works.
+	hist.StoreURLTestHistory("chain-c-h1", &adapter.URLTestHistory{LastOK: now.Add(-5 * time.Second), Delay: 40})
+	// L2 (group hop): BOTH member copies dead — this is the hop that died.
+	hist.StoreURLTestHistory("chain-c-h2-x", &adapter.URLTestHistory{LastFail: now.Add(-3 * time.Second)})
+	hist.StoreURLTestHistory("chain-c-h2-y", &adapter.URLTestHistory{LastFail: now.Add(-2 * time.Second)})
+	// L3 (group hop, exit): one member alive, one never measured.
+	hist.StoreURLTestHistory("chain-c-h3-a", &adapter.URLTestHistory{LastOK: now.Add(-7 * time.Second), Delay: 200})
+	// chain-c-h3-b: nothing at all.
+
+	pool := []adapter.Outbound{
+		&depOutbound{failingOutbound{tag: "chain-c-h1"}, nil},
+		&depGroup{fakeGroup{
+			tag: "chain-c-h2", kind: C.TypeSelector,
+			all: []string{"chain-c-h2-x", "chain-c-h2-y"},
+			now: "chain-c-h2-x",
+		}, []string{"chain-c-h2-x", "chain-c-h2-y"}},
+		&depGroup{fakeGroup{
+			tag: "chain-c-h3", kind: C.TypeSelector,
+			all: []string{"chain-c-h3-a", "chain-c-h3-b"},
+			now: "chain-c-h3-a",
+		}, []string{"chain-c-h3-a", "chain-c-h3-b"}},
+		// Noise the projection must ignore: a member copy is not a hop, another
+		// chain's wrapper is not this chain's.
+		&depOutbound{failingOutbound{tag: "chain-c-h2-x"}, nil},
+		&depOutbound{failingOutbound{tag: "chain-other-h1"}, nil},
+	}
+
+	hops := chainHopHealthOf(pool, "c", newHealthView(hist, healthTTLFloor, now))
+	if len(hops) != 3 {
+		t.Fatalf("got %d hops, want 3: %+v", len(hops), hops)
+	}
+
+	// Ordered by index, exit on the largest.
+	for i, wantIdx := range []int{1, 2, 3} {
+		if hops[i].Index != wantIdx {
+			t.Fatalf("hops out of order: %+v", hops)
+		}
+		if got, want := hops[i].Exit, wantIdx == 3; got != want {
+			t.Errorf("hop %d Exit = %v, want %v", wantIdx, got, want)
+		}
+	}
+
+	h1, h2, h3 := hops[0], hops[1], hops[2]
+
+	// L1: one measurement, its own numbers, no selection.
+	if h1.Kind != "node" || h1.State != HealthAlive || h1.Total != 1 || h1.Alive != 1 ||
+		h1.DelayMs != 40 || h1.AgeSeconds != 5 || h1.Selected != "" {
+		t.Errorf("h1 = %+v, want an alive node hop with its own 40ms/5s and no selection", h1)
+	}
+
+	// L2: the dead hop. Both members tested, none alive => a POSITIVE dead
+	// finding on exactly this index. The selected member (x) is dead, and a
+	// dead observation carries delay 0 with the failure's age.
+	if h2.Kind != "group" || h2.State != HealthDead {
+		t.Fatalf("h2 = %+v, want the DEAD group hop — this is the answer to 'which hop died'", h2)
+	}
+	if h2.Total != 2 || h2.Tested != 2 || h2.Alive != 0 || h2.Dead != 2 || h2.Untested != 0 {
+		t.Errorf("h2 counters = %+v, want 2 tested / 2 dead", h2)
+	}
+	if h2.Selected != "x" {
+		t.Errorf("h2 Selected = %q, want the node NAME x", h2.Selected)
+	}
+	if h2.DelayMs != 0 || h2.AgeSeconds != 3 {
+		t.Errorf("h2 delay/age = %d/%d, want 0/3 (the selected member's failure observation)", h2.DelayMs, h2.AgeSeconds)
+	}
+
+	// L3: BEHIND the break. Its board still holds an alive record for member "a"
+	// (probed before L2 died), but the prober has not dialled this hop since, so
+	// publishing that record would be a verdict nobody currently holds — and the
+	// symmetric case, a stale FAILURE, would send the operator to fix a hop that
+	// is fine. It reads untested, counters collapsed into Untested, with L2 named.
+	if h3.Kind != "group" || h3.State != HealthUntested {
+		t.Fatalf("h3 = %+v, want an UNTESTED hop: the walk stopped at L2 and never dialled it", h3)
+	}
+	if h3.BlockedBy == nil {
+		t.Fatalf("h3 = %+v, want BlockedBy naming L2 — 'why is this empty' must be answered on the row", h3)
+	}
+	if h3.BlockedBy.Index != 2 || h3.BlockedBy.Tag != "chain-c-h2" {
+		t.Errorf("h3.BlockedBy = %+v, want the dead hop 2 / chain-c-h2", *h3.BlockedBy)
+	}
+	if h3.Total != 2 || h3.Tested != 0 || h3.Alive != 0 || h3.Dead != 0 || h3.Untested != 2 {
+		t.Errorf("h3 counters = %+v, want every member untested (nothing was measured at this hop)", h3)
+	}
+	if h3.DelayMs != 0 || h3.AgeSeconds != -1 {
+		t.Errorf("h3 delay/age = %d/%d, want 0/-1 — there is no observation to age", h3.DelayMs, h3.AgeSeconds)
+	}
+	// The selection is not a measurement: the wrapper really would route through
+	// "a", and that stays true whether or not anything reached this hop.
+	if h3.Selected != "a" {
+		t.Errorf("h3 Selected = %q, want a — a block hides measurements, not configuration", h3.Selected)
+	}
+	// Nothing in FRONT of the break may be touched by it.
+	if h1.BlockedBy != nil || h2.BlockedBy != nil {
+		t.Errorf("BlockedBy leaked onto a measured hop: h1=%+v h2=%+v", h1.BlockedBy, h2.BlockedBy)
+	}
+
+	// The invariants, on every hop, exactly as GroupHealth promises.
+	for _, h := range hops {
+		if h.Tested != h.Alive+h.Dead {
+			t.Errorf("hop %d: Tested = %d, want alive+dead = %d", h.Index, h.Tested, h.Alive+h.Dead)
+		}
+		if h.Alive+h.Dead+h.Untested != h.Total {
+			t.Errorf("hop %d: alive+dead+untested = %d, want total = %d",
+				h.Index, h.Alive+h.Dead+h.Untested, h.Total)
+		}
+	}
+}
+
+// A group hop whose SELECTION has no measurement shows the freshest ALIVE
+// member's numbers instead — the shown number must always be an observation
+// somebody took.
+func TestChainHopSelectionWithoutMeasurementFallsBack(t *testing.T) {
+	hist := urltest.NewHistoryStorage()
+	now := time.Now()
+	hist.StoreURLTestHistory("chain-c-h1-a", &adapter.URLTestHistory{LastOK: now.Add(-30 * time.Second), Delay: 90})
+	hist.StoreURLTestHistory("chain-c-h1-b", &adapter.URLTestHistory{LastOK: now.Add(-4 * time.Second), Delay: 150})
+	// The selection points at c, which has no observation at all.
+	pool := []adapter.Outbound{
+		&depGroup{fakeGroup{
+			tag: "chain-c-h1", kind: C.TypeSelector,
+			all: []string{"chain-c-h1-a", "chain-c-h1-b", "chain-c-h1-c"},
+			now: "chain-c-h1-c",
+		}, nil},
+	}
+	hops := chainHopHealthOf(pool, "c", newHealthView(hist, healthTTLFloor, now))
+	if len(hops) != 1 {
+		t.Fatalf("got %d hops, want 1", len(hops))
+	}
+	h := hops[0]
+	if h.Selected != "c" {
+		t.Errorf("Selected = %q, want c (the selection is reported even unmeasured)", h.Selected)
+	}
+	if h.DelayMs != 150 || h.AgeSeconds != 4 {
+		t.Errorf("delay/age = %d/%d, want the freshest ALIVE member's 150/4", h.DelayMs, h.AgeSeconds)
+	}
+	if h.State != HealthAlive || h.Alive != 2 || h.Untested != 1 {
+		t.Errorf("hop = %+v, want alive with 2 alive / 1 untested", h)
 	}
 }

shater/engine/grouptest.go

@@ -12,33 +12,46 @@ import (
 	"time"
 
 	"github.com/sagernet/sing-box/adapter"
-	"github.com/sagernet/sing-box/common/urltest"
 	C "github.com/sagernet/sing-box/constant"
 )
 
-// Exit test — "what am I actually going out through, and how fast" (F2, plan §5.E).
+// Group/chain test — "ask the observatory to refresh, then report what it
+// measured, plus the exit address" (F2, plan §5.E; reworked under the one-probe
+// rule).
 //
-// # Why this is not just another node probe
+// # This file no longer measures latency. On purpose.
 //
-// The observatory (observatory.go) answers "which nodes are alive". It cannot
-// answer the question an operator actually asks after switching a group: *through
-// which address am I leaving the country right now*. A group is an indirection —
-// a selector or urltest over many members — so the delay of the group and the
-// public address it exits from are properties of the CURRENT selection, not of
-// any node the panel can point at. A CHAIN is the same question over a longer
-// path: its exit wrapper "chain-<name>-hN" tunnels through every hop, so dialling
-// it measures the whole L1..Ln path end to end.
+// It used to: one urltest.URLTest per target, dialled right here. That was the
+// defect, not a feature. The observatory (observatory.go) probes every path the
+// routing rules actually use — per-chain member copies, egress-bound group
+// copies, chain exits — and it is the ONLY thing allowed to dial for health.
+// A second dial path from this file measured the WRONG thing: pressing "Test"
+// dialled the base groups directly from the router over the default WAN, a path
+// no rule routes through, and (worse) URLTest's DialContext touched the group,
+// arming its own 30-minute probing ticker, which kept writing those false
+// direct measurements under the members' base tags. For a node that is blocked
+// on the direct WAN and alive only behind a tunnel, that reading is not stale —
+// it is FALSE, and it poisoned selection and the panel alike.
 //
-// So one test per target (group or chain) measures two things:
+// So a manual test is now a READ with a refresh request in front of it:
 //
-//	delay_ms  — reusing urltest.URLTest, the SAME primitive the observatory uses
-//	            for a node. There is deliberately no second latency mechanism
-//	            here: the target is just an outbound, and probing it exercises
-//	            exactly the path traffic will take.
-//	exit_ip   — a real HTTP request THROUGH the target to a service that echoes
-//	            the client address back. Nothing else can produce this number: the
-//	            router cannot know its own public address, and the proxy protocol
-//	            does not report it.
+//	delay_ms / ok — the observatory's OWN measurement of the target's dial
+//	                path. TestGroups rewinds the observatory (RefreshObservatory)
+//	                so the numbers are fresh — taken AFTER the button press —
+//	                then each target waits for an observation newer than the
+//	                run's start instant and reports it verbatim. tested_unix is
+//	                the instant that observation was taken, not "now".
+//	exit_ip       — a real HTTP request THROUGH the target to a service that
+//	                echoes the client address back. This is the ONE connection
+//	                this file still opens, and it stays because no probe can
+//	                answer it: the router cannot know its own public address,
+//	                and the proxy protocol does not report it. It is NOT a
+//	                second health probe — it travels the target's own routed
+//	                path (the same outbound object the rules dial), and it is
+//	                only ever issued for a target that (a) the observatory's
+//	                used-set covers and (b) just resolved ALIVE. A target
+//	                outside the rules, or one whose path is down, gets an empty
+//	                exit_ip — never a connection.
 //
 // # The direct-egress trap
 //
@@ -51,16 +64,15 @@ import (
 // exit_ip instead of somebody else's number.
 
 const (
-	// groupTestDelayTimeout bounds the latency probe of one group.
-	groupTestDelayTimeout = 5 * time.Second
 	// groupTestExitTimeout bounds the whole exit-address lookup for one group
 	// (connect through the tunnel + TLS + response). Short on purpose: this runs
 	// while a human waits on a panel button, and a slow answer is worth less than a
 	// prompt "could not determine".
 	groupTestExitTimeout = 6 * time.Second
-	// groupTestConcurrency bounds how many groups are tested in parallel. Small:
-	// every one of these opens a real tunnelled connection, and a router with a
-	// handful of groups is the normal case.
+	// groupTestConcurrency bounds how many EXIT-ADDRESS lookups run in parallel.
+	// Small: each one opens a real tunnelled connection, and a router with a
+	// handful of groups is the normal case. The board polling itself is not
+	// bounded by this — it is sleep-and-read, no I/O.
 	groupTestConcurrency = 4
 	// exitBodyLimit caps what is read from the exit-address service. These responses
 	// are a few hundred bytes; anything larger is a hijacked/captive-portal answer
@@ -68,19 +80,66 @@ const (
 	exitBodyLimit = 4 << 10
 )
 
+// groupTestWaitDeadline / groupTestPollEvery pace the wait for the observatory:
+// each covered target polls the health board once a second until its measured
+// tag carries an observation newer than the run's start, giving up after the
+// deadline. 120s covers a forced pass of a large plan (batches chain
+// back-to-back during a forced pass, see observatoryTickOnce) with room for the
+// probe timeouts of a mostly-dead population. Package variables, not constants,
+// for exactly one reason: the timeout tests must not take two minutes.
+var (
+	groupTestWaitDeadline = 120 * time.Second
+	groupTestPollEvery    = time.Second
+)
+
+// The fixed result texts for the targets that are never (or not yet) measured.
+// They are contract, not decoration — the panel shows them verbatim.
+const (
+	// groupTestErrNotRouted: the target is outside the observatory's used-set,
+	// so no rule routes through it and nothing measures it. Dialling it anyway
+	// would recreate the false direct measurement this rework removed.
+	groupTestErrNotRouted = "not routed by any enabled rule, so nothing measures it — the observatory only probes paths the rules use"
+	// groupTestErrNotReached: the deadline passed without a fresh observation.
+	groupTestErrNotReached = "the observatory has not reached this target yet — it refreshes on the global probe interval"
+	// groupTestErrProbingOff: the observatory is disabled (the GroupHealth
+	// master switch), so a refresh request has nothing to wake and waiting for
+	// the deadline would just delay the same answer by two minutes.
+	groupTestErrProbingOff = "background probing is disabled, so there is nothing to measure this target with"
+	// groupTestErrPathDead: the fresh observation exists and it is a FAILURE —
+	// the observatory probed the target's path after the button press and the
+	// path did not answer. An honest negative, not a missing measurement.
+	groupTestErrPathDead = "the observatory's probe through this path failed"
+	// groupTestErrChainBlockedFmt: a CHAIN whose exit was never dialled because
+	// an earlier hop was probed and did not answer. The prober walks a chain in
+	// order and stops at the first dead hop, so there is no end-to-end
+	// measurement to wait for and there never will be while that hop is down.
+	// Reported at once, naming the hop, instead of spending the full deadline to
+	// answer "not reached yet" about a path that is known to be broken — and
+	// naming it is the whole value: the operator's next action is at that hop.
+	groupTestErrChainBlockedFmt = "hop %d of this chain was probed and did not answer, so nothing reaches the exit through it — fix that hop first"
+)
+
 // GroupTestResult is one target's test outcome — a group's or a chain's (Group
 // then carries the chain's model name). The JSON tags are the panel contract —
-// see the shater API docs for /api/groups/test.
+// see the shater API docs for /api/groups/test. The field names and types are
+// FROZEN; what changed in the rework is where the numbers come from.
+//
+// DelayMs and OK are a READ of the observatory's measurement of the target's
+// dial path — not a fresh dial performed by this file. OK is true exactly when
+// the health board's state for the measured tag is alive; DelayMs is that
+// observation's RTT; TestedUnix is the instant the OBSERVATION was taken (now
+// minus its age), so a result honestly says how old its number is instead of
+// stamping the poll time over it.
 //
 // Selected is the group's current pick (OutboundGroup.Now()); for a chain it is
 // the node NAME the chain's last group hop currently selects, "" when the chain
 // has no group hop (a fixed path selects nothing).
 //
-// OK reports whether the LATENCY measurement succeeded, which is the test's primary
-// question. A failed exit-address lookup deliberately does NOT clear it: knowing the
-// target is up and fast is useful on its own, and a probe service being unreachable
-// says nothing about the tunnel. In that case OK stays true and ExitIP is empty —
-// "not determined", never a guess and never somebody else's address.
+// A failed exit-address lookup deliberately does NOT clear OK: knowing the
+// target is up and fast is useful on its own, and a probe service being
+// unreachable says nothing about the tunnel. In that case OK stays true and
+// ExitIP is empty — "not determined", never a guess and never somebody else's
+// address.
 type GroupTestResult struct {
 	Group       string `json:"group"`
 	Selected    string `json:"selected"`
@@ -117,6 +176,13 @@ type groupTestTarget struct {
 	name string
 	ob   adapter.Outbound
 	sel  func() string
+	// isChain marks a CHAIN target. A chain is the one target whose measurement
+	// can be legitimately absent while the target is known to be broken: the
+	// prober walks a chain in order and stops at the first dead hop, so a chain
+	// whose hop 2 died never has its exit dialled at all. Without this flag a run
+	// would sit out its whole deadline and then report "not reached yet" about a
+	// path it knows is down — see testOneTarget.
+	isChain bool
 }
 
 // chainTargetsFrom discovers each materialised chain in the running
@@ -161,7 +227,7 @@ func chainTargetsFrom(pool []adapter.Outbound) []groupTestTarget {
 		if !ok {
 			continue
 		}
-		t := groupTestTarget{name: name, ob: ob}
+		t := groupTestTarget{name: name, ob: ob, isChain: true}
 		if hop := chainLastGroupHop(byTag, name); hop != nil {
 			t.sel = func() string { return chainMemberName(hop.Now(), name) }
 		}
@@ -175,18 +241,38 @@ func chainTargetsFrom(pool []adapter.Outbound) []groupTestTarget {
 // "chain-<name>-h<digits>". Member copies ("…-h<i>-<member>") and non-chain tags
 // parse false.
 func parseChainExitTag(tag string) (string, bool) {
+	name, _, ok := parseChainHopTag(tag)
+	return name, ok
+}
+
+// parseChainHopTag is parseChainExitTag plus the number: it recovers the chain
+// NAME and the 1-based HOP INDEX from a hop wrapper tag "chain-<name>-h<digits>"
+// (generate/chain.go buildHopWrapper). Member copies ("…-h<i>-<member>") and
+// non-chain tags parse false.
+//
+// The index is what lets the probe plan ORDER a chain's measurements. A chain is
+// a series path — hop i is dialled through hops 1..i-1 — so the difference
+// between "this hop failed" and "the hop in front of it failed" is the whole
+// diagnosis, and it cannot be recovered from an unordered set of tags.
+//
+// The split takes the LAST "-h<digits>", so a chain literally named "a-h2" is
+// read as chain "a-h2" hop 1 rather than chain "a" hop 2 — the same documented
+// reserved-namespace edge case parseGroupCopyTag accepts, pinned by
+// TestParseChainExitTag.
+func parseChainHopTag(tag string) (name string, hop int, ok bool) {
 	rest, ok := strings.CutPrefix(tag, "chain-")
 	if !ok {
-		return "", false
+		return "", 0, false
 	}
 	i := strings.LastIndex(rest, "-h")
 	if i <= 0 {
-		return "", false
+		return "", 0, false
 	}
-	if _, ok := parseAllDigits(rest[i+2:]); !ok {
-		return "", false
+	hop, ok = parseAllDigits(rest[i+2:])
+	if !ok {
+		return "", 0, false
 	}
-	return rest[:i], true
+	return rest[:i], hop, true
 }
 
 // chainLastGroupHop finds the chain's LAST group hop — the wrapper selector
@@ -259,19 +345,30 @@ func parseAllDigits(s string) (int, bool) {
 // and chains (empty/nil = every group and every chain in the running box),
 // returning started=false when a run is already in flight.
 //
-// It is a SINGLETON: a second request while a run is in flight is refused rather
-// than queued or run in parallel, because these runs open real tunnelled
-// connections and a panel that double-fires a button must not multiply the load
-// on the uplink. The observatory checks the same guard and skips its tick while
-// a run is in flight (observatory.go), so a manual test never competes with
-// background probing for the uplink.
+// It does NOT probe. It records the run's start instant, asks the observatory
+// for an out-of-turn full pass (RefreshObservatory), and then each target waits
+// for the health board to carry an observation NEWER than that instant on the
+// tag the observatory actually measures for it — see testOneTarget. The only
+// connection a run may still open is the exit-address lookup, and only for a
+// target that resolved alive on a rule-routed path.
 //
-// probeURL is the latency-probe URL; "" falls back to urltest's gstatic default.
+// It is a SINGLETON: a second request while a run is in flight is refused
+// rather than queued, because two overlapping runs would each rewind the
+// observatory's cursor and neither pass would ever complete — and the panel's
+// progress contract assumes one run's counters at a time anyway.
 //
-// Apply-swap safety: the target outbounds are snapshotted up front, so a config swap
-// mid-run cannot change what is being tested. A target torn down mid-run simply fails
-// its probe and is reported not-ok.
+// probeURL is accepted and IGNORED. The probe URL is a global observatory
+// setting now (ObservatoryConfig.ProbeURL, set at apply time); a per-run URL
+// would mean this run measures something different from what the board holds,
+// which is exactly the two-instruments split the rework removed. The parameter
+// stays so the callers (shater/apply, shater/panel) keep compiling and the
+// control-plane API shape does not churn.
+//
+// Apply-swap safety: the target outbounds are snapshotted up front, so a config
+// swap mid-run cannot change what is being tested. A target torn down mid-run
+// simply never receives a fresh observation and resolves on the deadline.
 func (e *Engine) TestGroups(names []string, probeURL string) (started bool) {
+	_ = probeURL // ignored — see the doc comment above
 	if !e.groupTestRunning.CompareAndSwap(false, true) {
 		return false
 	}
@@ -285,6 +382,13 @@ func (e *Engine) TestGroups(names []string, probeURL string) (started bool) {
 	// GroupTestStatus for why the scope is a set of names.
 	e.setGroupTestScope(scopeOf(targets, missing))
 
+	// The freshness watermark: only an observation taken AFTER this instant may
+	// answer this run. Recorded BEFORE the refresh request so a probe that lands
+	// between the two can never be missed, only double-counted as fresh — the
+	// harmless direction.
+	t0 := time.Now()
+	e.RefreshObservatory()
+
 	go func() {
 		defer e.groupTestRunning.Store(false)
 
@@ -303,15 +407,22 @@ func (e *Engine) TestGroups(names []string, probeURL string) (started bool) {
 		e.setGroupTestResults(results)
 		e.groupTestDone.Add(int64(len(missing)))
 
+		// The used-set and the enabled bit are snapshotted once for the whole
+		// run: they only change on an apply, and a run that straddles an apply
+		// is already best-effort (see the swap-safety note above).
+		used := e.observatoryUsed()
+		obsEnabled, _, _ := e.ObservatoryStatus()
+
+		// One goroutine per target: they spend their life sleeping on the board
+		// poll, so there is nothing to bound — the semaphore below bounds the
+		// exit-address lookups, the only real connections left in a run.
 		sem := make(chan struct{}, groupTestConcurrency)
 		var wg sync.WaitGroup
 		for i, tgt := range targets {
 			wg.Add(1)
-			sem <- struct{}{}
 			go func(i int, tgt groupTestTarget) {
 				defer wg.Done()
-				defer func() { <-sem }()
-				res := e.testOneTarget(tgt, probeURL)
+				res := e.testOneTarget(tgt, used, obsEnabled, t0, sem)
 				e.storeGroupTestResult(i, res)
 				e.groupTestDone.Add(1)
 			}(i, tgt)
@@ -393,29 +504,185 @@ func (e *Engine) groupTargets(names []string) (targets []groupTestTarget, missin
 	return targets, missing
 }
 
-// testOneTarget measures one target: what it currently selects, the latency
-// through it, and the public address it exits from. For a chain the dialled
-// outbound is the exit wrapper, so the delay and the exit address are end-to-end
-// properties of the whole L1..Ln path.
-func (e *Engine) testOneTarget(t groupTestTarget, probeURL string) GroupTestResult {
+// testOneTarget resolves one target WITHOUT probing it: it decides whether the
+// observatory measures this target at all, and if so waits for a fresh
+// observation and reports it. The three ways out, in order:
+//
+//  1. the used-set does not cover the target — no enabled rule routes through
+//     it, so nothing measures it and nothing SHOULD: resolved immediately with
+//     groupTestErrNotRouted, never dialled, empty exit address. A nil used-set
+//     means "unknown" (observatory not yet configured) and is treated as
+//     covered — no refusal is better than a wrong one;
+//  2. the observatory is disabled — the refresh request went nowhere, so the
+//     wait below could only ever end on its deadline: resolved immediately
+//     with groupTestErrProbingOff instead of stalling the panel for two
+//     minutes to say the same thing;
+//  3. covered and enabled — poll the health board once a second until the
+//     MEASURED TAG carries an observation newer than since, then report that
+//     observation verbatim (readFreshObservation). On the deadline:
+//     groupTestErrNotReached.
+//
+// The exit-address lookup runs ONLY on the alive path of (3) — a rule-routed
+// target whose path just answered a probe — and through sem, so a run never
+// opens more than groupTestConcurrency tunnelled connections at once.
+func (e *Engine) testOneTarget(t groupTestTarget, used map[string]bool, obsEnabled bool, since time.Time, sem chan struct{}) GroupTestResult {
 	res := GroupTestResult{Group: t.name, TestedUnix: time.Now().Unix()}
 	if t.sel != nil {
 		res.Selected = t.sel()
 	}
 
-	ctx, cancel := context.WithTimeout(context.Background(), groupTestDelayTimeout)
-	delay, err := urltest.URLTest(ctx, probeURL, t.ob)
-	cancel()
-	if err != nil {
-		res.Error = err.Error()
+	if used != nil && !used[t.ob.Tag()] {
+		res.Error = groupTestErrNotRouted
+		return res
+	}
+	if !obsEnabled {
+		res.Error = groupTestErrProbingOff
 		return res
 	}
-	res.OK = true
-	res.DelayMs = int(delay)
 
-	// The exit address is best-effort by design: see GroupTestResult.OK.
-	res.ExitIP, res.ExitCountry = e.exitAddress(t.ob)
-	return res
+	deadline := time.Now().Add(groupTestWaitDeadline)
+	for {
+		// Asked BEFORE the board read, and only for a chain. The exit of a blocked
+		// chain does carry a fresh dead verdict now — the observatory derives it
+		// from the broken hop (markChainExitDead) so selection cannot be tempted
+		// down a path that provably does not work — but "the probe through this
+		// path failed" would be the wrong sentence to show a person: no probe of
+		// the exit ran, and the actionable fact is WHICH hop stopped it. Same
+		// verdict, better answer.
+		if idx, ok := e.blockedChainHop(t, since); ok {
+			res.OK = false
+			res.Error = fmt.Sprintf(groupTestErrChainBlockedFmt, idx)
+			return res
+		}
+		if e.readFreshObservation(&res, t, since) {
+			if res.OK {
+				// The exit address is best-effort by design: see GroupTestResult.
+				sem <- struct{}{}
+				res.ExitIP, res.ExitCountry = e.exitAddress(t.ob)
+				<-sem
+			}
+			return res
+		}
+		if !time.Now().Before(deadline) {
+			res.Error = groupTestErrNotReached
+			return res
+		}
+		time.Sleep(groupTestPollEvery)
+	}
+}
+
+// blockedChainHop reports the hop that stopped this CHAIN target's ordered walk
+// before its exit, and only when the finding is FRESH enough to answer this run.
+//
+// Both halves matter. The projection (chainHopHealthOf) already computes the
+// break exactly once, and reading it here rather than re-deriving it keeps the
+// run and the Targets card from ever naming different hops. And the freshness
+// check is the same watermark readFreshObservation uses: a run rewinds the
+// observatory and then reports what it measures AFTERWARDS, so a break left over
+// from before the button press must not short-circuit the wait — the forced pass
+// may be about to find that hop alive again.
+//
+// Non-chain targets, unmaterialised chains and chains with no break all report
+// false, and the caller goes on waiting exactly as before.
+func (e *Engine) blockedChainHop(t groupTestTarget, since time.Time) (int, bool) {
+	if !t.isChain {
+		return 0, false
+	}
+	return blockingHopOf(chainHopHealthOf(e.runningPool(), t.name, e.HealthView()), time.Now(), since)
+}
+
+// blockingHopOf is the decision itself, split out so it is testable without a
+// box: given one chain's hop readout, the hop whose failure kept the EXIT from
+// being dialled, and only when that failure was observed at or after since.
+//
+// The exit's own BlockedBy is what is consulted, not "any dead hop": a chain
+// whose exit was itself probed and failed has a real end-to-end measurement, and
+// that measurement is the honest answer (groupTestErrPathDead). Only when the
+// exit was never reached is there nothing to wait for.
+func blockingHopOf(hops []ChainHopHealth, now, since time.Time) (int, bool) {
+	if len(hops) == 0 {
+		return 0, false
+	}
+	blocker := hops[len(hops)-1].BlockedBy
+	if blocker == nil {
+		return 0, false
+	}
+	for _, h := range hops {
+		if h.Index != blocker.Index {
+			continue
+		}
+		if h.AgeSeconds < 0 {
+			return 0, false
+		}
+		if now.Add(-time.Duration(h.AgeSeconds) * time.Second).Before(since) {
+			return 0, false // a break observed before this run started; keep waiting
+		}
+		return h.Index, true
+	}
+	return 0, false
+}
+
+// measuredTagOf is the tag the observatory actually probes for this target's
+// dial path — the tag whose board entry answers "how is this target doing":
+//
+//   - a GROUP target dials whatever it currently selects, so the group's health
+//     IS its selection's health: OutboundGroup.Now(). For an egress-bound group
+//     that is a per-group copy tag, which is exactly what the plan probes;
+//   - a CHAIN whose exit wrapper is a PLAIN outbound is probed end-to-end under
+//     that wrapper tag (probeplan.go: a chain exit is its own measurement);
+//   - a CHAIN whose exit wrapper is a GROUP (the last hop is a group) has its
+//     member copies probed instead of the wrapper, so the wrapper's Now() — the
+//     member copy the chain currently dials through — is the measured tag. The
+//     wrapper here IS the last group hop, so this is chainLastGroupHop's Now()
+//     without a second lookup;
+//   - fallback: the target's own tag, for a group that has not selected yet
+//     (cold selector mid-swap). Its board entry is almost certainly empty, and
+//     the caller then honestly reports "not reached" rather than inventing one.
+func measuredTagOf(t groupTestTarget) string {
+	if g, ok := t.ob.(adapter.OutboundGroup); ok {
+		if now := g.Now(); now != "" {
+			return now
+		}
+	}
+	return t.ob.Tag()
+}
+
+// readFreshObservation reads the board once: if the target's measured tag holds
+// an observation taken at or after since, it is written into res (state, delay,
+// the observation's own timestamp, and the current selection so Selected and
+// the measurement describe the same pick) and true is returned. Otherwise res
+// is left for the next poll.
+//
+// Precision note: the board reports ages in whole seconds, so "at or after
+// since" is accurate to one second — an observation taken up to a second
+// BEFORE the refresh can slip through as fresh. That is the acceptable
+// direction: it is still a real measurement of the same path, at most a second
+// older than requested; the strict direction (discarding genuinely fresh
+// observations) would make every run one probe interval slower for nothing.
+func (e *Engine) readFreshObservation(res *GroupTestResult, t groupTestTarget, since time.Time) bool {
+	// Re-read the selection at every poll: a forced observatory pass is exactly
+	// the kind of event that makes a urltest group switch members, and the
+	// measurement below is taken against the CURRENT pick.
+	if t.sel != nil {
+		res.Selected = t.sel()
+	}
+	tag := measuredTagOf(t)
+	now := time.Now()
+	state, delayMs, age := e.HealthView().State(tag)
+	if age < 0 {
+		return false // no observation at all (untested)
+	}
+	observedAt := now.Add(-time.Duration(age) * time.Second)
+	if observedAt.Before(since) {
+		return false // an old reading; the refresh has not reached this tag yet
+	}
+	res.OK = state == HealthAlive
+	res.DelayMs = delayMs
+	res.TestedUnix = observedAt.Unix()
+	if !res.OK {
+		res.Error = groupTestErrPathDead
+	}
+	return true
 }
 
 // exitProbe is one exit-address service: a URL and the parser for its body.

shater/engine/grouptest_test.go

@@ -3,6 +3,7 @@ package engine
 import (
 	"context"
 	"crypto/tls"
+	"fmt"
 	"net"
 	"net/http"
 	"net/http/httptest"
@@ -143,10 +144,10 @@ func TestChainMemberName(t *testing.T) {
 	}
 }
 
-// dialableOutbound routes every dial to a fixed local address — a stand-in for a
-// chain exit whose whole path is up. urltest.URLTest dials the probe URL's host
-// through the outbound, so pointing every dial at a local HTTP server makes the
-// latency probe succeed without any network.
+// dialableOutbound routes every dial to a fixed local address — the sink the
+// exit-address lookup lands in during tests. Since the rework nothing else in
+// this file dials at all; the local server refuses to be an exit-address
+// service (wrong status, no TLS), so the lookup honestly comes back empty.
 type dialableOutbound struct {
 	failingOutbound
 	addr string
@@ -158,20 +159,42 @@ func (d *dialableOutbound) DialContext(ctx context.Context, network string, _ M.
 	return (&net.Dialer{}).DialContext(ctx, network, d.addr)
 }
 
-// TestChainExitTestMeasuresEndToEnd is the §6-S4 acceptance path for chains: the
-// exit test dials the chain's EXIT TAG, returns a measured delay, carries the
-// chain's model name (not the wrapper tag) as the result's Group, and reports the
-// last group hop's pick as Selected. The exit address is measured through the
-// same outbound (unreachable from a test => empty, never a guess).
-func TestChainExitTestMeasuresEndToEnd(t *testing.T) {
-	probe := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+// countingOutbound counts every DialContext/ListenPacket. It is the tripwire of
+// the rework: a target the observatory does not cover must NEVER be dialled,
+// and the counter is the proof.
+type countingOutbound struct {
+	failingOutbound
+	dials int
+}
+
+func (c *countingOutbound) DialContext(ctx context.Context, network string, dst M.Socksaddr) (net.Conn, error) {
+	c.dials++
+	return nil, fmt.Errorf("dial refused (test)")
+}
+
+func (c *countingOutbound) ListenPacket(ctx context.Context, dst M.Socksaddr) (net.PacketConn, error) {
+	c.dials++
+	return nil, fmt.Errorf("dial refused (test)")
+}
+
+// groupTestSem is a fresh exit-lookup semaphore for direct testOneTarget calls.
+func groupTestSem() chan struct{} { return make(chan struct{}, groupTestConcurrency) }
+
+// TestChainTestReportsObservatoryMeasurement is the §6-S4 acceptance path for
+// chains under the one-probe rule: the manual test does NOT dial the exit — it
+// reads the observatory's board entry for the exit tag, reports its delay and
+// ITS timestamp, carries the chain's model name as Group and the last group
+// hop's pick as Selected. The exit-address lookup still travels the exit
+// outbound (unreachable from a test => empty, never a guess).
+func TestChainTestReportsObservatoryMeasurement(t *testing.T) {
+	sink := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNoContent)
 	}))
-	defer probe.Close()
+	defer sink.Close()
 
 	exit := &dialableOutbound{
 		failingOutbound: failingOutbound{tag: "chain-x-h2"},
-		addr:            probe.Listener.Addr().String(),
+		addr:            sink.Listener.Addr().String(),
 		deps:            []string{"chain-x-h1"},
 	}
 	pool := []adapter.Outbound{
@@ -187,14 +210,31 @@ func TestChainExitTestMeasuresEndToEnd(t *testing.T) {
 	if len(targets) != 1 || targets[0].ob.Tag() != "chain-x-h2" {
 		t.Fatalf("targets = %+v, want the chain dialled via its exit tag", targets)
 	}
+	if got := measuredTagOf(targets[0]); got != "chain-x-h2" {
+		t.Fatalf("measuredTagOf = %q, want the plain exit wrapper itself", got)
+	}
 
 	e := New()
-	res := e.testOneTarget(targets[0], probe.URL)
+	// The observatory measured the exit 10 seconds ago, AFTER the run's start
+	// instant below: that observation — delay and timestamp both — is the answer.
+	observedAt := time.Now().Add(-10 * time.Second)
+	e.URLTestHistory().StoreURLTestHistory("chain-x-h2", &adapter.URLTestHistory{LastOK: observedAt, Delay: 77})
+	since := time.Now().Add(-time.Minute)
+
+	res := e.testOneTarget(targets[0], map[string]bool{"chain-x-h2": true}, true, since, groupTestSem())
 	if res.Group != "x" {
 		t.Errorf("Group = %q, want the chain's model name x", res.Group)
 	}
 	if !res.OK || res.Error != "" {
-		t.Fatalf("result = %+v, want a successful measurement through the exit tag (a local roundtrip may legitimately read 0ms)", res)
+		t.Fatalf("result = %+v, want the board's alive observation reported", res)
+	}
+	if res.DelayMs != 77 {
+		t.Errorf("DelayMs = %d, want the observatory's 77 — this file measures nothing itself", res.DelayMs)
+	}
+	// tested_unix is the OBSERVATION's instant (whole-second precision), never
+	// the poll's.
+	if got, want := res.TestedUnix, observedAt.Unix(); got < want-1 || got > want+1 {
+		t.Errorf("TestedUnix = %d, want the observation's instant ~%d", got, want)
 	}
 	if res.Selected != "relay" {
 		t.Errorf("Selected = %q, want the last group hop's pick relay", res.Selected)
@@ -204,6 +244,93 @@ func TestChainExitTestMeasuresEndToEnd(t *testing.T) {
 	}
 }
 
+// TestTestOneTargetUnroutedNeverDialled is the rework's core promise: a target
+// outside the observatory's used-set is resolved immediately with the
+// documented explanation and ZERO dials — no latency probe, no exit-address
+// lookup, nothing. Dialling it would manufacture exactly the false direct
+// measurement the rework removed.
+func TestTestOneTargetUnroutedNeverDialled(t *testing.T) {
+	e := New()
+	ob := &countingOutbound{failingOutbound: failingOutbound{tag: "idle"}}
+	tgt := groupTestTarget{name: "idle", ob: ob}
+
+	res := e.testOneTarget(tgt, map[string]bool{"something-else": true}, true, time.Now(), groupTestSem())
+	if ob.dials != 0 {
+		t.Fatalf("an unrouted target was dialled %d time(s); it must never be", ob.dials)
+	}
+	if res.OK {
+		t.Fatal("an unrouted target reported ok=true")
+	}
+	if res.Error != groupTestErrNotRouted {
+		t.Fatalf("Error = %q, want the not-routed explanation", res.Error)
+	}
+	if res.ExitIP != "" || res.ExitCountry != "" {
+		t.Fatalf("an unrouted target must carry no exit address: %+v", res)
+	}
+}
+
+// A disabled observatory resolves covered targets immediately too: the refresh
+// request went nowhere, so waiting out the deadline would only delay the same
+// honest answer — and still, nothing is dialled.
+func TestTestOneTargetProbingOffNeverDialled(t *testing.T) {
+	e := New()
+	ob := &countingOutbound{failingOutbound: failingOutbound{tag: "auto"}}
+	tgt := groupTestTarget{name: "auto", ob: ob}
+
+	res := e.testOneTarget(tgt, nil, false, time.Now(), groupTestSem())
+	if ob.dials != 0 {
+		t.Fatalf("target dialled %d time(s) with probing off; want 0", ob.dials)
+	}
+	if res.OK || res.Error != groupTestErrProbingOff {
+		t.Fatalf("result = %+v, want ok=false with the probing-off explanation", res)
+	}
+}
+
+// The deadline path: a covered target whose measured tag never receives a fresh
+// observation resolves with the not-reached explanation — and, again, without a
+// single dial of its own.
+func TestTestOneTargetDeadlineWithoutObservation(t *testing.T) {
+	// Shrink the wait so the test answers in milliseconds; restore afterwards.
+	oldDeadline, oldPoll := groupTestWaitDeadline, groupTestPollEvery
+	groupTestWaitDeadline, groupTestPollEvery = 30*time.Millisecond, 5*time.Millisecond
+	defer func() { groupTestWaitDeadline, groupTestPollEvery = oldDeadline, oldPoll }()
+
+	e := New()
+	ob := &countingOutbound{failingOutbound: failingOutbound{tag: "auto"}}
+	tgt := groupTestTarget{name: "auto", ob: ob}
+
+	res := e.testOneTarget(tgt, map[string]bool{"auto": true}, true, time.Now(), groupTestSem())
+	if ob.dials != 0 {
+		t.Fatalf("target dialled %d time(s) while waiting on the board; want 0", ob.dials)
+	}
+	if res.OK || res.Error != groupTestErrNotReached {
+		t.Fatalf("result = %+v, want ok=false with the not-reached explanation", res)
+	}
+}
+
+// A fresh DEAD observation is an answer, not a timeout: ok=false with the
+// path-dead explanation, delay 0, and no exit-address connection for a path
+// that just failed its probe.
+func TestTestOneTargetReportsFreshDeath(t *testing.T) {
+	e := New()
+	ob := &countingOutbound{failingOutbound: failingOutbound{tag: "auto"}}
+	tgt := groupTestTarget{name: "auto", ob: ob}
+
+	since := time.Now().Add(-time.Minute)
+	e.URLTestHistory().MarkFailed("auto")
+
+	res := e.testOneTarget(tgt, map[string]bool{"auto": true}, true, since, groupTestSem())
+	if ob.dials != 0 {
+		t.Fatalf("a dead target was dialled %d time(s); the exit lookup is for alive paths only", ob.dials)
+	}
+	if res.OK || res.Error != groupTestErrPathDead {
+		t.Fatalf("result = %+v, want ok=false with the path-dead explanation", res)
+	}
+	if res.DelayMs != 0 || res.ExitIP != "" {
+		t.Fatalf("a dead path must carry no delay and no exit address: %+v", res)
+	}
+}
+
 // TestGroupTestSingleton is the "no parallel runs" invariant: while a run holds the
 // guard, a second TestGroups must be refused rather than starting a concurrent run
 // (each of these opens real tunnelled connections).
@@ -460,3 +587,57 @@ func TestGroupTestScopeDedupedAndSorted(t *testing.T) {
 		t.Fatalf("scope = %v, want [alpha zeta]", scope)
 	}
 }
+
+// A manual run against a chain whose walk is blocked must say so, at once and by
+// hop number. The prober stops at the first dead hop, so such a chain's exit is
+// never dialled and no end-to-end observation is ever coming: waiting for one
+// would burn the full 120s deadline and then answer "the observatory has not
+// reached this target yet" — which reads like a timing artefact about a chain
+// that is, in fact, down and whose broken hop is already known.
+//
+// The freshness rule is the same one readFreshObservation uses: a run rewinds
+// the observatory and reports what it measures AFTERWARDS, so a break left over
+// from before the button press must not short-circuit the wait — the forced pass
+// may be about to find that hop alive again.
+func TestBlockingHopOfChainWalk(t *testing.T) {
+	since := time.Now()
+	// A 3-hop readout as the projection builds it: hop 2 dead, hop 3 not reached.
+	blocked := func(ageOfBreak int64) []ChainHopHealth {
+		blocker := &ChainHopBlock{Index: 2, Tag: "chain-c-h2"}
+		return []ChainHopHealth{
+			{Index: 1, Tag: "chain-c-h1", State: HealthAlive, AgeSeconds: 1},
+			{Index: 2, Tag: "chain-c-h2", State: HealthDead, AgeSeconds: ageOfBreak},
+			{Index: 3, Tag: "chain-c-h3", State: HealthUntested, AgeSeconds: -1, Exit: true, BlockedBy: blocker},
+		}
+	}
+
+	// Measured after the run started: answer now, naming hop 2.
+	if idx, ok := blockingHopOf(blocked(0), since.Add(time.Second), since); !ok || idx != 2 {
+		t.Errorf("fresh break = (%d,%v), want (2,true) — the run must name the hop instead of timing out", idx, ok)
+	}
+
+	// Measured BEFORE the run started: keep waiting. The forced pass has not
+	// re-probed that hop yet, and it may be about to answer.
+	if idx, ok := blockingHopOf(blocked(30), since.Add(time.Second), since); ok {
+		t.Errorf("stale break reported as this run's finding (hop %d); a run answers with what IT measured", idx)
+	}
+
+	// A chain whose exit WAS reached has a real end-to-end reading; the ordinary
+	// path reports it (alive, or groupTestErrPathDead). Nothing to short-circuit.
+	reached := []ChainHopHealth{
+		{Index: 1, Tag: "chain-c-h1", State: HealthAlive, AgeSeconds: 1},
+		{Index: 2, Tag: "chain-c-h2", State: HealthDead, AgeSeconds: 0, Exit: true},
+	}
+	if _, ok := blockingHopOf(reached, since.Add(time.Second), since); ok {
+		t.Error("a dead EXIT was reported as a block; its own probe is the answer")
+	}
+	if _, ok := blockingHopOf(nil, since, since); ok {
+		t.Error("an unmaterialised chain reported a block")
+	}
+
+	// A non-chain target never consults any of this.
+	e := New()
+	if _, ok := e.blockedChainHop(groupTestTarget{name: "auto"}, since); ok {
+		t.Error("a GROUP target was treated as a blocked chain")
+	}
+}

shater/engine/observatory.go

@@ -2,6 +2,7 @@ package engine
 
 import (
 	"context"
+	"sort"
 	"sync"
 	"time"
 
@@ -23,12 +24,40 @@ import (
 // MarkFailed. The strategies read the same board, so a death found here makes the
 // node unselectable immediately — no private overlay, no panel-only truth.
 //
-// It never replaces a group's own probing. An ACTIVE urltest group is its own
-// fast failure detector (failover switches on its 30s probe tick), and the
-// freshness gate below skips any tag whose newest observation is younger than the
-// global probe interval — which is precisely the set of tags an active group is
-// already keeping current. The observatory's budget lands on what nobody else
-// probes: idle groups' members, selector candidates, chain exits.
+// # ONE DIALLER PER TARGET
+//
+// It does not probe what a urltest group already probes — not "less often",
+// not at all. A urltest group dials its own members on its own ticker
+// (protocol/group/urltest.go testNodes), and for a chain's group hop that
+// checker is strictly the better instrument: each member copy carries the
+// previous hop as its Detour, so the group's probe travels the chain prefix by
+// construction, which is the path the traffic takes. Two probers on one target
+// is one measurement too many however carefully they take turns, so the plan
+// marks those measurements SelfChecked (probeplan.go) and this loop skips them.
+//
+// What is left is what no group covers, and it is the observatory's whole job:
+//
+//   - targets with no group behind them — a chain's NODE hop wrapper, the
+//     AmneziaWG endpoint at L1, a chain exit that is a plain outbound. Nothing
+//     else in the process will ever dial these;
+//   - members of a SELECTOR group, which has no checker at all
+//     (protocol/group/selector.go), and of a urltest group whose self-check was
+//     stood down;
+//   - egress-bound group copies, whose measurement carries the base-tag alias
+//     that feeds the per-node stats and that no group checker writes;
+//   - the GATE — who is allowed to dial at all (the used-set drives SelfCheck,
+//     the ordered walk drives ProbeAllowed) — and the reading of the board back
+//     out for the panel.
+//
+// The freshness gate below still skips any tag whose newest observation is
+// younger than the global probe interval, which now matters for the remaining
+// population rather than as the mechanism that kept two probers apart.
+//
+// The cost of the split: a used urltest group that carries no traffic runs its
+// warm-up sweep at box start and then, once its idle timeout expires, stops —
+// and the observatory no longer fills in behind it, so its members age out to
+// "untested". That is honest (nothing measured them) rather than wrong, and it
+// is the price of one dialler per target.
 //
 // # Schedule and cost
 //
@@ -41,6 +70,21 @@ import (
 // first pass starts IMMEDIATELY after an apply (cold boot: used paths validated
 // in seconds).
 //
+// # A chain is walked in order, and the walk stops at the first dead hop
+//
+// Most of the plan is independent measurements and is fired concurrently. A
+// CHAIN is not: hop i is dialled through hops 1..i-1, so a probe of hop 3 across
+// a hop 2 with no live member measures hop 2's failure and learns nothing about
+// hop 3. Each chain's jobs therefore run hop by hop (probeChainOrdered), and the
+// walk returns at the first hop the board reads dead — every hop behind it is
+// left undialled for that pass and reported untested with the blocker named,
+// which is both the honest answer and the cheap one.
+//
+// Nothing about a block is remembered. The gate is a fresh read of the health
+// board at every hop of every batch, and each cycle restarts at the top of the
+// plan, so the blocking hop is always re-probed and a recovery opens the rest of
+// the chain in the same pass.
+//
 // # Reconfiguration must not restart the walk
 //
 // ConfigureObservatory runs on every successful apply, and cron reconciles every
@@ -98,8 +142,46 @@ type observatoryState struct {
 	used   map[string]bool
 	cursor int
 	cycles uint64
+	// keepWarm is the set of tags the routing config REACHES, and it answers
+	// ProbeWhenIdle: a group in it keeps its own probing ticker running with no
+	// traffic flowing.
+	//
+	// It is deliberately NOT the same field as used above, even though both hold
+	// a used-set. used is published only after a SUCCESSFUL apply, because the
+	// panel's "unused" badge must describe the config that is actually running;
+	// this one is published BEFORE the new box is built, because a group asks the
+	// question during its own PostStart. A failed apply can therefore leave this
+	// describing a config that never started — worst case a group keeps a ticker
+	// it did not need until the next apply, which nobody can see and which costs
+	// one probe interval. Merging the two would force one of those two timings on
+	// the other, and each is right for its own reader.
+	keepWarm map[string]bool
+	// hops indexes the plan's chain measurements — chain name -> hops in wire
+	// order -> the dial tags measuring each hop. Rebuilt from the plan whenever
+	// the plan is, and read (never mutated) by a tick to decide whether a hop's
+	// jobs may run at all. Derived state, kept rather than recomputed per tick
+	// only because it is derived from something that changes once per apply.
+	hops chainPlanIndex
+	// probeFn overrides how ONE planned measurement is executed. nil — the
+	// production value — means probeJob: resolve the dial tag against the running
+	// box and dial it.
+	//
+	// It exists for one assertion that cannot be made any other way. The ordered
+	// walk's contract is that hops below a dead one are never DIALLED; the
+	// resulting health readout cannot prove that, because "not probed" and
+	// "probed, failed, then overridden" are the same untested row. Only counting
+	// attempts distinguishes them, so the tests substitute a counter here.
+	probeFn func(ProbeJob)
 	// busy guards against a slow tick overlapping the next one.
 	busy bool
+	// force is the ONE-SHOT "check now" flag raised by RefreshObservatory: while
+	// it is up the freshness gate is bypassed, so a manual refresh really
+	// RE-MEASURES everything on the plan instead of skipping whatever happens to
+	// be fresh, and each finished batch immediately nudges the next one so the
+	// pass runs back-to-back rather than on the 10s tick. It is cleared the
+	// moment the forced pass schedules its last batch (cursor reaches the end of
+	// the plan) — one full walk, then back to the polite steady state.
+	force bool
 }
 
 // ConfigureObservatory installs (or re-tunes, or stops) the observatory. It is
@@ -119,7 +201,11 @@ func (e *Engine) ConfigureObservatory(cfg ObservatoryConfig) {
 	e.obs.interval = interval
 
 	if !cfg.Enabled {
-		e.obs.plan, e.obs.used, e.obs.cursor = nil, nil, 0
+		e.obs.plan, e.obs.used, e.obs.cursor, e.obs.hops = nil, nil, 0, nil
+		// The master switch is off: nothing probes in the background, so no group
+		// keeps a ticker alive on the background prober's behalf either.
+		e.obs.keepWarm = nil
+		e.obs.force = false
 		if e.obs.stop != nil {
 			close(e.obs.stop)
 			e.obs.stop, e.obs.done, e.obs.nudge = nil, nil, nil
@@ -134,6 +220,10 @@ func (e *Engine) ConfigureObservatory(cfg ObservatoryConfig) {
 		e.obs.plan = jobs
 		e.obs.cursor = 0
 	}
+	// Derived from whichever plan is now installed — the kept one when the
+	// reconcile was a no-op, so the index can never describe a plan the cursor is
+	// not walking.
+	e.obs.hops = indexChainHops(e.obs.plan)
 
 	if e.obs.stop == nil {
 		stop, done := make(chan struct{}), make(chan struct{})
@@ -162,7 +252,9 @@ func (e *Engine) StopObservatory() {
 	stop, done := e.obs.stop, e.obs.done
 	e.obs.stop, e.obs.done, e.obs.nudge = nil, nil, nil
 	e.obs.enabled = false
-	e.obs.plan, e.obs.used, e.obs.cursor = nil, nil, 0
+	e.obs.plan, e.obs.used, e.obs.cursor, e.obs.hops = nil, nil, 0, nil
+	e.obs.keepWarm = nil
+	e.obs.force = false
 	if stop != nil {
 		close(stop)
 	}
@@ -172,6 +264,49 @@ func (e *Engine) StopObservatory() {
 	}
 }
 
+// RefreshObservatory asks for an OUT-OF-TURN full pass of the probe plan: the
+// cursor is rewound to the top, the one-shot force flag is raised so the pass
+// bypasses the freshness gate (a "check now" that skipped everything fresh
+// would measure nothing and answer with yesterday's numbers), and the loop is
+// nudged so the first batch starts immediately instead of on the next 10s tick.
+//
+// This is the ONLY way the panel's "Test" button touches the network now: the
+// manual group test (grouptest.go) no longer dials anything itself — it calls
+// this, then watches the health board for observations newer than its start
+// instant. One prober, one set of dial paths, one truth.
+//
+// No-op when the observatory is disabled or has no plan: there is nothing to
+// walk, and raising force with no loop to consume it would only arm a stale
+// flag for a future enable. The caller (TestGroups) reports that situation
+// through its own results; this method stays silent about it on purpose —
+// it is a request, not a query.
+func (e *Engine) RefreshObservatory() {
+	e.obsMu.Lock()
+	defer e.obsMu.Unlock()
+	if !e.obs.enabled || len(e.obs.plan) == 0 {
+		return
+	}
+	e.obs.cursor = 0
+	e.obs.force = true
+	if e.obs.nudge != nil {
+		select {
+		case e.obs.nudge <- struct{}{}:
+		default:
+		}
+	}
+}
+
+// setProbeFn installs a stand-in for the per-job dial (observatoryState.probeFn).
+// It exists for the tests: the ordered walk promises that hops behind a dead one
+// are never DIALLED, and only an attempt counter can show that — the health
+// readout afterwards looks the same whether a job was skipped or run and
+// discarded. Passing nil restores the production path.
+func (e *Engine) setProbeFn(f func(ProbeJob)) {
+	e.obsMu.Lock()
+	defer e.obsMu.Unlock()
+	e.obs.probeFn = f
+}
+
 // ObservatoryStatus reports whether the observatory is on, how many measurements
 // the current plan holds, and how many full passes have completed. Cheap; used by
 // tests and available for diagnostics.
@@ -240,17 +375,18 @@ func (e *Engine) observatoryLoop(stop <-chan struct{}, done chan<- struct{}, nud
 // observatoryTickOnce runs one batch. It is deliberately conservative about when
 // it does nothing:
 //
-//   - a manual exit test (grouptest.go) is in flight => SKIP. That run is the
-//     human's explicit request; the observatory defers rather than competing for
-//     the uplink. It checks the guard but never CLAIMS it, so a pressed Test
-//     button can never be answered "already running" because of background work;
 //   - the previous tick has not finished => SKIP, so slow probes never stack;
 //   - the engine is stopped => jobs no longer resolve and are skipped (probeJob).
+//
+// There is deliberately NO deferral to a manual group test any more. The guard
+// that used to sit here ("skip the tick while e.groupTestRunning is up") made
+// sense when the manual run dialled the uplink itself and the two would have
+// competed for it; that run no longer probes ANYTHING — it asks for a forced
+// pass via RefreshObservatory and then reads the board. Keeping the guard would
+// therefore be worse than pointless: a manual run now DEPENDS on the
+// observatory ticking, and skipping ticks for its whole duration would deadlock
+// the very refresh it is waiting on (up to its full 120s deadline).
 func (e *Engine) observatoryTickOnce() {
-	if e.groupTestRunning.Load() {
-		return
-	}
-
 	e.obsMu.Lock()
 	if e.obs.busy || !e.obs.enabled || len(e.obs.plan) == 0 {
 		e.obsMu.Unlock()
@@ -258,7 +394,8 @@ func (e *Engine) observatoryTickOnce() {
 	}
 	if e.obs.cursor >= len(e.obs.plan) {
 		// Cycle complete: count it and start the next pass from the top. This is
-		// the ONE place the cursor is deliberately rewound.
+		// the ONE place the cursor is rewound on the observatory's own schedule
+		// (RefreshObservatory rewinds it too, but that is the caller's request).
 		e.obs.cycles++
 		e.obs.cursor = 0
 	}
@@ -270,12 +407,37 @@ func (e *Engine) observatoryTickOnce() {
 	batch := append([]ProbeJob(nil), e.obs.plan[start:end]...)
 	e.obs.cursor = end
 	interval := e.obs.interval
+	hops := e.obs.hops
+	probe := e.obs.probeFn
+	if probe == nil {
+		probe = e.probeJob
+	}
+	// A forced pass (RefreshObservatory) bypasses the freshness gate for its one
+	// walk of the plan. The flag is captured for THIS batch and cleared the
+	// moment the walk's last batch is scheduled: the remaining jobs of this very
+	// batch still run unfiltered off the captured copy, and the next pass is an
+	// ordinary polite one again.
+	force := e.obs.force
+	if force && end >= len(e.obs.plan) {
+		e.obs.force = false
+	}
 	e.obs.busy = true
 	e.obsMu.Unlock()
 
 	defer func() {
 		e.obsMu.Lock()
 		e.obs.busy = false
+		// Mid-forced-pass: chain straight into the next batch instead of waiting
+		// out the 10s tick. A human pressed "check now"; walking a subscription-
+		// sized plan at one batch per tick would stretch the answer past the
+		// manual run's deadline for no reason — the batch size still bounds how
+		// much is in flight at once, which is the limit that actually matters.
+		if e.obs.force && e.obs.nudge != nil {
+			select {
+			case e.obs.nudge <- struct{}{}:
+			default:
+			}
+		}
 		e.obsMu.Unlock()
 	}()
 
@@ -286,8 +448,13 @@ func (e *Engine) observatoryTickOnce() {
 	now := time.Now()
 	sem := make(chan struct{}, observatoryConcurrency)
 	var wg sync.WaitGroup
-	for _, j := range batch {
-		if !observatoryShouldProbe(hist, j, interval, now) {
+
+	// Two populations, two disciplines. A job that measures nothing on a chain is
+	// independent of every other job and runs as it always did: fire the lot,
+	// bounded by the semaphore. A chain's jobs are a SERIES and run hop by hop.
+	free, chains := splitChainBatch(batch)
+	for _, j := range free {
+		if j.SelfChecked || (!force && !observatoryShouldProbe(hist, j, interval, now)) {
 			continue
 		}
 		wg.Add(1)
@@ -295,12 +462,393 @@ func (e *Engine) observatoryTickOnce() {
 		go func(j ProbeJob) {
 			defer wg.Done()
 			defer func() { <-sem }()
-			e.probeJob(j)
+			probe(j)
 		}(j)
 	}
+	for _, walk := range chains {
+		wg.Add(1)
+		go func(walk chainBatch) {
+			defer wg.Done()
+			e.probeChainOrdered(walk, hops, hist, interval, now, force, sem, probe)
+		}(walk)
+	}
 	wg.Wait()
 }
 
+// probeChainOrdered runs one chain's share of a batch hop by hop, in wire order,
+// and RETURNS the moment a hop below a dead one comes up — leaving every
+// remaining job of that chain undialled for this pass.
+//
+// # Why the walk stops rather than filtering
+//
+// A chain is a series path: the plan's job for hop i dials through hops 1..i-1.
+// If hop 2 has no live member, the hop-3 probe fails INSIDE hop 2, learns nothing
+// about hop 3, and costs a full probe timeout to learn it. Recording that as
+// "hop 3 is dead" is the exact class of lie this codebase keeps removing: dead is
+// a positive finding about the thing that was probed, and hop 3 was never
+// reached. So the walk stops, the skipped hops keep no fresh observation, and
+// they surface as untested WITH the blocking hop named (grouphealth.go
+// ChainHopHealth.BlockedBy) rather than as faults of their own.
+//
+// # Why it cannot get stuck
+//
+// Nothing is remembered between passes. The gate is re-read from the health board
+// at every hop of every batch (blockedBefore), and the cursor rewinds to the top
+// of the plan each cycle, so the FIRST dead hop is always re-probed — it is never
+// itself below a break. The moment it answers again the gate opens and the rest
+// of the chain is probed in the same pass. There is no "blocked" flag anywhere to
+// clear, which is the point: a cached block would outlive the failure that caused
+// it.
+//
+// # Cost
+//
+// Hops within one batch are serialised, so a batch holding several hops of one
+// chain can take hops x probeTimeout instead of one probeTimeout. The busy guard
+// in observatoryTickOnce absorbs that (a slow tick makes the next a no-op), and
+// the case it exists for — a dead hop — now costs LESS than before, because
+// everything behind it is skipped entirely.
+func (e *Engine) probeChainOrdered(
+	walk chainBatch,
+	idx chainPlanIndex,
+	hist *urltest.HistoryStorage,
+	interval time.Duration,
+	now time.Time,
+	force bool,
+	sem chan struct{},
+	probe func(ProbeJob),
+) {
+	for _, hop := range walk.hops {
+		// Re-read the board here, not once up front: the hop before this one may
+		// have been probed moments ago by the loop's previous iteration, and its
+		// verdict is exactly what decides this one.
+		if blocker, blocked := idx.blockedBefore(walk.chain, hop.index, e.HealthView()); blocked {
+			e.markChainExitDead(walk.chain, idx, blocker)
+			return // hops are ascending, so everything left is behind the same break
+		}
+		var wg sync.WaitGroup
+		for _, j := range hop.jobs {
+			// A self-checked job is measured by its own group's checker, which is
+			// gated by ProbeAllowed on the same rule this loop applies. It is
+			// present here only so the hop shows up in the map the gate reads;
+			// dialling it would be the duplicate the flag exists to remove.
+			if j.SelfChecked || (!force && !observatoryShouldProbe(hist, j, interval, now)) {
+				continue
+			}
+			wg.Add(1)
+			sem <- struct{}{}
+			go func(j ProbeJob) {
+				defer wg.Done()
+				defer func() { <-sem }()
+				probe(j)
+			}(j)
+		}
+		// The hop's verdict is only complete when every member copy has answered,
+		// so the next hop's gate must not be read until they have.
+		wg.Wait()
+	}
+}
+
+// markChainExitDead records a DEAD verdict for a chain's EXIT on the shared
+// health board when the ordered walk stopped short of it.
+//
+// # Two questions, two answers, and why they differ
+//
+// "Is this hop's own node alive?" and "can this chain carry traffic?" are not the
+// same question, and behind a break they have different answers:
+//
+//   - the HOP's own health is genuinely UNKNOWN. Nothing dialled it, so its card
+//     reads untested with BlockedBy naming the blocker (markBlockedHops), and
+//     that stays exactly as it is;
+//   - the CHAIN's health is KNOWN, and the answer is no. A chain is a series
+//     path; hop k was probed and did not answer — a positive finding — and every
+//     dial through the chain crosses hop k. The exit cannot carry traffic. That
+//     is not absence of knowledge, it is a conclusion drawn from a measurement
+//     somebody took.
+//
+// # Why the board must say so
+//
+// The board is not only the panel's data source; the strategies select on it, and
+// they rank UNTESTED ABOVE DEAD on purpose (protocol/group/urltest_health_lx.go
+// selectExcluding: "an untested one is a better bet than a known-dead one"). So
+// leaving a provably-broken path untested is not a neutral silence — it is an
+// invitation to route traffic down it, which is worse than the mislabelling this
+// whole change set exists to remove. Marking it keeps
+// TestChainDeadExitMarkedByObservatory's older invariant intact too: a dead chain
+// is marked dead, and a dead entry stays distinguishable from a never-measured
+// one.
+//
+// # Why this is not a fabricated verdict
+//
+// Nothing here claims a probe happened. It records the CONSEQUENCE of a probe
+// that did happen, one hop earlier, and it is re-derived from the board every
+// pass — the instant the blocking hop answers again, the walk proceeds and the
+// exit's next verdict is a real measurement of its own. The flip is logged with
+// its cause so the trail never reads as an unexplained death.
+//
+// The exit's tags are the LAST hop's measurement tags: the wrapper itself for a
+// node exit, the member copies for a group exit — in both cases exactly what a
+// reader consults to ask whether the chain works.
+func (e *Engine) markChainExitDead(chain string, idx chainPlanIndex, blocker chainPlanHop) {
+	hops := idx[chain]
+	if len(hops) == 0 {
+		return
+	}
+	exit := hops[len(hops)-1]
+	if exit.index <= blocker.index {
+		return // the blocker IS the exit: its own probe already said so
+	}
+	hist := e.URLTestHistory()
+	if hist == nil {
+		return
+	}
+	ttl := e.healthTTL()
+	for _, tag := range exit.tags {
+		if e.log != nil && hist.Verdict(tag, ttl) != urltest.VerdictDead {
+			e.log.Info("observatory: ", tag, ": -> dead (chain hop ", blocker.index,
+				" was probed and did not answer, so nothing reaches the exit through it)")
+		}
+		hist.MarkFailed(tag)
+	}
+}
+
+// chainBatch is one chain's share of one batch, grouped into hops in wire order.
+type chainBatch struct {
+	chain string
+	hops  []chainBatchHop
+}
+
+// chainBatchHop is the jobs of ONE hop that fell inside the current batch. It is
+// a subset: a hop with more member copies than a batch holds is split across
+// consecutive batches, which is harmless — the gate is computed from the whole
+// plan (chainPlanIndex), never from what happens to be in hand.
+type chainBatchHop struct {
+	index int
+	jobs  []ProbeJob
+}
+
+// splitChainBatch separates a batch into the chain-less jobs and the per-chain
+// series. The plan is already sorted so a chain's jobs are contiguous and
+// ascending, but this does not rely on that: it groups explicitly and sorts each
+// chain's hops, so a batch that arrived out of order still runs in path order.
+func splitChainBatch(batch []ProbeJob) (free []ProbeJob, chains []chainBatch) {
+	at := map[string]int{}
+	for _, j := range batch {
+		if j.Chain == "" {
+			free = append(free, j)
+			continue
+		}
+		i, ok := at[j.Chain]
+		if !ok {
+			i = len(chains)
+			at[j.Chain] = i
+			chains = append(chains, chainBatch{chain: j.Chain})
+		}
+		c := &chains[i]
+		h := -1
+		for k := range c.hops {
+			if c.hops[k].index == j.Hop {
+				h = k
+				break
+			}
+		}
+		if h < 0 {
+			c.hops = append(c.hops, chainBatchHop{index: j.Hop})
+			h = len(c.hops) - 1
+		}
+		c.hops[h].jobs = append(c.hops[h].jobs, j)
+	}
+	for i := range chains {
+		hops := chains[i].hops
+		sort.Slice(hops, func(a, b int) bool { return hops[a].index < hops[b].index })
+	}
+	return free, chains
+}
+
+// chainPlanIndex is the whole plan's chain measurements: chain name -> hops in
+// wire order, each carrying every DIAL TAG that measures it.
+//
+// It is the gate's source of truth, and it must come from the PLAN rather than
+// from the running box, for the same reason probeJob resolves its dial tag at
+// dial time: the plan is what this pass is walking. A hop's verdict rolled up
+// from a set of tags the pass does not probe would gate the pass on somebody
+// else's measurements.
+type chainPlanIndex map[string][]chainPlanHop
+
+type chainPlanHop struct {
+	index int
+	tags  []string
+}
+
+// indexChainHops builds the index from a plan. nil for a plan with no chain in it
+// — the overwhelmingly common case, and a nil map answers every lookup with "no
+// hops, nothing blocks" at no cost.
+func indexChainHops(plan []ProbeJob) chainPlanIndex {
+	var out chainPlanIndex
+	for _, j := range plan {
+		if j.Chain == "" {
+			continue
+		}
+		if out == nil {
+			out = chainPlanIndex{}
+		}
+		hops := out[j.Chain]
+		at := -1
+		for k := range hops {
+			if hops[k].index == j.Hop {
+				at = k
+				break
+			}
+		}
+		if at < 0 {
+			hops = append(hops, chainPlanHop{index: j.Hop})
+			at = len(hops) - 1
+		}
+		hops[at].tags = append(hops[at].tags, j.Dial)
+		out[j.Chain] = hops
+	}
+	for name, hops := range out {
+		sort.Slice(hops, func(a, b int) bool { return hops[a].index < hops[b].index })
+		out[name] = hops
+	}
+	return out
+}
+
+// blockedBefore reports the LOWEST hop of chain, strictly before hop, that the
+// health board currently reads dead — the hop that stops the walk. Only a
+// positive dead finding blocks: an untested hop in front means nothing is known
+// yet, and refusing to probe on "nothing is known" would make a cold start
+// permanent.
+func (idx chainPlanIndex) blockedBefore(chain string, hop int, view HealthView) (chainPlanHop, bool) {
+	for _, h := range idx[chain] {
+		if h.index >= hop {
+			break
+		}
+		if hopBoardState(h.tags, view) == HealthDead {
+			return h, true
+		}
+	}
+	return chainPlanHop{}, false
+}
+
+// ProbeAllowed implements urltest.ProbeGate: it answers, for one outbound tag,
+// whether that outbound's OWN probing schedule may dial right now.
+//
+// # What it is for
+//
+// The observatory is not the only prober. A urltest group probes its own
+// members — a warm-up sweep at box start and a ticker while traffic touches it
+// — and a chain's GROUP HOP is materialised as exactly such a group
+// ("chain-<n>-h<i>", generate/chain.go). Every member of that group dials
+// through the hop in front of it, so when THAT hop is dead the group's sweep
+// spends one probe timeout per member to rediscover the same broken hop, and
+// files each result against a hop nothing reached. The projection already
+// refuses to publish those readings (markBlockedHops); this stops them being
+// taken.
+//
+// # Why this is not the SelfCheck flag
+//
+// standDownUnusedSelfCheck answers a different question — "does any enabled
+// rule reach this group at all" — decided once, written into the config that
+// reaches box.New, and true for the whole life of that box. A chain hop wrapper
+// IS reached by the rules and must keep its flag (TestStandDownNeverTouchesChainHopWrappers
+// pins that). This answers "is the path in front of it working AT THIS MOMENT",
+// which changes on its own and must therefore be asked, never stored. Merging
+// the two would either put a live question in a static flag or take a used
+// chain permanently off the board.
+//
+// # Why it cannot get stuck
+//
+// It holds nothing. Every call recomputes the block from the same plan index
+// and the same health board the observatory's own walk uses, so the moment the
+// blocking hop answers a probe this returns true again and the wrapper's next
+// tick dials normally. The blocking hop is itself never behind a break, so the
+// observatory re-probes it every cycle: there is always something re-asking the
+// question that produced the block.
+//
+// It answers TRUE whenever it does not know — no plan, observatory disabled,
+// not a chain hop tag, chain absent from the plan. Refusing on missing
+// information would silence probing exactly when least is known, and nothing
+// would ever measure its way back out.
+func (e *Engine) ProbeAllowed(tag string) bool {
+	chain, hop, ok := parseChainHopTag(tag)
+	if !ok {
+		return true // not a chain hop wrapper: nothing sits in front of it
+	}
+	e.obsMu.Lock()
+	enabled, idx := e.obs.enabled, e.obs.hops
+	e.obsMu.Unlock()
+	if !enabled || idx == nil {
+		return true
+	}
+	// HealthView takes obsMu itself (healthTTL), so it must be called with the
+	// lock released.
+	_, blocked := idx.blockedBefore(chain, hop, e.HealthView())
+	return !blocked
+}
+
+// ProbeWhenIdle implements urltest.ProbeGate: it reports whether an outbound
+// must keep measuring itself with no traffic flowing through it.
+//
+// TRUE for anything the routing configuration reaches. Such a group's health is
+// a live question at all times — a rule matching a narrow domain list is in
+// force whether or not it fired in the last half hour — and without this its own
+// ticker would retire on the idle timeout and NOTHING would replace it: the
+// observatory stands off a urltest group's members by design (ProbeJob.SelfChecked).
+// The panel would then report "untested" about an armed rule, and the first
+// request through it would pay a cold probe instead of picking a member already
+// known to work. Keeping the group's own ticker running restores exactly what
+// the observatory used to spend on those same targets, at the same interval, and
+// keeps it to ONE dialler.
+//
+// FALSE whenever nothing is known — no config applied yet, unknown tag, master
+// switch off. This method adds work rather than withholding it, so the direction
+// of "don't know" is the opposite of ProbeAllowed's: claiming keep-warm on
+// missing information would leave groups probing forever for no stated reason.
+//
+// It does NOT bypass any other refusal. A stood-down group never asks (the
+// group's own keepWarm short-circuits on selfCheckDisabled), and a kept-warm
+// group behind a dead hop still ticks WITHOUT dialling, because every tick goes
+// through scheduledCheck -> ProbeAllowed. Warm means measured on schedule, never
+// "hammering through a broken path".
+func (e *Engine) ProbeWhenIdle(tag string) bool {
+	e.obsMu.Lock()
+	defer e.obsMu.Unlock()
+	return e.obs.keepWarm[tag]
+}
+
+// publishKeepWarm installs the set ProbeWhenIdle answers from. Called from
+// applyLocked with the used-set of the config being applied, and cleared when
+// background probing is switched off — see the keepWarm field for why this is
+// published on a different schedule from the observatory's own used-set.
+func (e *Engine) publishKeepWarm(used map[string]bool) {
+	e.obsMu.Lock()
+	e.obs.keepWarm = used
+	e.obsMu.Unlock()
+}
+
+// hopBoardState rolls a hop's measurement tags into one verdict, by exactly the
+// rule chainGroupHop (grouphealth.go) uses for the same question — "can this hop
+// carry the chain": alive as soon as anything answers, dead only when something
+// was tested and nothing answers, untested when nothing was tested at all. The
+// prober and the panel must agree about which hop broke a chain, so this is that
+// rule written once more against tags instead of against a materialised group;
+// TestChainHopGateMatchesProjection pins the two together.
+func hopBoardState(tags []string, view HealthView) string {
+	tested := 0
+	for _, tag := range tags {
+		switch state, _, _ := view.State(tag); state {
+		case HealthAlive:
+			return HealthAlive
+		case HealthDead:
+			tested++
+		}
+	}
+	if tested > 0 {
+		return HealthDead
+	}
+	return HealthUntested
+}
+
 // observatoryShouldProbe is the freshness gate: a job runs when ANY tag it
 // covers has no observation at all, or its newest observation — success OR
 // failure — is older than the global probe interval.

shater/engine/probeplan.go

@@ -27,8 +27,12 @@ import (
 //   - a CHAIN entry tag "chain-<n>-hN" (the exit wrapper, generate/chain.go) is
 //     probed ITSELF: dialling the copy pulls the whole L1→…→Ln path through its
 //     Detour links, so one probe is the chain's end-to-end health. Intermediate
-//     NODE hops are not probed separately — their death is visible in the exit
-//     probe and no selection depends on them;
+//     NODE hop wrappers ("chain-<n>-h<i>" that are plain outbounds) are probed
+//     TOO — not because selection needs them (it does not), but because an
+//     operator does: dialling "chain-<n>-h1" measures exactly the prefix of the
+//     path up to and including hop 1, so when the exit probe dies the per-hop
+//     probes say WHICH hop died instead of only that the chain did (the
+//     ChainHealth hops surface, grouphealth.go);
 //   - a GROUP hop inside a chain ("chain-<n>-h<i>", a wrapper selector reached by
 //     walking the exit's Detour links) additionally has its member copies
 //     "chain-<n>-h<i>-<member>" probed: they are the wrapper's selection
@@ -47,6 +51,28 @@ import (
 // ever being dialled by the observatory. Chain copies are recorded only under
 // themselves: a chain prefix is nobody else's path.
 //
+// # Who dials
+//
+// Reaching a target does not make it OURS to dial. A member of a urltest group
+// already has a prober — that group's own checker — and for a chain hop that
+// checker measures the better path: the member copy carries the previous hop as
+// its Detour, so its probe travels the chain prefix without anything having to
+// be arranged. Those measurements are emitted with SelfChecked set and the
+// observatory never dials them. What stays ours is what no group probes: node
+// hop wrappers, endpoints, selector members, stood-down groups' members, and
+// egress copies (whose base-tag alias no checker writes).
+//
+// # Order
+//
+// The plan is a LIST, not a set, and for a chain the order is load-bearing. Each
+// job that measures a chain carries the chain name and its 1-based hop index
+// (ProbeJob.Chain/Hop, threaded through the walk as planPos), and the emitted
+// plan is sorted so a chain's jobs come out grouped and ascending by hop. The
+// observatory walks them in that order and stops at the first dead hop —
+// probing hop 3 through a hop 2 with no live member measures hop 2's failure and
+// nothing else, so recording it against hop 3 names the wrong suspect and burns a
+// probe timeout doing it.
+//
 // # Dedup
 //
 // The probe URL is global (plan §5.D), so the dedup key is the dial path alone:
@@ -65,6 +91,42 @@ type ProbeJob struct {
 	Dial  string
 	URL   string
 	Store []string
+	// Chain and Hop place this measurement ON a chain's path: the chain NAME and
+	// the 1-based hop index it measures. Both zero ("" / 0) for every job that is
+	// not part of a chain, which is most of them.
+	//
+	// This is what makes the walk ORDERED (observatory.go). A chain is a series
+	// path, so the probe of hop 3 dials THROUGH hops 1 and 2; if hop 2 has no live
+	// member, that probe fails at hop 2 and says nothing whatsoever about hop 3.
+	// Recording it as a verdict about hop 3 was the defect: it pointed the
+	// operator at the wrong hop and spent a full probe timeout to do it. The
+	// prober therefore walks a chain h1 -> hN and stops at the first dead hop, and
+	// these two fields are the only thing that tells it which jobs form which hop
+	// of which path.
+	//
+	// A hop is usually SEVERAL jobs — a group hop's member copies are one
+	// measurement each — so Hop is a grouping key, never a job's identity.
+	Chain string
+	Hop   int
+	// SelfChecked marks a measurement whose target already has a dialler: it is a
+	// member of a URLTEST group, and that group's own checker probes exactly this
+	// outbound, on exactly this dial path, on the same global interval
+	// (protocol/group/urltest.go testNodes). The observatory therefore does NOT
+	// dial it. One target, one dialler.
+	//
+	// The group's checker is the RIGHT dialler for these, not merely an equal
+	// one: a chain hop member carries the Detour of the hop in front of it, so
+	// the checker's probe travels the chain prefix by construction, which is the
+	// path the traffic takes. Nothing had to be arranged for that to be true.
+	//
+	// The job STAYS in the plan rather than being dropped, because the plan is
+	// two things at once: the observatory's dial list AND the map of which tags
+	// measure which hop of which chain. The ordered walk's gate reads the second
+	// (indexChainHops -> blockedBefore), and it must see every measurement of a
+	// hop, not only the ones this prober performs — a hop whose members are all
+	// self-checked would otherwise vanish from the map and stop being able to
+	// block anything.
+	SelfChecked bool
 }
 
 // BuildObservatoryPlan derives the observatory's probe plan from the applied
@@ -77,7 +139,7 @@ type ProbeJob struct {
 // probeURL is the global probe URL; "" lets urltest fall back to its gstatic
 // default, exactly as the generator does.
 //
-// The result is deterministic (sorted by Dial) so a cursor walking it across
+// The result is deterministic (see probeJobLess) so a cursor walking it across
 // ticks is stable, and plansEqual can tell a no-op reconcile from real change.
 func BuildObservatoryPlan(opts option.Options, probeURL string) ([]ProbeJob, map[string]bool) {
 	w := &planWalk{
@@ -88,7 +150,9 @@ func BuildObservatoryPlan(opts option.Options, probeURL string) ([]ProbeJob, map
 		targets: map[string]*planTarget{},
 	}
 	for _, root := range planRoots(opts) {
-		w.visit(root)
+		// A root comes from a routing rule, not from a group, so nothing is
+		// checking it on our behalf.
+		w.visit(root, planPos{}, false)
 	}
 
 	jobs := make([]ProbeJob, 0, len(w.targets))
@@ -98,18 +162,49 @@ func BuildObservatoryPlan(opts option.Options, probeURL string) ([]ProbeJob, map
 			store = append(store, tag)
 		}
 		sort.Strings(store)
-		jobs = append(jobs, ProbeJob{Dial: t.dial, URL: probeURL, Store: store})
+		jobs = append(jobs, ProbeJob{
+			Dial: t.dial, URL: probeURL, Store: store,
+			Chain: t.pos.chain, Hop: t.pos.hop, SelfChecked: t.selfChecked,
+		})
 	}
-	sort.Slice(jobs, func(i, j int) bool { return jobs[i].Dial < jobs[j].Dial })
+	sort.Slice(jobs, func(i, j int) bool { return probeJobLess(jobs[i], jobs[j]) })
 	return jobs, w.used
 }
 
+// probeJobLess is the plan's order, and it is a CONTRACT rather than a
+// presentation detail: a chain's jobs come out grouped by chain and ascending by
+// hop, so a cursor walking the plan meets h1 before h2 before h3. The observatory
+// relies on that to stop at the first dead hop (see probeChainOrdered); a plan
+// sorted by dial tag alone would interleave the hops of one path and there would
+// be no "first" to stop at.
+//
+// Chain-less jobs (Chain "") sort first, among themselves by dial tag, exactly as
+// the whole plan used to. Ties inside one hop break on the dial tag, so the order
+// is total and two builds of one config are byte-identical — the property
+// ConfigureObservatory's cursor keeping depends on.
+func probeJobLess(a, b ProbeJob) bool {
+	if a.Chain != b.Chain {
+		return a.Chain < b.Chain
+	}
+	if a.Hop != b.Hop {
+		return a.Hop < b.Hop
+	}
+	return a.Dial < b.Dial
+}
+
 // planEntry is the slice of one configured outbound/endpoint the planner needs.
 type planEntry struct {
 	typ     string
 	group   bool     // selector/urltest — expanded, never dialled
 	members []string // group members, in config order
 	detour  string   // DialerOptions.Detour ("" when none)
+	// selfChecks is true for a group that PROBES ITS OWN MEMBERS: a urltest
+	// group whose self-check has not been stood down. A selector never does (it
+	// has no checker at all — protocol/group/selector.go), and a urltest group
+	// with SelfCheck=false has had its schedule taken away deliberately
+	// (standDownUnusedSelfCheck), so in both of those cases the observatory is
+	// the only possible dialler and must remain one.
+	selfChecks bool
 }
 
 // planIndex flattens opts into tag -> planEntry. Endpoints (wireguard/AmneziaWG)
@@ -119,10 +214,11 @@ func planIndex(opts option.Options) map[string]planEntry {
 	byTag := make(map[string]planEntry, len(opts.Outbounds)+len(opts.Endpoints))
 	for _, ob := range opts.Outbounds {
 		byTag[ob.Tag] = planEntry{
-			typ:     ob.Type,
-			group:   ob.Type == C.TypeSelector || ob.Type == C.TypeURLTest,
-			members: groupMembersOf(ob.Options),
-			detour:  detourOf(ob.Options),
+			typ:        ob.Type,
+			group:      ob.Type == C.TypeSelector || ob.Type == C.TypeURLTest,
+			members:    groupMembersOf(ob.Options),
+			detour:     detourOf(ob.Options),
+			selfChecks: ob.Type == C.TypeURLTest && urltestSelfChecks(ob.Options),
 		}
 	}
 	for _, ep := range opts.Endpoints {
@@ -188,6 +284,23 @@ func groupMembersOf(options any) []string {
 	return nil
 }
 
+// urltestSelfChecks reports whether a urltest group still runs its OWN probing
+// schedule. nil/absent SelfCheck means on — the documented compatibility default
+// (option.URLTestOutboundOptions.SelfCheck) — and only an explicit false stands
+// it down. An options struct of an unexpected shape is read as "on", the same
+// direction standDownUnusedSelfCheck refuses to guess in: assuming a checker
+// exists when it does not would leave a target with NO dialler, which is worse
+// than one dialled twice.
+func urltestSelfChecks(options any) bool {
+	switch o := options.(type) {
+	case *option.URLTestOutboundOptions:
+		return o.SelfCheck == nil || *o.SelfCheck
+	case option.URLTestOutboundOptions:
+		return o.SelfCheck == nil || *o.SelfCheck
+	}
+	return true
+}
+
 // detourOf reads DialerOptions.Detour out of any outbound/endpoint/dns-server
 // option struct that carries dialer options (they all embed option.DialerOptions
 // and therefore satisfy DialerOptionsWrapper); "" for everything else.
@@ -211,11 +324,40 @@ func probeablePlanTag(typ, tag string) bool {
 	return !strings.HasPrefix(tag, "egress-")
 }
 
+// planPos is where a measurement sits on a chain: the chain name and the 1-based
+// hop index. The zero value means "not on any chain", which is what every job
+// outside a chain carries.
+//
+// It is threaded through the walk rather than parsed back out of each tag,
+// because only the walk knows the STRUCTURE. A hop wrapper's tag names its own
+// position ("chain-<n>-h<i>"), but a group hop's member copies
+// ("chain-<n>-h<i>-<member>") end in free-form operator text: a node named
+// "h2-eu" would make the tag ambiguous to any parser. Inheriting the position
+// from the wrapper the walk arrived through has no such failure mode.
+type planPos struct {
+	chain string
+	hop   int
+}
+
+// chainPosOf reads a hop WRAPPER tag's own position, or the zero position for
+// anything else.
+func chainPosOf(tag string) planPos {
+	if name, hop, ok := parseChainHopTag(tag); ok {
+		return planPos{chain: name, hop: hop}
+	}
+	return planPos{}
+}
+
 // planTarget accumulates one dial path's job: the tag to dial (the smallest
-// dialable tag, for determinism) and every tag the measurement is recorded under.
+// dialable tag, for determinism), every tag the measurement is recorded under,
+// and where on a chain it sits (planPos).
 type planTarget struct {
 	dial  string
 	store map[string]bool
+	pos   planPos
+	// selfChecked: some group's own checker already dials this path, so the
+	// observatory must not. See ProbeJob.SelfChecked.
+	selfChecked bool
 }
 
 // planWalk is the reachability expansion state.
@@ -230,13 +372,30 @@ type planWalk struct {
 // addTarget registers tag as a measurement under the dial-path key, recording it
 // under itself plus aliases. When several dialable tags share one path (copies of
 // one node through one egress across groups) the smallest dials, deterministically.
-func (w *planWalk) addTarget(key, tag string, aliases ...string) {
+//
+// pos is the chain position and is taken from the FIRST arrival only. Two
+// arrivals at one dial-path key are copies of the same node through the same
+// egress (see the file header), which live outside every chain and therefore
+// carry the zero position anyway; a chain tag's dial key is its own tag, so it is
+// reached once by construction. Never overwriting means a shared key cannot have
+// its position depend on walk order.
+//
+// selfChecked, by contrast, is ANDed across arrivals, and the asymmetry is
+// deliberate: it claims "somebody else already dials this", and one path that
+// reaches the target WITHOUT a checker in front of it (a selector member, a
+// stood-down group) falsifies the claim outright. Merging the pessimistic way
+// can only cost a duplicate probe; merging the optimistic way would leave a
+// target with no dialler at all.
+func (w *planWalk) addTarget(key string, pos planPos, selfChecked bool, tag string, aliases ...string) {
 	t := w.targets[key]
 	if t == nil {
-		t = &planTarget{dial: tag, store: map[string]bool{}}
+		t = &planTarget{dial: tag, store: map[string]bool{}, pos: pos, selfChecked: selfChecked}
 		w.targets[key] = t
-	} else if tag < t.dial {
-		t.dial = tag
+	} else {
+		if tag < t.dial {
+			t.dial = tag
+		}
+		t.selfChecked = t.selfChecked && selfChecked
 	}
 	t.store[tag] = true
 	for _, a := range aliases {
@@ -247,7 +406,15 @@ func (w *planWalk) addTarget(key, tag string, aliases ...string) {
 // visit expands one root/member reference. Groups recurse into their members;
 // leaves become measurements; a leaf's Detour link is then walked to surface the
 // group hops of a chain (walkDetour).
-func (w *planWalk) visit(tag string) {
+//
+// pos is the chain position INHERITED from the group this reference was expanded
+// out of; a tag that names its own hop position (a chain hop wrapper, typically
+// the exit reached straight from a rule) overrides it.
+//
+// selfChecked says the group this reference came out of probes its own members,
+// so the leaf reached here already has a dialler. A ROOT is reached from a
+// routing rule, which has no checker behind it, so roots start false.
+func (w *planWalk) visit(tag string, pos planPos, selfChecked bool) {
 	if tag == "" || w.visited[tag] {
 		return
 	}
@@ -257,14 +424,17 @@ func (w *planWalk) visit(tag string) {
 		return // dangling reference; box.New would have refused it anyway
 	}
 	w.used[tag] = true
+	if own := chainPosOf(tag); own.chain != "" {
+		pos = own
+	}
 	if ent.group {
 		for _, m := range ent.members {
-			w.visitMember(tag, m)
+			w.visitMember(tag, m, pos, ent.selfChecks)
 		}
 		return
 	}
 	if probeablePlanTag(ent.typ, tag) {
-		w.addTarget(dialKeyTag(tag), tag)
+		w.addTarget(dialKeyTag(tag), pos, selfChecked, tag)
 	}
 	w.walkDetour(ent.detour)
 }
@@ -273,26 +443,49 @@ func (w *planWalk) visit(tag string) {
 // ("group-<group>-m<i>-<member>") is keyed by its (node, egress) dial path — so
 // two groups bound to one egress share the measurement — and recorded under the
 // copy AND the base node tag (the store alias). Every other member is expanded
-// exactly like a root.
-func (w *planWalk) visitMember(group, member string) {
+// exactly like a root, carrying the owning group's chain position down with it:
+// the members of a chain's exit group hop are measurements OF that hop.
+//
+// The EGRESS COPY branch is deliberately never marked self-checked, even when
+// the owning group runs its own checker. Such a job carries a second store tag —
+// the base node tag, the alias that keeps the per-node stats surface filled in
+// without the base outbound (a different dial path) ever being dialled. The
+// group's checker records under the copy tag ALONE (protocol/group/urltest.go
+// stores under RealTag), so handing this measurement over would silently drop
+// the alias and empty /api/stats node_health for every egress-bound node. That
+// is a real duplicate probe knowingly kept, and the alternative is losing data
+// no other writer produces.
+func (w *planWalk) visitMember(group, member string, pos planPos, ownerSelfChecks bool) {
 	ent, ok := w.byTag[member]
 	if !ok {
 		return
 	}
 	if node, isCopy := parseGroupCopyTag(group, member); isCopy && !ent.group {
 		w.used[member] = true
-		w.addTarget(dialKeyCopy(node, ent.detour), member, node)
+		w.addTarget(dialKeyCopy(node, ent.detour), pos, false, member, node)
 		w.walkDetour(ent.detour)
 		return
 	}
-	w.visit(member)
+	w.visit(member, pos, ownerSelfChecks)
 }
 
 // walkDetour follows a probed tag's Detour links toward the router. A group met
 // on the way is a chain's GROUP HOP wrapper: its member copies are selection
 // candidates and are probed, each through its own prefix of the path. A plain
-// outbound met on the way is an intermediate node hop — marked used, never probed
-// on its own — and the walk continues through it.
+// outbound met on the way falls in two halves:
+//
+//   - a chain NODE HOP wrapper ("chain-<n>-h<i>", parseChainExitTag) is probed
+//     as a measurement of its own. Dialling it pulls exactly the prefix of the
+//     chain up to and including hop i through the Detour links, so its verdict
+//     LOCALISES a failure: the exit probe says the chain died, the hop probes
+//     say where. It used to be skipped here on the argument that its death
+//     shows up in the exit probe anyway — true for end-to-end health, useless
+//     for an operator staring at a dead 4-hop chain. The measurement is stored
+//     under the wrapper tag alone: a chain prefix is nobody else's dial path,
+//     so no alias may borrow its verdict;
+//   - anything else on the detour path — an "egress-…" interface outbound, an
+//     ordinary node's egress detour — keeps today's behaviour: marked used,
+//     never probed on its own, and the walk continues through it.
 func (w *planWalk) walkDetour(tag string) {
 	if tag == "" || w.walked[tag] {
 		return
@@ -303,25 +496,38 @@ func (w *planWalk) walkDetour(tag string) {
 		return
 	}
 	w.used[tag] = true
-	if ent.group {
-		next := ""
-		for _, m := range ent.members {
-			ment, ok := w.byTag[m]
-			if !ok {
-				continue
-			}
-			w.used[m] = true
-			if !ment.group && probeablePlanTag(ment.typ, m) {
-				w.addTarget(dialKeyTag(m), m)
-			}
-			if next == "" {
-				next = ment.detour // every member detours into the same previous hop
-			}
+	// A tag met on a detour path names its own position or has none: the walk
+	// arrived here from BELOW (a later hop detouring back), so there is nothing
+	// sensible to inherit.
+	pos := chainPosOf(tag)
+	if !ent.group {
+		// A NODE hop wrapper is nobody's member, so no checker exists for it and
+		// the observatory is its only possible dialler.
+		if pos.chain != "" && probeablePlanTag(ent.typ, tag) {
+			w.addTarget(dialKeyTag(tag), pos, false, tag)
 		}
-		w.walkDetour(next)
+		w.walkDetour(ent.detour)
 		return
 	}
-	w.walkDetour(ent.detour)
+	next := ""
+	for _, m := range ent.members {
+		ment, ok := w.byTag[m]
+		if !ok {
+			continue
+		}
+		w.used[m] = true
+		if !ment.group && probeablePlanTag(ment.typ, m) {
+			// A GROUP hop's members are that wrapper's members: when the wrapper
+			// is a urltest group it probes them itself, and it probes them along
+			// the chain prefix, because each copy carries the previous hop as its
+			// Detour. A selector wrapper has no checker, so those stay ours.
+			w.addTarget(dialKeyTag(m), pos, ent.selfChecks, m)
+		}
+		if next == "" {
+			next = ment.detour // every member detours into the same previous hop
+		}
+	}
+	w.walkDetour(next)
 }
 
 // dialKeyTag / dialKeyCopy build the dedup key for one measurement target.
@@ -342,8 +548,14 @@ func dialKeyCopy(node, egress string) string {
 func lenPrefixed(s string) string { return fmt.Sprintf("%d:%s", len(s), s) }
 
 // plansEqual reports whether two plans describe exactly the same measurements —
-// same jobs, same order, same dial tag, same URL, same store set. This is what
-// lets a no-op reconcile keep the observatory's cursor (see ConfigureObservatory).
+// same jobs, same order, same dial tag, same URL, same store set, same chain
+// position. This is what lets a no-op reconcile keep the observatory's cursor
+// (see ConfigureObservatory).
+//
+// The chain position is part of the comparison because it is part of the PLAN,
+// not an annotation on it: it decides the order jobs run in and which of them the
+// ordered walk may skip. A config that moves a node from hop 2 to hop 3 without
+// changing any dial tag is a different plan and must restart the cursor.
 func plansEqual(a, b []ProbeJob) bool {
 	if len(a) != len(b) {
 		return false
@@ -352,6 +564,9 @@ func plansEqual(a, b []ProbeJob) bool {
 		if a[i].Dial != b[i].Dial || a[i].URL != b[i].URL || len(a[i].Store) != len(b[i].Store) {
 			return false
 		}
+		if a[i].Chain != b[i].Chain || a[i].Hop != b[i].Hop || a[i].SelfChecked != b[i].SelfChecked {
+			return false
+		}
 		for j := range a[i].Store {
 			if a[i].Store[j] != b[i].Store[j] {
 				return false

shater/engine/probeplan_test.go

@@ -218,6 +218,64 @@ func TestObservatoryPlanChain(t *testing.T) {
 	}
 }
 
+// A chain with a plain NODE hop wrapper on the way to the exit: the wrapper IS
+// a measurement of its own now (walkDetour) — dialling "chain-<c>-h1" measures
+// exactly the path prefix up to hop 1, which is what localises a dead hop. And
+// the other half of the honesty contract: a base node that appears ONLY as a
+// chain group-hop member is never measured under its BASE tag — the member
+// copy's observation stays on the copy, because the copy's dial path (through
+// the chain prefix) is not the base outbound's dial path, and no job may write
+// a direct-looking verdict onto a tag it did not dial.
+func TestObservatoryPlanChainHopWrappersProbed(t *testing.T) {
+	opts := option.Options{
+		Outbounds: []option.Outbound{
+			// L1: a plain node hop wrapper.
+			fixNode("chain-c2-h1", ""),
+			// L2: a group hop over one member copy of base node N.
+			fixNode("chain-c2-h2-N", "chain-c2-h1"),
+			fixGroup(C.TypeSelector, "chain-c2-h2", "chain-c2-h2-N"),
+			// L3: the exit, a plain node copy.
+			fixNode("chain-c2-h3", "chain-c2-h2"),
+			// The base node behind the L2 member copy: emitted, referenced by
+			// NOTHING but the copy's name.
+			fixNode("N", ""),
+		},
+		Route: fixRoute("", "chain-c2-h3"),
+	}
+	byDial, used := planOf(t, opts)
+
+	// The node hop wrapper is a job of its own, stored only under itself.
+	j := assertPlanHas(t, byDial, "chain-c2-h1")
+	if len(j.Store) != 1 || j.Store[0] != "chain-c2-h1" {
+		t.Errorf("node hop wrapper store = %v, want only itself (a chain prefix is nobody else's path)", j.Store)
+	}
+	// The exit and the group-hop member copy are jobs, as before.
+	assertPlanHas(t, byDial, "chain-c2-h3")
+	assertPlanHas(t, byDial, "chain-c2-h2-N")
+
+	// NO job may record anything under the base tag N: not as a dial, not as a
+	// store alias. A direct measurement can never land on it from this config.
+	if _, ok := byDial["N"]; ok {
+		t.Error("plan dials the base node N, which no rule reaches")
+	}
+	for dial, job := range byDial {
+		for _, tag := range job.Store {
+			if tag == "N" {
+				t.Errorf("job %q stores under the base tag N; a chain member copy must never alias its base", dial)
+			}
+		}
+	}
+	if used["N"] {
+		t.Error("used-set claims the base node N; only the chain copies are on the path")
+	}
+	// The wrappers themselves are used (they are the path).
+	for _, u := range []string{"chain-c2-h1", "chain-c2-h2", "chain-c2-h3", "chain-c2-h2-N"} {
+		if !used[u] {
+			t.Errorf("used-set is missing %q", u)
+		}
+	}
+}
+
 // DNS server detours and route.Final are roots too — a group referenced only as a
 // resolver's detour is still a used, probed path.
 func TestObservatoryPlanDNSDetourRoot(t *testing.T) {

shater/engine/selfcheck.go

@@ -0,0 +1,99 @@
+package engine
+
+import (
+	C "github.com/sagernet/sing-box/constant"
+	"github.com/sagernet/sing-box/option"
+)
+
+// Standing down the self-check of unused urltest groups (health board §5.C).
+//
+// # Why the engine does this, and not the generator
+//
+// A urltest group probes its own members: a warm-up sweep at PostStart and a
+// ticker for as long as traffic touches it (protocol/group/urltest.go). For a
+// group the routing rules actually use, that probing travels the same path the
+// traffic does and is welcome. For a group NO rule reaches, it dials the
+// members' base outbounds directly from the router — a path nothing uses — and
+// stores the results under the base tags, where every health consumer reads
+// them as "the node's health". A node that only works behind a tunnel then
+// reads dead on the shared board because an idle group measured it over the
+// blocked direct WAN. The observatory's plan (probeplan.go) is the single
+// statement of what gets probed and along which paths; this file makes the
+// config that reaches box.New SAY so, by flipping SelfCheck off on every
+// urltest group outside the plan's used-set.
+//
+// The generator cannot do this: whether a group is used is a property of the
+// EMITTED rules and DNS detours as a whole, and BuildObservatoryPlan is the one
+// place that reachability is computed. Recomputing it in the generator would be
+// a second copy of the same walk, and second copies drift.
+//
+// # NOT the same thing as Engine.ProbeAllowed — do not merge them
+//
+// There are two reasons a group's own schedule stands down, and they are
+// answered in two different places on purpose:
+//
+//	THIS FILE — "no enabled rule reaches this group AT ALL". A property of the
+//	  CONFIG. Decided once per apply, written into the option struct that
+//	  reaches box.New, and unchangeable for the life of that box, because the
+//	  rules cannot change while the box runs.
+//
+//	Engine.ProbeAllowed — "the path in front of this group is dead RIGHT NOW".
+//	  A property of the WORLD. It changes on its own, so it is asked at every
+//	  scheduled check and never stored; that is the only reason a chain hop
+//	  resumes probing by itself when the hop in front of it recovers.
+//
+// A CHAIN HOP WRAPPER is precisely where the difference bites. It is reached by
+// the rules, so it is in the used-set and this function must leave its flag
+// alone — TestStandDownNeverTouchesChainHopWrappers pins that, and it is not a
+// technicality: standing a hop wrapper down here would take a working chain off
+// its own board permanently, with nothing to turn it back on. If a hop wrapper
+// should not probe because the hop in front of it is down, that is the gate's
+// answer, not this one's, and it lasts exactly as long as the failure does.
+
+// standDownUnusedSelfCheck flips SelfCheck to false on every urltest group in
+// opts that the observatory's used-set does not cover, and returns how many it
+// stood down (for the apply log and the tests). Selector groups are left alone
+// — they have no self-check to stand down — and a group any rule, route.Final
+// or DNS detour reaches keeps its default (nil == on).
+//
+// It MUTATES the option structs the caller handed in: opts.Outbounds carries
+// the generator's option values as pointers behind an `any` (the generator
+// always emits *option.URLTestOutboundOptions), so writing through them changes
+// the caller's config. That is deliberate, not an accident to guard against:
+// the plan is the single source of what gets probed, and the config that
+// reaches box.New must already say so — a copy-on-write here would build a box
+// whose groups probe paths the hash and the plan claim nobody probes. It runs
+// BEFORE hashOptions in applyLocked for the same reason: the hash must describe
+// what is really built, so a rule change that flips a group used<->unused is a
+// real config change and triggers a swap.
+//
+// A urltest outbound whose Options is not the expected pointer type (a value,
+// or something foreign) is skipped rather than guessed at: it did not come from
+// our generator, and silently rebuilding somebody else's option struct is worse
+// than leaving one group's self-check up.
+// It also RETURNS the used-set it computed. That set is needed before the new
+// box starts — a group's PostStart asks whether it must keep measuring with no
+// traffic (Engine.ProbeWhenIdle), and the observatory does not publish its own
+// copy until after the swap has succeeded. Handing back the walk that has
+// already run here is cheaper than a second one and, more to the point, cannot
+// disagree with the flags just written from it.
+func standDownUnusedSelfCheck(opts option.Options) (int, map[string]bool) {
+	_, used := BuildObservatoryPlan(opts, "")
+	stood := 0
+	for i := range opts.Outbounds {
+		ob := &opts.Outbounds[i]
+		if ob.Type != C.TypeURLTest || used[ob.Tag] {
+			continue
+		}
+		utOpts, ok := ob.Options.(*option.URLTestOutboundOptions)
+		if !ok {
+			continue
+		}
+		// One fresh pointer per group, so no two option structs alias a shared
+		// bool that a later caller could flip for both at once.
+		off := false
+		utOpts.SelfCheck = &off
+		stood++
+	}
+	return stood, used
+}

shater/engine/selfcheck_test.go

@@ -0,0 +1,224 @@
+package engine
+
+import (
+	"testing"
+
+	C "github.com/sagernet/sing-box/constant"
+	"github.com/sagernet/sing-box/option"
+)
+
+// standDownUnusedSelfCheck is the enforcement half of the one-probe rule: a
+// urltest group no rule reaches gets SelfCheck=false written into its option
+// struct (in place — the struct the box will be built from), a rule-reachable
+// one keeps its nil default, and selectors are never touched at all (they have
+// no self-check to stand down). The count it returns is what applyLocked logs.
+func TestStandDownUnusedSelfCheck(t *testing.T) {
+	opts := option.Options{
+		Outbounds: []option.Outbound{
+			fixNode("n1", ""),
+			fixNode("idle1", ""),
+			fixNode("pin1", ""),
+			// Reached by a rule: must keep probing itself.
+			fixGroup(C.TypeURLTest, "auto", "n1"),
+			// Reached by nothing: its self-check dials a path nobody uses and
+			// must be stood down.
+			fixGroup(C.TypeURLTest, "idle", "idle1"),
+			// A selector reached by nothing: left alone — no self-check exists.
+			fixGroup(C.TypeSelector, "pins", "pin1"),
+		},
+		Route: fixRoute("auto"),
+	}
+
+	stood, used := standDownUnusedSelfCheck(opts)
+	if stood != 1 {
+		t.Fatalf("stood down %d group(s), want exactly 1 (idle)", stood)
+	}
+	// The returned used-set is the SAME walk the flags were written from — the
+	// engine publishes it for ProbeWhenIdle before the new box is built, so the
+	// two statements about one group ("keeps its self-check", "keeps it warm")
+	// can never be computed from two different reachability answers.
+	if !used["auto"] || used["idle"] {
+		t.Errorf("used-set = %v, want the reached group in and the unreached one out", used)
+	}
+
+	find := func(tag string) option.Outbound {
+		t.Helper()
+		for _, ob := range opts.Outbounds {
+			if ob.Tag == tag {
+				return ob
+			}
+		}
+		t.Fatalf("outbound %q missing from opts", tag)
+		return option.Outbound{}
+	}
+
+	// The unused urltest group: SelfCheck is now an explicit false in the very
+	// struct the caller handed in (the mutation is the point — the config that
+	// reaches box.New must say what the plan says).
+	idle := find("idle").Options.(*option.URLTestOutboundOptions)
+	if idle.SelfCheck == nil || *idle.SelfCheck {
+		t.Fatalf("idle group SelfCheck = %v, want an explicit false", idle.SelfCheck)
+	}
+
+	// The used urltest group keeps the nil default (self-check on): its probing
+	// travels the path traffic actually takes and is welcome.
+	auto := find("auto").Options.(*option.URLTestOutboundOptions)
+	if auto.SelfCheck != nil {
+		t.Fatalf("used group SelfCheck = %v, want nil (untouched default)", *auto.SelfCheck)
+	}
+
+	// The selector's option struct has no SelfCheck field at all; what is
+	// pinned here is that stand-down neither counted it nor mangled its type.
+	if _, ok := find("pins").Options.(*option.SelectorOutboundOptions); !ok {
+		t.Fatal("selector options were rebuilt; stand-down must leave selectors alone")
+	}
+
+	// Idempotence: a second pass finds the same one group (already-false is
+	// still counted — the function reports plan membership, not novelty) and
+	// changes nothing further. This is what keeps the apply hash stable across
+	// the every-minute reconcile.
+	if again, _ := standDownUnusedSelfCheck(opts); again != 1 {
+		t.Fatalf("second pass stood down %d, want 1 (deterministic on identical opts)", again)
+	}
+	if idle.SelfCheck == nil || *idle.SelfCheck {
+		t.Fatal("second pass flipped the idle group's SelfCheck back")
+	}
+}
+
+// TestStandDownNeverTouchesChainHopWrappers pins the property the production
+// config lives or dies by, DIRECTLY rather than transitively through the plan
+// tests: a CHAIN HOP WRAPPER group ("chain-<name>-h<i>", type urltest) must
+// NEVER be stood down.
+//
+// The failure mode this guards against is subtle and silent. The owner's live
+// rule routes through egress:ewan -> node:awgout -> group:sub0 -> group:sub1
+// -> group:sub2 — a chain whose group hops are rebuilt as urltest wrappers
+// over per-chain member copies. Those wrappers are the ONLY probing that
+// travels the real path: their own schedule is the on-path measurement, and
+// the selection inside the chain (which member each hop dials) depends on the
+// verdicts it writes. Reachability of a wrapper is established by walkDetour
+// (probeplan.go) walking the exit's Detour links — a DIFFERENT code path from
+// the root/member expansion the other tests exercise. If a future change to
+// that walk dropped the wrappers from the used-set, standDownUnusedSelfCheck
+// would obediently flip their SelfCheck off, the chain would stop measuring
+// itself, and nothing else would ever measure it: we would have replaced the
+// false reading this rework removed with NO reading at all. Both existing
+// tests could stay green while that happened — the plan test asserts the
+// used-set, not the stand-down; the stand-down test above never mentions
+// chains. This one closes that gap by asserting the stand-down's OUTPUT on
+// the production topology.
+//
+// The fixture mirrors what the generator actually emits for that config, not
+// a toy: an exit wrapper chain-p-h4 (urltest over member copies) whose copies
+// detour into chain-p-h3 (urltest), whose copies detour into chain-p-h2
+// (urltest), whose copies detour into chain-p-h1 (the plain AmneziaWG hop
+// copy), which detours into egress-ewan — the detour lives on the member
+// COPIES, not on the wrappers, exactly as generate/chain.go builds it. The
+// base groups sub0/sub1/sub2 are ALSO emitted, over the base node tags,
+// reached by nothing — which is precisely what buildGroups does today and
+// precisely the false direct prober the stand-down exists to silence.
+func TestStandDownNeverTouchesChainHopWrappers(t *testing.T) {
+	opts := option.Options{
+		Outbounds: []option.Outbound{
+			// The egress the whole chain leaves through.
+			fixUtility(C.TypeDirect, "egress-ewan"),
+			// L1: the plain AWG hop copy (in production an endpoint; a plain
+			// outbound here exercises the same walk — walkDetour treats both as
+			// non-group entries).
+			fixNode("chain-p-h1", "egress-ewan"),
+			// L2..L4: urltest group hop wrappers over per-chain member copies;
+			// each COPY detours into the previous hop.
+			fixNode("chain-p-h2-a", "chain-p-h1"),
+			fixNode("chain-p-h2-b", "chain-p-h1"),
+			fixGroup(C.TypeURLTest, "chain-p-h2", "chain-p-h2-a", "chain-p-h2-b"),
+			fixNode("chain-p-h3-a", "chain-p-h2"),
+			fixNode("chain-p-h3-b", "chain-p-h2"),
+			fixGroup(C.TypeURLTest, "chain-p-h3", "chain-p-h3-a", "chain-p-h3-b"),
+			fixNode("chain-p-h4-a", "chain-p-h3"),
+			fixNode("chain-p-h4-b", "chain-p-h3"),
+			fixGroup(C.TypeURLTest, "chain-p-h4", "chain-p-h4-a", "chain-p-h4-b"),
+			// The base nodes and the base groups over them: emitted alongside
+			// the chain, reached by no rule — the generator keeps emitting them
+			// today, and they are exactly the direct-WAN probers that poisoned
+			// the board.
+			fixNode("a", ""),
+			fixNode("b", ""),
+			fixGroup(C.TypeURLTest, "sub0", "a", "b"),
+			fixGroup(C.TypeURLTest, "sub1", "a", "b"),
+			fixGroup(C.TypeURLTest, "sub2", "a", "b"),
+		},
+		// One rule, targeting the chain's exit wrapper — the production shape.
+		Route: fixRoute("", "chain-p-h4"),
+	}
+
+	stood, used := standDownUnusedSelfCheck(opts)
+	if stood != 3 {
+		t.Fatalf("stood down %d group(s), want exactly the 3 base groups sub0/sub1/sub2", stood)
+	}
+	// The hop wrappers are also what ProbeWhenIdle must say yes to: the chain is
+	// reached by a rule, so its hops keep measuring whether or not traffic is
+	// crossing them. The base groups behind them are not, and must not.
+	for _, tag := range []string{"chain-p-h2", "chain-p-h3", "chain-p-h4"} {
+		if !used[tag] {
+			t.Errorf("used-set is missing hop wrapper %q; it would idle out with nothing to replace it", tag)
+		}
+	}
+	for _, tag := range []string{"sub0", "sub1", "sub2"} {
+		if used[tag] {
+			t.Errorf("used-set claims base group %q, which no rule reaches", tag)
+		}
+	}
+
+	utOptions := func(tag string) *option.URLTestOutboundOptions {
+		t.Helper()
+		for _, ob := range opts.Outbounds {
+			if ob.Tag == tag {
+				o, ok := ob.Options.(*option.URLTestOutboundOptions)
+				if !ok {
+					t.Fatalf("outbound %q is not a urltest group", tag)
+				}
+				return o
+			}
+		}
+		t.Fatalf("outbound %q missing from opts", tag)
+		return nil
+	}
+
+	// Every hop wrapper keeps its self-check: nil, the untouched default. An
+	// explicit false on ANY of these is the chain going blind.
+	for _, wrapper := range []string{"chain-p-h2", "chain-p-h3", "chain-p-h4"} {
+		if sc := utOptions(wrapper).SelfCheck; sc != nil {
+			t.Errorf("hop wrapper %q SelfCheck = %v, want nil — its own schedule IS the on-path measurement", wrapper, *sc)
+		}
+	}
+	// Every base group is stood down: nothing routes through them, and their
+	// probing would dial the base nodes over the direct WAN.
+	for _, base := range []string{"sub0", "sub1", "sub2"} {
+		if sc := utOptions(base).SelfCheck; sc == nil || *sc {
+			t.Errorf("base group %q SelfCheck = %v, want an explicit false", base, sc)
+		}
+	}
+
+	// And the reason the stand-down of sub0/sub1/sub2 is SAFE in this config:
+	// with the base groups silenced, the base node tags a/b have no measurement
+	// path at all — no job dials them and no job stores under them (the chain's
+	// member copies record only under themselves). Their board entries simply
+	// stop being written, honestly untested, instead of carrying a false
+	// direct-WAN verdict.
+	jobs, used := BuildObservatoryPlan(opts, "")
+	for _, baseTag := range []string{"a", "b"} {
+		if used[baseTag] {
+			t.Errorf("used-set claims base node %q; only the chain copies are on the path", baseTag)
+		}
+		for _, j := range jobs {
+			if j.Dial == baseTag {
+				t.Errorf("plan dials base node %q, which no rule reaches", baseTag)
+			}
+			for _, s := range j.Store {
+				if s == baseTag {
+					t.Errorf("job %q stores under base node %q; a chain copy must never alias its base", j.Dial, baseTag)
+				}
+			}
+		}
+	}
+}