forgedock 1.32.1 → 1.34.0

package/pool/install/install-agent-linux.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Native Linux (systemd) agent install: the Windows installer without the VM layer. Resolves host settings, then runs install-agent.sh,
+# which installs docker, node, enrolls the agent, builds the lane image and installs the computeshare-agent systemd unit.
+# Usage: install-agent-linux.sh --router URL --token CODE [--name N] [--port P] [--cpus N] [--mem GB] [--bundle FILE] [--dry-run]
+# Env equivalents: ROUTER_URL ENROLL_TOKEN AGENT_NAME AGENT_PORT ALLOW_CPUS ALLOW_MEM_GB BUNDLE AGENT_URL
+set -euo pipefail
+DRY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --router) ROUTER_URL="${2:?}"; shift 2 ;;
+    --token) ENROLL_TOKEN="${2:?}"; shift 2 ;;
+    --name) AGENT_NAME="${2:?}"; shift 2 ;;
+    --port) AGENT_PORT="${2:?}"; shift 2 ;;
+    --cpus) ALLOW_CPUS="${2:?}"; shift 2 ;;
+    --mem) ALLOW_MEM_GB="${2:?}"; shift 2 ;;
+    --bundle) BUNDLE="${2:?}"; shift 2 ;;
+    --dry-run) DRY=1; shift ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+: "${ROUTER_URL:?--router or ROUTER_URL required}" "${ENROLL_TOKEN:?--token or ENROLL_TOKEN required}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PORT="${AGENT_PORT:-7711}"
+AGENT_NAME="${AGENT_NAME:-$(hostname | tr 'A-Z' 'a-z')}"
+# Same defaults as install-agent.ps1: logical CPUs minus 4 (min 2); half of physical RAM (min 4 GB).
+CPUS="${ALLOW_CPUS:-0}"
+if [ "$CPUS" -le 0 ]; then CPUS=$(( $(nproc) - 4 )); [ "$CPUS" -ge 2 ] || CPUS=2; fi
+MEM="${ALLOW_MEM_GB:-0}"
+if [ "$MEM" -le 0 ]; then MEM=$(( $(awk '/MemTotal/ {print int($2/1024/1024)}' /proc/meminfo) / 2 )); [ "$MEM" -ge 4 ] || MEM=4; fi
+if [ -z "${AGENT_URL:-}" ]; then
+  if [ "$DRY" = 1 ] && ! command -v tailscale >/dev/null; then TS_IP="<tailscale-ip>"; else
+    TS_IP="$(tailscale ip -4 | head -1)"
+    [[ "$TS_IP" == 100.* ]] || { echo "no Tailscale IPv4 found (got '$TS_IP')" >&2; exit 1; }
+  fi
+  AGENT_URL="http://${TS_IP}:${PORT}"
+fi
+
+if [ "$DRY" = 1 ]; then
+  echo "router=$ROUTER_URL name=$AGENT_NAME url=$AGENT_URL port=$PORT cpus=$CPUS mem_gb=$MEM bundle=${BUNDLE:-<download>} token=<redacted>"
+  exit 0
+fi
+[ "$(id -u)" = 0 ] || { echo "run as root" >&2; exit 1; }
+
+if [ -z "${BUNDLE:-}" ]; then
+  BUNDLE="$(mktemp /tmp/computeshare-bundle.XXXXXX.tar.gz)"
+  trap 'rm -f "$BUNDLE"' EXIT
+  curl -fsS "${ROUTER_URL}/bootstrap/bundle.tar.gz?token=${ENROLL_TOKEN}" -o "$BUNDLE"
+fi
+export ROUTER_URL ENROLL_TOKEN AGENT_NAME AGENT_URL BUNDLE
+export AGENT_PORT="$PORT" ALLOW_CPUS="$CPUS" ALLOW_MEM_GB="$MEM"
+bash "$HERE/install-agent.sh"

package/pool/install/install-agent.ps1

@@ -0,0 +1,225 @@
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+<#
+.SYNOPSIS
+  Installs a computeshare agent on a Windows host: a dedicated WSL2 distro ("computeshare") running Docker and the agent,
+  reachable on this machine's Tailscale IP, with a CPU/RAM ceiling enforced by the WSL VM itself.
+.NOTES
+  Run in an elevated PowerShell. Normally started by the router's bootstrap one-liner (computeshare install-command).
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory)] [string] $RouterUrl,
+  [Parameter(Mandatory)] [string] $EnrollToken,
+  [Parameter(Mandatory)] [string] $BundlePath,
+  [string] $AgentName = $env:COMPUTERNAME.ToLower(),
+  [int] $Port = 7711,
+  [int] $AllowCpus = 0,      # 0 = logical CPUs minus 4 (min 2)
+  [int] $AllowMemGb = 0,     # 0 = half of physical RAM (min 4)
+  [string] $Distro = 'computeshare',
+  [switch] $Force            # kept for compatibility; the install never prompts
+)
+$ErrorActionPreference = 'Stop'
+$env:WSL_UTF8 = '1'
+function Say($m) { Write-Host "[computeshare] $m" -ForegroundColor Cyan }
+function Fail($m) { Write-Host "[computeshare] $m" -ForegroundColor Red; exit 1 }
+
+$principal = [Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()
+if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { Fail 'Run this from an elevated (Administrator) PowerShell.' }
+
+$installDir = Join-Path $env:ProgramData 'computeshare'
+New-Item -ItemType Directory -Force -Path $installDir | Out-Null
+
+# --- Tailscale ---------------------------------------------------------------------------------------------------
+$ts = (Get-Command tailscale.exe -ErrorAction SilentlyContinue).Source
+if (-not $ts) { $ts = Join-Path $env:ProgramFiles 'Tailscale\tailscale.exe' }
+if (-not (Test-Path $ts)) { Fail 'Tailscale is not installed.' }
+$tsIp = (& $ts ip -4 | Select-Object -First 1).Trim()
+if ($tsIp -notmatch '^100\.') { Fail "Could not read this machine's Tailscale IPv4 (got '$tsIp')." }
+Say "Tailscale IP $tsIp"
+
+# --- Resource ceiling --------------------------------------------------------------------------------------------
+$threads = [Environment]::ProcessorCount
+Add-Type -AssemblyName Microsoft.VisualBasic
+$ramGb = [math]::Floor((New-Object Microsoft.VisualBasic.Devices.ComputerInfo).TotalPhysicalMemory / 1GB)
+if ($AllowCpus -le 0) { $AllowCpus = [math]::Max(2, $threads - 4) }
+if ($AllowMemGb -le 0) { $AllowMemGb = [math]::Max(4, [math]::Floor($ramGb / 2)) }
+$vmMemGb = $AllowMemGb + 2   # docker + agent overhead inside the VM
+Say "Host: $threads threads, $ramGb GB RAM. Lanes get $AllowCpus CPUs / $AllowMemGb GB (WSL VM capped at $AllowCpus CPUs / $vmMemGb GB)."
+
+# --- WSL ---------------------------------------------------------------------------------------------------------
+# wsl.exe can hang when the WSL service is wedged. Every call runs in a job with a timeout; on a hang the service is
+# restarted once and the call retried, so the install never needs a manual fix.
+function Reset-WslService {
+  Say 'WSL service is not responding: restarting it'
+  Get-Process wsl, wslhost, wslrelay, wslservice -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue
+  Start-Sleep -Seconds 2
+  Start-Service WSLService -ErrorAction SilentlyContinue
+  Start-Sleep -Seconds 3
+}
+function Invoke-Wsl([string[]] $WslArgs, [int] $TimeoutSec = 120, [switch] $Optional) {
+  for ($try = 1; $try -le 2; $try++) {
+    $job = Start-Job -ScriptBlock { param($a) $env:WSL_UTF8 = '1'; $o = & wsl.exe @a 2>&1 | Out-String; [pscustomobject]@{ rc = $LASTEXITCODE; out = $o } } -ArgumentList (, $WslArgs)
+    if (Wait-Job $job -Timeout $TimeoutSec) { $r = Receive-Job $job; Remove-Job $job -Force; return $r }
+    Stop-Job $job -ErrorAction SilentlyContinue; Remove-Job $job -Force -ErrorAction SilentlyContinue
+    if ($Optional) { return $null }
+    if ($try -eq 1) { Reset-WslService }
+  }
+  Fail "wsl $($WslArgs -join ' ') still hangs after restarting the WSL service. Reboot this PC, then run a fresh install command."
+}
+Say 'Checking WSL'
+$v = Invoke-Wsl @('--version') 60
+if ($v.rc -ne 0) {
+  Say 'WSL is missing or the old inbox version: installing it. Reboot when it finishes, then run a fresh install command.'
+  $r = Invoke-Wsl @('--install', '--no-distribution', '--web-download') 1200
+  Write-Host $r.out
+  exit 3010
+}
+$wslVer = [version]'0.0'
+if ($v.out -match 'WSL[^:\r\n]*:\s*([0-9]+(\.[0-9]+)+)') { $wslVer = [version]$Matches[1] }
+Say "WSL $wslVer"
+if ($wslVer -lt [version]'2.0') {
+  # mirrored networking and the current --import behaviour need WSL 2.0+; only then is an update worth the wait
+  Say 'Updating WSL (up to 10 min; skipped if it stalls)'
+  $u = Invoke-Wsl @('--update', '--web-download') 600 -Optional
+  if ($null -eq $u) { Say 'wsl --update stalled; continuing with the installed version.' }
+}
+
+# WSL 2 needs the Virtual Machine Platform feature and CPU virtualisation enabled in firmware (wsl.exe alone is not enough).
+$cpu = Get-CimInstance Win32_Processor -ErrorAction SilentlyContinue | Select-Object -First 1
+$hvPresent = [bool](Get-CimInstance Win32_ComputerSystem -ErrorAction SilentlyContinue).HypervisorPresent
+if (-not $hvPresent -and $cpu -and $cpu.VirtualizationFirmwareEnabled -eq $false) {
+  Fail 'CPU virtualisation is disabled in the BIOS/UEFI (Intel VT-x / AMD SVM). Enable it in the firmware setup, boot Windows, then run a fresh install command.'
+}
+$needReboot = $false
+foreach ($f in 'VirtualMachinePlatform', 'Microsoft-Windows-Subsystem-Linux') {
+  $st = (Get-WindowsOptionalFeature -Online -FeatureName $f -ErrorAction SilentlyContinue).State
+  if ($st -and $st -ne 'Enabled') {
+    Say "Enabling Windows feature $f"
+    $r = Enable-WindowsOptionalFeature -Online -FeatureName $f -All -NoRestart -ErrorAction Stop
+    if ($r.RestartNeeded) { $needReboot = $true }
+  }
+}
+if ($needReboot) {
+  Say 'Windows features for WSL 2 were enabled. Reboot this PC, then run a fresh install command (computeshare install-command).'
+  exit 3010
+}
+
+$build = [int](Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion').CurrentBuildNumber
+$mirrored = $build -ge 22621
+Say ("Networking: " + ($(if ($mirrored) { 'mirrored (agent listens on the Tailscale IP directly)' } else { 'NAT + portproxy (Windows 10 / older 11)' })))
+
+# .wslconfig is per Windows user and applies to every distro: merge our keys, keep everything else.
+$wslConfig = Join-Path $env:USERPROFILE '.wslconfig'
+$lines = @(); if (Test-Path $wslConfig) { $lines = Get-Content $wslConfig }
+$want = [ordered]@{ processors = "$AllowCpus"; memory = "${vmMemGb}GB"; vmIdleTimeout = '-1' }
+if ($mirrored) { $want['networkingMode'] = 'mirrored' }
+$out = New-Object System.Collections.Generic.List[string]; $inWsl2 = $false; $seen = @{}
+foreach ($l in $lines) {
+  if ($l -match '^\s*\[(.+)\]\s*$') {
+    if ($inWsl2) { foreach ($k in $want.Keys) { if (-not $seen[$k]) { $out.Add("$k=$($want[$k])"); $seen[$k] = $true } } }
+    $inWsl2 = ($Matches[1].Trim().ToLower() -eq 'wsl2')
+    $out.Add($l); continue
+  }
+  if ($inWsl2 -and $l -match '^\s*([A-Za-z]+)\s*=') {
+    $k = $want.Keys | Where-Object { $_ -ieq $Matches[1] } | Select-Object -First 1
+    if ($k) { $out.Add("$k=$($want[$k])"); $seen[$k] = $true; continue }
+  }
+  $out.Add($l)
+}
+if ($inWsl2) { foreach ($k in $want.Keys) { if (-not $seen[$k]) { $out.Add("$k=$($want[$k])"); $seen[$k] = $true } } }
+if (-not ($out | Where-Object { $_ -match '^\s*\[wsl2\]\s*$' })) { $out.Add('[wsl2]'); foreach ($k in $want.Keys) { $out.Add("$k=$($want[$k])") } }
+$changed = (($lines -join "`n") -ne ($out -join "`n"))
+if ($changed) {
+  if (Test-Path $wslConfig) { Copy-Item $wslConfig "$wslConfig.computeshare-backup" -Force }
+  Set-Content -Path $wslConfig -Value $out -Encoding ascii
+  Say "Updated $wslConfig (backup: .wslconfig.computeshare-backup). NOTE: these limits apply to all your WSL distros."
+}
+
+# --- Dedicated distro -------------------------------------------------------------------------------------------
+$distros = (Invoke-Wsl @('-l', '-q') 60).out -split "`r?`n" | ForEach-Object { $_.Trim() } | Where-Object { $_ }
+if ($distros -notcontains $Distro) {
+  $base = 'https://cloud-images.ubuntu.com/wsl/releases/24.04/current'
+  $file = 'ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz'
+  $tar = Join-Path $installDir $file
+  # SHA256SUMS is served without a content type, so PowerShell 5.1 would hand back bytes: save it and read it as text.
+  $sumsFile = Join-Path $installDir 'SHA256SUMS'
+  Invoke-WebRequest -UseBasicParsing "$base/SHA256SUMS" -OutFile $sumsFile
+  $expected = ((Get-Content $sumsFile | Where-Object { $_ -match [regex]::Escape($file) } | Select-Object -First 1) -split '\s+')[0]
+  if (-not $expected) { Fail "no checksum for $file in SHA256SUMS" }
+  $actual = if (Test-Path $tar) { (Get-FileHash -Algorithm SHA256 $tar).Hash.ToLower() } else { '' }
+  if ($actual -ne $expected.ToLower()) {
+    Say "Downloading Ubuntu 24.04 WSL rootfs"
+    Invoke-WebRequest -UseBasicParsing "$base/$file" -OutFile $tar
+    $actual = (Get-FileHash -Algorithm SHA256 $tar).Hash.ToLower()
+    if ($actual -ne $expected.ToLower()) { Remove-Item $tar -Force; Fail "rootfs checksum mismatch ($actual vs $expected)" }
+  } else { Say 'Reusing the already downloaded rootfs (checksum verified)' }
+  Say "Importing WSL distro '$Distro'"
+  $r = Invoke-Wsl @('--import', $Distro, (Join-Path $installDir 'wsl'), $tar, '--version', '2') 900
+  if ($r.rc -ne 0) {
+    if ($r.out -match 'HCS_E_HYPERV_NOT_INSTALLED|Virtual Machine Platform') { Fail "WSL 2 cannot start a VM here: enable virtualisation (Intel VT-x / AMD SVM) in the BIOS/UEFI, reboot, and run a fresh install command. Details: $($r.out.Trim())" }
+    Fail "wsl --import failed: $($r.out)"
+  }
+  Remove-Item $tar -Force
+}
+
+# systemd for docker + the agent; no Windows PATH or Windows binaries inside the lane distro.
+$wslConf = "[boot]\nsystemd=true\n\n[network]\nhostname=$AgentName-cs\n\n[interop]\nappendWindowsPath=false\n"
+$before = (Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'cat', '/etc/wsl.conf') 120).out
+[void](Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'sh', '-c', "printf '$wslConf' > /etc/wsl.conf") 120)
+$after = (Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'cat', '/etc/wsl.conf') 120).out
+$confChanged = ($before -ne $after)
+
+if ($changed -or $confChanged -or -not ((Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'ps', '-p', '1', '-o', 'comm=') 120).out -match 'systemd')) {
+  Say 'Restarting WSL to apply the settings (this briefly stops every running WSL distro)'
+  [void](Invoke-Wsl @('--shutdown') 120)
+  Start-Sleep -Seconds 3
+  $p1 = (Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'ps', '-p', '1', '-o', 'comm=') 180).out
+  if ($p1 -notmatch 'systemd') { Fail "systemd did not start in the '$Distro' distro (PID 1: $($p1.Trim()))." }
+}
+
+# --- Firewall ------------------------------------------------------------------------------------------------------
+# Idempotent: re-runs replace the rules (a leftover rule must never stop the install).
+Remove-NetFirewallRule -Name 'computeshare-agent' -ErrorAction SilentlyContinue
+New-NetFirewallRule -Name 'computeshare-agent' -DisplayName 'computeshare agent (Tailscale only)' -Direction Inbound -Protocol TCP -LocalPort $Port -InterfaceAlias 'Tailscale' -Action Allow | Out-Null
+if ($mirrored -and (Get-Command New-NetFirewallHyperVRule -ErrorAction SilentlyContinue)) {
+  $wslCreator = '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}'
+  # Hyper-V rules are not always addressable by the -Name they were created with: match ours by display name or port.
+  Get-NetFirewallHyperVRule -ErrorAction SilentlyContinue |
+    Where-Object { $_.DisplayName -like 'computeshare*' -or $_.Name -like '*computeshare*' -or ("$($_.LocalPorts)" -eq "$Port" -and "$($_.VMCreatorId)" -eq $wslCreator) } |
+    ForEach-Object { Remove-NetFirewallHyperVRule -Name $_.Name -ErrorAction SilentlyContinue }
+  try {
+    New-NetFirewallHyperVRule -Name "computeshare-agent-$Port" -DisplayName 'computeshare agent' -Direction Inbound -VMCreatorId $wslCreator -Protocol TCP -LocalPorts $Port -Action Allow -ErrorAction Stop | Out-Null
+  } catch {
+    Say "Hyper-V firewall rule not created ($($_.Exception.Message.Trim())); continuing, reachability is checked at the end."
+  }
+}
+
+# --- Agent inside the distro --------------------------------------------------------------------------------------
+$bundleWsl = (Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'wslpath', '-a', ($BundlePath -replace '\\', '/')) 60).out.Trim()
+$r = Invoke-Wsl @('-d', $Distro, '-u', 'root', '--', 'sh', '-c', "tar -xzf '$bundleWsl' -C /tmp pool/install/install-agent.sh && cp '$bundleWsl' /tmp/computeshare-bundle.tar.gz") 120
+if ($r.rc -ne 0) { Fail "could not stage the bundle in the distro: $($r.out)" }
+$envs = "ROUTER_URL='$RouterUrl' ENROLL_TOKEN='$EnrollToken' AGENT_NAME='$AgentName' AGENT_URL='http://${tsIp}:$Port' AGENT_PORT='$Port' ALLOW_CPUS='$AllowCpus' ALLOW_MEM_GB='$AllowMemGb' BUNDLE=/tmp/computeshare-bundle.tar.gz"
+Say 'Installing Docker, Node and the agent inside the distro (first run builds the lane image; this takes a while)'
+& wsl.exe -d $Distro -u root -- bash -c "$envs bash /tmp/pool/install/install-agent.sh"
+if ($LASTEXITCODE -ne 0) { Fail 'Linux-side install failed (see output above).' }
+
+# --- Keep-alive task: keeps the distro up, holds off sleep while lanes run, refreshes portproxy on NAT -----------------
+$keep = Join-Path $installDir 'keepalive.ps1'
+Copy-Item (Join-Path $PSScriptRoot 'keepalive.ps1') $keep -Force
+$taskArgs = "-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$keep`" -Distro $Distro -Port $Port -TailscaleIp $tsIp" + $(if ($mirrored) { ' -Mirrored' } else { '' })
+$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument $taskArgs
+$trigger = New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"
+$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit ([TimeSpan]::Zero) -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1)
+Register-ScheduledTask -TaskName 'computeshare-keepalive' -Action $action -Trigger $trigger -Settings $settings -Description 'computeshare agent keep-alive' -Force | Out-Null
+Start-ScheduledTask -TaskName 'computeshare-keepalive'
+
+Start-Sleep -Seconds 5
+try {
+  # Windows cannot reach its own Tailscale IP through the mirrored WSL network (no hairpin), so check via loopback;
+  # the router reaches the agent on the Tailscale IP.
+  $h = Invoke-RestMethod -Uri "http://127.0.0.1:$Port/health" -TimeoutSec 10
+  Say "Agent '$AgentName' is up on http://${tsIp}:$Port : $($h.cpus_total) CPUs / $($h.mem_total_gb) GB reserved for lanes."
+} catch {
+  Say "Installed, but http://${tsIp}:$Port/health is not answering yet. Check: wsl -d $Distro -u root -- journalctl -u computeshare-agent -n 50"
+}

package/pool/install/install-agent.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Linux side of the agent install. Runs as root inside the dedicated `computeshare` WSL distro (or any systemd Linux host).
+# Required env: ROUTER_URL ENROLL_TOKEN AGENT_NAME AGENT_URL ALLOW_CPUS ALLOW_MEM_GB BUNDLE
+set -euo pipefail
+: "${ROUTER_URL:?}" "${ENROLL_TOKEN:?}" "${AGENT_NAME:?}" "${AGENT_URL:?}" "${ALLOW_CPUS:?}" "${ALLOW_MEM_GB:?}" "${BUNDLE:?}"
+# Never resolve tools through the Windows PATH that WSL appends (e.g. Docker Desktop's docker CLI).
+export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+NODE_VERSION=22.12.0
+PORT="${AGENT_PORT:-7711}"
+log() { echo "[computeshare] $*"; }
+
+[ "$(id -u)" = 0 ] || { echo "run as root" >&2; exit 1; }
+pidof systemd >/dev/null || [ "$(ps -p 1 -o comm=)" = systemd ] || { echo "systemd is not PID 1; enable it in /etc/wsl.conf and restart the distro" >&2; exit 1; }
+
+log "base packages"
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y -qq ca-certificates curl git jq xz-utils >/dev/null
+
+if [ ! -x /usr/bin/dockerd ]; then
+  log "docker engine"
+  install -d -m 0755 /etc/apt/keyrings
+  . /etc/os-release
+  DOCKER_DISTRO=ubuntu; [ "${ID:-}" = debian ] && DOCKER_DISTRO=debian
+  curl -fsSL "https://download.docker.com/linux/${DOCKER_DISTRO}/gpg" -o /etc/apt/keyrings/docker.asc
+  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${DOCKER_DISTRO} ${VERSION_CODENAME} stable" > /etc/apt/sources.list.d/docker.list
+  apt-get update -qq
+  apt-get install -y -qq docker-ce docker-ce-cli containerd.io >/dev/null
+fi
+# WSL mirrored networking usually has no IPv6 route; dockerd would still dial registries over IPv6 and fail.
+if grep -qi microsoft /proc/sys/kernel/osrelease && [ -z "$(ip -6 route show default 2>/dev/null)" ]; then
+  printf 'net.ipv6.conf.all.disable_ipv6=1\nnet.ipv6.conf.default.disable_ipv6=1\n' > /etc/sysctl.d/90-computeshare-noipv6.conf
+  sysctl -q -p /etc/sysctl.d/90-computeshare-noipv6.conf
+  systemctl restart docker 2>/dev/null || true
+fi
+systemctl enable --now docker >/dev/null
+
+if [ ! -x /opt/node/bin/node ] || [ "$(/opt/node/bin/node --version)" != "v${NODE_VERSION}" ]; then
+  log "node ${NODE_VERSION}"
+  rm -rf /opt/node
+  case "$(uname -m)" in aarch64|arm64) NODE_ARCH=arm64 ;; *) NODE_ARCH=x64 ;; esac
+  curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz" | tar -xJ -C /opt
+  mv "/opt/node-v${NODE_VERSION}-linux-${NODE_ARCH}" /opt/node
+fi
+
+log "agent code"
+rm -rf /opt/computeshare.new && mkdir -p /opt/computeshare.new
+tar -xzf "$BUNDLE" -C /opt/computeshare.new
+rm -rf /opt/computeshare && mv /opt/computeshare.new /opt/computeshare
+
+install -d -m 0700 /etc/computeshare /var/lib/computeshare
+if [ ! -s /etc/computeshare/agent.token ]; then
+  log "enrolling ${AGENT_NAME} (${AGENT_URL}) with ${ROUTER_URL}"
+  resp=$(curl -fsS -X POST "${ROUTER_URL}/enroll" -H 'content-type: application/json' \
+    -d "$(jq -n --arg t "$ENROLL_TOKEN" --arg n "$AGENT_NAME" --arg u "$AGENT_URL" '{token:$t,name:$n,url:$u}')")
+  umask 077
+  echo "$resp" | jq -r .agent_token > /etc/computeshare/agent.token
+  [ -s /etc/computeshare/agent.token ] && [ "$(cat /etc/computeshare/agent.token)" != null ] || { echo "enrollment failed: $resp" >&2; rm -f /etc/computeshare/agent.token; exit 1; }
+fi
+
+jq -n --arg name "$AGENT_NAME" --arg router "$ROUTER_URL" --argjson port "$PORT" --argjson cpus "$ALLOW_CPUS" --argjson mem "$ALLOW_MEM_GB" '{
+  name: $name, listen: {host: "0.0.0.0", port: $port}, token_file: "/etc/computeshare/agent.token",
+  router_url: $router, code_root: "/opt/computeshare",
+  state_dir: "/var/lib/computeshare",
+  allow_cpus: $cpus, allow_mem_gb: $mem, lease_ttl_s: 600, max_lifetime_s: 21600, keep_exited_s: 7200, reap_interval_s: 30
+}' > /etc/computeshare/agent.json
+chmod 0600 /etc/computeshare/agent.json
+
+log "building lane image (first run takes several minutes)"
+FD_VERSION="$(jq -r .version /opt/computeshare/package.json)"
+docker build -q -t "forgedock-lane:${FD_VERSION}" --build-arg "FORGEDOCK_VERSION=${FD_VERSION}" /opt/computeshare/pool/image >/dev/null
+
+cat > /etc/systemd/system/computeshare-agent.service <<EOF
+[Unit]
+Description=computeshare agent
+After=docker.service network-online.target
+Requires=docker.service
+
+[Service]
+ExecStart=/opt/node/bin/node /opt/computeshare/bin/pool/cli.mjs agent --config /etc/computeshare/agent.json
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+systemctl daemon-reload
+systemctl enable computeshare-agent >/dev/null
+systemctl restart computeshare-agent
+
+for i in $(seq 1 20); do
+  if curl -fsS "http://127.0.0.1:${PORT}/health" >/dev/null 2>&1; then
+    log "agent healthy: $(curl -fsS "http://127.0.0.1:${PORT}/health")"
+    exit 0
+  fi
+  sleep 1
+done
+echo "agent did not become healthy; see: journalctl -u computeshare-agent" >&2
+exit 1

package/pool/install/install-router.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Installs the computeshare router as a systemd --user service on the host that runs ForgeDock.
+# It listens only on this machine's Tailscale IP. Re-running keeps existing tokens and agent enrollments.
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CONF_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/computeshare"
+PORT="${ROUTER_PORT:-7710}"
+TS_IP="$(tailscale ip -4 | head -1)"
+[[ "$TS_IP" == 100.* ]] || { echo "no Tailscale IPv4 found" >&2; exit 1; }
+NODE="$(command -v node)"
+
+mkdir -p "$CONF_DIR" && chmod 700 "$CONF_DIR"
+umask 077
+for t in forgedock enroll; do
+  [ -s "$CONF_DIR/$t.token" ] || openssl rand -hex 32 > "$CONF_DIR/$t.token"
+done
+
+# repos: slug -> gitignored forge.yaml that lanes need (passed to the sandbox, never committed). Extend as needed.
+# An existing router.json is kept (re-running the installer must not drop repos or settings added later).
+[ -s "$CONF_DIR/router.json" ] || cat > "$CONF_DIR/router.json" <<EOF
+{
+  "listen": { "host": "$TS_IP", "port": $PORT },
+  "public_url": "http://$TS_IP:$PORT",
+  "state_dir": "$CONF_DIR/state",
+  "lane": { "cpus": ${LANE_CPUS:-2}, "mem_gb": ${LANE_MEM_GB:-3} },
+  "lease_interval_s": 60,
+  "abandon_after_s": 1800,
+  "retry_after_s": 60,
+  "repos": {}
+}
+EOF
+
+mkdir -p "$HOME/.config/systemd/user"
+cat > "$HOME/.config/systemd/user/computeshare-router.service" <<EOF
+[Unit]
+Description=computeshare router
+After=network-online.target tailscaled.service
+
+[Service]
+ExecStart=$NODE $REPO_ROOT/bin/pool/cli.mjs router --config $CONF_DIR/router.json
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now computeshare-router >/dev/null
+systemctl --user restart computeshare-router
+loginctl enable-linger "$USER" 2>/dev/null || true
+
+# ForgeDock reads execution.token_env from the env, then the OS keychain (service forgedock, account = the name).
+if command -v secret-tool >/dev/null; then
+  secret-tool store --label "forgedock COMPUTESHARE_TOKEN" service forgedock account COMPUTESHARE_TOKEN < "$CONF_DIR/forgedock.token" \
+    && echo "[computeshare] stored the ForgeDock token in the keychain as COMPUTESHARE_TOKEN"
+fi
+
+for i in $(seq 1 15); do
+  curl -fsS "http://$TS_IP:$PORT/health" >/dev/null 2>&1 && break
+  sleep 1
+done
+echo "[computeshare] router: $(curl -fsS "http://$TS_IP:$PORT/health")"
+echo
+echo "Install an agent: run this in an elevated PowerShell on the Windows host:"
+"$NODE" "$REPO_ROOT/bin/pool/cli.mjs" install-command --config "$CONF_DIR/router.json"

package/pool/install/keepalive.ps1

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Runs at logon (scheduled task). Keeps the computeshare distro running, keeps Windows awake while lanes are active,
+# and on NAT networking keeps a portproxy from the Tailscale IP to the distro's current address.
+param([string] $Distro = 'computeshare', [int] $Port = 7711, [string] $TailscaleIp, [switch] $Mirrored)
+$ErrorActionPreference = 'Continue'
+$env:WSL_UTF8 = '1'
+
+Add-Type -Namespace CS -Name Power -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint flags);'
+$ES_CONTINUOUS = [uint32]'0x80000000'; $ES_SYSTEM_REQUIRED = [uint32]'0x00000001'
+
+$holder = $null
+while ($true) {
+  if (-not $holder -or $holder.HasExited) {
+    # A long-lived process keeps the distro (and its systemd services) from being stopped by WSL.
+    $holder = Start-Process -FilePath 'wsl.exe' -ArgumentList @('-d', $Distro, '-u', 'root', '--', 'sleep', 'infinity') -WindowStyle Hidden -PassThru
+    Start-Sleep -Seconds 5
+  }
+  if (-not $Mirrored -and $TailscaleIp) {
+    $wslIp = ((& wsl.exe -d $Distro -u root -- hostname -I) -split '\s+' | Where-Object { $_ -match '^\d+\.' } | Select-Object -First 1)
+    if ($wslIp) {
+      $cur = (netsh interface portproxy show v4tov4) -match [regex]::Escape("$TailscaleIp") -match "$Port"
+      if (-not ($cur -match [regex]::Escape($wslIp))) {
+        netsh interface portproxy delete v4tov4 listenaddress=$TailscaleIp listenport=$Port | Out-Null
+        netsh interface portproxy add v4tov4 listenaddress=$TailscaleIp listenport=$Port connectaddress=$wslIp connectport=$Port | Out-Null
+      }
+    }
+  }
+  $active = 0
+  try { $active = [int](Invoke-RestMethod -Uri "http://127.0.0.1:$Port/health" -TimeoutSec 5).active } catch {
+    if ($TailscaleIp) { try { $active = [int](Invoke-RestMethod -Uri "http://${TailscaleIp}:$Port/health" -TimeoutSec 5).active } catch {} }
+  }
+  if ($active -gt 0) { [void][CS.Power]::SetThreadExecutionState($ES_CONTINUOUS -bor $ES_SYSTEM_REQUIRED) }
+  else { [void][CS.Power]::SetThreadExecutionState($ES_CONTINUOUS) }
+  Start-Sleep -Seconds 60
+}

package/pool/install/uninstall-agent.ps1

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+<#
+.SYNOPSIS
+  Removes the computeshare agent from this Windows host: keep-alive task, firewall rules, portproxy, the dedicated WSL
+  distro (with every container, image and cache in it) and the .wslconfig changes (restored from the backup).
+#>
+param([string] $Distro = 'computeshare', [int] $Port = 7711)
+$ErrorActionPreference = 'Continue'
+$env:WSL_UTF8 = '1'
+Unregister-ScheduledTask -TaskName 'computeshare-keepalive' -Confirm:$false -ErrorAction SilentlyContinue
+Get-Process powershell -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -match 'computeshare\\keepalive.ps1' } | Stop-Process -Force
+Get-NetFirewallRule -Name 'computeshare-agent' -ErrorAction SilentlyContinue | Remove-NetFirewallRule
+if (Get-Command Get-NetFirewallHyperVRule -ErrorAction SilentlyContinue) { Get-NetFirewallHyperVRule -ErrorAction SilentlyContinue | Where-Object { $_.DisplayName -like 'computeshare*' -or $_.Name -like '*computeshare*' } | ForEach-Object { Remove-NetFirewallHyperVRule -Name $_.Name -ErrorAction SilentlyContinue } }
+(netsh interface portproxy show v4tov4) -match " $Port " | ForEach-Object { $a = ($_ -split '\s+')[0]; if ($a) { netsh interface portproxy delete v4tov4 listenaddress=$a listenport=$Port | Out-Null } }
+& wsl.exe --unregister $Distro
+$cfg = Join-Path $env:USERPROFILE '.wslconfig'
+if (Test-Path "$cfg.computeshare-backup") { Move-Item "$cfg.computeshare-backup" $cfg -Force; Write-Host 'Restored .wslconfig from backup (takes effect after wsl --shutdown).' }
+Remove-Item -Recurse -Force (Join-Path $env:ProgramData 'computeshare') -ErrorAction SilentlyContinue
+Write-Host '[computeshare] agent removed. Remove it from the router with: computeshare status (then delete it from router-state.json).'

package/scripts/hotspots.sh

@@ -7,14 +7,17 @@
 #
 # Usage: hotspots.sh [--base <ref>] [--] <path>...
 # Config: forge.yaml maintenance.hotspot {enabled, file_lines, growth_lines, exclude_globs}; defaults true/2000/150/[]
-#   (also when forge.yaml or yq is missing).
+#   (also when forge.yaml or yq is missing); maintenance.generated_paths (forge#4519): shell globs of generated,
+#   bot-owned files, default [].
 # Output (stdout, one JSON object):
-#   {"enabled","file_lines","growth_lines","files":[{path,lines,commits_90d,hotspot,over,excluded,base_lines,growth}]}
+#   {"enabled","file_lines","growth_lines","generated_paths",
+#    "files":[{path,lines,commits_90d,hotspot,over,generated,excluded,base_lines,growth}]}
 # lines = `wc -l` of the working-tree file (0 when missing); commits_90d = `git rev-list --count --since=90.days HEAD`;
-# hotspot = lines × commits_90d; over = lines > file_lines; excluded = linguist-generated / linguist-vendored set by
-# .gitattributes, or a match of an exclude_glob (shell pattern, `*` crosses `/`). Without --base no blob is read and
+# hotspot = lines × commits_90d; over = lines > file_lines; generated = linguist-generated set by .gitattributes, a
+# match of a generated_paths glob, or `@generated` / `DO NOT EDIT` in the first 5 lines of the working-tree file;
+# excluded = generated, linguist-vendored, or a match of an exclude_glob (shell pattern, `*` crosses `/`). Without --base no blob is read and
 # base_lines/growth are null; with --base they are the line count at git merge-base(<ref>, HEAD) (0 when absent there)
-# and lines - base_lines. enabled:false prints files:[] and does no per-file work.
+# and lines - base_lines. enabled:false prints files:[] (generated_paths still set) and does no per-file work.
 # Exit: 0 ok | 2 usage or bad ref. bash 3.2 portable.
 set -uo pipefail
 
@@ -31,19 +34,21 @@ while [ $# -gt 0 ]; do
 done
 
 # ---- config: maintenance.hotspot as JSON, {} when unreadable ----
-CFG='{}'
+CFG='{}'; GEN_CFG='[]'
 if [ -f forge.yaml ] && command -v yq >/dev/null 2>&1; then
   c=$(yq -o=json '.maintenance.hotspot // {}' forge.yaml 2>/dev/null) || c=""
   printf '%s' "$c" | jq -e 'type == "object"' >/dev/null 2>&1 && CFG="$c"
+  g=$(yq -o=json '.maintenance.generated_paths // []' forge.yaml 2>/dev/null) || g=""
+  printf '%s' "$g" | jq -e 'type == "array"' >/dev/null 2>&1 && GEN_CFG="$g"
 fi
+GEN_CFG=$(printf '%s' "$GEN_CFG" | jq -c '[.[] | strings | select(length > 0)]')
 CFG=$(printf '%s' "$CFG" | jq -c '
   def pos($d): if type == "number" and . > 0 then floor else $d end;
   { enabled: (.enabled != false), file_lines: (.file_lines | pos(2000)), growth_lines: (.growth_lines | pos(150)),
     exclude_globs: ([(.exclude_globs // [])[]? | strings]) }')
 ENABLED=$(printf '%s' "$CFG" | jq -r '.enabled')
 FILE_LINES=$(printf '%s' "$CFG" | jq -r '.file_lines')
-GROWTH_LINES=$(printf '%s' "$CFG" | jq -r '.growth_lines')
-head_json() { printf '%s' "$CFG" | jq -c --argjson files "$1" '{enabled, file_lines, growth_lines, files: $files}'; }
+head_json() { printf '%s' "$CFG" | jq -c --argjson files "$1" --argjson gen "$GEN_CFG" '{enabled, file_lines, growth_lines, generated_paths: $gen, files: $files}'; }
 [ "$ENABLED" = true ] || { head_json '[]'; exit 0; }
 
 MB=""
@@ -53,6 +58,19 @@ if [ -n "$BASE" ]; then
 fi
 HAS_HEAD=0; git rev-parse --verify -q "HEAD^{commit}" >/dev/null && HAS_HEAD=1
 GLOBS=$(printf '%s' "$CFG" | jq -r '.exclude_globs[]')
+GEN_GLOBS=$(printf '%s' "$GEN_CFG" | jq -r '.[]')
+# 0 when $1 matches a newline-separated list of shell patterns in $2 (`*` crosses `/`)
+glob_hit() {
+  [ -n "$2" ] || return 1
+  while IFS= read -r g; do
+    [ -n "$g" ] || continue
+    # shellcheck disable=SC2254
+    case "$1" in $g) return 0 ;; esac
+  done <<EOF
+$2
+EOF
+  return 1
+}
 
 T=$(mktemp -d "${TMPDIR:-/tmp}/hotspots.XXXXXX") || die "mktemp failed"
 trap 'rm -rf "$T"' EXIT
@@ -72,29 +90,23 @@ for p in "$@"; do
   [ -n "$p" ] || continue
   lines=0; [ -f "$p" ] && lines=$(wc -l < "$p" | tr -d ' ')
   commits=$(cat "$T/c.$i" 2>/dev/null); case "$commits" in ''|*[!0-9]*) commits=0 ;; esac
-  excluded=false
-  if git check-attr linguist-generated linguist-vendored -- "$p" 2>/dev/null | grep -qE ': (set|true)$'; then excluded=true; fi
-  if [ "$excluded" = false ] && [ -n "$GLOBS" ]; then
-    while IFS= read -r g; do
-      [ -n "$g" ] || continue
-      # shellcheck disable=SC2254
-      case "$p" in $g) excluded=true; break ;; esac
-    done <<EOF
-$GLOBS
-EOF
-  fi
+  generated=false; excluded=false
+  if git check-attr linguist-generated -- "$p" 2>/dev/null | grep -qE ': (set|true)$' || glob_hit "$p" "$GEN_GLOBS" \
+    || { [ -f "$p" ] && head -n 5 "$p" 2>/dev/null | grep -qE '@generated|DO NOT EDIT'; }; then generated=true; excluded=true; fi
+  if [ "$excluded" = false ] && git check-attr linguist-vendored -- "$p" 2>/dev/null | grep -qE ': (set|true)$'; then excluded=true; fi
+  if [ "$excluded" = false ] && glob_hit "$p" "$GLOBS"; then excluded=true; fi
   base_lines=null; growth=null
   if [ -n "$MB" ]; then
     base_lines=0
     git cat-file -e "$MB:$p" 2>/dev/null && base_lines=$(git show "$MB:$p" | wc -l | tr -d ' ')
     growth=$((lines - base_lines))
   fi
-  printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$p" "$lines" "$commits" "$excluded" "$base_lines" "$growth" >> "$T/rows"
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$p" "$lines" "$commits" "$excluded" "$base_lines" "$growth" "$generated" >> "$T/rows"
 done
 
 FILES=$(jq -R -s -c --argjson fl "$FILE_LINES" '
   [split("\n")[] | select(length > 0) | split("\t") |
    { path: .[0], lines: (.[1] | tonumber), commits_90d: (.[2] | tonumber) } as $r |
-   $r + { hotspot: ($r.lines * $r.commits_90d), over: ($r.lines > $fl), excluded: (.[3] == "true"),
+   $r + { hotspot: ($r.lines * $r.commits_90d), over: ($r.lines > $fl), generated: (.[6] == "true"), excluded: (.[3] == "true"),
           base_lines: (.[4] | fromjson), growth: (.[5] | fromjson) }]' < "$T/rows")
 head_json "$FILES"