From f931f892e392685073075dcaf559350b229fb544 Mon Sep 17 00:00:00 2001
From: centra <p@centraworks.net>
Date: Sun, 5 Apr 2026 04:17:40 +0900
Subject: [PATCH] Document and harden remote KVM publishable lane

---
 README.md                  | 2 ++
 docs/testing.md            | 2 ++
 nix/test-cluster/README.md | 1 +
 nix/test-cluster/flake.nix | 2 +-
 4 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index daef69e..aefcf70 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,8 @@ nix run ./nix/test-cluster#cluster -- fresh-matrix
 ./nix/test-cluster/run-publishable-kvm-suite.sh ./work/publishable-kvm-suite
 ```
 
+The repository-owned remote entrypoint for the same suite is [`.github/workflows/kvm-publishable-selfhosted.yml`](.github/workflows/kvm-publishable-selfhosted.yml). It runs the wrapper on Forgejo runners labeled `nix-host`, and those runners must expose `/dev/kvm` with nested virtualization enabled.
+
 Project-done release proof now requires both halves of the public validation surface to be green:
 
 - `baremetal-iso` and `baremetal-iso-e2e` for the canonical `deployer -> installer -> nix-agent` bare-metal bootstrap path
diff --git a/docs/testing.md b/docs/testing.md
index 975d4cf..e6e9d93 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -86,6 +86,8 @@ Use these commands as the release-facing local proof set:
 - `baremetal-iso-e2e`: flake-check wrapper around the same canonical ISO harness
 - `deployer-vm-smoke`: lightweight regression proving that `nix-agent` can activate a host-built target closure without guest-side compilation
 
+The repository-owned remote entrypoint for the same publishable KVM proof is [`.github/workflows/kvm-publishable-selfhosted.yml`](../.github/workflows/kvm-publishable-selfhosted.yml). It targets Forgejo runners labeled `nix-host` and expects `/dev/kvm` plus nested virtualization on those hosts.
+
 ## Responsibility Coverage
 
 - `baremetal-iso` and `baremetal-iso-e2e` are the canonical proof for `deployer -> installer -> nix-agent`. They cover phone-home, install-plan materialization, Disko, reboot, and desired-system activation.
diff --git a/nix/test-cluster/README.md b/nix/test-cluster/README.md
index 11934d5..00f0ae7 100644
--- a/nix/test-cluster/README.md
+++ b/nix/test-cluster/README.md
@@ -7,6 +7,7 @@ The same harness also owns the canonical bare-metal bootstrap proof: a raw-QEMU
 
 When `/dev/kvm` is absent, the portable fallback is not another harness subcommand. Use the root-flake non-KVM lane instead: `nix build .#checks.x86_64-linux.portable-control-plane-regressions`.
 When `/dev/kvm` and nested virtualization are available, the reproducible publishable lane is `./nix/test-cluster/run-publishable-kvm-suite.sh`, which records environment metadata and then runs `fresh-smoke`, `fresh-demo-vm-webapp`, and `fresh-matrix` in order.
+The repository-owned remote entrypoint for the same suite is [`.github/workflows/kvm-publishable-selfhosted.yml`](../../.github/workflows/kvm-publishable-selfhosted.yml), which targets Forgejo `nix-host` runners with `/dev/kvm` and nested virtualization enabled.
 
 ## What it validates
 
diff --git a/nix/test-cluster/flake.nix b/nix/test-cluster/flake.nix
index a1f2d53..4d858aa 100644
--- a/nix/test-cluster/flake.nix
+++ b/nix/test-cluster/flake.nix
@@ -74,7 +74,7 @@
         text = ''
           repo_root="$(${pkgs.gitMinimal}/bin/git rev-parse --show-toplevel 2>/dev/null || ${pkgs.coreutils}/bin/pwd)"
           export PHOTON_CLUSTER_FLAKE="''${repo_root}/nix/test-cluster"
-          exec "''${repo_root}/nix/test-cluster/run-cluster.sh" "$@"
+          exec ${pkgs.bash}/bin/bash "''${repo_root}/nix/test-cluster/run-cluster.sh" "$@"
         '';
       };