msks 0.1.0__tar.gz

msks-0.1.0/.github/actionlint.yaml

@@ -0,0 +1,10 @@
+# actionlint config — repo-specific knowledge the linter cannot
+# infer (https://github.com/rhysd/actionlint/blob/main/docs/config.md).
+#
+# Custom self-hosted runner labels: nightly-l3.yml's proving smoke
+# runs on a registered runner labeled `msks-l3` (#135) — the depth
+# of nesting the recursion proves (two levels below the runner)
+# exists only there, not on GitHub's hosted runners.
+self-hosted-runner:
+  labels:
+    - msks-l3

msks-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+# CI: the authoritative unit-test run (#6, split to tests-only in #17).
+#
+# Everything runs inside the devenv shell built from this repo's
+# devenv.nix/devenv.yaml — the same pinned nixpkgs, the same uv venv,
+# the same cloud-hypervisor as every contributor gets — so a green run
+# here means the dev environment itself is healthy too.
+#
+# Lint/xenon (lint.yml) and the guest-asset build (guest-assets.yml)
+# are now their own workflows: each reports as its own check and none
+# can mask the others, which is what the old `if: !cancelled()`
+# chaining approximated inside a single job.
+#
+# The real-VM smoke tests run in smoke.yml — the hosted runner's
+# /dev/kvm (changelog 2024-04-02) plus the built guest assets
+# (.devenv/state/guest) satisfy the local suite's gate (#64). This
+# workflow stays TEST_*-free by design: coverage-gated units
+# only.
+name: CI
+
+# Markdown-only changes cannot move the gates (ruff/xenon read src/,
+# the unit tests exercise code) — so an .md-only push skips both runs
+# instead of burning a runner. guest-assets.yml already path-filters
+# to its own inputs.
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "**.md"
+  pull_request:
+    paths-ignore:
+      - "**.md"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: cachix/cachix-action@v17
+        with:
+          name: devenv
+
+      # Pinned release, not the moving default registry: the devenv
+      # that evaluates the 2.x tasks syntax and parses -O is the one
+      # moving part otherwise — an upstream break would red CI with no
+      # repo change.
+      - name: Install devenv.sh
+        run: nix profile add github:cachix/devenv/v2.3.1
+
+      # The CI-identical invocation (AGENTS.md): pytest -n auto with
+      # coverage flags from pyproject addopts, COVERAGE_CORE=sysmon
+      # pinned by conftest, fail_under = 100 branch coverage. The
+      # runner's TMPDIR nests deep enough to push AF_UNIX socket paths
+      # past the 108-byte limit; pytest's basetemp belongs under /tmp
+      # (belt to the fixtures' shallow state dirs).
+      - name: Unit tests
+        env:
+          TMPDIR: /tmp
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          unit-tests

msks-0.1.0/.github/workflows/guest-assets.yml

@@ -0,0 +1,107 @@
+# Guest-asset build (#17, split out of ci.yml).
+#
+# The nix-heavy derivation check from #5's ubuntu-latest criterion:
+# a cold checkout must still build the kernel/initrd/rootfs, so the
+# guest-asset expressions cannot silently rot. The
+# artifacts are not consumed on the runner — CH smoke needs KVM —
+# which is exactly why this reports as its own check: slow and
+# independent of both lint and the unit tests.
+#
+# Needs none of the test-run plumbing (no TMPDIR pin, no coverage
+# env): just the devenv shell and the msks-build-guest script.
+#
+# Path-filtered: runs only when the guest inputs change — the nix
+# expressions, the build script, the devenv files that pin nixpkgs
+# and define the task, or this workflow itself. The trade vs. #5's
+# anti-rot criterion is accepted deliberately: unrelated PRs skip
+# this job (and show it as skipped), guest-touching PRs and any
+# devenv pin move still build from cold.
+name: Guest assets
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - .github/workflows/guest-assets.yml
+      - devenv.nix
+      - devenv.yaml
+      - devenv.lock
+      - nix/guest.nix
+      - nix/agent-toolchain.nix
+      - nix/pi-shrinkwrap-patch.py
+      - nix/pi-shrinkwrap-integrity.json
+      - nix/guest-debian.nix
+      - nix/guest-nixos.nix
+      - nix/image-archive.nix
+      - nix/guest-pi-extension.ts
+      - scripts/build-guest.sh
+  pull_request:
+    paths:
+      - .github/workflows/guest-assets.yml
+      - devenv.nix
+      - devenv.yaml
+      - devenv.lock
+      - nix/guest.nix
+      - nix/agent-toolchain.nix
+      - nix/pi-shrinkwrap-patch.py
+      - nix/pi-shrinkwrap-integrity.json
+      - nix/guest-debian.nix
+      - nix/guest-nixos.nix
+      - nix/image-archive.nix
+      - nix/guest-pi-extension.ts
+      - scripts/build-guest.sh
+
+permissions:
+  contents: read
+
+concurrency:
+  group: guest-assets-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-guest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: cachix/cachix-action@v17
+        with:
+          name: devenv
+
+      # Pinned release, not the moving default registry: the devenv
+      # that evaluates the 2.x tasks syntax and parses -O is the one
+      # moving part otherwise — an upstream break would red CI with no
+      # repo change.
+      - name: Install devenv.sh
+        run: nix profile add github:cachix/devenv/v2.3.1
+
+      - name: Build guest assets
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          msks-build-guest
+
+      # The NixOS guest (#250): the second catalog image, built from
+      # the same pinned nixpkgs the Debian guest's toolchain uses.
+      # Its closure is all cache.nixos.org downloads on a cold
+      # runner — the 60-minute ceiling holds, but the step sits
+      # after the Debian build so a slow mirror never muddies its
+      # signal.
+      - name: Build the NixOS guest assets
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          msks-build-guest nixos
+
+      # The real-artifact pinning test: the ''-escape RepoTag bug
+      # shipped precisely because this test skipped everywhere CI
+      # ran. The import costs ~8s against each built archive.
+      - name: Import the built images (pinning test)
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          python -m pytest src/msks/tests/test_imagestore.py
+          -q -p no:cacheprovider --no-cov
+          -k real_built

msks-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,80 @@
+# Lint + complexity + format gates (#17, #72).
+#
+# Split out of ci.yml so a lint failure reports as its own check: it
+# can neither mask the unit-test result nor be masked by it, and both
+# run in parallel. The ruff and xenon steps keep their pre-split
+# invocations (targeted failure names); the hook-suite step runs the
+# full pre-commit suite — the same .pre-commit-config.yaml devenv.nix
+# generates and `git commit` enforces — so a push whose commits
+# bypassed the hooks (or landed before a new one) still meets every
+# gate in CI.
+name: Lint
+
+# Every file type is gated by some hook (markdownlint and prettier
+# read docs/*.md, nixfmt reads nix/, shfmt/shellcheck read scripts/),
+# so no path filters here: every push runs. ci.yml keeps its .md
+# ignore — the unit tests do not read Markdown.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: cachix/cachix-action@v17
+        with:
+          name: devenv
+
+      # Pinned release, not the moving default registry: the devenv
+      # that evaluates the 2.x tasks syntax and parses -O is the one
+      # moving part otherwise — an upstream break would red CI with no
+      # repo change.
+      - name: Install devenv.sh
+        run: nix profile add github:cachix/devenv/v2.3.1
+
+      - name: Lint (ruff check + format)
+        env:
+          TMPDIR: /tmp
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          bash -c 'ruff check src/ && ruff format --check src/'
+
+      - name: Complexity gate (xenon rank A)
+        env:
+          TMPDIR: /tmp
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          msks-xenon
+
+      # The full pre-commit suite (#72): deferred-imports, shfmt,
+      # shellcheck, markdownlint, actionlint, trufflehog, nixfmt,
+      # check-toml, yamllint, prettier, jscpd (ruff and xenon run in
+      # their own steps above and again here). devenv:git-hooks:run is
+      # pre-commit run --all-files over the generated config — the one
+      # definition, shared with the commit-time hook. Write-mode hooks
+      # (prettier/nixfmt/shfmt/ruff format) only "fail" in CI when a
+      # tracked file is not formatted; the runner tree is disposable.
+      # trufflehog scans the file set itself (staged files at commit
+      # time, all tracked files here) for verifiable live credentials.
+      - name: Pre-commit hook suite
+        env:
+          TMPDIR: /tmp
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          devenv tasks run devenv:git-hooks:run

msks-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,248 @@
+# Release (#564): the wheel publishes to PyPI, guest images
+# publish to a hash-keyed channel, and the version release carries
+# the small manifest that ties them together.
+#
+# Three jobs, ordered so each has what it needs:
+#
+# 1. wheel   — build the wheel, publish to PyPI through the
+#              registered trusted publisher (the pending publisher
+#              names this file and the `pypi` environment; no
+#              token lives in the repo).
+# 2. release — create the version release: the changelog's
+#              human-authored section (scripts/release_notes.py
+#              extracts it at the tag) prepended to GitHub's
+#              auto-generated notes, with the wheel and its
+#              checksum attached.
+# 3. images  — the hash-keyed channel, one job walking the flavors
+#              in order (both legs share one images.json merge, so
+#              the merge cannot race itself). Per flavor the nix
+#              evaluation of the archive derivation — building
+#              nothing — is compared against the last manifest; a
+#              changed flavor builds once, compresses with
+#              zstd -19 (the debian archive lands ~266 MiB, the
+#              nixos one ~578 MiB — both under GitHub's 2 GiB asset
+#              ceiling, which the plain nixos tar exceeds), and
+#              uploads to an immutable release tagged
+#              images/<hash> whose title names the flavor and body
+#              links what changed. images.json — ref, hash,
+#              description, kernel, size, url, build, built_from
+#              for every flavor — attaches to the version release,
+#              so `msks image import <url>` pulls straight from
+#              the channel with no manual download.
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  wheel:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+
+      # The changelog gate, before anything publishes: a tag cut
+      # without its docs/changes.md section refuses here — a live
+      # PyPI package with no GitHub release is the failure this
+      # ordering prevents.
+      - name: Refuse a tag without its changelog section
+        env:
+          TAG: ${{ github.ref_name }}
+        run: python scripts/release_notes.py "$TAG" > /dev/null
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Build the wheel and sdist
+        run: |
+          python -m pip install --quiet build
+          python -m build
+
+      - name: Publish to PyPI (trusted publisher)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Stage the wheel for the release job
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: dist/
+          retention-days: 1
+
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: wheel
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Download the wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: wheel
+          path: dist/
+
+      # The human-authored notes come first; GitHub's auto-generated
+      # PR list and compare link follow. release_notes.py refuses a
+      # tag whose changelog section is missing — the section is the
+      # reason the file exists.
+      - name: Compose the release notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          python scripts/release_notes.py "$TAG" > notes.md
+          gh api \
+            -X POST "repos/$GITHUB_REPOSITORY/releases/generate-notes" \
+            -f tag_name="$TAG" \
+            --jq .body > auto.md || printf '' > auto.md
+          cat auto.md >> notes.md
+
+      - name: Create the release with the wheel
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          sha256sum dist/* > dist/SHASUMS
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file notes.md \
+            --verify-tag \
+            dist/*
+
+  images:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    needs: release
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+      TAG: ${{ github.ref_name }}
+      SHA: ${{ github.sha }}
+      REPO: ${{ github.repository }}
+    steps:
+      # Full history: the previous-version lookup reads the tag
+      # list, and a depth-1 checkout carries only this tag.
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: cachix/cachix-action@v17
+        with:
+          name: devenv
+
+      - name: Install devenv.sh
+        run: nix profile add github:cachix/devenv/v2.3.1
+
+      # The manifest being replaced: the previous version
+      # release's images.json — the newest tag strictly below
+      # this one (a re-tagged release's own manifest wins when it
+      # carries one) — so flavors whose derivation did not change
+      # carry their rows — and their built_from — forward across
+      # releases.
+      - name: Read the previous manifest
+        run: |
+          set -eu
+          if gh release download "$TAG" -p images.json -O prev.json; then
+            echo "re-tagged release: keeping its manifest"
+          elif prev_tag=$(git tag --sort=-v:refname | grep '^v' | \
+                  grep -vx "$TAG" | while read -r t; do \
+                    if [ "$t" = "$(printf '%s\n%s\n' "$TAG" "$t" | \
+                                  sort -V | head -1)" ]; then \
+                      echo "$t"; break; \
+                    fi; \
+                  done) && \
+               [ -n "$prev_tag" ] && \
+               gh release download "$prev_tag" -p images.json -O prev.json
+          then
+            echo "carrying forward from $prev_tag's manifest"
+          else
+            printf '{}' > prev.json
+          fi
+
+      # One flavor at a time: each changed flavor publishes its
+      # immutable channel slot, and every flavor (changed or not)
+      # leaves a row in rows.json for the final merge.
+      - name: Publish changed images, collect manifest rows
+        run: |
+          set -eu
+          printf '{}' > rows.json
+          for flavor in debian nixos; do
+            attr=guest
+            dir=.devenv/state/guest
+            if [ "$flavor" = nixos ]; then attr=guest-nixos; dir=.devenv/state/guest-nixos; fi
+            # The single quotes are the point: the devenv shell's
+            # environment expands GUEST_NIXPKGS inside the inner
+            # bash, where it lives.
+            # shellcheck disable=SC2016
+            build=$(devenv --quiet -O dotenv.enable:bool false shell -- \
+              bash -c 'nix eval --raw -I nixpkgs="$GUEST_NIXPKGS" \
+                -f nix/guest.nix "$1.imageArchive.outPath"' \
+                bash "$attr" \
+              | xargs basename)
+            prev_build=$(jq -r --arg f "$flavor" '.[$f].build // empty' prev.json)
+            prev_row=$(jq -c --arg f "$flavor" '.[$f] // empty' prev.json)
+            if [ "$build" = "$prev_build" ] && [ -n "$prev_row" ]; then
+              echo "$flavor: derivation unchanged ($build) — row carries forward"
+              jq --arg f "$flavor" --argjson row "$prev_row" \
+                '.[$f] = $row' rows.json > rows.json.new
+              mv rows.json.new rows.json
+              continue
+            fi
+            echo "$flavor: derivation changed — building"
+            devenv --quiet -O dotenv.enable:bool false shell -- \
+              msks-build-guest "$flavor"
+            zstd -19 -T0 -q "$dir/$(cat "$dir/image-archive-name")" \
+              -o "$flavor.tar.zst"
+            hash=$(sha256sum "$flavor.tar.zst" | cut -d' ' -f1)
+            short=${hash:0:12}
+            tag="images/$short"
+            if gh release view "$tag" >/dev/null 2>&1; then
+              echo "$flavor: channel slot $tag already published"
+            else
+              prev_from=$(jq -r --arg f "$flavor" \
+                '.[$f].built_from // empty' prev.json)
+              gh release create "$tag" \
+                --target "$SHA" \
+                --title "$flavor image ($short)" \
+                --notes "Built from $SHA. What changed: https://github.com/$REPO/compare/${prev_from:-$SHA}...$SHA" \
+                "$flavor.tar.zst#$flavor.tar.zst" \
+                || gh release upload "$tag" \
+                  "$flavor.tar.zst#$flavor.tar.zst" --clobber
+            fi
+            meta=$(devenv --quiet -O dotenv.enable:bool false shell -- \
+              python scripts/image_meta.py "$dir")
+            jq \
+              --arg f "$flavor" \
+              --arg hash "$hash" \
+              --arg url "https://github.com/$REPO/releases/download/$tag/$flavor.tar.zst" \
+              --arg build "$build" \
+              --arg sha "$SHA" \
+              --argjson size "$(stat -c%s "$flavor.tar.zst")" \
+              --argjson meta "$meta" \
+              '.[$f] = {ref: $meta.ref, description: $meta.description,
+                        kernel: $meta.kernel_version, hash: $hash,
+                        size: $size, url: $url, build: $build,
+                        built_from: $sha}' \
+              rows.json > rows.json.new
+            mv rows.json.new rows.json
+          done
+
+      - name: Attach images.json to the version release
+        run: gh release upload "$TAG" rows.json#images.json --clobber

msks-0.1.0/.github/workflows/smoke-debian.yml

@@ -0,0 +1,138 @@
+# The Debian real-VM smoke suite (#64, split from the one-job smoke
+# workflow): boots workspace VMs through cloud-hypervisor against
+# the built Debian guest assets, unprivileged — /dev/kvm but no
+# root, no host network. The egress/root suite and the NixOS image's
+# suite each carry their own workflow now, so a failure names its
+# lane and the lanes run in parallel.
+#
+# The suite never counts toward the coverage gate (the
+# faked-transport unit suites own the 100%); serial (-n stays off)
+# so the real boots do not fight over the runner's 2 vCPUs. TMPDIR
+# is pinned for the AF_UNIX path-depth reason as ci.yml. Verbose (-
+# v): every test's name and verdict streams as it runs, so a
+# hanging boot is visible mid-job, not only in the final summary.
+#
+# Path-filtered to its real inputs: this workflow's own file, the
+# toolchain pins, the Debian guest build and the shared pieces,
+# everything under the server package the boots exercise, and the
+# suite itself.
+name: Smoke (Debian)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - .github/workflows/smoke-debian.yml
+      - devenv.nix
+      - devenv.yaml
+      - devenv.lock
+      - nix/guest.nix
+      - nix/agent-toolchain.nix
+      - nix/pi-shrinkwrap-patch.py
+      - nix/pi-shrinkwrap-integrity.json
+      - nix/guest-debian.nix
+      - nix/image-archive.nix
+      - nix/guest-pi-extension.ts
+      - scripts/build-guest.sh
+      - src/msks/msks/**
+      - src/msks/tests/conftest.py
+      - src/msks/tests/test_smoke/__init__.py
+      - src/msks/tests/test_smoke/*.py
+      - src/msks/tests/test_smoke/core/**
+  pull_request:
+    paths:
+      - .github/workflows/smoke-debian.yml
+      - devenv.nix
+      - devenv.yaml
+      - devenv.lock
+      - nix/guest.nix
+      - nix/agent-toolchain.nix
+      - nix/pi-shrinkwrap-patch.py
+      - nix/pi-shrinkwrap-integrity.json
+      - nix/guest-debian.nix
+      - nix/image-archive.nix
+      - nix/guest-pi-extension.ts
+      - scripts/build-guest.sh
+      - src/msks/msks/**
+      - src/msks/tests/conftest.py
+      - src/msks/tests/test_smoke/__init__.py
+      - src/msks/tests/test_smoke/*.py
+      - src/msks/tests/test_smoke/core/**
+
+permissions:
+  contents: read
+
+concurrency:
+  group: smoke-debian-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke-debian:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: cachix/cachix-action@v17
+        with:
+          name: devenv
+
+      # Pinned release, not the moving default registry: the devenv
+      # that evaluates the 2.x tasks syntax and parses -O is the one
+      # moving part otherwise — an upstream break would red CI with no
+      # repo change.
+      - name: Install devenv.sh
+        run: nix profile add github:cachix/devenv/v2.3.1
+
+      # The documented KVM permission rule (github.blog 2024-04-02):
+      # /dev/kvm exists on the hosted runner image but is restricted;
+      # this makes it 0666 for the runner user. kvm_available() then
+      # passes and the conftest points the smoke tests at the built
+      # guest assets under .devenv/state/guest.
+      - name: Enable KVM group perms
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Build guest assets
+        run: >-
+          devenv --quiet -O dotenv.enable:bool false shell --
+          msks-build-guest
+
+      # Nested-KVM guests run slower than a dev host's KVM guest
+      # (#64): the env ceilings below give the persistence test's four
+      # boot cycles room; the closing grep is the guard pattern — the
+      # smoke tests skip — not fail — when a prerequisite is missing,
+      # and a run that quietly skipped everything would report green
+      # while proving nothing.
+      - name: Smoke tests
+        env:
+          TMPDIR: /tmp
+          TEST_GUEST_UP_TIMEOUT_S: "180"
+          TEST_CONSOLE_TIMEOUT_S: "120"
+          TEST_SHUTDOWN_TIMEOUT_S: "180"
+        run: |
+          set -eo pipefail
+          devenv --quiet -O dotenv.enable:bool false shell -- \
+            python -m pytest src/msks/tests/test_smoke/core \
+            -v -rs -p no:cacheprovider --no-cov 2>&1 \
+            | tee /tmp/smoke-debian.log
+          ! grep -q 'test_boot_lifecycle.*SKIPPED' /tmp/smoke-debian.log \
+            || { echo 'the local boots skipped — assets or /dev/kvm regressed'; exit 1; }
+
+      # The failing boot's own evidence, kept by the tests' failure
+      # path — the runner recycles, so /tmp/msks-smoke-failed/ is the
+      # only place the guest's side of the story survives.
+      - name: Collect smoke state on failure
+        if: failure() || cancelled()
+        uses: actions/upload-artifact@v4
+        with:
+          name: smoke-debian-evidence
+          path: /tmp/msks-smoke-failed/
+          if-no-files-found: ignore
+          retention-days: 7