fix: correct runner registration ordering — oneshot + tmpfiles

The nixpkgs gitea-actions-runner module uses tokenFile as a systemd
EnvironmentFile, loaded before any ExecStartPre. Our previous
ExecStartPre override was too late — file didn't exist yet.

Fix: tmpfiles pre-creates /run/hive-ci/runner-token with a placeholder
on every boot. A new hive-ci-register.service oneshot (gated on
ConditionPathExists=!/var/lib/gitea-runner/hive/.runner) fetches the
real token and overwrites before gitea-runner-hive.service starts,
wired via After/Wants. On subsequent boots the placeholder is harmless
— nixpkgs register step exits early when .runner already exists.

Closes #918.

nix/modules/hive-ci.nix

@@ -13,28 +13,23 @@ let
   # the runner registration-token API endpoint.
   coreTokenPath = "/var/lib/hyperhive/forge-core-token";
 
-  # Script run before the gitea-runner-hive service starts.
+  # Oneshot run before gitea-runner-hive.service starts.
-  # On first boot (no .runner credentials yet) it fetches a fresh
+  #
-  # runner registration token from the forge admin API and writes it to
+  # The nixpkgs gitea-actions-runner module uses tokenFile as a systemd
-  # /run/hive-ci/runner-token so gitea-actions-runner can register.
+  # EnvironmentFile (sets TOKEN= in the environment). EnvironmentFile is
-  # On subsequent boots the .runner credentials file already exists and
+  # loaded before any ExecStartPre, so the file MUST exist at service start —
-  # the runner ignores the token file entirely, so we write a dummy to
+  # an ExecStartPre override is too late. We solve this with:
-  # satisfy the file-existence check in the NixOS module.
+  #   1. tmpfiles: pre-create /run/hive-ci/runner-token with TOKEN=placeholder
-  autoRegisterScript = pkgs.writeShellScript "hive-ci-autoregister" ''
+  #   2. hive-ci-register.service (this script): on first boot only,
+  #      fetch the real token from forge and overwrite with TOKEN=<real>.
+  #   3. gitea-runner-hive.service: After=hive-ci-register.service
+  #
+  # On subsequent boots: .runner credentials file exists so the nixpkgs
+  # register step exits early — TOKEN value in the EnvironmentFile is
+  # irrelevant (placeholder is fine).
+  registerScript = pkgs.writeShellScript "hive-ci-register" ''
     set -euo pipefail
     TOKEN_FILE=/run/hive-ci/runner-token
-    STATE_FILE=/var/lib/gitea-runner/hive/.runner
-
-    mkdir -p /run/hive-ci
-    chmod 700 /run/hive-ci
-
-    if [ -f "$STATE_FILE" ]; then
-      # Already registered — dummy token satisfies the module's path check.
-      echo "already-registered" > "$TOKEN_FILE"
-      chmod 600 "$TOKEN_FILE"
-      exit 0
-    fi
-
     CORE_TOKEN=$(cat /run/hive-ci/core-token)
     FORGE_URL="http://127.0.0.1:${toString forgeCfg.httpPort}"
 
@@ -52,7 +47,8 @@ let
       exit 1
     fi
 
-    echo "$REG_TOKEN" > "$TOKEN_FILE"
+    # Write in EnvironmentFile format: TOKEN=<value>
+    echo "TOKEN=$REG_TOKEN" > "$TOKEN_FILE"
     chmod 600 "$TOKEN_FILE"
   '';
 in
@@ -64,13 +60,11 @@ in
   # survive restarts (gitea-actions-runner writes them to its stateDir
   # on first registration and reuses them on every subsequent start).
   #
-  # Auto-registration: on first boot the container fetches a runner
+  # Auto-registration: on first boot a oneshot service fetches a runner
   # registration token from the forge's admin API using the core token
   # hive-c0re writes to /var/lib/hyperhive/forge-core-token. No manual
   # token handling needed — `forge.ci.enable = true` is the full operator
-  # bootstrap. Registration flow: preStart calls the Forgejo admin API,
+  # bootstrap.
-  # writes the token to /run/hive-ci/runner-token, runner registers and
-  # persists credentials to stateDir — token file ignored on next boot.
   #
   # Nix builds inside the container use the shared /nix/store (standard
   # nixos-container behaviour) with sandbox-fallback = true, because
@@ -84,7 +78,10 @@ in
       example = true;
       description = ''
         Run a Forgejo Actions runner in a `hive-ci` nixos-container.
-        Disabled by default; requires `services.hyperhive.forge.enable = true`.
+        Grouped under `services.hyperhive.forge` because the runner is
+        tightly coupled to the forge instance it registers against.
+        Disabled by default; `services.hyperhive.forge.enable = true` is
+        a prerequisite (enforced by assertion).
 
         On first start the container auto-registers against hive-forge using
         hive-c0re's admin token — no manual token provisioning needed.
@@ -156,7 +153,7 @@ in
       privateNetwork = false;
 
       bindMounts = {
-        # Core token — used by the auto-register script on first boot.
+        # Core token — used by hive-ci-register.service on first boot.
         # Read-only: the container only reads it, never modifies it.
         "/run/hive-ci/core-token" = {
           hostPath = coreTokenPath;
@@ -185,9 +182,9 @@ in
             enable = true;
             name = cfg.name;
             url = "http://127.0.0.1:${toString forgeCfg.httpPort}";
-            # Token file is written by the ExecStartPre script below.
+            # EnvironmentFile providing TOKEN= for the nixpkgs register step.
-            # On first boot: real registration token fetched from forge API.
+            # Pre-created by tmpfiles (placeholder); overwritten with the real
-            # On subsequent boots: dummy value (runner uses .runner creds).
+            # token by hive-ci-register.service on first boot only.
             tokenFile = "/run/hive-ci/runner-token";
             labels = cfg.labels;
             settings = {
@@ -197,17 +194,41 @@ in
             };
           };
 
-          # Prepend auto-register script before the runner service starts.
+          # Pre-create the EnvironmentFile so gitea-runner-hive.service can
-          # `+` prefix runs with elevated privileges so it can read the
+          # always load it. The nixpkgs module sets EnvironmentFile=tokenFile
-          # bind-mounted core-token (owned by root on the host).
+          # which systemd loads before any ExecStartPre — the file must exist
-          systemd.services."gitea-runner-hive".serviceConfig.ExecStartPre = lib.mkBefore [
+          # at service-start time. On first boot hive-ci-register.service
-            "+${autoRegisterScript}"
+          # overwrites this placeholder with the real token before the runner
+          # starts. On subsequent boots the placeholder is harmless because
+          # the nixpkgs register step exits early when .runner already exists.
+          systemd.tmpfiles.rules = [
+            "f /run/hive-ci/runner-token 0600 root root - TOKEN=placeholder"
           ];
 
+          # Oneshot that fetches a runner registration token from the forge
+          # admin API and writes it to the EnvironmentFile. Runs only on
+          # first boot (ConditionPathExists gates on .runner absence) and
+          # before gitea-runner-hive.service via the After= dependency below.
+          systemd.services.hive-ci-register = {
+            description = "Register hive-ci runner against Forgejo (first boot)";
+            serviceConfig = {
+              Type = "oneshot";
+              RemainAfterExit = true;
+              ExecStart = registerScript;
+            };
+            # Only needed before .runner credentials exist.
+            unitConfig.ConditionPathExists = "!/var/lib/gitea-runner/hive/.runner";
+          };
+
+          # Runner must start after the register oneshot so the EnvironmentFile
+          # contains the real token on first boot.
+          systemd.services."gitea-runner-hive".after = [ "hive-ci-register.service" ];
+          systemd.services."gitea-runner-hive".wants = [ "hive-ci-register.service" ];
+
           # git is required by the runner's checkout step.
           # Everything else (nix, rust tools) is either part of NixOS
           # by default or pulled in hermetically by nix flake check.
-          # curl/jq in the autoregister preStart use absolute store paths.
+          # curl/jq in the register script use absolute store paths.
           environment.systemPackages = [ pkgs.git ];
         };
     };