installer-e2e.yml

# The 3-OS installer end-to-end contract test (dig_ecosystem#502).
#
# Every other CI job here (ci.yml) proves the installer's PURE logic (asset
# selection, the update decision, the JSON contract) with mocked resolvers and
# service backends. Neither dig-node's nor dig-dns's OWN "service-smoke" CI
# (their repos) covers what a real END USER actually runs: the `dig-installer`
# BINARY, installing BOTH services in one pass and reporting its own aggregate
# "DIG is ready" verdict (#493). This job drives exactly that, against the
# REAL OS service manager, on all three OSes DIG ships for:
#
#   build dig-installer -> run it (installing pinned dig-node + dig-dns +
#   dig-updater releases) -> assert the #493 fail-loud readiness verdict sees
#   BOTH services registered + RUNNING by their canonical id, the Windows SCM
#   display names read back correctly (#494), `dig.local` resolves (#140), AND
#   the auto-update beacon's daily scheduler artifact is registered by the
#   real OS scheduler (#514) -> run --uninstall-dig-node/--uninstall-dig-dns/
#   --uninstall-dig-updater -> assert both services are deregistered, the
#   hosts entry is gone, and the beacon's scheduler artifact is removed.
#
# dig_ecosystem#524: the dig-node/dig-dns versions below are PINNED to a
# specific released tag (never "latest"), so this job — like the two
# `tests/cli.rs` cases it mirrors — stays deterministic across either repo's
# release-in-progress window instead of racing GitHub's `/releases/latest`.
# Bump these deliberately when validating against a newer release.
# DIG_DNS_VERSION is pinned to 0.15.1, a stable release with all required
# binaries (dig-dns and digd) needed by the installer's default component set.
name: Installer e2e (install -> health -> uninstall)

on:
  pull_request:
    branches: [main]
    paths:
      - "src/**"
      - "tests/**"
      - "Cargo.toml"
      - "Cargo.lock"
      - ".github/workflows/installer-e2e.yml"
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  CARGO_TERM_COLOR: always
  DIG_NODE_VERSION: "0.29.0"
  DIG_DNS_VERSION: "0.15.1"
  # Auto-update beacon (#514) — pinned for the same determinism reason as the
  # two above (dig_ecosystem#524): a specific tagged release, never "latest".
  DIG_UPDATER_VERSION: "0.6.0"
  # Authenticates the installer's GitHub release-API lookups (never the asset
  # download itself) so this job doesn't race the unauthenticated 60/hour
  # per-IP cap GitHub Actions' shared runner pool routinely exhausts — see
  # `download::get_text_with_token` / SPEC.md §1's "Optional GitHub API
  # authentication" note.
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  e2e:
    name: install -> health -> uninstall (${{ matrix.os }})
    strategy:
      fail-fast: false
      matrix:
        os: [windows-latest, macos-14, ubuntu-latest]
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install Rust (stable)
        shell: bash
        run: |
          rustup toolchain install stable
          rustup default stable
          rustc --version

      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: ${{ runner.os }}-installer-e2e-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-installer-e2e-

      # dig-dns's default gateway loopback IP (127.0.0.5, SPEC S5) has no
      # alias on lo0 out of the box on macOS (unlike Linux/Windows, which
      # accept the whole 127.0.0.0/8 range) — without it the gateway can't
      # bind either its primary or fallback port, so dig-dns never reaches a
      # live resolution path (mirrors dig-dns's own service-smoke setup).
      - name: Alias the dig-dns loopback IP on lo0 (macOS)
        if: runner.os == 'macOS'
        run: sudo ifconfig lo0 alias 127.0.0.5 up

      - name: Build dig-installer (release)
        run: cargo build --release --locked --bin dig-installer

      - name: Resolve the built binary + a stable, HOME-independent bin dir
        shell: bash
        run: |
          if [ "${{ runner.os }}" = "Windows" ]; then
            echo "INSTALLER=$(pwd)/target/release/dig-installer.exe" >> "$GITHUB_ENV"
          else
            echo "INSTALLER=$(pwd)/target/release/dig-installer" >> "$GITHUB_ENV"
          fi
          if [ "${{ runner.os }}" != "Windows" ]; then
            # dig-dns's Linux systemd unit runs as a DEDICATED, unprivileged
            # service account (CAP_NET_BIND_SERVICE only, dns/linux.rs) —
            # `${{ runner.temp }}` lives under `/home/runner`, whose default
            # 0750 permissions that account cannot traverse (systemd reports
            # this as `status=203/EXEC`, a bare exec failure — found via this
            # job). `/opt` is world-traversable, matching what a real Linux
            # package (`.deb`) would install into. Root-owned 0755 also satisfies
            # the #565 H3 install-root ACL verify (no group/other write).
            #
            # macOS uses the same directory (#1748): `${{ runner.temp }}` lives
            # under `/Users/runner`, owned by uid 501, and an ELEVATED install
            # into a directory a non-root account owns is now refused outright —
            # correctly, since that account could replace a binary root executes.
            #
            # `/opt` itself is normalised to 755 FIRST. The GitHub runner image
            # ships it mode 777, and since #1748 the install-root verify walks
            # EVERY level: write permission on `/opt` is permission to rename
            # `/opt/dig-bin` aside and substitute an attacker-owned directory of
            # the same name, so a root-owned leaf under a world-writable parent is
            # correctly refused. Repairing the image's own `/opt` is the honest
            # fix here; the installer deliberately does not re-mode a directory
            # the distribution owns.
            sudo chmod 755 /opt
            # And the veneer: the runner image ships /usr/local/bin world-writable, which the install now
            # refuses because it is where root's PATH resolves DIG commands from (#1748 WU3).
            sudo chmod 755 /usr/local/bin && sudo chown 0:0 /usr/local/bin
            sudo mkdir -p /opt/dig-bin && sudo chmod 755 /opt/dig-bin
            echo "BIN_DIR=/opt/dig-bin" >> "$GITHUB_ENV"
          else
            # #565 H3: a privileged (service-executed) install into a custom
            # --bin-dir is now ACL-verified fail-loud, exactly like the protected
            # root — a LocalSystem service must not run a binary from a
            # user-writable dir. `${{ runner.temp }}` inherits a Users-writable
            # ACE, so harden this custom dir admin-only FIRST (mirror Program
            # Files' DACL + the root-owned Linux /opt/dig-bin above): SYSTEM +
            # Administrators full, Users read+execute, inheritance removed.
            # `MSYS_NO_PATHCONV=1` keeps git-bash from mangling icacls's
            # `/inheritance:r`/`/grant:r` flags (same pitfall as `schtasks /Query`).
            BIN_DIR="${{ runner.temp }}/dig-bin"
            mkdir -p "$BIN_DIR"
            MSYS_NO_PATHCONV=1 icacls "$(cygpath -w "$BIN_DIR")" /inheritance:r \
              /grant:r '*S-1-5-18:(OI)(CI)F' \
              /grant:r '*S-1-5-32-544:(OI)(CI)F' \
              /grant:r '*S-1-5-32-545:(OI)(CI)RX'
            echo "BIN_DIR=$BIN_DIR" >> "$GITHUB_ENV"
          fi

      # The installer registers OS services and writes the hosts file — the
      # SAME Administrator/root requirement a real end-user install needs
      # (elevation.rs's pre-install guard, #492). GitHub's hosted Windows
      # runner already executes as Administrator (mirrors dig-node's/
      # dig-dns's own service-smoke jobs, which need no elevation dance
      # either); Linux/macOS need `sudo` (passwordless on hosted runners).
      # `-E` preserves the invoking user's HOME/USER so daemon_dir's
      # SUDO_USER-scoped read ACL (#501) resolves the real interactive
      # account rather than root's.
      - name: Elevate on Linux/macOS
        if: runner.os != 'Windows'
        run: echo "SUDO=sudo -E" >> "$GITHUB_ENV"

      # dig-node's own `install` prefers a USER-level systemd unit on Linux
      # regardless of privilege (dig-node's service.rs `PREFERS_USER_LEVEL`,
      # a deliberate no-elevation-needed design) — but the elevated run above
      # makes dig-node's subprocess execute AS ROOT (uid 0), which has no
      # systemd/D-Bus user session of its own by default, so `systemctl
      # --user` fails ("Failed to connect to bus: Operation not permitted",
      # dig_ecosystem#524 finding). Fix: give root its OWN lingering user
      # session (mirrors dig-node's own service-smoke.yml, which does the
      # same for its unprivileged runner-user run) and point every later
      # step's `XDG_RUNTIME_DIR` at it so both the elevated install AND this
      # job's own verification/uninstall queries can reach it.
      - name: (Linux) bring up a systemd/D-Bus user session for root
        # This workaround stays HERE and only here, deliberately. This leg passes
        # `--bin-dir`, which #565 FORCES to user scope, so the unit really is
        # per-user and reading it really does need root to have a session bus —
        # the workaround is load-bearing for THIS leg's shape, not a leftover.
        #
        # It is the DEFAULT-path install that must never need it, and that is
        # asserted in the `system-scope-e2e` job below, which carries no linger
        # and fails if the install turns it on. Removing it here would only break
        # a leg whose scope is forced, while proving nothing about #526.
        if: runner.os == 'Linux'
        run: |
          sudo loginctl enable-linger root
          sudo systemctl start user@0.service
          for _ in $(seq 1 10); do
            [ -S "/run/user/0/bus" ] && break
            sleep 1
          done
          echo "XDG_RUNTIME_DIR=/run/user/0" >> "$GITHUB_ENV"

      # #1748 REGRESSION GATE (part 1 of 2): reproduce the precondition that broke
      # dig-app autostart. An earlier PRIVILEGED step leaves root-owned levels in the
      # target user's XDG config chain -- `sudo -E` leaks
      # XDG_CONFIG_HOME=/home/runner/.config into the root process, and a
      # `systemctl --user` run as root then creates `.config/systemd/user` as root:root
      # (observed in run 30402180957). `mkdir -p` is then a silent no-op and only the
      # redirect fails, so the unit is never written while the install still reports
      # ready. Created explicitly here so the ordering is driven by THIS job rather than
      # by whatever a future dig-node happens to do.
      - name: (Linux) #1748 precondition — an earlier component leaves a root-owned XDG level
        if: runner.os == 'Linux'
        run: |
          sudo mkdir -p /home/runner/.config/systemd/user
          sudo chown root:root /home/runner/.config/systemd /home/runner/.config/systemd/user
          ls -ldn /home/runner/.config /home/runner/.config/systemd /home/runner/.config/systemd/user

      # digstore is out of THIS contract's scope (it has its own installed-
      # binary integration tests, CLAUDE.md §3.5) — skipped here to keep the
      # run focused on the dig-node + dig-dns service contract #502 tracks.
      # A CI runner is not an interactive desktop, and dig_ecosystem#919 makes the installer SKIP
      # dig-app's login autostart on a host with no graphical session — correctly, since a tray agent
      # has nowhere to appear and an `HKCU\…\Run` value written from Session 0 belongs to nobody who
      # logs in. Both facts below are the ones the installer reads, named here so this job exercises
      # the REGISTERING path (the write, its ownership, and the artifact location) rather than the
      # skip. The skip itself is covered by `autostart::tests` for all three operating systems.
      - name: Represent an interactive desktop session, so the autostart write path is exercised
        shell: bash
        run: |
          if [ "$RUNNER_OS" = "Linux" ]; then
            echo "DISPLAY=:99" >> "$GITHUB_ENV"
          elif [ "$RUNNER_OS" = "Windows" ]; then
            echo "SESSIONNAME=Console" >> "$GITHUB_ENV"
          fi

      - name: Install (dig-node + dig-dns + the auto-update beacon, pinned versions)
        run: |
          $SUDO "$INSTALLER" \
            --no-digstore \
            --dig-node-version "$DIG_NODE_VERSION" \
            --dig-dns-version "$DIG_DNS_VERSION" \
            --dig-updater-version "$DIG_UPDATER_VERSION" \
            --bin-dir "$BIN_DIR" \
            --json | tee install.json

      # Diagnostics only — never gates the job (`if: always()`). Surfaces the
      # REAL systemd-level reason if dig-node's `--user` unit reports
      # anything other than active, since svc.rs's health check only sees
      # is-active's one-word verdict, not WHY. Queries the REAL unit name
      # (`dignetwork-dig-node`, see `svc::linux_unit_name` — the
      # `service-manager` crate drops the "net" qualifier on Linux, #524),
      # never the canonical `net.dignetwork.dig-node` id Windows/macOS use.
      - name: (Linux) diagnose the dig-node --user unit's real systemd state
        if: always() && runner.os == 'Linux'
        run: |
          echo "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR"
          sudo -E systemctl --user status dignetwork-dig-node --no-pager -l || true
          sudo -E systemctl --user list-units --all --no-pager | grep -i dig || true
          sudo -E journalctl --user -u dignetwork-dig-node --no-pager -n 60 || true

      - name: (Linux) diagnose the dig-dns system unit's real systemd state
        if: always() && runner.os == 'Linux'
        run: |
          sudo systemctl status dignetwork-dig-dns --no-pager -l || true
          sudo journalctl -u dignetwork-dig-dns --no-pager -n 60 || true
          sudo ss -ltnp 2>/dev/null | grep -i ':80\|:8053' || true

      # #1748 REGRESSION GATE (part 2 of 2): dig-app MUST be registered to start at
      # login. Nothing asserted this before, which is exactly why the regression was
      # invisible -- autostart is best-effort, so `ready` stayed true while dig-app
      # would never start. A tray agent that installs and never launches is the failure
      # this contract exists to prevent, one layer over.
      - name: Assert dig-app autostart registered (#1748), or a REPORTED skip (#919)
        run: |
          jq -c '.result.autostart' install.json
          # Registered, or skipped for a stated reason — and NEVER "not registered with no reason",
          # which is what a genuine registration failure looks like. The step above names a session,
          # so a green run here is the REGISTERED arm; the disjunction exists so a runner image
          # change surfaces as a legible outcome instead of an unexplained red.
          jq -e '.result.autostart
                 | (.registered == true and .disposition == "register")
                   or (.registered == false
                       and (.disposition == "skip-headless" or .disposition == "skip-no-target-user"))' install.json
          # This job names a session, so the registering arm is the one that must be taken.
          jq -e '.result.autostart.registered == true' install.json
          jq -e '.result.autostart.disposition == "register"' install.json

      # And on Linux the artifact must really exist AND belong to the invoking user --
      # a unit root owns is one `systemd --user` declines to load, so ownership is part
      # of the property, not a nicety.
      - name: (Linux) Assert the XDG autostart entry exists, is owned by the invoking user, and no stale unit remains
        if: runner.os == 'Linux'
        run: |
          entry=/home/runner/.config/autostart/dig-app.desktop
          ls -ldn "$entry" /home/runner/.config/autostart
          test -f "$entry"
          owner=$(stat -c %u "$entry")
          test "$owner" = "$(id -u runner)" || {
            echo "entry is owned by uid $owner, not by runner"
            exit 1
          }
          dir_owner=$(stat -c %u /home/runner/.config/autostart)
          test "$dir_owner" = "$(id -u runner)" || {
            echo "entry DIR is owned by uid $dir_owner, not by runner"
            exit 1
          }
          # #919: the mechanism must be one that STARTS something. A desktop entry is loaded at login
          # with no enable step; the systemd user unit earlier versions wrote never was, so it must be
          # gone rather than sitting alongside this and producing two agents at the next login.
          grep -q '^Exec=' "$entry"
          test ! -e /home/runner/.config/systemd/user/dig-app.service || {
            echo "the stale systemd user unit is still present — two autostarts at next login"
            exit 1
          }

      - name: Assert the #493 fail-loud readiness verdict — both components ready
        run: |
          jq -e '.ok == true' install.json
          jq -e '.result.ready == true' install.json
          jq -e '.result.failures == []' install.json

      # #1774: dig-app must resolve a build this host can actually LOAD, on the
      # default path — never the GTK-linked build handed over by the old
      # shortest-name tiebreak that dies inside `ld.so` before `main` (#1753).
      # The variant CHOSEN is incidental here (stock ubuntu-latest may lack
      # libxdo.so.3, so even it can fall through to `-headless`) — the property is
      # that a loadable, non-refused build was selected. The genuinely GTK-less
      # `headless-linux-e2e` job below pins the `-headless` choice explicitly.
      - name: Assert dig-app resolved a loadable, non-refused build (#1774)
        run: |
          DIGAPP='.result.components[] | select(.component=="dig-app")'
          jq -e "[$DIGAPP] | length == 1" install.json
          jq -e "$DIGAPP | has(\"refused\") | not" install.json
          jq -e "$DIGAPP | .selected_variant != null" install.json
      - name: (Linux) Assert the selected dig-app build is loadable and its DT_NEEDED resolve (#1774)
        if: runner.os == 'Linux'
        run: |
          DIGAPP='.result.components[] | select(.component=="dig-app")'
          jq -e "$DIGAPP | .loadable == true" install.json
          dest=$(jq -r "$DIGAPP | .dest" install.json)
          echo "placed dig-app at: $dest"
          # The install verdict said loadable by PARSING; prove it on the host too —
          # no DT_NEEDED of the placed binary may resolve to "not found".
          if ldd "$dest" 2>&1 | grep -i "not found"; then
            echo "FAIL: the placed dig-app build has unresolved shared libraries"
            exit 1
          fi

      # #565: the install root a privileged service runs from was actually
      # ACL-verified admin-only (not merely assumed), and no privileged
      # registration's binPath resolves under a legacy/user-writable root.
      # The audit + migration now run on this `--bin-dir` privileged leg too
      # (#565 H3 completion — the gate is `installs_a_privileged_binary`, not the
      # `--bin-dir`-false `installs_a_protected_component`), so the audit array is
      # NON-EMPTY here: assert that explicitly so the `under_legacy_root` check is
      # meaningful, not vacuously true over an empty list.
      - name: Assert the #565 install-root is verified admin-only + the audit ran with no legacy-bound registration
        run: |
          jq -e '.result.install_root_security.checked == true' install.json
          jq -e '.result.install_root_security.secure == true' install.json
          jq -e '(.result.registration_audit | length) > 0' install.json
          jq -e '[.result.registration_audit[] | select(.under_legacy_root)] | length == 0' install.json

      # #623/#858: the installer provisions the privileged TLS root so dig-node can serve HTTPS on
      # https://dig.local instead of plaintext. Assert the reported provisioning first (cross-OS, from
      # the JSON), then — on unix, where the layout + ownership are directly checkable — that the root
      # is REALLY root-owned 0700 with the CA + leaf present and the CA private key owner-only. This
      # verifies THIS installer's deliverable; the dig-node-side "HTTPS listening" log depends on the
      # pinned dig-node version consuming the root (coordinated separately) and is not asserted here.
      - name: Assert the privileged TLS root was provisioned (#623/#858)
        run: |
          jq -e '.result.tls_root.created == true' install.json
          jq -e '.result.tls_root.ca_minted == true' install.json
      - name: Assert the TLS root is root-owned 0700 with a CA + leaf (unix, #623/#858)
        if: runner.os != 'Windows'
        run: |
          set -e
          root=/etc/dig/tls
          # The root is deliberately 0700 root-owned — it holds the CA private key, so an unprivileged
          # user must not be able to descend into it. That is exactly why the file checks below run under
          # `sudo`: resolving `$root/ca.crt` needs SEARCH permission on the 0700 dir, which only root has.
          # A plain `test -f "$root/ca.crt"` fails on permission (not absence) and would falsely read as
          # "missing" against a correctly locked-down root. The install itself ran with `$SUDO`, so we
          # inspect its output the same way. `stat` on the dir inode only needs search on /etc/dig (0755),
          # but running it under sudo too keeps the whole assertion uniform.
          sudo test -d "$root" || { echo "TLS root $root missing"; exit 1; }
          owner=$(sudo stat -c %u "$root" 2>/dev/null || sudo stat -f %u "$root")
          test "$owner" = "0" || { echo "TLS root owned by uid $owner, not root"; exit 1; }
          mode=$(sudo stat -c %a "$root" 2>/dev/null || sudo stat -f %Lp "$root")
          test "$mode" = "700" || { echo "TLS root mode $mode, expected 700"; exit 1; }
          for f in ca.crt ca.key leaf.crt leaf.key; do
            sudo test -f "$root/$f" || { echo "missing $root/$f"; exit 1; }
          done
          keymode=$(sudo stat -c %a "$root/ca.key" 2>/dev/null || sudo stat -f %Lp "$root/ca.key")
          test "$keymode" = "600" || { echo "ca.key mode $keymode, expected 600"; exit 1; }

      # dig_ecosystem#526: the registration's SCOPE and its reboot survival are now reported, so the
      # e2e asserts them rather than only "installed". This leg passes `--bin-dir`, which is FORCED to
      # user scope (#565: a machine-wide daemon must never be pointed at a caller-selected path), so
      # the expected verdict here is user scope AND `survives_reboot: false` — stated positively, and
      # from both sides, so a run that silently registered machine-wide from a caller-chosen root
      # would FAIL here rather than look like an improvement.
      - name: Assert the reported service scope matches the --bin-dir contract (#526)
        if: runner.os != 'Windows'
        run: |
          jq -e '.result.service.scope == "user"' install.json
          jq -e '.result.service.survives_reboot == false' install.json
          jq -e '(.result.service.scope_note | length) > 0' install.json

      # Windows has no per-user service domain, so the SCM registration is machine-wide and DOES
      # survive a reboot with nobody logged in.
      - name: Assert the reported service scope is machine-wide on Windows (#526)
        if: runner.os == 'Windows'
        run: |
          jq -e '.result.service.scope == "system"' install.json
          jq -e '.result.service.survives_reboot == true' install.json

      - name: Assert dig-node registered + RUNNING by canonical id, dig.local resolves
        run: |
          jq -e '.result.service.installed == true' install.json
          jq -e '.result.service.health_checked == true' install.json
          jq -e '.result.service.health_ok == true' install.json
          jq -e '.result.service.dig_local_resolves == true' install.json

      - name: Assert dig-dns registered + RUNNING by canonical id, with a live resolution path
        run: |
          jq -e '.result.dns.installed == true' install.json
          jq -e '.result.dns.service_running == true' install.json
          jq -e '(.result.dns.paths_live | length) > 0' install.json

      - name: Assert the auto-update beacon's daily scheduler registered (#514)
        run: |
          jq -e '.result.beacon.applied == true' install.json
          if [ "${{ runner.os }}" = "Windows" ]; then
            test -f "$BIN_DIR/dig-updater.exe"
            test -f "$BIN_DIR/dig-updater-worker.exe"
          else
            test -f "$BIN_DIR/dig-updater"
            test -f "$BIN_DIR/dig-updater-worker"
          fi

      # `MSYS_NO_PATHCONV=1` is REQUIRED: git-bash's automatic POSIX-path
      # conversion mistakes `/Query` for a Unix-style absolute path and
      # rewrites it to `<git-install-root>/Query`, so a bare
      # `schtasks.exe /Query /TN …` fails with "Invalid argument/option -
      # 'C:/Program Files/Git/Query'" — confirmed live on this exact job
      # (dig_ecosystem#514). Every OTHER `sc.exe`/`schtasks`-style call in this
      # file uses positional (non-`/flag`) args, so this is the first one to
      # trip the well-known MSYS argv-mangling pitfall.
      - name: Windows — the beacon's Scheduled Task is registered (#514)
        if: runner.os == 'Windows'
        run: MSYS_NO_PATHCONV=1 schtasks.exe /Query /TN '\DIG\dig-updater'

      - name: Linux — the beacon's systemd timer is enabled (#514)
        if: runner.os == 'Linux'
        run: systemctl is-enabled dig-updater.timer

      - name: macOS — the beacon's LaunchDaemon is loaded (#514)
        if: runner.os == 'macOS'
        run: sudo launchctl print system/net.dignetwork.dig-updater

      - name: Windows — verify the SCM display names via `sc qc` (#494)
        if: runner.os == 'Windows'
        run: |
          # `grep` over a HERE-STRING rather than a pipe: a matching `grep -q` exits early and SIGPIPEs its
          # producer, which under `pipefail` fails the step after the assertion has already passed.
          NODE_QC="$(sc.exe qc net.dignetwork.dig-node)"
          echo "$NODE_QC"
          grep -q "DIG NETWORK: NODE" <<< "$NODE_QC"
          DNS_QC="$(sc.exe qc net.dignetwork.dig-dns)"
          echo "$DNS_QC"
          grep -q "DIG NETWORK: DNS" <<< "$DNS_QC"

      - name: Windows — both services RUNNING per `sc query` (belt-and-braces)
        if: runner.os == 'Windows'
        run: |
          # Captured first, then matched: see the `sc qc` step above for why a pipe into `grep -q` is unsafe.
          grep -q "RUNNING" <<< "$(sc.exe query net.dignetwork.dig-node)"
          grep -q "RUNNING" <<< "$(sc.exe query net.dignetwork.dig-dns)"

      - name: Linux — both units active per `systemctl` (belt-and-braces)
        if: runner.os == 'Linux'
        run: |
          # Real Linux unit names, NOT the canonical dotted id (svc::linux_unit_name /
          # dns::plan::service_script_name, #524): the "net" qualifier is dropped and
          # {organization}-{application} hyphen-joined for BOTH services (the
          # service-manager crate's ServiceLabel::to_script_name(), which every
          # dig-node/dig-dns Linux registration in this workspace goes through) --
          # dig-node -> dignetwork-dig-node, dig-dns -> dignetwork-dig-dns. dig-node is
          # USER-level under root's own session (see the "bring up a systemd/D-Bus
          # user session for root" step above); dig-dns is machine-wide (#494). `-E`
          # carries this job's XDG_RUNTIME_DIR override to root's shell.
          sudo -E systemctl --user is-active dignetwork-dig-node
          systemctl is-active dignetwork-dig-dns

      - name: macOS — both jobs running per `launchctl` (belt-and-braces)
        if: runner.os == 'macOS'
        run: |
          # `launchctl print` emits multi-KB output and the match is near the top, so a piped `grep -q`
          # SIGPIPEs it almost every time — the most likely of these to fail after passing.
          grep -q "state = running" <<< "$(sudo launchctl print system/net.dignetwork.dig-node)"
          grep -q "state = running" <<< "$(sudo launchctl print system/net.dignetwork.dig-dns)"

      - name: Uninstall dig-node via the installer flag + assert deregistered
        run: |
          $SUDO "$INSTALLER" --uninstall-dig-node --bin-dir "$BIN_DIR" --json | tee uninstall-node.json
          jq -e '.result.uninstalled == true' uninstall-node.json
          jq -e '.result.dig_local_removed == true' uninstall-node.json

      - name: Uninstall dig-dns via the installer flag + assert deregistered
        run: |
          $SUDO "$INSTALLER" --uninstall-dig-dns --json | tee uninstall-dns.json
          jq -e '.result.uninstalled == true' uninstall-dns.json

      - name: Uninstall the auto-update beacon's scheduler via the installer flag + assert removed (#514)
        run: |
          $SUDO "$INSTALLER" --uninstall-dig-updater --bin-dir "$BIN_DIR" --json | tee uninstall-updater.json
          jq -e '.result.applied == true' uninstall-updater.json

      - name: Windows — the beacon's Scheduled Task is gone
        if: runner.os == 'Windows'
        run: |
          ! MSYS_NO_PATHCONV=1 schtasks.exe /Query /TN '\DIG\dig-updater'

      - name: Linux — the beacon's systemd timer is gone
        if: runner.os == 'Linux'
        run: |
          ! systemctl cat dig-updater.timer

      - name: macOS — the beacon's LaunchDaemon is gone
        if: runner.os == 'macOS'
        run: |
          ! sudo launchctl print system/net.dignetwork.dig-updater

      - name: Windows — both services gone per `sc query`
        if: runner.os == 'Windows'
        run: |
          ! sc.exe query net.dignetwork.dig-node
          ! sc.exe query net.dignetwork.dig-dns

      - name: Linux — both units gone per `systemctl`
        if: runner.os == 'Linux'
        run: |
          ! sudo -E systemctl --user cat dignetwork-dig-node.service
          ! systemctl cat dignetwork-dig-dns.service

      - name: macOS — both jobs gone per `launchctl`
        if: runner.os == 'macOS'
        run: |
          ! sudo launchctl print system/net.dignetwork.dig-node
          ! sudo launchctl print system/net.dignetwork.dig-dns

      - name: Assert the dig.local hosts entry is gone
        run: |
          if [ "${{ runner.os }}" = "Windows" ]; then
            HOSTS_FILE="/c/Windows/System32/drivers/etc/hosts"
          else
            HOSTS_FILE="/etc/hosts"
          fi
          ! grep -q "dig.local" "$HOSTS_FILE"

      - name: Upload diagnostics
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: installer-e2e-${{ matrix.os }}
          path: |
            install.json
            uninstall-node.json
            uninstall-dns.json
            uninstall-updater.json
          if-no-files-found: ignore

  # dig_ecosystem#1774: a genuinely GTK-less host must install a dig-app build it
  # can actually LOAD.
  #
  # The `e2e` job runs on stock `ubuntu-latest`, which ships libgtk-3 — so it
  # cannot prove the fall-through, only that SOME loadable build was chosen. This
  # job runs the whole install inside a `debian:bookworm-slim` container with NO
  # GTK3 installed, which is exactly the #1753 headless-server shape: the GTK
  # `tray` build's `DT_NEEDED` (libgtk-3.so.0, …) resolve to nothing, so the
  # loadability-driven selector MUST fall through to the `-headless` build and
  # report it loadable — never place the GTK build that dies before `main`.
  #
  # The install runs INSIDE the container (not a host-built binary shipped in) so
  # the installer's own glibc matches the box it inspects. Only dig-app is
  # installed (per-user, no services) to keep the leg fast + focused.
  headless-linux-e2e:
    name: "#1774 a GTK-less host installs the headless dig-app build (debian:bookworm-slim)"
    runs-on: ubuntu-latest
    container:
      image: debian:bookworm-slim
    timeout-minutes: 20
    defaults:
      run:
        shell: bash
    permissions:
      contents: read
    env:
      CARGO_TERM_COLOR: always
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # rustup/cargo live under a writable HOME inside the container.
      CARGO_HOME: /root/.cargo
      RUSTUP_HOME: /root/.rustup
    steps:
      # curl + ca-certificates: fetch rustup and the GitHub release assets.
      # gcc + build-essential: native deps (ring) compile. git: the Cargo.toml
      # `dig-cert` git dependency. jq: the JSON assertions. Deliberately NO
      # libgtk-3 — a GTK-less box is the whole point of this leg.
      - name: Install build prerequisites (NO GTK)
        run: |
          apt-get update
          apt-get install -y --no-install-recommends \
            curl ca-certificates gcc build-essential git jq pkg-config
          # Prove the box really lacks GTK3 — if a base-image change ever adds it,
          # this leg would silently stop testing the fall-through.
          if ldconfig -p | grep -qi 'libgtk-3'; then
            echo "FAIL: this container unexpectedly ships libgtk-3 — the fall-through is not exercised"
            exit 1
          fi

      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install Rust (stable)
        run: |
          curl -fsSL https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
          echo "$CARGO_HOME/bin" >> "$GITHUB_PATH"

      - name: Build dig-installer (release)
        run: cargo build --release --locked --bin dig-installer

      - name: A stable, root-owned bin dir under a world-traversable /opt
        run: |
          # /opt in a fresh debian image is root-owned 0755, satisfying the #1748
          # install-root chain verify. --bin-dir places dig-app here.
          chmod 755 /opt
          mkdir -p /opt/dig-bin && chmod 755 /opt/dig-bin
          echo "BIN_DIR=/opt/dig-bin" >> "$GITHUB_ENV"

      # dig-app only: per-user, no OS-service registration, so no elevation dance
      # and no systemd needed (the container has no init). The run is root (uid 0),
      # which satisfies the elevation gate for the nothing-privileged plan.
      - name: Install dig-app on the GTK-less host
        run: |
          ./target/release/dig-installer \
            --no-digstore --no-dig-node --no-dig-dns --no-auto-update \
            --bin-dir "$BIN_DIR" \
            --json | tee install.json

      - name: Assert dig-app fell through to the -headless build and it is loadable (#1774)
        run: |
          DIGAPP='.result.components[] | select(.component=="dig-app")'
          # Exactly one dig-app component, and it was NOT refused (a refusal would
          # mean NO build loaded — the headless build must have).
          jq -e "[$DIGAPP] | length == 1" install.json
          jq -e "$DIGAPP | has(\"refused\") | not" install.json
          # THE property: a GTK-less host selects the headless build, proven loadable.
          jq -e "$DIGAPP | .selected_variant == \"headless\"" install.json
          jq -e "$DIGAPP | .loadable == true" install.json
          # And the chosen asset name really is the -headless artifact.
          jq -e "$DIGAPP | .asset | test(\"-headless\")" install.json

      - name: Prove the placed headless build's DT_NEEDED resolve on this GTK-less box
        run: |
          DIGAPP='.result.components[] | select(.component=="dig-app")'
          dest=$(jq -r "$DIGAPP | .dest" install.json)
          echo "placed dig-app at: $dest"
          ldd "$dest" || true
          if ldd "$dest" 2>&1 | grep -i "not found"; then
            echo "FAIL: the placed headless dig-app build has unresolved shared libraries"
            exit 1
          fi

      - name: Upload diagnostics
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: installer-headless-linux-e2e
          path: install.json
          if-no-files-found: ignore

  # #565 H3 — the seeded-legacy MIGRATION + DEFAULT-protected-root proof.
  #
  # The `e2e` job above installs with a custom `--bin-dir`, so it verifies the
  # audit/ACL on a CUSTOM dir and starts from a clean runner (nothing to migrate).
  # Two things that leaves uncovered — and both are the heart of #565: (1) the
  # DEFAULT protected root's own ACL (`%ProgramFiles%\DIG\bin`), and (2) the
  # MIGRATION of a pre-#565 install whose privileged registration still points at
  # a user-writable legacy root. This job covers both on Windows — the canonical
  # #565 threat surface the issue names (the SYSTEM `\DIG\dig-updater` beacon task
  # executing a binary a non-admin can replace).
  #
  # It SEEDS that exact pre-#565 shape (a SYSTEM beacon task whose binPath is under
  # `%LOCALAPPDATA%\Programs\DIG\bin`), installs the beacon into the DEFAULT
  # protected root with NO `--bin-dir`, and asserts the installer DEREGISTERED the
  # legacy-bound task, verified the default root admin-only, and re-registered the
  # beacon under the protected root. Beacon-only keeps it light + deterministic
  # (no long-running network services). This is what makes the migration + audit
  # assertions NON-VACUOUS — there is a real legacy registration to vacate.
  migrate-e2e:
    name: seeded-legacy migration into the default protected root (Windows)
    runs-on: windows-latest
    timeout-minutes: 15
    defaults:
      run:
        shell: bash
    env:
      CARGO_TERM_COLOR: always
      DIG_UPDATER_VERSION: "0.6.0"
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install Rust (stable)
        run: |
          rustup toolchain install stable
          rustup default stable
          rustc --version

      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: Windows-migrate-e2e-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
            Windows-migrate-e2e-
            Windows-installer-e2e-

      - name: Build dig-installer (release)
        run: cargo build --release --locked --bin dig-installer

      - name: Resolve the built binary
        run: echo "INSTALLER=$(pwd)/target/release/dig-installer.exe" >> "$GITHUB_ENV"

      # Seed a PRE-#565 install shape: a SYSTEM beacon scheduled task whose binary
      # lives in the user-writable legacy root (%LOCALAPPDATA%\Programs\DIG\bin) —
      # exactly the escalation #565 fixes (a non-admin could replace that
      # dig-updater.exe and the SYSTEM task would run it). The task id + legacy root
      # are the canonical ones the installer's migration reads back and vacates
      # (`regaudit::BEACON_WINDOWS_TASK` / `paths::legacy_privileged_roots`).
      # `MSYS_NO_PATHCONV=1` stops git-bash mangling schtasks's `/`-flags (the same
      # pitfall the beacon steps in the `e2e` job document).
      - name: Seed a legacy-bound SYSTEM beacon task (pre-#565 shape)
        run: |
          LEGACY_DIR="$LOCALAPPDATA/Programs/DIG/bin"
          mkdir -p "$LEGACY_DIR"
          # A dummy stand-in binary at the legacy path — never executed by the
          # installer (#565); only its PRESENCE + the task's binPath matter.
          printf '@echo off\r\n' > "$LEGACY_DIR/dig-updater.exe"
          LEGACY_WIN="$(cygpath -w "$LEGACY_DIR")\\dig-updater.exe"
          echo "LEGACY_DIR=$LEGACY_DIR" >> "$GITHUB_ENV"
          MSYS_NO_PATHCONV=1 schtasks.exe /Create /TN '\DIG\dig-updater' \
            /TR "\"$LEGACY_WIN\" run" /SC DAILY /ST 03:00 /RU SYSTEM /RL HIGHEST /F
          echo "Seeded task now resolves to:"
          MSYS_NO_PATHCONV=1 schtasks.exe /Query /TN '\DIG\dig-updater' /XML \
            > seeded-task.xml
          # NOT `| grep -q`: under `pipefail` a matching `grep -q` exits immediately, SIGPIPEs
          # schtasks, and the step fails with 141 having actually PASSED. Read the file instead.
          grep -i 'Programs.DIG.bin' seeded-task.xml > /dev/null

      # Install the beacon into the DEFAULT protected root (NO --bin-dir). The
      # hosted Windows runner is already Administrator (see the `e2e` job's note),
      # so no elevation dance is needed. The migration runs FIRST (it now gates on
      # `installs_a_privileged_binary`, which is true here), deregisters the seeded
      # legacy task, then the install re-registers the beacon from Program Files.
      - name: Install the auto-update beacon into the default protected root (no --bin-dir)
        run: |
          "$INSTALLER" \
            --no-digstore --no-dig-node --no-dig-dns \
            --dig-updater-version "$DIG_UPDATER_VERSION" \
            --json | tee install.json

      - name: Assert ready + the DEFAULT protected root is ACL-verified admin-only (#565)
        run: |
          jq -e '.ok == true' install.json
          jq -e '.result.ready == true' install.json
          jq -e '.result.failures == []' install.json
          jq -e '.result.install_root_security.checked == true' install.json
          jq -e '.result.install_root_security.secure == true' install.json
          # The verified root is the built-in Program Files root, not a custom dir.
          jq -e '.result.install_root_security.root | ascii_downcase | contains("program files")' install.json

      - name: Assert the migration DEREGISTERED the legacy-bound beacon task (#565 H1)
        run: |
          jq -e '.result.migration.migrated == true' install.json
          jq -e '[.result.migration.deregistered[] | select(ascii_downcase | contains("beacon"))] | length > 0' install.json
          jq -e '.result.migration | has("deregister_failures") and (.deregister_failures | length == 0)' install.json

      - name: Assert the audit ran + no privileged registration resolves under a legacy root (#565 H2b)
        run: |
          jq -e '(.result.registration_audit | length) > 0' install.json
          jq -e '[.result.registration_audit[] | select(.under_legacy_root)] | length == 0' install.json
          jq -e '.result.beacon.applied == true' install.json

      # The re-registered SYSTEM task now points UNDER Program Files, and the
      # migration removed the legacy dummy binary — the escalation is closed.
      - name: Assert the re-registered task points at the protected root + the legacy binary is gone
        run: |
          MSYS_NO_PATHCONV=1 schtasks.exe /Query /TN '\DIG\dig-updater' /XML \
            > migrated-task.xml
          # NOT `| grep -q`: under `pipefail` a matching `grep -q` exits immediately, SIGPIPEs
          # schtasks, and the step fails with 141 having actually PASSED. Read the file instead.
          grep -i 'Program Files.DIG.bin' migrated-task.xml > /dev/null
          test ! -f "$LEGACY_DIR/dig-updater.exe"

      - name: Cleanup — uninstall the beacon
        if: always()
        run: |
          "$INSTALLER" --uninstall-dig-updater --json | tee uninstall-updater.json || true
          MSYS_NO_PATHCONV=1 schtasks.exe /Delete /TN '\DIG\dig-updater' /F || true

      - name: Upload diagnostics
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: installer-migrate-e2e-windows
          path: |
            install.json
            uninstall-updater.json
            seeded-task.xml
            migrated-task.xml
          if-no-files-found: ignore

  # ---------------------------------------------------------------------------
  # dig_ecosystem#1854: what happens to a host's auto-updates when the #565
  # migration vacates a legacy-root beacon schedule on a run that DECLINED the
  # beacon?
  #
  # The Windows `migrate-e2e` job above installs WITH the beacon, so its run
  # re-registers the schedule at step 5 and `rearm_beacon_after_migration` returns
  # `None` on every CI run — no e2e reached the opt-out path at all, which is how
  # the whole branch shipped unexercised end to end.
  #
  # This leg drives the opt-out shape: a SYSTEM beacon timer whose ExecStart
  # resolves under the user-writable legacy root (`~/.dig/bin`), then an install
  # that says `--no-auto-update`. The migration MUST still vacate that schedule
  # (it is itself the #565 vulnerability), the run MUST stay READY (the beacon was
  # not part of what was asked for), and the resulting auto-updates-OFF state MUST
  # be REPORTED in `beacon_rearm` rather than swallowed.
  #
  # Linux only for now — the Windows + macOS parity legs are a sibling ticket.
  migrate-optout-e2e:
    name: "#1854 a declining run reports the auto-updates it lost (Linux)"
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        shell: bash
    permissions:
      contents: read
    env:
      CARGO_TERM_COLOR: always
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install Rust (stable)
        run: rustup toolchain install stable && rustup default stable

      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: ubuntu-1854-optout-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
            ubuntu-1854-optout-
            ubuntu-1748-reach-

      - name: Build the installer
        run: cargo build --release --locked --bin dig-installer

      # The runner image ships `/opt` world-writable, and the #1748 install-root
      # verify walks every ancestor — so an unrepaired image makes the install
      # report NOT ready for a reason unrelated to this leg. Repaired + asserted
      # exactly as the `#1748` job documents.
      - name: Normalise the runner image's world-writable /opt chain
        run: |
          sudo chmod 755 /opt /usr /usr/local /usr/local/bin
          sudo chown 0:0 /usr /usr/local /usr/local/bin
          for level in /opt /usr /usr/local /usr/local/bin; do
            test -z "$(find "$level" -maxdepth 0 \( -perm -0002 -o -perm -0020 \))" \
              || { echo "FAIL: $level is still group- or world-writable"; exit 1; }
          done

      # Seed the PRE-#565 shape on Linux: a machine-wide (root-run) dig-updater
      # timer whose service ExecStart lives in the INVOKING user's `~/.dig/bin` —
      # a directory that user can write, so the root timer would execute a binary
      # they can replace. `regaudit::beacon_bin_path` reads that ExecStart back via
      # `systemctl show`, which is what makes the migration act on it.
      # dig-node's own `install` prefers a USER-level systemd unit regardless of
      # privilege, and an elevated run executes it as uid 0, which has no user
      # session by default ("Failed to connect to bus: Operation not permitted",
      # dig_ecosystem#524). Same recipe the `e2e` job documents: give root its own
      # lingering session so the dig-node service registration succeeds and the run
      # can reach `ready` — otherwise this leg would red on #524, not on #1854.
      - name: Bring up a systemd/D-Bus user session for root
        run: |
          sudo loginctl enable-linger root
          sudo systemctl start user@0.service
          for _ in $(seq 1 10); do
            [ -S "/run/user/0/bus" ] && break
            sleep 1
          done
          echo "XDG_RUNTIME_DIR=/run/user/0" >> "$GITHUB_ENV"

      - name: Seed a legacy-root SYSTEM beacon timer (pre-#565 shape)
        run: |
          LEGACY_DIR="$HOME/.dig/bin"
          mkdir -p "$LEGACY_DIR"
          # A stand-in binary at the legacy path — never executed by the installer
          # (#565); only its PRESENCE and the unit's ExecStart matter.
          printf '#!/bin/sh\nexit 0\n' > "$LEGACY_DIR/dig-updater"
          chmod +x "$LEGACY_DIR/dig-updater"
          echo "LEGACY_DIR=$LEGACY_DIR" >> "$GITHUB_ENV"
          sudo tee /etc/systemd/system/dig-updater.service >/dev/null <<UNIT
          [Unit]
          Description=DIG auto-update beacon (seeded pre-#565 legacy-root shape)
          [Service]
          Type=oneshot
          ExecStart=$LEGACY_DIR/dig-updater run
          UNIT
          sudo tee /etc/systemd/system/dig-updater.timer >/dev/null <<'UNIT'
          [Unit]
          Description=DIG auto-update beacon daily check
          [Timer]
          OnCalendar=daily
          Unit=dig-updater.service
          [Install]
          WantedBy=timers.target
          UNIT
          sudo systemctl daemon-reload
          sudo systemctl enable --now dig-updater.timer
          echo "seeded ExecStart:"
          systemctl show -p ExecStart dig-updater.service | tee seeded-execstart.txt
          grep -F "$LEGACY_DIR/dig-updater" seeded-execstart.txt > /dev/null

      # DECLINE the beacon (`--no-auto-update`) while still installing a privileged
      # binary (dig-node, default-on) so the #565 migration gate fires. No
      # `--bin-dir`: the privileged root is the protected root, which is the only
      # root the re-arm is permitted to consider at all.
      - name: Install with the beacon DECLINED into the default protected root
        run: |
          sudo -E ./target/release/dig-installer \
            --no-digstore --no-dig-dns --no-dig-app --no-auto-update \
            --json | tee install.json

      - name: Assert the migration vacated the legacy-root beacon schedule (#565)
        run: |
          jq -e '.ok == true' install.json
          jq -e '.result.migration.migrated == true' install.json
          jq -e '[.result.migration.deregistered[] | select(ascii_downcase | contains("beacon"))] | length > 0' install.json
          jq -e '.result.migration | has("deregister_failures") and (.deregister_failures | length == 0)' install.json

      # THE #1854 acceptance assertions. `beacon_rearm` non-null is what proves the
      # opt-out path RAN and REPORTED — `null` is exactly the silent state the issue
      # was filed about, and is what this leg sees if the re-arm block is removed.
      - name: Assert the lost auto-updates are REPORTED, and the run is still ready
        run: |
          jq -e '.result.beacon_rearm != null' install.json \
            || { echo "FAIL: the declining run said nothing about the auto-updates it lost"; exit 1; }
          jq -e '.result.beacon_rearm | has("applied") and has("note")' install.json
          # Declining the beacon is NOT a readiness failure — the beacon was never
          # part of what this run was asked to install.
          jq -e '.result.ready == true' install.json
          jq -e '.result.failures == []' install.json

      # The escalation must be CLOSED, and asserted on the host rather than on the
      # report: this run declined the beacon and installs no other machine-wide
      # privileged registration, so `registration_audit` is legitimately EMPTY once
      # the schedule is vacated — a `select(.under_legacy_root) | length == 0`
      # filter would pass vacuously on an empty array and prove nothing. The
      # systemd + filesystem checks below cannot pass vacuously.
      - name: Assert the legacy-root escalation is closed on the host (#565)
        run: |
          jq -e '[.result.registration_audit[] | select(.under_legacy_root)] | length == 0' install.json
          # The run declined the beacon, so nothing may have re-installed it.
          jq -e '.result.beacon == null' install.json

          # The seeded root-run timer must no longer resolve at all. `systemctl disable`
          # alone leaves the unit file loadable, which is the defect this leg found.
          systemctl show -p LoadState dig-updater.timer | tee post-loadstate.txt
          grep -qx 'LoadState=loaded' post-loadstate.txt \
            && { echo "FAIL: the beacon timer is still loaded — the schedule was not vacated"; exit 1; }
          test ! -f /etc/systemd/system/dig-updater.timer \
            || { echo "FAIL: the beacon timer unit file survived the deregister"; exit 1; }
          # The .service fragment too: `beacon_is_registered` reads only the TIMER, so
          # dropping the .service removal is invisible to both the unit tests and the
          # LoadState check above, and the leftover unit is what a stray `systemctl start`
          # would run out of the legacy root.
          test ! -f /etc/systemd/system/dig-updater.service \
            || { echo "FAIL: the beacon .service unit file survived the deregister"; exit 1; }
          # And the user-writable binary the root timer used to execute is gone.
          test ! -f "$LEGACY_DIR/dig-updater" \
            || { echo "FAIL: the legacy dig-updater binary survived the migration"; exit 1; }

      - name: Cleanup — remove the seeded units + uninstall
        if: always()
        run: |
          sudo ./target/release/dig-installer --uninstall --json \
            | tee uninstall.json || true
          sudo systemctl disable --now dig-updater.timer || true
          sudo rm -f /etc/systemd/system/dig-updater.service /etc/systemd/system/dig-updater.timer
          sudo systemctl daemon-reload || true

      - name: Upload diagnostics
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: installer-migrate-optout-e2e-linux
          path: |
            install.json
            uninstall.json
            seeded-execstart.txt
            post-loadstate.txt
          if-no-files-found: ignore

  # ---------------------------------------------------------------------------
  # #1748: does the person who typed `sudo` actually end up with working CLIs?
  #
  # The `e2e` job above could not answer that, and passed against an install that
  # left everything in /root/.dig/bin. FOUR independent factors each hid it:
  #
  #   1. it passes `--bin-dir "$BIN_DIR"`, which bypasses `default_bin_dir()`
  #      entirely — the function that resolved `$HOME` was never called;
  #   2. it elevates with `sudo -E`, which PRESERVES the runner's `HOME`, so the
  #      `HOME=/root` inversion a real `curl | sudo sh` produces cannot occur;
  #   3. it manufactures a systemd user session for root (`loginctl enable-linger
  #      root` + `XDG_RUNTIME_DIR=/run/user/0`) that a real sudo install does not
  #      have; and
  #   4. every assertion runs AS ROOT, so a root-only PATH is never questioned.
  #
  # This job removes all four: the DEFAULT bin dir, `sudo -H` (which sets
  # HOME=/root exactly as sudo does for `curl | sudo sh`), no fabricated session,
  # and the acceptance assertions run as a NON-ROOT user in a FRESH LOGIN SHELL.
  #
  # Only the cheap CLI components are installed (`--no-dig-node --no-dig-dns
  # --no-auto-update`): the question here is reachability of user-facing binaries,
  # which needs no service registration, so the job stays fast.
  sudo-install-is-reachable-by-the-user:
    name: "#1748 a sudo install is reachable by the invoking user (non-root)"
    runs-on: ubuntu-latest
    timeout-minutes: 15
    defaults:
      run:
        shell: bash
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install Rust (stable)
        run: rustup toolchain install stable && rustup default stable

      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: ubuntu-1748-reach-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ubuntu-1748-reach-

      - name: Build the installer
        run: cargo build --release --bin dig-installer

      # `sudo -H` sets HOME=/root, which is what sudo does for the documented
      # `curl -fsSL https://dig.net/install.sh | sudo sh`. No `--bin-dir`, so the
      # real `default_bin_dir()` decision is exercised.
      # The runner image ships `/opt` mode 777, and since #1748 the install-root
      # verify walks EVERY level of the chain: write permission on `/opt` is
      # permission to rename `/opt/dig` aside and substitute an attacker-owned
      # directory of the same name, so a root-owned `/opt/dig/bin` beneath a
      # world-writable `/opt` is correctly refused. The installer does not re-mode
      # a directory the distribution owns, so the image's own `/opt` is repaired
      # here. Asserted, not assumed: if a future image ships it correctly this
      # still passes, and the check below proves the level really is safe.
      - name: Normalise the runner image's world-writable /opt and veneer chain
        run: |
          stat -c '%n %U %a' /opt /usr /usr/local /usr/local/bin
          # BOTH roots are shipped permissive by the runner image, and both are directories the installer
          # deliberately does not re-mode because the distribution owns them. /usr/local/bin matters as much
          # as /opt now: it is where root's own login PATH resolves DIG commands from, so an account that can
          # write it replaces a planted link and root runs whatever it points at. The image's own posture is
          # repaired here, and asserted rather than assumed.
          #
          # EVERY ANCESTOR, not just the leaf. `secure::verify_install_root` walks the whole chain (write
          # permission on `/usr/local` is permission to rename `/usr/local/bin` aside and substitute an
          # attacker-owned directory of the same name), so normalising only the leaf leaves the verdict at
          # the mercy of whatever the image happens to ship above it. It is not hypothetical: runner images
          # vary here, `/usr/local/bin` arrived `root 777` on one run and `runner 777` on the next, and the
          # walk reported `/usr` owned by uid 1001. Pinning the whole chain is what makes the veneer shape
          # this job asserts DETERMINISTIC rather than image-dependent.
          sudo chmod 755 /opt /usr /usr/local /usr/local/bin
          sudo chown 0:0 /usr /usr/local /usr/local/bin
          for level in /opt /usr /usr/local /usr/local/bin; do
            test "$(stat -c '%U' "$level")" = root \
              || { echo "FAIL: $level is still not root-owned"; exit 1; }
            test -z "$(find "$level" -maxdepth 0 \( -perm -0002 -o -perm -0020 \))" \
              || { echo "FAIL: $level is still group- or world-writable"; exit 1; }
          done

      - name: Install as root with HOME=/root and the DEFAULT bin dir
        run: |
          sudo -H ./target/release/dig-installer \
            --no-dig-node --no-dig-dns --no-auto-update --no-dig-app \
            --json | tee install.json
          echo "--- where did the binaries go? ---"
          ls -l /usr/local/bin/ | grep -Ei 'dig' || true
          echo "--- did anything land in root's home? ---"
          sudo ls -l /root/.dig/bin 2>/dev/null || echo "(nothing in /root/.dig/bin — correct)"

      # THE acceptance assertion, and the one the shipped bug would have failed:
      # a NON-ROOT user, in a FRESH LOGIN SHELL, must resolve and run the CLIs.
      # `su - $(id -un 1001)` is a login shell, so it reads /etc/profile and
      # /etc/profile.d/* exactly as the user's next terminal will.
      - name: A non-root user resolves + runs the CLIs in a fresh login shell
        run: |
          USER_NAME=$(id -un 1001)
          echo "asserting as: $USER_NAME"
          sudo su - "$USER_NAME" -c 'printf "login PATH: %s\n" "$PATH"'
          for cli in dig-store digs; do
            echo "--- $cli ---"
            sudo su - "$USER_NAME" -c "command -v $cli" \
              || { echo "FAIL: $cli is not on $USER_NAME's PATH"; exit 1; }
            sudo su - "$USER_NAME" -c "$cli --version" \
              || { echo "FAIL: $cli does not RUN for $USER_NAME"; exit 1; }
          done

      # THE PLACEMENT invariant, and the reason `/usr/local/bin` is a veneer:
      # root must never write to, or execute from, a directory a non-root account
      # can modify (Homebrew leaves `/usr/local/bin` group-writable). So every
      # binary an elevated install places lives in the root-owned protected root,
      # and `/usr/local/bin` holds only SYMLINKS. Asserted BOTH ways: a regression
      # that installs into the veneer again keeps `command -v` green above, so the
      # reachability assertion alone cannot see it.
      # The PLACEMENT invariant is unconditional; the REACHABILITY MECHANISM is a
      # measured choice, so it is asserted per the mechanism the run reported.
      #
      # `reachability_for()` picks `veneer_links` only when the veneer chain is
      # safe, and falls back to `direct_path_entry` — the protected root PREPENDED
      # onto the login PATH via /etc/profile.d — when it is not. That fallback is
      # #1748's own design, not a degradation: refusing to install is a refusal,
      # and planting a link in a directory an unprivileged account can write is
      # the escalation the whole task was about. The step above pins the veneer
      # chain so `veneer_links` is the branch that normally runs here.
      #
      # NEITHER branch is a free pass. Each asserts the full requirement for its
      # shape, an unrecognised value fails closed, and the placement + chain-posture
      # assertions below run either way. What #1748 actually requires — the invoking
      # non-root user reaches what was installed — is proven independently by the
      # login-shell step above, which runs before this one under both shapes.
      - name: Every binary lives in the protected root; reachability matches the reported mechanism
        run: |
          jq -e '(.result.components | length) > 0' install.json
          jq -e 'all(.result.components[]; .dest | startswith("/opt/dig/bin/"))' install.json \
            || { echo "FAIL: an elevated install placed a binary outside the protected root"; exit 1; }

          MECHANISM=$(jq -r '.result.reachability' install.json)
          echo "reported reachability mechanism: $MECHANISM"
          case "$MECHANISM" in
            veneer_links)
              # The veneer must hold ONLY symlinks into the protected root. Asserted
              # BOTH ways: a regression that installs a real binary into the veneer
              # again keeps `command -v` green above, so reachability cannot see it.
              jq -e '.result.veneer_security.secure == true' install.json \
                || { echo "FAIL: links were planted in a veneer the installer itself calls unsafe"; exit 1; }
              for cli in dig-store digs; do
                test -L "/usr/local/bin/$cli" \
                  || { echo "FAIL: /usr/local/bin/$cli must be a symlink, not an installed binary"; exit 1; }
                printf '%s -> %s\n' "$cli" "$(readlink -f "/usr/local/bin/$cli")"
                case "$(readlink -f "/usr/local/bin/$cli")" in
                  /opt/dig/bin/*) ;;
                  *) echo "FAIL: $cli link does not resolve into the protected root"; exit 1 ;;
                esac
              done
              jq -e '.result.path.dir == "/usr/local/bin"' install.json \
                || { echo "FAIL: report.path.dir must name the veneer under veneer_links"; exit 1; }
              ;;
            direct_path_entry)
              # The fallback's own requirements, and it is held to MORE than the
              # veneer branch, because falling back must not become the cheap way
              # to a green check.
              jq -e '.result.veneer_security.secure == false' install.json \
                || { echo "FAIL: fell back to a direct PATH entry from a veneer that was SAFE"; exit 1; }
              # 1. NOTHING may be planted in the veneer it declined to trust.
              for cli in dig-store digs; do
                test ! -e "/usr/local/bin/$cli" \
                  || { echo "FAIL: $cli was planted in /usr/local/bin the installer declined to trust"; \
                       ls -l "/usr/local/bin/$cli"; exit 1; }
              done
              # 2. The protected root must be the reported PATH dir, and be root-owned.
              jq -e '.result.path.dir == "/opt/dig/bin"' install.json \
              || {
               echo "FAIL: report.path.dir must name the protected root under direct_path_entry"
               exit 1
             }
              jq -e '.result.path.modified == true' install.json \
                || { echo "FAIL: the fallback must actually wire the protected root onto PATH"; exit 1; }
              # 3. It must be PREPENDED, so a DIG name resolves to the protected root and
              #    not to whatever made the veneer unsafe. Read the login PATH the user
              #    really gets and require the protected root to precede the veneer.
              #    Done in ONE awk over a FILE, with no pipeline: a `grep … | head -1`
              #    here would SIGPIPE grep under `pipefail` and yield an empty answer
              #    rather than a verdict, which is the #1813 skip-instead-of-fail shape.
              USER_NAME=$(id -un 1001)
              sudo su - "$USER_NAME" -c 'printf "%s\n" "$PATH"' > login-path.txt
              cat login-path.txt
              awk -v RS=':' '
                { gsub(/\n/, "") }
                $0 == "/opt/dig/bin"  && !dig { dig = NR }
                $0 == "/usr/local/bin" && !ven { ven = NR }
                END {
                  if (!dig) { print "FAIL: /opt/dig/bin is not on the login PATH at all"; exit 1 }
                  if (ven && ven < dig) {
                    print "FAIL: /usr/local/bin precedes /opt/dig/bin on the login PATH"; exit 1
                  }
                }
              ' login-path.txt
              # 4. And every CLI must still resolve INTO the protected root for that user.
              for cli in dig-store digs; do
                sudo su - "$USER_NAME" -c "command -v $cli" > "resolved-$cli.txt" \
                  || { echo "FAIL: $cli is not on $USER_NAME's PATH under the fallback"; exit 1; }
                cat "resolved-$cli.txt"
                case "$(cat "resolved-$cli.txt")" in
                  /opt/dig/bin/*) ;;
                  *) echo "FAIL: $cli does not resolve into the protected root under the fallback"; exit 1 ;;
                esac
              done
              ;;
            *)
              # Fail CLOSED. A null/absent/renamed mechanism must never skip the branch.
              echo "FAIL: unrecognised reachability mechanism '$MECHANISM' — neither shape was asserted"
              exit 1
              ;;
          esac
          # EVERY LEVEL of the chain, not just the leaf. Write permission on /opt/dig is
          # permission to rename /opt/dig/bin aside and substitute an attacker-owned
          # directory of the same name, so a 0777 parent is a complete escalation on its
          # own -- and checking only the leaf is what shipped.
          for level in /opt /opt/dig /opt/dig/bin; do
            stat -c '%n %U %a' "$level"
            test "$(stat -c '%U' "$level")" = root \
              || { echo "FAIL: $level is not root-owned"; exit 1; }
            test -z "$(find "$level" -maxdepth 0 \( -perm -0002 -o -perm -0020 \))" \
              || { echo "FAIL: $level is group- or world-writable"; exit 1; }
          done

          # And the REPAIR path: a pre-existing permissive level must be FIXED by an
          # install, not merely left alone. A box that installed 0.30.0 under umask 000
          # already has one, and 0.31.0 routes every binary and every service ExecStart
          # through it. umask 000 is set for the re-run, so a fix that only pins newly
          # created directories fails here too.
          sudo chmod 0777 /opt/dig
          test "$(stat -c '%a' /opt/dig)" = 777
          sudo -H sh -c 'umask 000; ./target/release/dig-installer \
            --no-dig-node --no-dig-dns --no-auto-update --no-dig-app --json' > repaired.json
          stat -c '%n %U %a' /opt/dig
          test -z "$(find /opt/dig -maxdepth 0 \( -perm -0002 -o -perm -0020 \))" \
            || { echo "FAIL: a permissive /opt/dig was NOT repaired by the install"; exit 1; }
          jq -e '.result.ready == true' repaired.json

      # The DEFAULT selection — every component, dig-app included — must obey the
      # same placement rule. Run as a dry-run so the full default set is covered
      # without installing services or importing dig-app's own start-up defect
      # (#1753) into this gate: placement is decided before anything is fetched.
      - name: The DEFAULT component selection places everything in the protected root
        run: |
          sudo -H ./target/release/dig-installer --dry-run --json > planned.json
          jq -r '.result.components[] | "\(.component) -> \(.dest)"' planned.json
          # An EXACT count plus explicit membership: "> 2" stayed green if a plan
          # regression silently dropped dig-app (or anything else) from the default set.
          jq -e '(.result.components | length) == 9' planned.json \
            || { echo "FAIL: the default component set changed -- update this count deliberately"; \
                 jq -r '.result.components | length' planned.json; exit 1; }
          for want in dig-store digs dig-node dign dig-app dig-dns digd dig-updater dig-updater-worker; do
            jq -e --arg c "$want" 'any(.result.components[]; .component == $c)' planned.json \
              || { echo "FAIL: $want is missing from the DEFAULT plan"; exit 1; }
          done
          jq -e 'all(.result.components[]; .dest | startswith("/opt/dig/bin/"))' planned.json \
            || { echo "FAIL: the default plan places a binary outside the protected root"; exit 1; }

      # The installer's own verdict must AGREE with what we just observed
      # independently. Before #1748 it claimed every CLI resolved while the loop
      # above would have failed, so agreement is the property under test.
      - name: The installer's own report agrees with the observation
        run: |
          jq -e '.ok == true' install.json
          jq -e '.result.ready == true' install.json
          jq -e '.result.failures == []' install.json
          jq -e '(.result.cli_path_checks | length) > 0' install.json
          jq -e 'all(.result.cli_path_checks[]; .resolved == true)' install.json
          # No user-facing binary may live under root's home.
          jq -e 'all(.result.components[]; (.dest | startswith("/root")) | not)' install.json
          # And the PATH result must name the dir that actually has to be searchable. This field is
          # machine-consumed, so the requirement is that it names the dir the REPORTED mechanism makes
          # searchable — the veneer under `veneer_links`, the protected root under the fallback (which
          # puts the root on PATH directly instead). Asserted per-mechanism in the placement step above;
          # here the property is that the named dir is genuinely on the invoking user's login PATH,
          # which is the agreement the pre-#1748 report failed to have.
          PATH_DIR=$(jq -r '.result.path.dir' install.json)
          echo "reported path.dir: $PATH_DIR"
          USER_NAME=$(id -un 1001)
          sudo su - "$USER_NAME" -c 'printf "%s\n" "$PATH"' > agree-login-path.txt
          awk -v RS=':' -v want="$PATH_DIR" '
            { gsub(/\n/, "") }
            $0 == want { found = 1 }
            END {
              if (!found) {
                print "FAIL: report.path.dir names a directory that is not on the user'"'"'s PATH"
                exit 1
              }
            }
          ' agree-login-path.txt

      # The other half of the bound: the check must be capable of going RED.
      # Point an install at a root-only directory (mode 0700, unreachable by any
      # unprivileged user) and require the readiness verdict to FAIL. A check that
      # stays green here is worthless — and staying green here is exactly what
      # shipped.
      - name: The PATH check goes RED against a root-only layout
        run: |
          sudo mkdir -p /root/dig-only && sudo chmod 700 /root/dig-only
          set +e
          sudo -H ./target/release/dig-installer \
            --no-dig-node --no-dig-dns --no-auto-update --no-dig-app \
            --bin-dir /root/dig-only \
            --json > broken.json
          RC=$?
          set -e
          echo "installer exit code: $RC"
          cat broken.json | jq '.result.cli_path_checks' || cat broken.json
          # It must NOT report ready, and the failure must name the PATH problem.
          jq -e '.result.ready == false' broken.json
          jq -e 'any(.result.cli_path_checks[]; .resolved == false)' broken.json
          jq -e '(.result.failures | length) > 0' broken.json
          test "$RC" -ne 0 || { echo "FAIL: a broken install must exit non-zero"; exit 1; }
          # And it must not have advised re-running elevated (it already was). Read a FILE, never a pipe:
          # under `pipefail` a matching `grep -qi` exits early, SIGPIPEs `jq`, the pipeline returns 141, the
          # `if` is false — and the check is SKIPPED rather than failed. This PR introduced that; the same
          # shape is fixed at the schtasks sites above.
          jq -r '.result.failures[]' broken.json > broken-failures.txt
          if grep -i 're-run elevated' broken-failures.txt > /dev/null; then
            echo "FAIL: must not advise elevating an already-elevated install"; exit 1
          fi

  # #1748 WU3: the ROOT gate. `cargo test` on a normal runner cannot be it.
  #
  # 23 lib tests failed when the suite ran as root, and the one executable proof of the root-exec guard
  # could not pass in the only environment where it runs — both because their fixtures sat under `/tmp`,
  # which is mode 1777 and which the whole-chain install-root verify correctly condemns. The verify was
  # right; the fixture LOCATION was wrong. This job runs the suite AS ROOT in a container that bakes a
  # purpose-made non-sticky 0755 fixture root, so the proofs run and the verify keeps every tooth.
  #
  # It then does what six rounds of mode-bit assertions could not: an unprivileged account plants a binary
  # where root would run it, root performs an ordinary install, and the job FAILS if root ever executed the
  # planted code. Every attempt carries a falsifying control — the same attempt with the posture repaired
  # must SUCCEED — so a build that simply refused everything could not pass.
  root-gate:
    name: "#1748 root gate: suite as root + an executed escalation attempt"
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Build the gate image
        run: docker build -f .github/docker/root-gate.Dockerfile -t dig-root-gate .

      # AS ROOT, with fixtures on the clean baked-in root. Any failure here is a real one: the environment
      # no longer contributes any.
      - name: The whole lib suite, as root, with fixtures off /tmp
        run: |
          docker run --rm -v "$PWD:/work" -w /work \
            -e CARGO_TARGET_DIR=/tmp/target \
            -e PATH=/usr/local/cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
            dig-root-gate \
            bash -c 'set -o pipefail; cargo test --lib 2>&1 | tail -20'

      # The escalation. Network is needed: it installs the real published binaries, because attacking a
      # mock would prove something about the mock.
      - name: An unprivileged account attempts to escalate through a real install
        run: |
          docker run --rm -v "$PWD:/work" -w /work \
            -e CARGO_TARGET_DIR=/tmp/target \
            -e PATH=/usr/local/cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
            dig-root-gate \
            bash -c 'cargo build --release --locked --bin dig-installer \
              && cd /tmp \
              && INSTALLER=/tmp/target/release/dig-installer \
                 bash /work/.github/scripts/root-gate-escalation.sh'

  # ---------------------------------------------------------------------------
  # #526 finding 4: the leg that exercises the path that SHIPS.
  #
  # The matrix job above passes `--bin-dir`, which FORCES user scope (#565), and
  # pins a pre-`--scope` dig-node. Its `scope == "user"` / `survives_reboot ==
  # false` assertions are therefore satisfied identically by the pre-#526 code —
  # they confirm a forced downgrade rather than the scope DECISION. Nothing
  # covered a default-path install, which is the only shape a real user gets.
  #
  # This job takes NO `--bin-dir`, so `engine_scope` genuinely decides, and it
  # carries NO `loginctl enable-linger root` / `user@0.service` workaround — that
  # workaround IS the thing #526 was filed to remove, so a job that keeps it
  # cannot show the need has gone.
  # ---------------------------------------------------------------------------
  # Two legs over the dig-node pin, because the job has to hold two DIFFERENT
  # contracts that only look like one:
  #
  #   current (0.71.0) — `--scope` shipped in dig-node v0.70.0, and `resolve_scope`
  #     maps `auto` under root to the system domain. So on a pin at or above that,
  #     a headless elevated install MUST reach a machine-wide, boot-started
  #     registration. This leg asserts the SUCCESS shape, and it is the leg that
  #     proves dig_ecosystem#526 is delivered rather than merely reported.
  #
  #   legacy (0.29.0) — predates the flag entirely. dig-node rejects `--scope`, the
  #     installer retries flag-less, and the component reaches for a per-user
  #     manager that root has no session bus for. The contract there is not that it
  #     works; it is that the degradation is reported HONESTLY and the run is NEVER
  #     called ready. Those assertions are the false-ready regression guard and are
  #     kept verbatim — an operator can still pin an old component, and this is the
  #     only leg that can observe the false-ready at all.
  #
  # Both legs assert a true property of their own pin. Neither asserts an
  # impossibility, which is what the single-pinned version of this job did.
  system-scope-e2e:
    name: "#526 a default-path install decides scope for itself (Linux, dig-node ${{ matrix.leg }})"
    runs-on: ubuntu-latest
    timeout-minutes: 20
    strategy:
      # Each leg is an independent contract: a legacy-leg failure must not hide
      # whether the current leg delivers, or vice versa.
      fail-fast: false
      matrix:
        include:
          - leg: current
            dig_node_version: "0.71.0"
          - leg: legacy
            dig_node_version: "0.29.0"
    defaults:
      run:
        shell: bash
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install Rust (stable)
        run: rustup toolchain install stable && rustup default stable

      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            target
          key: ubuntu-526-syscope-${{ matrix.leg }}-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ubuntu-526-syscope-${{ matrix.leg }}-

      - name: Build the installer
        run: cargo build --release --bin dig-installer

      # The install root's whole ancestor chain must be root-owned for a
      # default-path install to be permitted at all (#1748) — the same
      # normalisation the sibling job does, for the same reason.
      - name: Normalise the runner image's world-writable /opt and veneer chain
        run: |
          sudo chmod 755 /opt /usr /usr/local /usr/local/bin
          sudo chown 0:0 /usr /usr/local /usr/local/bin
          for level in /opt /usr /usr/local /usr/local/bin; do
            test "$(stat -c '%U' "$level")" = root \
              || { echo "FAIL: $level is not root-owned"; exit 1; }
          done

      # The precondition finding 2 is about: a leftover per-user unit from an
      # earlier install, sitting in root's own user scope exactly where a
      # pre-#526 `sudo dig-installer` put it. What must HAPPEN to it depends on
      # where the component actually registers, which is what the steps below
      # pin down.
      - name: Plant the leftover per-user unit an earlier install would have left
        run: |
          sudo mkdir -p /root/.config/systemd/user
          printf '%s\n' \
            '[Unit]' \
            'Description=leftover from a pre-#526 install' \
            '[Service]' \
            'ExecStart=/bin/true' \
            '[Install]' \
            'WantedBy=default.target' \
            | sudo tee /root/.config/systemd/user/dignetwork-dig-node.service >/dev/null
          sudo ls -l /root/.config/systemd/user/

      # The current leg has NO tolerance: on a pin that understands `--scope`, a
      # headless elevated install is required to succeed, so a non-zero exit is a
      # failure of the acceptance criterion and must fail the step here rather
      # than be re-interpreted by a later assertion.
      - name: Install with NO --bin-dir, so engine_scope actually decides (current)
        if: matrix.leg == 'current'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          sudo -H -E "$PWD/target/release/dig-installer" \
            --no-digstore --no-dig-app --no-auto-update \
            --dig-node-version "${{ matrix.dig_node_version }}" \
            --dig-dns-version "$DIG_DNS_VERSION" \
            --json > install.json
          # No pipe into `head`: this job runs with `-o pipefail`, and `head`
          # closing the pipe early SIGPIPEs `jq`, which would fail the step for a
          # diagnostic line.
          jq -r '{ready: .result.ready, scope: .result.service.scope}' install.json

      # The legacy leg DOES tolerate a non-zero exit: on a pre-`--scope` pin the
      # install genuinely cannot register on this host class, and that failure is
      # the subject of the assertions below rather than a reason to abort.
      - name: Install with NO --bin-dir, so engine_scope actually decides (legacy)
        if: matrix.leg == 'legacy'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set +e
          sudo -H -E "$PWD/target/release/dig-installer" \
            --no-digstore --no-dig-app --no-auto-update \
            --dig-node-version "${{ matrix.dig_node_version }}" \
            --dig-dns-version "$DIG_DNS_VERSION" \
            --json > install.json
          echo "installer exit: $?"
          jq -r '{ready: .result.ready, scope: .result.service.scope}' install.json
          true

      # THE assertion this job exists for. This is the scope the installer
      # DECIDED on its own for a protected-root install — "system" — which the
      # --bin-dir leg can never show, because it forces "user" before the
      # decision is ever reached.
      - name: The installer decided SYSTEM scope for a default-path install
        run: |
          jq -e '.result.service.scope == "system"' install.json || {
            echo "FAIL: a default-path elevated install must request machine-wide scope"
            exit 1
          }

      # THE #526 ACCEPTANCE PROPERTY: on a pin that understands `--scope`, a
      # headless elevated install reaches a machine-wide registration that comes
      # back after a reboot with nobody logged in.
      - name: The install reports a boot-surviving system registration (current)
        if: matrix.leg == 'current'
        run: |
          jq -e '.result.ready == true' install.json || {
            echo "FAIL: a supported dig-node pin must reach a ready install"
            exit 1
          }
          jq -e '.result.service.installed == true' install.json
          jq -e '.result.service.survives_reboot == true' install.json

      # `survives_reboot: true` above is the installer's OWN report, so on its own
      # it is the installer grading its own homework. This step asks the OS the
      # same question independently: a SYSTEM-scope systemd unit exists on disk
      # under /etc/systemd/system, and systemd itself reports it enabled — which is
      # precisely what "starts after a reboot with nobody logged in" means.
      #
      # `is-enabled` is run WITHOUT `--user`, so a per-user registration cannot
      # satisfy it, and the unit is discovered by glob rather than by a hardcoded
      # name — but the glob is required to match EXACTLY ONE unit, so a glob that
      # matches nothing fails loudly instead of passing vacuously.
      - name: systemd itself confirms a boot-started system unit (current)
        if: matrix.leg == 'current'
        run: |
          sudo ls -l /etc/systemd/system/ || true
          mapfile -t UNITS < <(sudo find /etc/systemd/system -maxdepth 1 \
            -name '*dig-node*.service' -printf '%f\n' | sort)
          echo "system units found: ${UNITS[*]:-<none>}"
          if [ "${#UNITS[@]}" -ne 1 ]; then
            echo "FAIL: expected exactly one dig-node unit in the SYSTEM scope," \
                 "found ${#UNITS[@]} — a machine-wide registration was not made"
            exit 1
          fi
          UNIT="${UNITS[0]}"

          # The unit must be enabled in the SYSTEM manager. `is-enabled` exits
          # non-zero for a disabled unit, so its exit status is captured rather
          # than allowed to abort the step before the state can be reported.
          set +e
          STATE=$(sudo systemctl is-enabled "$UNIT" 2>&1)
          set -e
          echo "systemctl is-enabled $UNIT -> $STATE"
          case "$STATE" in
            enabled|enabled-runtime|alias|static|indirect)
              echo "OK: $UNIT is wired to start at boot" ;;
            *)
              echo "FAIL: $UNIT is present but systemd reports '$STATE', so it will" \
                   "NOT come back after a reboot"
              exit 1 ;;
          esac

      # The positional counterpart to the legacy leg's "a failed registration
      # sweeps nothing", against the SAME planted fixture. A sweep keyed off the
      # REQUESTED scope would clear the planted unit on both legs; a sweep keyed
      # off what was actually SETTLED clears it only here, where a system
      # registration really happened. Asserting only one leg could not tell those
      # two implementations apart — the pair is what pins the behaviour.
      #
      # The GATE is the on-disk outcome, not the installer's own list: SPEC's rule
      # is that no unit may SHADOW a system registration, and `systemd --user`
      # starts a leftover user unit at the next login regardless of what the report
      # says. Asserting the report's `shadowing_units_removed` alone would pin the
      # MECHANISM, and would pass for a run that named a removal it did not make.
      - name: A successful system registration clears the shadowing user unit (current)
        if: matrix.leg == 'current'
        run: |
          echo "--- the run's own report ---"
          jq -r '.result.service.shadowing_units_removed' install.json
          echo "--- root's user-unit directory, after the install ---"
          sudo ls -la /root/.config/systemd/user/ || echo "(directory is gone)"

          # THE GATE: the planted unit must not survive a successful machine-wide
          # registration, or it starts a SECOND dig-node at the next login and both
          # bind the node's port.
          if sudo test -f /root/.config/systemd/user/dignetwork-dig-node.service; then
            echo "FAIL: a system registration succeeded, yet the leftover per-user unit is" \
                 "STILL on disk — systemd --user will start a second dig-node at the next" \
                 "login and both will bind the node's port"
            exit 1
          fi
          echo "OK: the shadowing per-user unit is gone, so the system unit wins positionally"

          # `shadowing_units_removed` is NOT asserted non-empty here, and that is
          # deliberate rather than an oversight. It records the INSTALLER'S OWN sweep,
          # and the installer enumerates the units on disk BEFORE delegating to
          # `dig-node install`. On a component at v0.70.0 or later the component
          # itself clears the stale per-user unit while registering machine-wide, so
          # by the time the sweep runs there is legitimately nothing left to remove
          # and an empty list is the honest report. Requiring an entry here would
          # demand the installer claim credit for a deletion another process
          # performed, and the only way to satisfy it would be to fabricate one.
          #
          # The installer's own sweep is pinned where it can be observed truthfully:
          # the `legacy` leg asserts it removes NOTHING when no registration was
          # established, and `units::a_user_scope_unit_is_found_under_each_config_home_that_has_one`
          # asserts both config homes' units are found and proposed for removal.
          # What matters on THIS leg is the positional outcome, which is gated above.
          if [ "$(jq -r '.result.service.shadowing_units_removed | length' install.json)" != "0" ]; then
            echo "the installer also swept units of its own:"
            jq -r '.result.service.shadowing_units_removed[]' install.json
            # Anything it CLAIMS to have removed must really be gone.
            while read -r swept; do
              if sudo test -e "$swept"; then
                echo "FAIL: the report claims it removed $swept, but it is still on disk"
                exit 1
              fi
            done < <(jq -r '.result.service.shadowing_units_removed[]' install.json)
          fi

      # NOT-READY GUARD, on the pre-`--scope` pin — and an HONEST account of what it
      # does and does NOT prove (dig_ecosystem#1894).
      #
      # dig-node gained `--scope` in v0.70.0, so this leg's 0.29.0 pin predates the
      # flag: `dig-node install` has the flag rejected, the installer retries
      # flag-less, the component reaches for a per-user manager, and on THIS headless
      # CI host — root with NO session bus (this job deliberately brings none up) —
      # that per-user registration cannot be made, so the component install FAILS.
      # The VERIFIED outcome here is therefore `installed: false` (traced: an
      # `install_service` `Err` on a bus-less host leaves `installed` false —
      # src/service.rs `install_engine_service`, src/lib.rs `register_dig_node` Err
      # arm), and readiness must follow: `evaluate_readiness` fails dig-node when it
      # did not register, so `ready: false`.
      #
      # The assertions below are pinned to `installed == false` AND to the not-ready
      # REASON naming dig-node's registration, so a run that failed for some UNRELATED
      # reason (an install-root ACL breach, a PATH-order finding) cannot satisfy them
      # by producing a coincidental `ready: false`.
      #
      # What this leg does NOT prove, stated so no one mistakes its reach: it exercises
      # the install-FAILURE path only. It does NOT exercise a registered-but-scope-
      # inadequate unit — a per-user unit that genuinely DID register (on a host that
      # HAS a session bus) for an install that needed system scope. That state reports
      # `ready: true` today, because `evaluate_readiness` gates dig-node on
      # installed + health_ok and NOT on reboot-survival/scope-adequacy
      # (src/lib.rs `evaluate_readiness_when`). Guarding that shape needs a product
      # readiness gate on scope, not a test change — tracked separately; earlier text
      # here claimed "the pre-#526 code reported `ready: true`", which was never
      # observed and is removed.
      - name: A host where the service could not register is NEVER reported ready
        if: matrix.leg == 'legacy'
        run: |
          jq -e '.result.ready == false' install.json || {
            echo "FAIL: false-ready — the service did not register, yet the run claims ready"
            exit 1
          }
          # The reason must BE the install failure this leg constructs, not a
          # coincidental unrelated failure — otherwise `ready == false` above is a
          # false green that a wholly-broken installer would also satisfy (#1894).
          jq -e '.result.service.installed == false' install.json || {
            echo "FAIL: the not-ready state was reached without an install failure — this leg proves nothing about the bus-less registration path"
            exit 1
          }
          jq -e '[.result.failures[] | select(startswith("dig-node"))] | length > 0' install.json || {
            echo "FAIL: not-ready for a reason unrelated to dig-node registration; the guard would pass for an incidentally-broken install. failures: $(jq -c '.result.failures' install.json)"
            exit 1
          }
          jq -e '.result.service.survives_reboot == false' install.json

          # The report must name the scope it tried and the real reason, so the
          # operator is not left guessing. Asserted on content, not merely on
          # non-emptiness, which any string would satisfy.
          NOTE=$(jq -r '.result.service.note' install.json)
          echo "reported: $NOTE"
          echo "$NOTE" | grep -qi 'machine-wide\|system' || {
            echo "FAIL: the failure does not name the scope it attempted"
            exit 1
          }
          echo "$NOTE" | grep -qi 'will NOT start' || {
            echo "FAIL: the failure does not state the consequence"
            exit 1
          }

          # And it must NOT have degraded into "could not determine" for a scope
          # systemd answered plainly about (`not-found` is an answer, #526 e2e).
          if echo "$NOTE" | grep -qi 'unrecognised systemd verdict'; then
            echo "FAIL: a plain systemd answer was misread as indeterminate"
            exit 1
          fi

      # Finding 2, positional: nothing was registered, so nothing may be swept.
      # A sweep driven by the REQUESTED scope would have deleted the planted unit
      # on the strength of a system registration that never happened.
      - name: A failed registration sweeps nothing
        if: matrix.leg == 'legacy'
        run: |
          jq -e '(.result.service.shadowing_units_removed | length) == 0' install.json || {
            echo "FAIL: swept per-user units although no registration was made"
            exit 1
          }
          sudo test -f /root/.config/systemd/user/dignetwork-dig-node.service || {
            echo "FAIL: deleted a per-user unit after a failed system registration"
            exit 1
          }

      # #526's workaround must not have crept back in. If the installer had
      # quietly enabled linger to make its own install work, the bug would be
      # papered over rather than reported.
      - name: The install did not enable the linger workaround
        run: |
          systemctl is-enabled dignetwork-dig-node 2>&1 || true
          if loginctl show-user root -p Linger 2>/dev/null | grep -q 'Linger=yes'; then
            echo "FAIL: the install enabled linger for root - #526 exists to remove that workaround"
            exit 1
          fi

      # The uninstall counterpart to finding 3, on the host class that produces
      # the probe failure: root with no session bus. A scope that could not be
      # READ must be named as unverified, never folded into a clean
      # "removed from every scope".
      - name: An unqueryable scope is named, not silently reported as cleared
        run: |
          set +e
          sudo -H "$PWD/target/release/dig-installer" --uninstall-dig-node --json > uninstall.json
          echo "uninstall exit: $?"
          NOTE=$(jq -r '[.. | strings] | join(" ")' uninstall.json)
          echo "reported: $NOTE"
          if echo "$NOTE" | grep -qi 'failed to connect to bus'; then
            echo "$NOTE" | grep -qi 'could not verify\|UNKNOWN rather than removed' || {
              echo "FAIL: hit a bus failure yet reported the scope as cleared"
              exit 1
            }
          fi
          if echo "$NOTE" | grep -qi 'unrecognised systemd verdict'; then
            echo "FAIL: a plain systemd answer was misread as indeterminate"
            exit 1
          fi