fix(ci): build-ns7zip workflow_dispatch only (decouple from CI-system tags)

build-ns7zip builds an EXTERNAL repo (nsis-plugin-ns7zip). The
`push: tags v*` trigger (inherited from when this workflow lived in
the plugin repo) made every CI-system tag — including the Phase A
marker v2.0.0-phaseA — auto-build and publish an ns7zip release on
the CI-system repo. Remove the tag trigger; manual dispatch only.
The release job's tag-gate `if` now never fires (skipped) — release
flow already validated with a throwaway tag.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitea/actions/local-ci-build/action.yml

@@ -0,0 +1,398 @@
+# .gitea/actions/local-ci-build/action.yml
+#
+# Reusable composite action — Local CI/CD System
+#
+# Wraps Invoke-CIJob.ps1 (ephemeral VMware VM pipeline) into a single callable
+# step, usable from any Gitea repository without duplicating the orchestration
+# logic.
+#
+# Stored in: Simone/local-ci-cd-system / .gitea/actions/local-ci-build/action.yml
+#
+# Usage from a calling repo's workflow:
+#
+#   jobs:
+#     build:
+#       runs-on: windows-build          # or linux-build
+#       steps:
+#         - uses: actions/checkout@v4
+#         - uses: Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+#           with:
+#             build-command: 'python build_plugin.py --final --dist-dir dist'
+#             artifact-source: 'dist'
+#             submodules: 'true'
+#
+# Runner label determines the guest OS template:
+#   windows-build  ->  WinBuild2025 (WinRM/HTTPS transport)
+#   linux-build    ->  LinuxBuild2404 (SSH transport)
+
+name: Local CI Build
+description: >
+  Builds a project using an ephemeral VMware VM managed by Invoke-CIJob.ps1.
+  Handles the full VM lifecycle: clone template -> start VM -> run build ->
+  collect artifacts -> destroy VM.
+  Compatible with windows-build (WinRM) and linux-build (SSH) runners.
+
+inputs:
+  build-command:
+    description: >
+      Shell command to execute inside the build VM.
+      Example: 'python build_plugin.py --final --dist-dir dist'
+    required: true
+
+  artifact-source:
+    description: >
+      Path inside VM where build outputs are located, relative to the CI work
+      directory. Collected to F:\CI\Artifacts\{JobId}\ on the host.
+    required: false
+    default: 'dist'
+
+  submodules:
+    description: >
+      Recurse submodules when cloning. Default "true". Set to "false"
+      to skip submodule init/update.
+    required: false
+    default: 'true'
+
+  guest-os:
+    description: >
+      Guest OS type: Windows, Linux, or Auto.
+      Auto (default) detects the OS from the VMX guestOS field after cloning.
+    required: false
+    default: 'Auto'
+
+  use-git-clone:
+    description: >
+      Transport for the repo source. Default "true": clone inside the
+      build VM (requires Git in the template — see
+      Install-CIToolchain-WinBuild2025.ps1 Step 12 /
+      Install-CIToolchain-Linux2404.sh). Set to "false" for the
+      host-side variant: the host clones the repo and transfers a zip
+      to the guest (useful when the guest cannot reach Gitea).
+    required: false
+    default: 'true'
+
+  configuration:
+    description: >
+      Build configuration string forwarded to the build command (Release/Debug).
+    required: false
+    default: 'Release'
+
+  template-path:
+    description: >
+      Override the VMX template path. Leave empty (default) to use the value
+      from the GITEA_CI_TEMPLATE_PATH runner environment variable set in
+      runner/config.yaml.
+    required: false
+    default: ''
+
+  snapshot-name:
+    description: >
+      Override the snapshot name to clone from. Leave empty (default) to use
+      GITEA_CI_SNAPSHOT_NAME runner env var, or "BaseClean" if that is also
+      unset.
+    required: false
+    default: ''
+
+  artifact-name:
+    description: >
+      Name for the artifact uploaded to Gitea. Leave empty to use the default:
+      build-{run_id}-{sha}.
+    required: false
+    default: ''
+
+  artifact-retention-days:
+    description: >
+      Deprecated / no-op. Artifacts are no longer uploaded to the Gitea
+      Actions store (that needs the github.com-hosted upload-artifact
+      action). They stay on the host under F:\CI\Artifacts and are aged
+      out by scripts/Invoke-RetentionPolicy.ps1. Kept for caller
+      back-compat.
+    required: false
+    default: '14'
+
+  job-id-suffix:
+    description: >
+      Optional suffix appended to the job ID: run_id-run_attempt-SUFFIX.
+      Use to disambiguate parallel matrix legs so each leg writes to its own
+      artifact directory (e.g. set to matrix.target: windows, linux).
+      Leave empty (default) for single-job workflows.
+    required: false
+    default: ''
+
+  repo-url:
+    description: >
+      Override the repository URL passed to Invoke-CIJob.ps1.
+      Defaults to github.server_url/repository.git (HTTPS).
+      Set to an SSH URL (e.g. ssh://gitea-ci/Org/repo.git) when the host
+      runner uses an SSH alias for Gitea.
+    required: false
+    default: ''
+
+  repo-branch:
+    description: >
+      Branch to clone in the target repo. Leave empty (default) to use
+      the workflow's own ref (github.ref_name) — correct only when
+      repo-url is the same repo as the workflow. Set explicitly (e.g.
+      "main") for cross-repo builds where repo-url points elsewhere.
+    required: false
+    default: ''
+
+  repo-commit:
+    description: >
+      Commit SHA to check out in the target repo. Leave empty (default)
+      to use github.sha only when repo-url is NOT overridden; for a
+      cross-repo build (repo-url set) an empty value means "branch tip,
+      no pin". Set explicitly to pin a specific commit of the target.
+    required: false
+    default: ''
+
+  extra-guest-env-json:
+    description: >
+      JSON object of extra environment variables to inject into the build VM
+      guest before the build command runs. Use for signing keys and secrets.
+      Example: '{"SIGN_PASS":"${{ secrets.SIGN_PASS }}","GPG_KEY_ID":"0xABCD1234"}'
+      Values are passed via ExtraGuestEnv hashtable in Invoke-CIJob.ps1 and
+      are never echoed to the log.
+    required: false
+    default: '{}'
+
+  guest-cpu:
+    description: >
+      Override the build VM vCPU count (numvcpus in the clone VMX).
+      "0" (default) keeps the template value.
+    required: false
+    default: '0'
+
+  guest-memory-mb:
+    description: >
+      Override the build VM RAM in MB (memsize in the clone VMX).
+      "0" (default) keeps the template value. Raise for memory-heavy
+      parallel builds (e.g. the Linux MinGW cross-compile thrashes at
+      the 4 GB template default).
+    required: false
+    default: '0'
+
+  use-shared-cache:
+    description: >
+      Set to "true" to redirect NuGet and pip caches to VMware shared folders
+      on the host (F:\CI\Cache\NuGet and F:\CI\Cache\pip).
+      Requires Set-TemplateSharedFolders.ps1 to have been run on the template
+      and VMware Tools HGFS driver present in the guest.
+    required: false
+    default: 'false'
+
+  skip-artifact:
+    description: >
+      Set to "true" to skip artifact packaging and collection entirely.
+      Use for jobs that intentionally produce no output (lint, static analysis,
+      test-only). When absent (default), the build MUST produce artifact-source
+      or the job fails.
+    required: false
+    default: 'false'
+
+outputs:
+  artifact-path:
+    description: >
+      Host-side directory where Invoke-CIJob.ps1 placed collected artifacts.
+      Format: F:\CI\Artifacts\{run_id}-{run_attempt}
+    value: ${{ steps.invoke-ci.outputs.artifact-path }}
+
+  artifact-name:
+    description: 'Name used when uploading the artifact to Gitea.'
+    value: ${{ steps.invoke-ci.outputs.artifact-name }}
+
+runs:
+  using: composite
+  steps:
+
+    # ── Invoke the CI orchestrator ─────────────────────────────────────────────
+    - name: Invoke CI Job
+      id: invoke-ci
+      shell: powershell
+      # Inputs are forwarded via environment variables to avoid shell injection
+      # from user-supplied build-command or path strings.
+      env:
+        INPUT_BUILD_COMMAND:         ${{ inputs.build-command }}
+        INPUT_ARTIFACT_SOURCE:       ${{ inputs.artifact-source }}
+        INPUT_SUBMODULES:            ${{ inputs.submodules }}
+        INPUT_GUEST_OS:              ${{ inputs.guest-os }}
+        INPUT_USE_GIT_CLONE:         ${{ inputs.use-git-clone }}
+        INPUT_CONFIGURATION:         ${{ inputs.configuration }}
+        INPUT_TEMPLATE_PATH:         ${{ inputs.template-path }}
+        INPUT_SNAPSHOT_NAME:         ${{ inputs.snapshot-name }}
+        INPUT_ARTIFACT_NAME:         ${{ inputs.artifact-name }}
+        INPUT_JOB_ID_SUFFIX:         ${{ inputs.job-id-suffix }}
+        INPUT_REPO_URL:              ${{ inputs.repo-url }}
+        INPUT_REPO_BRANCH:           ${{ inputs.repo-branch }}
+        INPUT_REPO_COMMIT:           ${{ inputs.repo-commit }}
+        INPUT_EXTRA_GUEST_ENV_JSON:  ${{ inputs.extra-guest-env-json }}
+        INPUT_USE_SHARED_CACHE:      ${{ inputs.use-shared-cache }}
+        INPUT_SKIP_ARTIFACT:         ${{ inputs.skip-artifact }}
+        INPUT_GUEST_CPU:             ${{ inputs.guest-cpu }}
+        INPUT_GUEST_MEMORY_MB:       ${{ inputs.guest-memory-mb }}
+      run: |
+        #Requires -Version 5.1
+        Set-StrictMode -Version Latest
+        $ErrorActionPreference = 'Stop'
+
+        # Resolve Python interpreter from venv (Phase A4 — Python orchestrator).
+        # Override with CI_VENV_PYTHON env var; default matches Setup-Host.ps1 layout.
+        $venvPython = $env:CI_VENV_PYTHON
+        if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+        if (-not (Test-Path -LiteralPath $venvPython)) {
+            throw "Python interpreter not found at '$venvPython'. Set CI_VENV_PYTHON or run Setup-Host.ps1."
+        }
+
+        # Build job ID — append suffix when provided (matrix disambiguation)
+        $jobId = '${{ github.run_id }}-${{ github.run_attempt }}'
+        if ($env:INPUT_JOB_ID_SUFFIX) { $jobId = "$jobId-$($env:INPUT_JOB_ID_SUFFIX)" }
+        $artifactPath = "F:\CI\Artifacts\$jobId"
+
+        # Resolve artifact name: caller-supplied or default to build-{run_id}-{sha}
+        if ($env:INPUT_ARTIFACT_NAME) {
+            $artifactName = $env:INPUT_ARTIFACT_NAME
+        }
+        else {
+            $artifactName = "build-${{ github.run_id }}-${{ github.sha }}"
+        }
+
+        # Resolve repository URL: explicit override or construct from GitHub context
+        if ($env:INPUT_REPO_URL) {
+            $repoUrl = $env:INPUT_REPO_URL
+        }
+        else {
+            $repoUrl = '${{ github.server_url }}/${{ github.repository }}.git'
+        }
+
+        # Resolve target branch/commit. github.ref_name/github.sha refer
+        # to the workflow's own repo — only valid when repo-url is NOT
+        # overridden. For a cross-repo build the caller must give
+        # repo-branch (and optionally repo-commit); an unset commit means
+        # "branch tip, no pin".
+        if ($env:INPUT_REPO_BRANCH) {
+            $repoBranch = $env:INPUT_REPO_BRANCH
+        }
+        else {
+            $repoBranch = '${{ github.ref_name }}'
+        }
+        if ($env:INPUT_REPO_COMMIT) {
+            $repoCommit = $env:INPUT_REPO_COMMIT
+        }
+        elseif ($env:INPUT_REPO_URL) {
+            $repoCommit = ''   # cross-repo: don't pin the workflow's sha
+        }
+        else {
+            $repoCommit = '${{ github.sha }}'
+        }
+
+        # Resolve guest OS: honor explicit input; for Auto, infer from RUNNER_LABELS
+        $resolvedGuestOS = $env:INPUT_GUEST_OS
+        if ($resolvedGuestOS -eq 'Auto') {
+            if ($env:RUNNER_LABELS -match 'linux') {
+                $resolvedGuestOS = 'Linux'
+            } else {
+                $resolvedGuestOS = 'Windows'
+            }
+        }
+
+        # Select template path: explicit input overrides OS-based runner env var
+        $resolvedTemplatePath = $env:INPUT_TEMPLATE_PATH
+        if (-not $resolvedTemplatePath) {
+            if ($resolvedGuestOS -eq 'Linux') {
+                $resolvedTemplatePath = $env:GITEA_CI_LINUX_TEMPLATE_PATH
+            } else {
+                $resolvedTemplatePath = $env:GITEA_CI_TEMPLATE_PATH
+            }
+        }
+
+        # Select snapshot name: explicit input > OS-based default
+        # GITEA_CI_SNAPSHOT_NAME applies to Windows (template-refresh override)
+        $resolvedSnapshotName = $env:INPUT_SNAPSHOT_NAME
+        if (-not $resolvedSnapshotName) {
+            if ($resolvedGuestOS -eq 'Linux') {
+                $resolvedSnapshotName = 'BaseClean-Linux'
+            } else {
+                $resolvedSnapshotName = if ($env:GITEA_CI_SNAPSHOT_NAME) { $env:GITEA_CI_SNAPSHOT_NAME } else { 'BaseClean' }
+            }
+        }
+
+        # Build argument list for the Python CLI. Long-form kebab-case flags only.
+        # NOTE: never put an empty string in the splatted array — PowerShell
+        # 5.1 drops zero-length args when calling a native exe, which would
+        # shift the flag/value pairing. Add optional args conditionally.
+        $pyArgs = @(
+            '-m', 'ci_orchestrator', 'job',
+            '--job-id',                $jobId,
+            '--repo-url',              $repoUrl,
+            '--branch',                $repoBranch,
+            '--build-command',         $env:INPUT_BUILD_COMMAND,
+            '--guest-artifact-source', $env:INPUT_ARTIFACT_SOURCE,
+            '--guest-os',              $resolvedGuestOS,
+            '--configuration',         $env:INPUT_CONFIGURATION,
+            '--template-path',         $resolvedTemplatePath,
+            '--snapshot-name',         $resolvedSnapshotName
+        )
+        if ($repoCommit) { $pyArgs += @('--commit', $repoCommit) }
+
+        # Submodules and transport default to ON; pass the explicit
+        # negative flag when the caller opted out so the Python default
+        # (also ON) is overridden deterministically.
+        if ($env:INPUT_SUBMODULES -eq 'false') { $pyArgs += '--no-submodules' }
+        else { $pyArgs += '--submodules' }
+        if ($env:INPUT_USE_GIT_CLONE -eq 'false') { $pyArgs += '--host-clone' }
+        else { $pyArgs += '--use-git-clone' }
+        if ($env:INPUT_USE_SHARED_CACHE -eq 'true') { $pyArgs += '--use-shared-cache' }
+        if ($env:INPUT_SKIP_ARTIFACT    -eq 'true') { $pyArgs += '--skip-artifact' }
+        # VMX overrides: forward only when > 0 (0 = keep template value).
+        if ([int]($env:INPUT_GUEST_CPU)       -gt 0) { $pyArgs += @('--guest-cpu', $env:INPUT_GUEST_CPU) }
+        if ([int]($env:INPUT_GUEST_MEMORY_MB) -gt 0) { $pyArgs += @('--guest-memory-mb', $env:INPUT_GUEST_MEMORY_MB) }
+        if ($env:INPUT_EXTRA_GUEST_ENV_JSON -and $env:INPUT_EXTRA_GUEST_ENV_JSON -ne '{}') {
+            $pyArgs += @('--extra-env-json', $env:INPUT_EXTRA_GUEST_ENV_JSON)
+        }
+
+        & $venvPython @pyArgs
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+        # Emit outputs consumed by subsequent steps.
+        # PowerShell 5.1 `Out-File -Encoding utf8` writes a BOM; the act_runner
+        # GITHUB_OUTPUT parser then reads the key as "artifact-path" and
+        # the output resolves empty. An empty artifact-path made the upload
+        # step glob the entire F: drive. Write UTF-8 without BOM.
+        if (-not $artifactPath) { throw "artifactPath is empty; refusing to emit." }
+        $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+        [System.IO.File]::AppendAllText(
+            $env:GITHUB_OUTPUT, "artifact-path=$artifactPath`n", $utf8NoBom)
+        [System.IO.File]::AppendAllText(
+            $env:GITHUB_OUTPUT, "artifact-name=$artifactName`n", $utf8NoBom)
+
+    # ── Report artifact location ──────────────────────────────────────────────
+    # No actions/upload-artifact: that action's code is fetched from
+    # github.com (and v4 is GHES-incompatible, v3 deprecated). The runner
+    # host is single and its filesystem is shared across jobs, so the
+    # orchestrator's host-side collect dir IS the artifact handoff.
+    # Downstream jobs read F:\CI\Artifacts\{run_id}-{run_attempt}[-suffix]
+    # directly (see build-nsInnoUnp.yml release job).
+    - name: Report artifact location
+      if: success() && inputs.skip-artifact != 'true'
+      shell: powershell
+      run: |
+        $p = '${{ steps.invoke-ci.outputs.artifact-path }}'
+        if (-not (Test-Path -LiteralPath $p) -or
+            -not (Get-ChildItem -Force -LiteralPath $p)) {
+            throw "no artifacts at $p"
+        }
+        Write-Host "Artifacts on host: $p"
+        Get-ChildItem -Recurse -File -LiteralPath $p |
+            ForEach-Object { Write-Host "  $($_.FullName)" }
+
+    - name: Report diagnostic log location on failure
+      if: failure()
+      shell: powershell
+      run: |
+        $p = '${{ steps.invoke-ci.outputs.artifact-path }}'
+        if ($p -and (Test-Path -LiteralPath $p)) {
+            Write-Host "Diagnostic logs (if any) on host: $p"
+            Get-ChildItem -Recurse -File -Filter '*.log' -LiteralPath $p `
+                -ErrorAction SilentlyContinue |
+                ForEach-Object { Write-Host "  $($_.FullName)" }
+        }

.gitea/workflows/build-ns7zip.yml

@@ -0,0 +1,127 @@
+# Build ns7zip (Local CI) — pipeline per nsis-plugin-ns7zip
+#
+# Cross-platform matrix build: runs in parallel on both windows-build (WinRM)
+# and linux-build (SSH) runners using the reusable composite action.
+# Uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+#
+# Trigger: SOLO run manuale (workflow_dispatch).
+# Builda un repo ESTERNO (nsis-plugin-ns7zip): i tag del repo
+# CI-system non c'entrano con le release ns7zip. Il vecchio trigger
+# `push: tags v*` (ereditato da quando il workflow viveva nel repo
+# plugin) faceva auto-buildare+pubblicare ns7zip su ogni tag del
+# CI-system (es. il marker Fase A v2.0.0-phaseA) — rimosso.
+
+name: Build ns7zip (Local CI)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        target: [windows, linux]
+      fail-fast: false
+
+    # Runner label must match config.yaml labels: windows-build or linux-build
+    runs-on: ${{ matrix.target }}-build
+
+    steps:
+      - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+        with:
+          # build_plugin.py auto-detects host/toolset and builds all
+          # configs by default; --dist forwards to the per-version script
+          # which copies the DLLs to <repo>/dist/<config> instead of the
+          # committed plugins/ dir.
+          build-command:   'python build_plugin.py --dist'
+          artifact-source: 'dist'
+          submodules:      'true'
+          guest-os:        ${{ matrix.target == 'linux' && 'Linux' || 'Windows' }}
+          # In-guest clone (default). repo-url must be reachable FROM the
+          # guest (VMnet8 NAT -> gitea.emulab.it), not the host-only SSH
+          # alias. ci_orchestrator injects the GiteaPAT credential into
+          # the HTTPS URL, so GiteaPAT must exist in the LocalSystem
+          # keyring (Set-CIGuestCredential.ps1 -Target GiteaPAT) — or
+          # nsis-plugin-ns7zip must be public.
+          use-git-clone:   'true'
+          repo-url:        'https://gitea.emulab.it/Simone/nsis-plugin-ns7zip.git'
+          # Cross-repo build: github.ref_name is this repo's branch, not
+          # nsis-plugin-ns7zip's. Pin the target repo's branch.
+          repo-branch:     'main'
+          # 8 vCPU / 8 GB. WSL on the host builds the 3 configs in
+          # parallel in ~103s (= one config); the 4-vCPU CI VM thrashes
+          # (3x make -j on 4 cores) and takes ~3x. Not structural — just
+          # vCPU starvation. Host is 10c/20t; this matrix = 2 VMs.
+          guest-cpu:       '8'
+          guest-memory-mb: '8192'
+          # Suffix disambiguates artifact dirs: F:\CI\Artifacts\{run_id}-{attempt}-windows
+          job-id-suffix:   '${{ matrix.target }}'
+          artifact-name:   'nsis-plugin-ns7zip-${{ matrix.target }}-${{ github.ref_name }}'
+
+  # ── Publish Gitea release with build artifacts ────────────────────────────
+  # Runs only on tag pushes, after both matrix legs succeed.
+  # Requires a GITEA_TOKEN secret with repo write permissions.
+  release:
+    needs: build
+    # Tag pushes only. Explicit ${{ }} + event gate: a bare
+    # `if: github.ref_type == 'tag'` can leave the job stuck "blocked"
+    # (instead of skipped) on Gitea for workflow_dispatch runs.
+    if: ${{ github.event_name == 'push' && github.ref_type == 'tag' }}
+    runs-on: windows-build
+
+    steps:
+      # No actions/download-artifact (its code is fetched from github.com).
+      # The runner host is single and shared; the build matrix legs left
+      # their outputs at F:\CI\Artifacts\{run_id}-{run_attempt}-{target}
+      # (job-id-suffix = matrix.target). Read them directly from disk.
+      - name: Create Gitea release and upload assets
+        shell: powershell
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_URL:   ${{ github.server_url }}
+          REPO:        ${{ github.repository }}
+          TAG:         ${{ github.ref_name }}
+          RUN_ID:      ${{ github.run_id }}
+          RUN_ATTEMPT: ${{ github.run_attempt }}
+        run: |
+          #Requires -Version 5.1
+          Set-StrictMode -Version Latest
+          $ErrorActionPreference = 'Stop'
+
+          $authHeader = @{ Authorization = "token $env:GITEA_TOKEN" }
+          $apiBase    = "$env:GITEA_URL/api/v1/repos/$env:REPO"
+
+          # Create the release (non-draft, non-prerelease)
+          $releaseBody = @{
+              tag_name   = $env:TAG
+              name       = $env:TAG
+              draft      = $false
+              prerelease = $false
+          } | ConvertTo-Json
+          $jsonHeaders = $authHeader + @{ 'Content-Type' = 'application/json' }
+          $release = Invoke-RestMethod -Method Post -Uri "$apiBase/releases" `
+                         -Headers $jsonHeaders -Body $releaseBody
+          $releaseId = $release.id
+          Write-Host "Release created: id=$releaseId name=$($release.name)"
+
+          # Compress each host-side artifact directory and upload as a
+          # release asset. The build legs collected to
+          # F:\CI\Artifacts\{run_id}-{run_attempt}-{target}.
+          foreach ($target in @('windows', 'linux')) {
+              $srcDir  = "F:\CI\Artifacts\$env:RUN_ID-$env:RUN_ATTEMPT-$target"
+              if (-not (Test-Path -LiteralPath $srcDir) -or
+                  -not (Get-ChildItem -Force -LiteralPath $srcDir)) {
+                  throw "artifact dir missing or empty: $srcDir"
+              }
+              $zipName = "nsis-plugin-ns7zip-$target-$env:TAG.zip"
+              Compress-Archive -Path "$srcDir\*" -DestinationPath $zipName -Force
+
+              $uploadUrl     = "$apiBase/releases/$releaseId/assets?name=$zipName"
+              $uploadHeaders = $authHeader + @{ 'Content-Type' = 'application/zip' }
+              $zipBytes      = [System.IO.File]::ReadAllBytes(
+                                   (Resolve-Path $zipName).ProviderPath)
+              Invoke-RestMethod -Method Post -Uri $uploadUrl `
+                  -Headers $uploadHeaders -Body $zipBytes | Out-Null
+              Write-Host "Uploaded asset: $zipName"
+          }
+          Write-Host "Release $env:TAG published with $($release.html_url)"

.gitea/workflows/lint.yml

@@ -0,0 +1,139 @@
+# PSScriptAnalyzer + Python lint — runs on every push/PR that touches code files.
+# Requires PSScriptAnalyzer installed on the runner host:
+#   Install-Module PSScriptAnalyzer -Scope AllUsers -Force
+#
+# Failures block the PR. Fix warnings with:
+#   Invoke-ScriptAnalyzer -Path scripts\ -Recurse -Fix
+
+
+name: Lint
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - '**.ps1'
+      - '**.psm1'
+      - '**.py'
+      - 'pyproject.toml'
+      - '.gitea/workflows/lint.yml'
+  pull_request:
+    paths:
+      - '**.ps1'
+      - '**.psm1'
+      - '**.py'
+      - 'pyproject.toml'
+      - '.gitea/workflows/lint.yml'
+
+jobs:
+  pssa:
+    runs-on: windows-build
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run PSScriptAnalyzer
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+
+          if (-not (Get-Module -ListAvailable PSScriptAnalyzer)) {
+            Write-Host "Installing PSScriptAnalyzer..."
+            Install-Module PSScriptAnalyzer -Scope CurrentUser -Force -AllowClobber
+          }
+
+          $settings = Join-Path $PWD 'PSScriptAnalyzerSettings.psd1'
+          $paths = @('scripts', 'template', 'Setup-Host.ps1')
+          $results = $paths | ForEach-Object {
+            if (Test-Path $_) {
+              Invoke-ScriptAnalyzer -Path $_ -Recurse -Settings $settings -Severity Error,Warning
+            }
+          }
+
+          if ($results) {
+            $results | Format-Table -AutoSize
+            Write-Error "PSScriptAnalyzer found $($results.Count) issue(s). Fix before merging."
+            exit 1
+          }
+          else {
+            Write-Host "PSScriptAnalyzer: no issues found."
+          }
+
+  python:
+    runs-on: windows-build
+    timeout-minutes: 20
+
+    env:
+      PYTHONIOENCODING: utf-8
+      # Job-local, ephemeral venv. MUST NOT be the production venv
+      # (F:\CI\python\venv): an editable install here would repoint the
+      # shared orchestrator package at this run's transient checkout and
+      # break every later smoke/build job with "No module named
+      # ci_orchestrator". github.workspace is discarded after the job.
+      VENV_DIR: ${{ github.workspace }}\.venv-lint
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Setup venv + install package
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+
+          # Production venv lives at $env:VENV_DIR (F:\CI\python\venv per AGENTS.md).
+          # The system Python used to bootstrap it is configured once in
+          # runner/config.yaml as CI_PYTHON_LAUNCHER (single source of truth).
+          if (-not $env:CI_PYTHON_LAUNCHER) {
+            throw "CI_PYTHON_LAUNCHER not set. Configure it in runner/config.yaml (runner.envs) and restart act_runner."
+          }
+          if (-not (Test-Path $env:CI_PYTHON_LAUNCHER)) {
+            throw "CI_PYTHON_LAUNCHER points to '$env:CI_PYTHON_LAUNCHER' which does not exist."
+          }
+
+          $venvPy = Join-Path $env:VENV_DIR 'Scripts\python.exe'
+
+          # Always build a fresh, job-local venv. Never reuse or repair a
+          # shared one — lint must be fully isolated from the production
+          # orchestrator venv.
+          if (Test-Path $env:VENV_DIR) {
+            Remove-Item $env:VENV_DIR -Recurse -Force
+          }
+          & $env:CI_PYTHON_LAUNCHER -m venv $env:VENV_DIR
+          if ($LASTEXITCODE -ne 0) { throw "venv creation failed" }
+
+          Write-Host "Using venv python: $venvPy"
+          & $venvPy --version
+          if ($LASTEXITCODE -ne 0) { throw "python --version failed" }
+
+          & $venvPy -m pip install --upgrade pip
+          if ($LASTEXITCODE -ne 0) { throw "pip upgrade failed" }
+          & $venvPy -m pip install -e ".[dev]"
+          if ($LASTEXITCODE -ne 0) { throw "pip install failed" }
+
+      - name: ruff
+        shell: powershell
+        run: |
+          $venvPy = Join-Path $env:VENV_DIR 'Scripts\python.exe'
+          & $venvPy -m ruff check src tests/python
+          if ($LASTEXITCODE -ne 0) { throw "ruff failed" }
+
+      - name: mypy --strict
+        shell: powershell
+        run: |
+          $venvPy = Join-Path $env:VENV_DIR 'Scripts\python.exe'
+          & $venvPy -m mypy --strict src
+          if ($LASTEXITCODE -ne 0) { throw "mypy failed" }
+
+      - name: pytest (coverage >= 90%)
+        shell: powershell
+        run: |
+          $venvPy = Join-Path $env:VENV_DIR 'Scripts\python.exe'
+          & $venvPy -m pytest tests/python --cov=ci_orchestrator --cov-fail-under=90
+          if ($LASTEXITCODE -ne 0) { throw "pytest failed" }

.gitea/workflows/self-test.yml

@@ -0,0 +1,73 @@
+# CI Self-Test (smoke) — Local CI/CD System
+#
+# On-demand smoke test that validates the full pipeline end-to-end:
+# VM clone -> start -> IP detect -> trivial build -> artifact collect -> destroy
+#
+# Trigger: workflow_dispatch only (never runs on push/tag).
+# Jobs are independent — a failure in one does not cancel the others.
+# Covers both source transports: in-guest git clone (default) and the
+# host-side clone + zip transfer variant (use-git-clone: 'false').
+#
+# Prerequisites (must be in place before running):
+#   - Runner labels: windows-build:host and linux-build:host active
+#   - Templates at GITEA_CI_TEMPLATE_PATH / GITEA_CI_LINUX_TEMPLATE_PATH
+#   - Snapshots BaseClean (Windows) and BaseClean-Linux (Linux) exist
+#   - ci-report-ip.service enabled in LinuxBuild2404 template
+
+name: CI Self-Test (smoke)
+
+on:
+  workflow_dispatch:
+
+jobs:
+
+  smoke-windows:
+    runs-on: windows-build
+    steps:
+      - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+        with:
+          # Trivial no-op build: write a marker file to the CI output directory.
+          # The Windows build VM maps C:\CI\output as the artifact source.
+          build-command:   'New-Item -ItemType Directory -Path C:\CI\output -Force | Out-Null; Set-Content C:\CI\output\smoke.txt "smoke-ok"'
+          artifact-source: 'C:\CI\output'
+          guest-os:        'Windows'
+          job-id-suffix:   'smoke-win'
+          artifact-name:   'smoke-windows-${{ github.run_id }}'
+
+  smoke-linux:
+    runs-on: linux-build
+    steps:
+      - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+        with:
+          # Trivial no-op build: write a marker file to the CI output directory.
+          # The Linux build VM uses /opt/ci/output as the artifact source.
+          build-command:   'mkdir -p /opt/ci/output && echo smoke-ok > /opt/ci/output/smoke.txt'
+          artifact-source: '/opt/ci/output'
+          guest-os:        'Linux'
+          job-id-suffix:   'smoke-linux'
+          artifact-name:   'smoke-linux-${{ github.run_id }}'
+
+  # ── Host-side clone + zip transfer variant (use-git-clone: 'false') ───────
+  smoke-windows-hostclone:
+    runs-on: windows-build
+    steps:
+      - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+        with:
+          build-command:   'New-Item -ItemType Directory -Path C:\CI\output -Force | Out-Null; Set-Content C:\CI\output\smoke.txt "smoke-ok"'
+          artifact-source: 'C:\CI\output'
+          guest-os:        'Windows'
+          use-git-clone:   'false'
+          job-id-suffix:   'smoke-win-hostclone'
+          artifact-name:   'smoke-windows-hostclone-${{ github.run_id }}'
+
+  smoke-linux-hostclone:
+    runs-on: linux-build
+    steps:
+      - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+        with:
+          build-command:   'mkdir -p /opt/ci/output && echo smoke-ok > /opt/ci/output/smoke.txt'
+          artifact-source: '/opt/ci/output'
+          guest-os:        'Linux'
+          use-git-clone:   'false'
+          job-id-suffix:   'smoke-linux-hostclone'
+          artifact-name:   'smoke-linux-hostclone-${{ github.run_id }}'

.github/agents/ci-ps51-author.agent.md

@@ -0,0 +1,102 @@
+---
+name: "CI PS51 Author"
+description: "Use when: writing, editing, reviewing, or linting PowerShell 5.1 scripts for the Local CI/CD System; authoring Gitea Actions workflow YAML; checking PS 5.1 compatibility; vmrun, WinRM, SSH transport scripts; New-BuildVM, Remove-BuildVM, Invoke-CIJob, _Common.psm1, _Transport.psm1, CI toolchain scripts, Pester tests; PSScriptAnalyzer compliance; CI/CD infrastructure scripting."
+tools: [read, search, edit, todo]
+---
+
+You are a PowerShell 5.1 CI/CD infrastructure specialist for this Local CI/CD System.
+Your job is to write, edit, and review scripts that orchestrate VMware build VMs on a Windows 11 host.
+
+## Environment (always apply)
+
+- Host OS: Windows 11, PowerShell **5.1** (Windows PowerShell — NOT Core/7)
+- VMware Workstation Pro; `vmrun.exe` at `C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe`
+- Transport: **WinRM HTTPS port 5986** for Windows guests; **SSH port 22** via `ssh.exe`/`scp.exe` for Linux guests
+- Directory layout (fixed):
+  - `F:\CI\act_runner\` — act_runner binary
+  - `F:\CI\Templates\WinBuild2025\` — Windows Server 2025 template VMX + `BaseClean` snapshot
+  - `F:\CI\Templates\WinBuild2022\` — Windows Server 2022 template VMX + `BaseClean` snapshot
+  - `F:\CI\Templates\LinuxBuild2404\` — Ubuntu 24.04 template VMX + `BaseClean-Linux` snapshot
+  - `F:\CI\BuildVMs\` — ephemeral clones (created and destroyed per job)
+  - `F:\CI\Artifacts\` — collected artifacts (by job-id)
+  - `F:\CI\ISO\` — ISO/VMDK bootstrap cache
+  - `F:\CI\keys\ci_linux` — SSH private key for Linux guests (no passphrase)
+- Gitea: `http://10.10.20.11:3100` / `https://gitea.emulab.it`
+- act_runner labels: `windows-build:host`, `linux-build:host`
+
+## PowerShell 5.1 Rules (hard constraints)
+
+Every script MUST:
+
+1. Begin with:
+   ```powershell
+   #Requires -Version 5.1
+   Set-StrictMode -Version Latest
+   $ErrorActionPreference = 'Stop'
+   ```
+
+2. NEVER use PS 7+ syntax. Forbidden constructs and their replacements:
+   | Forbidden (PS 7+)         | Use instead (PS 5.1)                      |
+   |---------------------------|-------------------------------------------|
+   | `$x ??= 'default'`        | `if ($null -eq $x) { $x = 'default' }`    |
+   | `$a ?? $b`                | `if ($null -ne $a) { $a } else { $b }`    |
+   | `cmd1 && cmd2`            | `cmd1; if ($LASTEXITCODE -eq 0) { cmd2 }` |
+   | `cmd1 \|\| cmd2`          | `cmd1; if ($LASTEXITCODE -ne 0) { cmd2 }` |
+   | `$a ? $b : $c` (ternary)  | `if ($a) { $b } else { $c }`              |
+   | `ForEach-Object -Parallel`| classic `foreach` or `Start-Job`          |
+
+3. Check `$LASTEXITCODE` after every external call (`vmrun`, `ssh.exe`, `scp.exe`, `git`) and `throw` if non-zero.
+
+4. Never hardcode critical paths — accept them as parameters with documented defaults.
+
+5. All state-changing functions must support `-WhatIf` / `ShouldProcess`.
+
+6. Credentials only as `[PSCredential]`, never plain-text strings. No `$global:` variables.
+
+7. Write-Host is preferred over Write-Output for status messages (act_runner captures stdout; Write-Output interferes with return values).
+
+8. Never use `Invoke-Expression`.
+
+## Transport Layer Rules
+
+- **Windows guest** → use `New-CISessionOption` from `_Common.psm1`, then `Invoke-Command -Session`, `Copy-Item -ToSession/-FromSession`
+- **Linux guest** → use `Invoke-SshCommand`, `Copy-SshItem`, `Test-SshReady` from `_Transport.psm1`
+- Never cross the boundary: no WinRM toward Linux, no SSH toward Windows
+- Keep `if ($GuestOS -eq 'Linux')` branches cleanly separated; do not mix in the same block
+
+## vmrun Conventions
+
+- Always invoke `vmrun` via `Invoke-Vmrun` from `_Common.psm1` (handles `$LASTEXITCODE` and output uniformly)
+- For "is VM running" checks, use `vmrun list` and search for the VMX path — do NOT use `vmrun getGuestIPAddress` (requires Tools; slow)
+- Clone only from fully powered-off snapshots (no `.vmem` files in template dir)
+
+## PSScriptAnalyzer Compliance
+
+Configured via `PSScriptAnalyzerSettings.psd1` at repo root. Key rules:
+- 4-space indentation, no tabs
+- `Write-Host` allowed
+- `Invoke-Expression` forbidden
+- Functions with side-effects need `ShouldProcess`
+
+## Gitea Actions Workflow YAML
+
+- Runner labels: `runs-on: [self-hosted, windows-build]` or `[self-hosted, linux-build]`
+- Env vars available in every job: `GITEA_CI_TEMPLATE_PATH`, `GITEA_CI_LINUX_TEMPLATE_PATH`, `GITEA_CI_CLONE_BASE_DIR`, `GITEA_CI_ARTIFACT_DIR`, `GITEA_CI_GUEST_CRED_TARGET`, `GITEA_CI_SSH_KEY_PATH`
+- Reference `gitea/workflows/` and `gitea/actions/` for existing patterns before authoring new ones
+
+## Approach
+
+1. Before writing any script, read the relevant existing scripts to match style (module imports, param blocks, error handling, comment-based help).
+2. When editing, search for all usages of the function/parameter being changed to avoid breaking callers.
+3. After writing, mentally trace the PS 5.1 forbidden-syntax list and flag any violations.
+4. For new functions, always include comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.OUTPUTS`).
+
+## DO NOT
+
+- Add PS 7+ syntax under any circumstance, even if it is cleaner
+- Mix WinRM and SSH branches in the same `if` block
+- Hardcode paths without a parameter + default
+- Create global variables
+- Use `Invoke-Expression`
+- Emit `Write-Output` for status messages (use `Write-Host`)
+- Modify Windows VM scripts when the task is Linux-only and vice versa

.gitignore

@@ -46,3 +46,10 @@ $RECYCLE.BIN/
 # Copilot Orchestrator temporary files
 .orchestrator/
 .worktrees/
+
+# AI/strumenti locali
+.claude/
+
+# Python bytecode
+__pycache__/
+*.pyc

AGENTS.md

@@ -0,0 +1,228 @@
+# AGENTS.md — Environment Reference
+
+Questo file descrive l'ambiente su cui e' costruito il progetto.
+Leggerlo prima di generare o modificare qualsiasi script.
+
+> **Istruzione per gli agenti**: questo file va tenuto aggiornato.
+> Se durante il lavoro si scopre un errore nuovo, un vincolo non documentato,
+> un pattern che ha causato problemi o una best-practice utile, aggiungerla
+> nella sezione "Errori frequenti da evitare" o in una sezione apposita.
+> Non aggiungere dettagli ovvi o gia' coperti; solo informazioni che
+> impedirebbero errori concreti in sessioni future.
+
+---
+
+## Host
+
+| Parametro          | Valore                                                                  |
+| ------------------ | ----------------------------------------------------------------------- |
+| OS                 | Windows 11                                                              |
+| Hardware           | i9-10900X, 64 GB RAM, NVMe SSD                                          |
+| PowerShell         | **5.1** (Windows PowerShell — NON Core/7)                               |
+| VMware Workstation | Pro, `vmrun.exe` in `C:\Program Files (x86)\VMware\VMware Workstation\` |
+| SSH client         | `ssh.exe` / `scp.exe` built-in Windows 11 (PATH)                        |
+| act_runner         | v1.0.2 — `F:\CI\act_runner\act_runner.exe`                              |
+| Gitea              | `http://10.10.20.11:3100` / `https://gitea.emulab.it`                   |
+
+---
+
+## PowerShell 5.1 — Vincoli critici
+
+Tutti gli script devono girare su **Windows PowerShell 5.1**. Le seguenti
+sintassi sono disponibili solo in PS 7+ e NON vanno usate:
+
+| Costrutto PS 7+           | Alternativa PS 5.1 corretta               |
+| ------------------------- | ----------------------------------------- |
+| `$x ??= 'default'`        | `if ($null -eq $x) { $x = 'default' }`    |
+| `$a ?? $b`                | `if ($null -ne $a) { $a } else { $b }`    |
+| `cmd1 && cmd2`            | `cmd1; if ($LASTEXITCODE -eq 0) { cmd2 }` |
+| `cmd1 \|\| cmd2`          | `cmd1; if ($LASTEXITCODE -ne 0) { cmd2 }` |
+| `$x is [int]`             | `$x -is [int]`                            |
+| Ternary `$a ? $b : $c`    | `if ($a) { $b } else { $c }`              |
+| `foreach-object` con `&&` | pipeline classico con `-ErrorAction Stop` |
+
+Ogni script deve avere in testa:
+
+```powershell
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+```
+
+---
+
+## Python development
+
+L'orchestratore CI vive in `src/ci_orchestrator/` (package `ci-orchestrator`,
+entry point `python -m ci_orchestrator`). Tutta la logica applicativa
+nuova va scritta in Python, non in PowerShell. Gli script PS in `scripts/`
+sono ridotti a shim a 3 righe verso la CLI Python e sono mantenuti solo
+per compatibilita' con Task Scheduler e caller esterni.
+
+| Parametro                | Valore                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| Python                   | **3.11+** richiesto (`requires-python` in `pyproject.toml`)                           |
+| Venv produzione          | `F:\CI\python\venv\` — install **non-editable**: `pip install .` (act_runner=LocalSystem; `-e` rompe con `No module named ci_orchestrator`). Ri-deploy a ogni modifica codice. |
+| Venv dev locale          | `.venv\` (NON committare; gitignored)                                                  |
+| Install (dev locale)     | `python -m pip install -e .[dev]` — editable solo nel `.venv` dev               |
+| Test                     | `python -m pytest tests\python -q --cov=ci_orchestrator --cov-fail-under=90`          |
+| Lint                     | `python -m ruff check src tests\python`                                               |
+| Type-check               | `python -m mypy --strict src`                                                         |
+
+**Convenzioni Python (enforced da ruff + mypy --strict)**:
+
+- Type hints obbligatori su funzioni pubbliche e helper esportati. Evitare
+  `Any` se esiste un tipo concreto/Protocol; `Any` solo per fixture pytest
+  e mock.
+- Niente variabili globali. Lo state vive in oggetti passati esplicitamente
+  (factory `backends.load_backend(config)`, `Config` dataclass).
+- Niente `print()`: usare `click.echo` (rispetta il flag `-q` di click e
+  il redirect `err=True` per stderr).
+- Niente `subprocess.run(..., shell=True)`. Niente shell-out per cose che
+  esistono come libreria Python (paramiko per SSH, pypsrp per WinRM,
+  keyring per credenziali).
+- Encoding stdio sempre UTF-8: i moduli Python lo assumono e
+  `runner/config.yaml` esporta `PYTHONIOENCODING=utf-8` ad act_runner.
+
+**Mappatura script PowerShell → sotto-comando Python** (Fase A2/A3/A4):
+
+| PowerShell legacy (shim)            | Python sub-command                         |
+| ----------------------------------- | ------------------------------------------ |
+| `Wait-VMReady.ps1`                  | `python -m ci_orchestrator wait-ready`     |
+| `New-BuildVM.ps1`                   | `python -m ci_orchestrator vm new`         |
+| `Remove-BuildVM.ps1`                | `python -m ci_orchestrator vm remove`      |
+| `Cleanup-OrphanedBuildVMs.ps1`      | `python -m ci_orchestrator vm cleanup`     |
+| `Invoke-RemoteBuild.ps1`            | `python -m ci_orchestrator build run`      |
+| `Get-BuildArtifacts.ps1`            | `python -m ci_orchestrator artifacts collect` |
+| `Watch-DiskSpace.ps1`               | `python -m ci_orchestrator monitor disk`   |
+| `Watch-RunnerHealth.ps1`            | `python -m ci_orchestrator monitor runner` |
+| `Get-CIJobSummary.ps1`              | `python -m ci_orchestrator report job`     |
+| `Invoke-CIJob.ps1`                  | `python -m ci_orchestrator job`            |
+
+Restano in PowerShell (girano sull'host fuori dal flusso CI o nel guest):
+`Setup-Host.ps1`, `Register-CIScheduledTasks.ps1`, `Backup-CITemplate.ps1`,
+`Invoke-RetentionPolicy.ps1`, `Measure-CIBenchmark.ps1`,
+`Test-CapacityBurnIn.ps1`, tutti i `template/Deploy-*.ps1`,
+`template/Prepare-*.ps1`, `template/Install-CIToolchain-*.ps1` e i
+`tests/Test-*.ps1` di smoke locale.
+
+**Test gate**: coverage totale ≥90% (alzato in A5, poi a 90%). Nuovi moduli devono
+includere unit test con mock; gli errori frequenti di questa stessa
+sezione sono coperti da `tests/python/test_agents_errors.py` come
+regression test — non rimuoverli senza aggiornare la voce in
+"Errori frequenti da evitare" e motivare la rimozione.
+
+**Closeout fasi A**: vedi `plans/A1-closeout.md`, `plans/A2-closeout.md`,
+`plans/A3-closeout.md`, `plans/A4-closeout.md`, `plans/A5-closeout.md`
+per stato per-fase, decisioni prese e voci pendenti a carico utente.
+
+---
+
+## Struttura directory host (fissa)
+
+```
+F:\CI\
+  act_runner\          — binario e stato act_runner
+  Templates\
+    WinBuild2025\      — template Windows Server 2025
+    WinBuild2022\      — template Windows Server 2022
+    LinuxBuild2404\    — template Ubuntu 24.04
+  BuildVMs\            — clone efimeri (creati/distrutti per ogni job)
+  Artifacts\           — artifact raccolti (per job-id)
+  ISO\                 — ISO/VMDK di bootstrap (cache download)
+  keys\
+    ci_linux           — chiave SSH privata per guest Linux (no passphrase)
+    ci_linux.pub       — chiave pubblica corrispondente
+```
+
+---
+
+## VM Template
+
+### Windows (WinBuild2025 — primario)
+
+| Parametro      | Valore                                                                          |
+| -------------- | ------------------------------------------------------------------------------- |
+| OS             | Windows Server 2025                                                             |
+| VMX            | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`                                 |
+| Snapshot clone | `BaseClean`                                                                     |
+| Transport      | WinRM HTTPS porta 5986, cert self-signed (lab-only)                             |
+| Credenziali    | Windows Credential Manager target `BuildVMGuest`                                |
+| Rete           | VMnet8 NAT — `192.168.79.0/24`                                                  |
+| Toolchain      | VS Build Tools 2026 (MSBuild 18.5 / v145), .NET SDK 10, Python 3.13, Git, 7-Zip |
+
+Variante **WinBuild2022**: path `F:\CI\Templates\WinBuild2022\WinBuild2022.vmx`, stesso snapshot `BaseClean`.
+
+### Linux (LinuxBuild2404)
+
+| Parametro      | Valore                                                        |
+| -------------- | ------------------------------------------------------------- |
+| OS             | Ubuntu 24.04 LTS (cloud image)                                |
+| VMX            | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx`           |
+| Snapshot clone | `BaseClean-Linux`                                             |
+| Transport      | SSH porta 22, utente `ci_build`, chiave `F:\CI\keys\ci_linux` |
+| Rete           | VMnet8 NAT — `192.168.79.0/24`                                |
+| Toolchain      | GCC, G++, Clang, CMake, Ninja, Python 3, Git, 7-Zip           |
+| CI dirs        | `/opt/ci/{build,output,scripts,cache}` — owner `ci_build`     |
+
+---
+
+## Transport layer
+
+- **Windows guest**: WinRM (`New-PSSession` con `New-CISessionOption` da `_Common.psm1`).
+  Usare `Invoke-Command -Session`, `Copy-Item -ToSession / -FromSession`.
+- **Linux guest**: SSH/SCP via `ssh.exe` / `scp.exe`.
+  Usare le funzioni di `scripts/_Transport.psm1`:
+  `Invoke-SshCommand`, `Copy-SshItem`, `Test-SshReady`.
+- **vmrun.exe**: sempre invocato tramite `Invoke-Vmrun` da `_Common.psm1`
+  (wrapper uniforme che gestisce `$LASTEXITCODE` e output).
+
+NON modificare il branch WinRM esistente quando si lavora sul branch Linux e viceversa.
+
+---
+
+## act_runner / Gitea Actions
+
+- Labels runner: `windows-build:host`, `linux-build:host`
+- Env vars iniettate in ogni job (da `runner/config.yaml`):
+  - `GITEA_CI_TEMPLATE_PATH` — VMX Windows template
+  - `GITEA_CI_LINUX_TEMPLATE_PATH` — VMX Linux template
+  - `GITEA_CI_CLONE_BASE_DIR` — `F:\CI\BuildVMs`
+  - `GITEA_CI_ARTIFACT_DIR` — `F:\CI\Artifacts`
+  - `GITEA_CI_GUEST_CRED_TARGET` — `BuildVMGuest`
+  - `GITEA_CI_SSH_KEY_PATH` — `F:\CI\keys\ci_linux`
+  - `CI_PYTHON_LAUNCHER` — absolute path al Python di sistema usato per
+    bootstrap del venv produzione (`F:\CI\python\venv`). act_runner gira come
+    SYSTEM con PATH sanitizzato (no `python`/`py.exe` risolvibili), quindi i
+    workflow Python leggono questo env come single source of truth. Aggiornare
+    solo quando si fa upgrade dell'interprete.
+
+---
+
+## Regole di stile (PSScriptAnalyzer)
+
+Configurazione in `PSScriptAnalyzerSettings.psd1`. Regole principali:
+
+- Indentazione: **4 spazi** (no tab)
+- `Write-Host` e' permesso (output catturato da act_runner; `Write-Output` interferisce con i return value)
+- `Invoke-Expression` vietato
+- Funzioni state-changing devono supportare `-WhatIf` / `ShouldProcess`
+- Credenziali solo come `[PSCredential]`, mai plain-text string
+- Nessuna variabile globale (`$global:`)
+
+---
+
+## Errori frequenti da evitare
+
+1. **Sintassi PS 7+** in script PS 5.1 — vedi tabella sopra.
+2. **`$LASTEXITCODE` non controllato** dopo `vmrun`, `ssh`, `scp` — controllare sempre e fare `throw` se non zero.
+3. **Percorsi hardcoded senza parametro** — ogni path critico deve avere un parametro con default documentato.
+4. **Modificare entrambi i branch (WinRM e SSH) nello stesso script** — mantenerli separati con `if ($GuestOS -eq 'Linux')`.
+5. **Usare `New-PSSession` / WinRM verso host Linux** — Linux usa solo SSH tramite `_Transport.psm1`.
+6. **Non rimuovere il seed ISO dal VMX** dopo il primo boot Linux — `ide1:0.present = "FALSE"` deve essere settato dopo cloud-init.
+7. **`[ordered]@{}` non disponibile in PS 2** — non e' un problema qui (PS 5.1), ma ricordare che `[ordered]` e' PS 3+.
+8. **`ForEach-Object -Parallel`** — disponibile solo in PS 7+; usare `foreach` classico o `Start-Job`.
+9. **Snapshot template catturato con VM accesa** — produce file `*.vmem` / `*.vmsn` con memoria; `vmrun clone ... linked -snapshot=<name>` rifiuta con `Error: The virtual machine should not be powered on. It is already running.` anche se `vmrun list` mostra 0 VM. Catturare snapshot SOLO da stato fully powered-off (verificare assenza di `.vmem` nella dir template).
+10. **`vmrun getGuestIPAddress` per check "VM running"** — richiede VMware Tools attivi nel guest; in headless Tools puo' impiegare 30-60s a rispondere e il check appare bloccato. Usare `vmrun list` e cercare il path del VMX nell'output per `is_running`. Per recuperare l'IP usare `getGuestIPAddress -wait` (blocca internamente finché Tools registrano l'IP) e filtrare le righe che iniziano con `"Error:"` perché vmrun in modalità headless può tornare exit code 0 con `"Error: The VMware Tools are not running..."` su stdout invece di usare un exit code non-zero.
+11. **Machine-id identico tra clone Linux** — le cloud image Ubuntu hanno un `/etc/machine-id` fisso. VMware DHCP assegna l'IP tramite DHCP client-id derivato da machine-id: se tutti i clone hanno lo stesso machine-id ottengono lo stesso IP e si bloccano per "IP collision". Fix nel template (prima di prendere lo snapshot): `sudo truncate -s 0 /etc/machine-id && sudo rm -f /var/lib/dbus/machine-id && sudo shutdown -h now`, poi ricreare lo snapshot `BaseClean-Linux` da stato powered-off.
+12. **`& nativecmd 2>$null` NON sopprime stderr in PS 5.1 con `$ErrorActionPreference='Stop'`** — la stderr del processo nativo viene convertita in ErrorRecord nel pipeline di PowerShell; sotto `'Stop'` questo diventa un errore terminante PRIMA che `2>$null` possa scartarlo. Esempio: `ssh-keygen -R <ip> -f <file>` stampa "Host X not found in file" su stderr → eccezione terminante. Fix: usare `$ErrorActionPreference = 'SilentlyContinue'` attorno alla chiamata oppure `2>&1 | Out-Null`. Per i job CI su VM ephemere locali, usare direttamente `StrictHostKeyChecking=no UserKnownHostsFile=NUL` (default in `_Transport.psm1` con `KnownHostsFile=''`) — nessun `ssh-keygen` necessario.

PSScriptAnalyzerSettings.psd1

@@ -0,0 +1,108 @@
+@{
+    # ── Rules to suppress project-wide ──────────────────────────────────────────
+    ExcludeRules = @(
+        # All CI scripts use Write-Host for structured output captured by act_runner.
+        # Write-Output would interleave with function return values and break callers.
+        'PSAvoidUsingWriteHost',
+
+        # Formatting-only rules: generate one warning per line across all existing scripts
+        # (thousands of hits). Run locally with Invoke-ScriptAnalyzer -Fix to auto-format;
+        # do not use as CI gate until the whole codebase has been reformatted.
+        'PSUseConsistentIndentation',
+        'PSUseConsistentWhitespace',
+
+        # The codebase uses the param() + -ArgumentList pattern for remote script blocks
+        # (Invoke-Command, Start-Job) consistently and correctly. PSSA does not recognise
+        # param() inside a ScriptBlock as a local declaration, so it fires a false positive
+        # on every parameter. $Using: is an alternative but not required here.
+        'PSUseUsingScopeModifierInNewRunspaces',
+
+        # UTF-8 without BOM is the editor default; adding BOM to ~35 files is cosmetic
+        # and does not affect PS 5.1 execution.
+        'PSUseBOMForUnicodeEncodedFile',
+
+        # Plural nouns in internal helpers (Get-GuestDiagnostics, Remove-OldJobDirs, etc.)
+        # are intentional — they describe collections, not single objects.
+        'PSUseSingularNouns',
+
+        # PSAvoidUsingPlainTextForPassword fires as a false positive on *CredentialTarget params
+        # (Windows Credential Manager target strings, not passwords). Real plain-text password
+        # usage in template setup scripts is already caught by PSAvoidUsingConvertToSecureStringWithPlainText
+        # with targeted SuppressMessage attributes where intentional.
+        'PSAvoidUsingPlainTextForPassword',
+
+        # These scripts use [switch]$VerifyArtifact = $true for opt-out patterns.
+        # Removing the default would silently change script behaviour.
+        'PSAvoidDefaultValueSwitchParameter',
+
+        # Stop-Vm is an intentional internal name in a VMware-only CI environment;
+        # Hyper-V is not installed on the CI host so there is no real cmdlet to shadow.
+        'PSAvoidOverwritingBuiltInCmdlets',
+
+        # Advisory rule only. Params may be declared for external callers, future use,
+        # or accepted-but-ignored forwarding. Not a safety issue.
+        'PSReviewUnusedParameter'
+    )
+
+    # ── Rule-specific configuration ──────────────────────────────────────────────
+    Rules = @{
+        # Security: never eval arbitrary strings
+        PSAvoidUsingInvokeExpression = @{
+            Enable = $true
+        }
+
+        # ShouldProcess/WhatIf support is not required for one-shot deployment scripts
+        # and internal CI helper functions; adding it to all state-changing functions
+        # would be invasive with no operational benefit in this environment.
+        PSUseShouldProcessForStateChangingFunctions = @{
+            Enable = $false
+        }
+
+        # Credentials must flow as [PSCredential], not plain strings
+        PSUsePSCredentialType = @{
+            Enable = $true
+        }
+
+        # Covered by ExcludeRules above (false positives on *CredentialTarget params).
+        PSAvoidUsingPlainTextForPassword = @{
+            Enable = $false
+        }
+
+        # ConvertTo-SecureString -AsPlainText only acceptable during template setup;
+        # use Suppress comments there if needed.
+        PSAvoidUsingConvertToSecureStringWithPlainText = @{
+            Enable = $true
+        }
+
+        # No script-scope globals that bleed across module boundaries
+        PSAvoidGlobalVars = @{
+            Enable = $true
+        }
+
+        # Formatting — 4-space indentation, spaces (not tabs)
+        PSUseConsistentIndentation = @{
+            Enable              = $true
+            IndentationSize     = 4
+            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
+            Kind                = 'space'
+        }
+
+        PSUseConsistentWhitespace = @{
+            Enable                          = $true
+            CheckInnerBrace                 = $true
+            CheckOpenBrace                  = $true
+            CheckOpenParen                  = $true
+            CheckOperator                   = $true
+            CheckPipe                       = $true
+            CheckPipeForRedundantWhitespace = $true
+            CheckSeparator                  = $true
+            CheckParameter                  = $false
+        }
+
+        # Alignment is a style preference; disable to avoid false positives on
+        # the deliberate column-aligned hashtable assignments used in this project.
+        PSAlignAssignmentStatement = @{
+            Enable = $false
+        }
+    }
+}

README.md

@@ -1,8 +1,8 @@
-# Local CI/CD System
+# Local CI/CD System
 
 Sistema CI/CD self-hosted su Windows per build isolati in VM efimere VMware.
 
-**Stato**: production-ready — e2e verificato (e2e-009 SUCCESS)
+**Stato**: production-ready — build Windows e Linux verificati e2e; burn-in concorrente a 4 job PASS; §3.3 in-VM git clone attivabile via `-UseGitClone`
 
 ---
 
@@ -15,46 +15,61 @@ Per ogni job, lo script `Invoke-CIJob.ps1` orchestra l'intero ciclo:
 Gitea push/tag
       │
       ▼
-  act_runner  (Windows service, label: windows-build)
+  act_runner  (label: windows-build | linux-build)
       │
       ▼
   Invoke-CIJob.ps1
       │
       ├─ 1. git clone repo su host  (con submoduli)
-      ├─ 2. Linked clone da snapshot BaseClean
+      ├─ 2. Linked clone da snapshot BaseClean / BaseClean-Linux
       ├─ 3. Avvio VM headless
-      ├─ 4. Attesa WinRM ready
-      ├─ 5. Zip transfer → build via WinRM → raccolta artifacts
+      ├─ 4. Attesa readiness  (WinRM/5986 per Windows, SSH/22 per Linux)
+      ├─ 5. Source transfer + build  (WinRM per Windows, SSH/SCP per Linux)
       ├─ 6. Copia artifacts in F:\CI\Artifacts\<jobid>\
       └─ finally: stop + rimozione VM clone
 ```
 
-Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dallo snapshot `BaseClean` ad ogni run.
+Ogni build gira in una VM **usa e getta** ripristinata dallo snapshot: Windows Server 2025/2022 (WinRM) o Ubuntu 24.04 (SSH).
 
 ---
 
 ## Requisiti Host
 
-| Componente | Versione / Dettaglio |
-|---|---|
-| OS | Windows 11 |
-| CPU/RAM | i9-10900X, 64 GB RAM |
-| VMware Workstation Pro | installato, `vmrun.exe` disponibile |
-| PowerShell | 5.1 |
-| act_runner | v1.0.2 — `F:\CI\act_runner\act_runner.exe` |
-| Gitea | self-hosted `http://10.10.20.11:3100` / `https://gitea.emulab.it` |
+| Componente             | Versione / Dettaglio                                              |
+| ---------------------- | ----------------------------------------------------------------- |
+| OS                     | Windows 11                                                        |
+| CPU/RAM                | i9-10900X, 64 GB RAM                                              |
+| VMware Workstation Pro | installato, `vmrun.exe` disponibile                               |
+| PowerShell             | 5.1                                                               |
+| act_runner             | v1.0.2 — `F:\CI\act_runner\act_runner.exe`                        |
+| Gitea                  | self-hosted `http://10.10.20.11:3100` / `https://gitea.emulab.it` |
 
-## Template VM (snapshot `BaseClean`)
+## Template VM
 
-| Componente | Versione |
-|---|---|
-| OS | Windows Server 2025 |
-| VMX | `F:\CI\Templates\WinBuild\CI-WinBuild.vmx` |
-| VS Build Tools | 2026 (MSBuild 18.5.4 / toolset v145) |
-| .NET SDK | 10.0.203 |
-| Python | 3.13.3 |
-| Rete | VMnet8 NAT — `192.168.79.0/24` |
-| WinRM | HTTP/5985, Basic auth (lab-only) |
+### Windows (snapshot `BaseClean`)
+
+| Componente     | Versione                                                                       |
+| -------------- | ------------------------------------------------------------------------------ |
+| OS             | Windows Server 2025                                                            |
+| VMX            | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` (env `GITEA_CI_TEMPLATE_PATH`) |
+| VS Build Tools | 2026 (MSBuild 18.5.4 / toolset v145)                                           |
+| .NET SDK       | 10.0.203                                                                       |
+| Python         | 3.13.3                                                                         |
+| Rete           | VMnet8 NAT — `192.168.79.0/24`                                                 |
+| WinRM          | HTTPS/5986, Basic auth, self-signed cert (SkipCACheck — lab-only)              |
+
+Variante **Windows Server 2022**: `*WinBuild2022.ps1` + VMX `F:\CI\Templates\WinBuild2022\WinBuild2022.vmx`.
+
+### Linux (snapshot `BaseClean-Linux`)
+
+| Componente   | Versione                                                                                 |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| OS           | Ubuntu 24.04 LTS (cloud image)                                                           |
+| VMX          | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` (env `GITEA_CI_LINUX_TEMPLATE_PATH`) |
+| Toolchain    | GCC, G++, Clang, CMake, Ninja, Python 3, Git, 7-Zip                                      |
+| Rete         | VMnet8 NAT — `192.168.79.0/24`                                                           |
+| SSH          | porta 22, utente `ci_build`, chiave `F:\CI\keys\ci_linux`                                |
+| Runner label | `linux-build:host`                                                                       |
 
 ---
 
@@ -62,59 +77,233 @@ Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dall
 
 ```
 ├── Setup-Host.ps1                # Bootstrap host: dirs F:\CI\, credenziali, act_runner service
+├── PSScriptAnalyzerSettings.psd1 # Regole linting condivise (§5.4)
 │
 ├── scripts/
-│   ├── Invoke-CIJob.ps1          # Orchestratore principale
+│   ├── _Common.psm1              # Shared module (vmrun wrapper, diagnostics)
+│   ├── _Transport.psm1           # SSH/SCP helpers per guest Linux (Invoke-SshCommand, Copy-SshItem)
+│   ├── Invoke-CIJob.ps1          # Orchestratore principale (Windows WinRM + Linux SSH, -UseGitClone)
 │   ├── New-BuildVM.ps1           # Linked clone da template
-│   ├── Wait-VMReady.ps1          # Polling WinRM readiness
-│   ├── Invoke-RemoteBuild.ps1    # Zip transfer + esecuzione build in VM
-│   ├── Get-BuildArtifacts.ps1    # Copia artifacts dall'host
-│   └── Remove-BuildVM.ps1        # Stop + rimozione VM clone
+│   ├── Wait-VMReady.ps1          # Polling readiness (WinRM/5986 o SSH/22)
+│   ├── Invoke-RemoteBuild.ps1    # Build remoto (WinRM per Windows, SSH/SCP per Linux)
+│   ├── Get-BuildArtifacts.ps1    # Raccolta artifacts (WinRM o SCP)
+│   ├── Remove-BuildVM.ps1        # Stop + rimozione VM clone (-WhatIf)
+│   ├── Cleanup-OrphanedBuildVMs.ps1   # Cleanup VM orfane (§2.2)
+│   ├── Invoke-RetentionPolicy.ps1     # Retention artifact + log (§2.3)
+│   ├── Watch-DiskSpace.ps1            # Alert spazio libero F: (§4.3)
+│   ├── Watch-RunnerHealth.ps1         # Health check runner (§2.7)
+│   ├── Backup-CITemplate.ps1          # Backup VMDK template (§2.6)
+│   ├── Set-TemplateSharedFolders.ps1  # Cache NuGet/pip via shared folders (§3.1)
+│   ├── Measure-CIBenchmark.ps1        # Benchmark fasi pipeline (§3.6)
+│   ├── Register-CIScheduledTasks.ps1  # Task Scheduler bootstrap
+│   ├── Test-CapacityBurnIn.ps1        # Burn-in concorrente N job × R round
+│   ├── Start-BurnInTest-Linux.ps1     # Wrapper burn-in specifico per LinuxBuild2404
+│   └── Get-CIJobSummary.ps1           # Report sintetico ultima esecuzione job
 │
 ├── template/
-│   ├── Prepare-WinBuild2025.ps1 # Provisioning automatico template VM (HOST-side)
-│   └── Setup-WinBuild2025.ps1    # Installazione toolchain nella VM (GUEST-side)
+│   ├── autounattend.template.xml  # Template XML per installazione Windows unattended
+│   ├── Deploy-WinBuild2025.ps1   # Deploy VM + install Windows 2025 unattended (HOST)
+│   ├── Prepare-WinBuild2025.ps1  # Provisioning toolchain 2025 via WinRM (HOST-side)
+│   ├── Install-CIToolchain-WinBuild2025.ps1    # Toolchain CI 2025 nella VM (GUEST-side)
+│   ├── Deploy-WinBuild2022.ps1   # Deploy VM + install Windows 2022 unattended (HOST)
+│   ├── Prepare-WinBuild2022.ps1  # Provisioning toolchain 2022 via WinRM (HOST-side)
+│   ├── Install-CIToolchain-WinBuild2022.ps1    # Toolchain CI 2022 nella VM (GUEST-side)
+│   ├── Deploy-LinuxBuild2404.ps1 # Deploy cloud image Ubuntu 24.04 su VMware (HOST)
+│   ├── Prepare-LinuxBuild2404.ps1# Provisioning toolchain Linux via SSH + snapshot (HOST-side)
+│   ├── Install-CIToolchain-Linux2404.sh        # Toolchain CI Ubuntu 24.04 nel guest (GUEST-side)
+│   ├── Validate-DeployState.ps1  # Validazione stato post-Deploy (2025, 2022, Linux)
+│   └── Validate-SetupState.ps1   # Validazione stato post-Setup (pre-snapshot)
+│
+├── tests/                        # Pester v5 unit tests (§5.1)
 │
 ├── gitea/
+│   ├── actions/
+│   │   └── local-ci-build/action.yml  # Composite action riusabile (wrap Invoke-CIJob.ps1)
 │   ├── workflows/
-│   │   └── build-nsis.yml        # Workflow live per nsis-plugin-nsinnounp
+│   │   ├── build-ns7zip.yml        # Workflow matrix Windows+Linux per nsis-plugin-ns7zip
+│   │   └── lint.yml              # PSScriptAnalyzer su push/PR (§5.4)
 │   └── workflow-example.yml      # Template generico adattabile
 │
 ├── runner/
-│   └── config.yaml               # Configurazione act_runner (no secrets)
+│   ├── config.yaml               # Configurazione act_runner (no secrets)
+│   └── Install-Runner.ps1
 │
 ├── docs/
 │   ├── ARCHITECTURE.md           # Diagramma sistema e componenti
 │   ├── CI-FLOW.md                # Flusso dettagliato passo-passo
+│   ├── HOST-SETUP.md             # Bootstrap macchina host
+│   ├── WINDOWS-TEMPLATE-SETUP.md # Provisioning template Windows
+│   ├── LINUX-TEMPLATE-SETUP.md   # Bozza template Linux (§6.1, non implementato)
 │   ├── OPTIMIZATION.md           # Layout disco, snapshot, cache, tuning
-│   ├── BEST-PRACTICES.md         # Sicurezza, WinRM, credenziali
-│   └── Setup-GiteaSSH.md         # Configurazione SSH alias per Gitea
+│   ├── BEST-PRACTICES.md         # Sicurezza, WinRM, credenziali, threat model
+│   ├── RUNBOOK.md                # Triage incident comuni (§4.4)
+│   ├── TEST-PLAN-v1.3-to-HEAD.md # Test plan completo features post-v1.3
+│   ├── Setup-GiteaSSH.md         # Configurazione SSH alias per Gitea
+│   └── archived/                 # Doc storici / sign-off
 │
-├── PLAN.md                       # Stato implementazione e decisioni tecniche
-└── TODO.md                       # Task completati e roadmap futura
+└── TODO.md                       # Roadmap, audit trail task completati, backlog
 ```
 
 ---
 
+## Python orchestrator (Phase A — in progress)
+
+A new Python 3.11+ rewrite of the orchestrator lives under `src/ci_orchestrator/`.
+Phase A (see [implementation-plan-A-B](plans/implementation-plan-A-B.md)) is on
+branch `feature/python-rewrite-and-linux-migration`. As of A5 the Python CLI is the
+production entry point invoked by `gitea/actions/local-ci-build/action.yml`;
+the PowerShell scripts in `scripts/` are 3-line shims that forward to the
+Python sub-commands listed below.
+
+### Setup
+
+```powershell
+# Production venv on the runner host (one-time + on every code deploy).
+# NON-editable: act_runner runs as LocalSystem and cannot resolve an
+# editable .pth into the dev tree or a transient RunnerWork dir
+# (-> "No module named ci_orchestrator"). Re-run `pip install .` after
+# each code change. No CI workflow may install into this venv.
+python -m venv F:\CI\python\venv
+F:\CI\python\venv\Scripts\python.exe -m pip install --upgrade pip
+F:\CI\python\venv\Scripts\python.exe -m pip install .
+
+# Local dev venv (NOT committed; see .gitignore) — editable is fine here
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+```
+
+Configuration: copy [config.example.toml](config.example.toml) to
+`F:\CI\config.toml` (or set `$env:CI_CONFIG`). Environment variables
+(`CI_ROOT`, `CI_TEMPLATES`, `CI_BUILD_VMS`, `CI_ARTIFACTS`, `CI_KEYS`)
+override the file. Dependency manifest and tool config (ruff, mypy,
+pytest, coverage) live in [pyproject.toml](pyproject.toml).
+
+### CLI sub-commands
+
+```powershell
+# Discover commands
+python -m ci_orchestrator --help
+
+# Wait for a VM to become reachable (WinRM 5986 or SSH 22 — auto-detected)
+python -m ci_orchestrator wait-ready `
+    --vmx F:\CI\BuildVMs\smoke\smoke.vmx --guest-os windows --timeout 300
+
+# Linked-clone lifecycle
+python -m ci_orchestrator vm new `
+    --template-path F:\CI\Templates\WinBuild2025\WinBuild2025.vmx `
+    --snapshot-name BaseClean `
+    --clone-base-dir F:\CI\BuildVMs `
+    --job-id smoke-001
+python -m ci_orchestrator vm remove --vmx F:\CI\BuildVMs\Clone_smoke-001_*\Clone_smoke-001_*.vmx
+python -m ci_orchestrator vm cleanup --max-age-hours 12
+
+# Build + artifact collection
+python -m ci_orchestrator build run `
+    --vmx F:\CI\BuildVMs\Clone_smoke-001_*\*.vmx `
+    --script .\build.ps1 --workdir C:\build --guest-os windows
+python -m ci_orchestrator artifacts collect `
+    --vmx F:\CI\BuildVMs\Clone_smoke-001_*\*.vmx `
+    --remote-path C:\build\dist --local-dir F:\CI\Artifacts\smoke-001
+
+# Monitoring (driven by Task Scheduler / systemd timers in B5)
+python -m ci_orchestrator monitor disk --min-free-gb 50 --drive-letter F
+python -m ci_orchestrator monitor runner --state-dir F:\CI\act_runner
+
+# Reporting
+python -m ci_orchestrator report job --job-id smoke-001
+
+# End-to-end orchestrator (replaces Invoke-CIJob.ps1)
+python -m ci_orchestrator job `
+    --job-id        smoke-001 `
+    --repo-url      ssh://gitea-ci/Simone/nsis-plugin-ns7zip.git `
+    --branch        main `
+    --template-path F:\CI\Templates\WinBuild2025\WinBuild2025.vmx `
+    --build-command "python build_plugin.py --final --dist-dir dist" `
+    --guest-artifact-source dist
+```
+
+The PowerShell wrappers (`scripts\Invoke-CIJob.ps1`,
+`scripts\New-BuildVM.ps1`, `scripts\Wait-VMReady.ps1`,
+`scripts\Remove-BuildVM.ps1`, `scripts\Cleanup-OrphanedBuildVMs.ps1`,
+`scripts\Invoke-RemoteBuild.ps1`, `scripts\Get-BuildArtifacts.ps1`,
+`scripts\Watch-DiskSpace.ps1`, `scripts\Watch-RunnerHealth.ps1`,
+`scripts\Get-CIJobSummary.ps1`) are kept as 3-line shims for Task
+Scheduler and external callers — they translate PascalCase parameters
+to the Python kebab-case CLI and propagate the exit code.
+
+### Local validation gates
+
+```powershell
+.\.venv\Scripts\python.exe -m ruff check src tests\python
+.\.venv\Scripts\python.exe -m mypy --strict src
+.\.venv\Scripts\python.exe -m pytest tests\python -q --cov=ci_orchestrator --cov-fail-under=90
+```
+
+Coverage gate is **90%**. Regression tests for the
+`AGENTS.md` "Errori frequenti da evitare" #9–#12 live in
+[tests/python/test_agents_errors.py](tests/python/test_agents_errors.py)
+and must stay green.
+
+---
+
 ## Setup rapido
 
-### 1. Template VM
+### 1a. Template VM Windows
+
+**Opzione A — Deploy automatico** (crea VM + installa Windows unattended da ISO):
 
 ```powershell
-# Dalla directory template/, dopo aver installato Windows Server 2025 nella VM
-# e annotato il suo IP DHCP su VMnet8:
-.\Prepare-WinBuild2025.ps1 -VMIPAddress 192.168.79.x -SkipWindowsUpdate
+cd N:\Code\Workspace\Local-CI-CD-System\template
+# Windows Server 2025 (corrente):
+.\Deploy-WinBuild2025.ps1 -ISOPath F:\CI\ISO\WinSrv2025.iso `
+    -VMPath F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
+# Windows Server 2022 (alternativa):
+.\Deploy-WinBuild2022.ps1 -ISOPath F:\CI\ISO\WinSrv2022.iso `
+    -VMPath F:\CI\Templates\WinBuild2022\WinBuild2022.vmx
+```
+
+**Opzione B — installazione manuale**: installa Windows nella VM, abilita WinRM
+(`winrm quickconfig -q` + `Enable-PSRemoting -Force`), annota l'IP VMnet8.
+
+**Provisioning toolchain** (dopo A o B, dalla directory `template/`):
+
+```powershell
+# Windows Server 2025:
+.\Prepare-WinBuild2025.ps1 -VMIPAddress 192.168.79.x -StoreCredential
+# Windows Server 2022:
+.\Prepare-WinBuild2022.ps1 -VMIPAddress 192.168.79.x -StoreCredential
 ```
 
 Poi spegni la VM e prendi lo snapshot con nome esatto **`BaseClean`**.
 
+### 1b. Template VM Linux
+
+```powershell
+cd N:\Code\Workspace\Local-CI-CD-System\template
+# Deploy cloud image Ubuntu 24.04 (scarica ISO/cloud img, crea VM):
+.\Deploy-LinuxBuild2404.ps1 -VMPath F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
+```
+
+**Provisioning toolchain** (SSH — la VM deve essere avviata e raggiungibile):
+
+```powershell
+.\Prepare-LinuxBuild2404.ps1 -VMIPAddress 192.168.79.x `
+    -VMXPath F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx `
+    -TakeSnapshot
+```
+
+`-TakeSnapshot` esegue automaticamente: reset machine-id → shutdown → snapshot **`BaseClean-Linux`**.
+Dettagli: [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md).
+
 ### 2. Credenziali guest
 
 ```powershell
-# PowerShell elevato — una volta sola sull'host
-Import-Module CredentialManager
-New-StoredCredential -Target "BuildVMGuest" -UserName "ci_build" `
-    -Password "<your-build-password>" -Persist LocalMachine
+# PowerShell elevato — una volta sola sull'host.
+# Scrive nel vault SYSTEM (act_runner gira come LocalSystem; un
+# New-StoredCredential dalla sessione utente NON sarebbe leggibile dal
+# runner). Username host-qualificato col computer name del guest
+# (bare 'ci_build' -> NTLM SEC_E_UNKNOWN_CREDENTIALS).
+.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'
 ```
 
 ### 3. act_runner
@@ -128,59 +317,111 @@ nssm install act_runner "F:\CI\act_runner\act_runner.exe" daemon
 nssm start act_runner
 ```
 
-Imposta `GITEA_CI_TEMPLATE_PATH` nelle variabili d'ambiente del servizio:
-`F:\CI\Templates\WinBuild\CI-WinBuild.vmx`
+Imposta queste variabili d'ambiente nel servizio (`runner/config.yaml`):
+
+| Variabile                      | Valore                                              |
+| ------------------------------ | --------------------------------------------------- |
+| `GITEA_CI_TEMPLATE_PATH`       | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`     |
+| `GITEA_CI_LINUX_TEMPLATE_PATH` | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` |
+| `GITEA_CI_CLONE_BASE_DIR`      | `F:\CI\BuildVMs`                                    |
+| `GITEA_CI_ARTIFACT_DIR`        | `F:\CI\Artifacts`                                   |
+| `GITEA_CI_GUEST_CRED_TARGET`   | `BuildVMGuest`                                      |
+| `GITEA_CI_SSH_KEY_PATH`        | `F:\CI\keys\ci_linux`                               |
+
+Labels runner: `windows-build:host` (job Windows) e `linux-build:host` (job Linux).
+
+Dettagli completi: [docs/HOST-SETUP.md](docs/HOST-SETUP.md).
 
 ### 4. SSH per Gitea
 
 Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `gitea-ci`
-(SSH port 2222, necessario per `git clone ssh://gitea-ci/...` durante i build).
+(SSH port 2222, usato dai workflow live in `git clone ssh://gitea-ci/...`).
 
 ---
 
 ## Uso — build manuale (test)
 
+**Windows guest:**
+
 ```powershell
 & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
-  -JobId               'test-001' `
-  -RepoUrl             'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git' `
+  -JobId               'test-win-001' `
+  -RepoUrl             'ssh://gitea-ci/Simone/nsis-plugin-ns7zip.git' `
   -Branch              'main' `
-  -Commit              '' `
-  -TemplatePath        'F:\CI\Templates\WinBuild\CI-WinBuild.vmx' `
+  -TemplatePath        'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
   -Submodules `
   -BuildCommand        'python build_plugin.py --final --dist-dir dist' `
   -GuestArtifactSource 'dist' `
   -GuestCredentialTarget 'BuildVMGuest'
 ```
 
-Artifacts raccolti in: `F:\CI\Artifacts\test-001\artifacts.zip`
+**Linux guest:**
+
+```powershell
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+  -JobId               'test-linux-001' `
+  -RepoUrl             'ssh://gitea-ci/Simone/nsis-plugin-ns7zip.git' `
+  -Branch              'main' `
+  -TemplatePath        'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
+  -SnapshotName        'BaseClean-Linux' `
+  -GuestOS             'Linux' `
+  -BuildCommand        'bash build.sh' `
+  -GuestArtifactSource '/opt/ci/output'
+```
+
+Artifacts raccolti in: `F:\CI\Artifacts\<jobid>\`.
+
+Aggiungi `-UseGitClone` per clonare direttamente in VM (skip host-zip-transfer; richiede Git in template — già incluso nel toolchain).
+Aggiungi `-SkipArtifact` per job che non producono output (es. lint, test puri).
 
 ---
 
 ## Workflow Gitea
 
-Il file [gitea/workflows/build-nsis.yml](gitea/workflows/build-nsis.yml) è il workflow
-attivo per `Simone/nsis-plugin-nsinnounp`. Si attiva su push di tag `v*` o manualmente.
+Il file [gitea/workflows/build-ns7zip.yml](gitea/workflows/build-ns7zip.yml) è il workflow
+attivo per `Simone/nsis-plugin-ns7zip`. Si attiva su push di tag `v*` o manualmente.
+Usa una **strategy matrix** `[windows, linux]` che esegue in parallelo su entrambi i runner.
 
-Per adattarlo ad altri repository, copia [gitea/workflow-example.yml](gitea/workflow-example.yml)
-e aggiorna `-RepoUrl`, `-BuildCommand` e `-GuestArtifactSource`.
+La composite action [gitea/actions/local-ci-build/action.yml](gitea/actions/local-ci-build/action.yml)
+asconde tutta la logica Invoke-CIJob.ps1 e accetta questi input principali:
+
+| Input             | Descrizione                                      |
+| ----------------- | ------------------------------------------------ |
+| `build-command`   | Comando di build da eseguire nel guest           |
+| `guest-os`        | `Windows` (default) o `Linux`                    |
+| `artifact-source` | Path artifacts nel guest                         |
+| `skip-artifact`   | `true` per job senza output                      |
+| `repo-url`        | URL SSH del repository                           |
+| `job-id-suffix`   | Suffisso per disambiguare artifact dir in matrix |
+
+Per adattare ad altri repository, copia [gitea/workflow-example.yml](gitea/workflow-example.yml)
+e aggiorna `build-command`, `artifact-source`, `repo-url`.
 
 ---
 
 ## Documentazione
 
-| File | Contenuto |
-|---|---|
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Diagramma componenti e flusso dati |
-| [docs/CI-FLOW.md](docs/CI-FLOW.md) | Descrizione dettagliata di ogni fase del pipeline |
-| [docs/OPTIMIZATION.md](docs/OPTIMIZATION.md) | Layout NVMe, snapshot strategy, cache, tuning WinRM |
-| [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md) | Sicurezza WinRM, gestione credenziali, isolamento |
-| [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) | Configurazione SSH alias `gitea-ci` |
+| File                                                             | Contenuto                                                                                      |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                     | Diagramma componenti e flusso dati                                                             |
+| [docs/CI-FLOW.md](docs/CI-FLOW.md)                               | Descrizione dettagliata di ogni fase del pipeline                                              |
+| [docs/HOST-SETUP.md](docs/HOST-SETUP.md)                         | Bootstrap macchina host (Setup-Host.ps1)                                                       |
+| [docs/WINDOWS-TEMPLATE-SETUP.md](docs/WINDOWS-TEMPLATE-SETUP.md) | Provisioning template Windows (Deploy + Prepare + Setup)                                       |
+| [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md)     | Template Ubuntu 24.04: Deploy-LinuxBuild2404, Prepare-LinuxBuild2404, snapshot BaseClean-Linux |
+| [docs/OPTIMIZATION.md](docs/OPTIMIZATION.md)                     | Layout NVMe, snapshot strategy, cache, tuning                                                  |
+| [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md)                 | Sicurezza WinRM, threat model, credenziali                                                     |
+| [docs/RUNBOOK.md](docs/RUNBOOK.md)                               | Triage incident comuni (runner offline, clone fail, ecc.)                                      |
+| [docs/TEST-PLAN-v1.3-to-HEAD.md](docs/TEST-PLAN-v1.3-to-HEAD.md) | Test plan completo features post-v1.3                                                          |
+| [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md)                 | Configurazione SSH alias `gitea-ci`                                                            |
+| [TODO.md](TODO.md)                                               | Roadmap, audit trail task completati, backlog                                                  |
 
 ---
 
 ## Note di sicurezza
 
-WinRM in modalità HTTP/Basic è **accettabile solo in ambiente lab isolato**.
-Per ambienti di produzione o condivisi, migrare a HTTPS/5986 con certificato self-signed
-e rimuovere `AllowUnencrypted=true`. Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md).
+WinRM usa **HTTPS/5986** con certificato self-signed e Basic auth.
+`-SkipCACheck`/`-SkipCNCheck` sono accettabili in lab isolato (il cert non è di una CA trusted).
+Per ambienti condivisi o di produzione, usare un certificato CA valida e rimuovere `-SkipCACheck`.
+Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md).
+
+

Setup-Host.ps1

@@ -114,13 +114,20 @@ if (-not $ActRunnerConfigYaml) { $ActRunnerConfigYaml = Join-Path $scriptDir 'ru
 # ── Step 1: Create F:\CI\ directory tree ─────────────────────────────────────
 Write-Step "Creating CI directory tree under $CIRoot"
 
+# Canonical layout — see AGENTS.md §Struttura directory host
 $dirs = @(
     "$CIRoot\BuildVMs",
     "$CIRoot\Artifacts",
     "$CIRoot\Logs",
-    "$CIRoot\Templates\WinBuild",
+    "$CIRoot\Templates\WinBuild2025",
+    "$CIRoot\Templates\WinBuild2022",
+    "$CIRoot\Templates\LinuxBuild2404",
+    "$CIRoot\State",
+    "$CIRoot\State\ip-leases",
+    "$CIRoot\keys",
     "$CIRoot\act_runner\logs",
     "$CIRoot\Cache\NuGet",
+    "$CIRoot\Cache\pip",
     "$CIRoot\RunnerWork",
     "$CIRoot\ISO"
 )
@@ -306,6 +313,7 @@ Host gitea-ci
     Port     $GiteaSSHPort
     User     git
     IdentityFile ~/.ssh/id_rsa
+    StrictHostKeyChecking accept-new
 "@
 
     $existingConfig = ''
@@ -318,7 +326,66 @@ Host gitea-ci
     } else {
         Add-Content -Path $sshConfig -Value $aliasBlock -Encoding UTF8
         Write-OK "SSH alias 'gitea-ci' written to $sshConfig"
-        Write-Warn "Ensure your public SSH key is registered in Gitea under User Settings → SSH Keys."
+        Write-Warn "Ensure your public SSH key is registered in Gitea under User Settings -> SSH Keys."
+    }
+}
+
+# ── Step 8: Replicate SSH config to LocalSystem profile ──────────────────────
+# act_runner runs as LocalSystem; its SSH home differs from the interactive
+# user's USERPROFILE. Copy .ssh/config and the private key so that
+# 'ssh gitea-ci' works when invoked from act_runner jobs.
+if ($SkipSSHConfig) {
+    Write-Host "`n=== SSH LocalSystem replication SKIPPED (-SkipSSHConfig) ===" -ForegroundColor Yellow
+}
+else {
+    Write-Step "Replicating SSH config to LocalSystem profile (H8 — act_runner fix)"
+
+    $localSystemSsh    = Join-Path $env:SystemRoot 'System32\config\systemprofile\.ssh'
+    $sourceSshDir      = Join-Path $env:USERPROFILE '.ssh'
+    $sourceConfigPath  = Join-Path $sourceSshDir 'config'
+    $sourceKeyPath     = Join-Path $sourceSshDir 'id_rsa'
+    $sourceKnownHosts  = Join-Path $sourceSshDir 'known_hosts'
+
+    if (-not (Test-Path $localSystemSsh)) {
+        New-Item -ItemType Directory -Path $localSystemSsh -Force | Out-Null
+        Write-OK "Created $localSystemSsh"
+    }
+
+    # Copy config
+    if (Test-Path $sourceConfigPath) {
+        Copy-Item -Path $sourceConfigPath -Destination (Join-Path $localSystemSsh 'config') -Force
+        Write-OK "SSH config copied to $localSystemSsh\config"
+    }
+    else {
+        Write-Warn "Source SSH config not found at $sourceConfigPath — skipping config copy."
+    }
+
+    # Copy private key and lock down permissions
+    if (Test-Path $sourceKeyPath) {
+        $destKeyPath = Join-Path $localSystemSsh 'id_rsa'
+        Copy-Item -Path $sourceKeyPath -Destination $destKeyPath -Force
+
+        $acl = New-Object System.Security.AccessControl.FileSecurity
+        $acl.SetAccessRuleProtection($true, $false)
+        $acl.AddAccessRule(
+            (New-Object System.Security.AccessControl.FileSystemAccessRule(
+                'NT AUTHORITY\SYSTEM', 'FullControl', 'Allow')))
+        $acl.AddAccessRule(
+            (New-Object System.Security.AccessControl.FileSystemAccessRule(
+                'BUILTIN\Administrators', 'FullControl', 'Allow')))
+        Set-Acl -Path $destKeyPath -AclObject $acl
+        Write-OK "SSH private key copied and ACLs locked to SYSTEM/Administrators at $destKeyPath"
+    }
+    else {
+        Write-Warn "SSH private key not found at $sourceKeyPath — skipping key copy."
+        Write-Warn "Generate a key with: ssh-keygen -t rsa -b 4096 -f $sourceKeyPath -N ''"
+        Write-Warn "Then re-run Setup-Host.ps1."
+    }
+
+    # Copy known_hosts if it exists (avoids first-connect host-key prompt)
+    if (Test-Path $sourceKnownHosts) {
+        Copy-Item -Path $sourceKnownHosts -Destination (Join-Path $localSystemSsh 'known_hosts') -Force
+        Write-OK "known_hosts copied to LocalSystem profile."
     }
 }
 
@@ -339,7 +406,7 @@ Write-Host "    $CIRoot\ISO\"
 Write-Host ""
 Write-Host " 3. Provision the template VM:"
 Write-Host "    a. Create VM in VMware Workstation (4 vCPU, 6 GB RAM, 80 GB thin)"
-Write-Host "       VMX: $CIRoot\Templates\WinBuild\CI-WinBuild.vmx"
+Write-Host "       VMX: $CIRoot\Templates\WinBuild2025\WinBuild2025.vmx"
 Write-Host "       NIC: VMnet8 (NAT) — internet required during provisioning"
 Write-Host "    b. Install Windows Server 2025 + enable WinRM inside VM"
 Write-Host "    c. From this host run:"
@@ -354,3 +421,4 @@ Write-Host ""
 Write-Host " 5. Verify act_runner is Online in Gitea:"
 Write-Host "    $GiteaUrl/-/admin/runners"
 Write-Host ""
+

config.example.toml

@@ -0,0 +1,34 @@
+# ci-orchestrator config example.
+#
+# Copy to $CI_ROOT/config.toml or set $CI_CONFIG to the file path.
+# Environment variables (CI_ROOT, CI_TEMPLATES, CI_BUILD_VMS, CI_ARTIFACTS,
+# CI_KEYS, CI_VMRUN_PATH, CI_SSH_KEY_PATH, CI_GUEST_CRED_TARGET) override
+# anything set here.
+#
+# IMPORTANT (TOML rule): top-level keys must appear BEFORE any [section] header.
+# Keys placed after a [section] belong to that section, not to the root table.
+
+# Top-level orchestrator settings.
+vmrun_path        = "C:/Program Files (x86)/VMware/VMware Workstation/vmrun.exe"
+ssh_key_path      = "F:/CI/keys/ci_linux"
+guest_cred_target = "BuildVMGuest"
+
+# --------------------------------------------------------------- Windows host
+[paths]
+root       = "F:/CI"
+templates  = "F:/CI/Templates"
+build_vms  = "F:/CI/BuildVMs"
+artifacts  = "F:/CI/Artifacts"
+keys       = "F:/CI/keys"
+
+# Phase B (Linux host) — uncomment after migration.
+# [paths]
+# root       = "/var/lib/ci"
+# templates  = "/var/lib/ci/templates"
+# build_vms  = "/var/lib/ci/build-vms"
+# artifacts  = "/var/lib/ci/artifacts"
+# keys       = "/etc/ci/keys"
+
+# Phase C hook: backend selector. Only "workstation" is implemented in Phase A.
+[backend]
+type = "workstation"

deploy/systemd/README.md

@@ -0,0 +1,105 @@
+# systemd units — Local CI/CD System (Linux host)
+
+Coppie `*.service` + `*.timer` che replicano i task periodici registrati su
+Windows da `scripts/Register-CIScheduledTasks.ps1`. Pensate per essere
+installate su un host Linux Mint / Ubuntu LTS, con il package
+`ci_orchestrator` installato in `/opt/ci/venv/`.
+
+## Mapping Windows Task Scheduler → systemd timer
+
+| Windows Task Scheduler  | systemd unit                       | Cadenza                 | Comando                                                         |
+| ----------------------- | ---------------------------------- | ----------------------- | --------------------------------------------------------------- |
+| `CI-CleanupOrphans`     | `ci-cleanup-orphans.timer`         | every 6h + at boot      | `python -m ci_orchestrator vm cleanup --max-age-hours 6`        |
+| `CI-RetentionPolicy`    | `ci-retention-policy.timer`        | daily 03:00 + at boot   | `pwsh Invoke-RetentionPolicy.ps1` (vedi nota PowerShell)        |
+| `CI-DiskSpaceAlert`     | `ci-watch-disk-space.timer`        | every 15 min            | `python -m ci_orchestrator monitor disk`                        |
+| `CI-RunnerHealth`       | `ci-watch-runner-health.timer`     | every 15 min            | `python -m ci_orchestrator monitor runner`                      |
+| *(nuovo)*               | `ci-backup-template.timer`         | weekly Sun 02:00        | `pwsh Backup-CITemplate.ps1` (vedi nota PowerShell)             |
+
+## Nota PowerShell su Linux
+
+Due unit (`ci-retention-policy`, `ci-backup-template`) invocano script
+PowerShell che, per scelta documentata in `AGENTS.md` ("Mappatura script
+PowerShell → Python"), restano in PowerShell. Su Linux questo richiede
+**PowerShell Core (`pwsh`)**:
+
+```bash
+# Ubuntu / Mint LTS
+sudo apt-get update
+sudo apt-get install -y wget apt-transport-https software-properties-common
+wget -q https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb
+sudo dpkg -i packages-microsoft-prod.deb
+sudo apt-get update
+sudo apt-get install -y powershell
+pwsh --version    # verifica
+```
+
+Se preferisci non installare `pwsh`, porta `Invoke-RetentionPolicy.ps1` e
+`Backup-CITemplate.ps1` come sub-comandi `python -m ci_orchestrator
+retention run` / `template backup` (out of scope B5 per il piano corrente
+— vedi `plans/implementation-plan-A-B.md`).
+
+## Prerequisiti
+
+1. Utente di sistema `ci-runner` con UID dedicato (creato in B1).
+2. Venv Python attivo in `/opt/ci/venv/` con `ci_orchestrator` installato:
+   ```bash
+   sudo -u ci-runner /opt/ci/venv/bin/pip install -e /opt/ci/local-ci-cd-system
+   ```
+3. Variabili d'ambiente `CI_*` definite in `/etc/ci/environment` (caricato
+   tramite `EnvironmentFile=` in ogni unit `.service`):
+   ```
+   CI_ROOT=/var/lib/ci
+   CI_TEMPLATES=/var/lib/ci/templates
+   CI_BUILD_VMS=/var/lib/ci/build-vms
+   CI_ARTIFACTS=/var/lib/ci/artifacts
+   CI_KEYS=/etc/ci/keys
+   PYTHONIOENCODING=utf-8
+   ```
+4. `Invoke-RetentionPolicy.ps1` e `Backup-CITemplate.ps1` presenti in
+   `/opt/ci/local-ci-cd-system/scripts/` (clone del repo).
+
+## Installazione
+
+```bash
+# 1. Copia le unit in /etc/systemd/system/
+sudo cp deploy/systemd/ci-*.service deploy/systemd/ci-*.timer /etc/systemd/system/
+
+# 2. Reload systemd
+sudo systemctl daemon-reload
+
+# 3. Abilita + avvia tutti i timer
+for t in ci-cleanup-orphans ci-retention-policy ci-watch-disk-space \
+         ci-watch-runner-health ci-backup-template; do
+    sudo systemctl enable --now "${t}.timer"
+done
+
+# 4. Verifica
+systemctl list-timers --all 'ci-*'
+```
+
+## Test e troubleshooting
+
+```bash
+# Trigger manuale di un singolo task (esegue il .service una volta)
+sudo systemctl start ci-cleanup-orphans.service
+
+# Log dell'ultima esecuzione
+journalctl -u ci-cleanup-orphans.service -n 50 --no-pager
+
+# Live tail di tutti i task CI
+journalctl -u 'ci-*' -f
+```
+
+## Rollback
+
+```bash
+for t in ci-cleanup-orphans ci-retention-policy ci-watch-disk-space \
+         ci-watch-runner-health ci-backup-template; do
+    sudo systemctl disable --now "${t}.timer"
+    sudo rm -f "/etc/systemd/system/${t}.service" "/etc/systemd/system/${t}.timer"
+done
+sudo systemctl daemon-reload
+```
+
+A questo punto il fallback è ri-attivare i task su Windows con
+`scripts/Register-CIScheduledTasks.ps1`.

deploy/systemd/ci-backup-template.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=Local CI/CD — weekly backup of VMware templates
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+After=network-online.target
+
+[Service]
+Type=oneshot
+User=ci-runner
+Group=ci-runner
+EnvironmentFile=/etc/ci/environment
+WorkingDirectory=/opt/ci/local-ci-cd-system
+# NOTE: requires PowerShell Core (`pwsh`) on the Linux host.
+# See deploy/systemd/README.md "Nota PowerShell su Linux".
+ExecStart=/usr/bin/pwsh -NoProfile -NonInteractive -File scripts/Backup-CITemplate.ps1
+TimeoutStartSec=4h
+IOSchedulingClass=best-effort
+IOSchedulingPriority=7
+Nice=19
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/ci /var/backups/ci
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/ci-backup-template.timer

@@ -0,0 +1,13 @@
+[Unit]
+Description=Local CI/CD — weekly timer for ci-backup-template.service
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+
+[Timer]
+# Sunday 02:00 + random delay 1h to avoid clashing with other CI tasks.
+OnCalendar=Sun *-*-* 02:00:00
+RandomizedDelaySec=1h
+Persistent=true
+Unit=ci-backup-template.service
+
+[Install]
+WantedBy=timers.target

deploy/systemd/ci-cleanup-orphans.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=Local CI/CD — destroy orphaned build VMs (max age 6h)
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+User=ci-runner
+Group=ci-runner
+EnvironmentFile=/etc/ci/environment
+ExecStart=/opt/ci/venv/bin/python -m ci_orchestrator vm cleanup --max-age-hours 6
+TimeoutStartSec=1h
+Nice=10
+# Hardening
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/ci /var/log/ci
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/ci-cleanup-orphans.timer

@@ -0,0 +1,16 @@
+[Unit]
+Description=Local CI/CD — periodic timer for ci-cleanup-orphans.service
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+
+[Timer]
+# Equivalent to Windows Task Scheduler:
+#   New-ScheduledTaskTrigger -Once -At '00:00' -RepetitionInterval 6h
+#   New-ScheduledTaskTrigger -AtStartup
+OnBootSec=2min
+OnUnitActiveSec=6h
+Persistent=true
+AccuracySec=1min
+Unit=ci-cleanup-orphans.service
+
+[Install]
+WantedBy=timers.target

deploy/systemd/ci-retention-policy.service

@@ -0,0 +1,24 @@
+[Unit]
+Description=Local CI/CD — purge old artifacts/logs/IP leases (retention policy)
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+After=network-online.target
+
+[Service]
+Type=oneshot
+User=ci-runner
+Group=ci-runner
+EnvironmentFile=/etc/ci/environment
+WorkingDirectory=/opt/ci/local-ci-cd-system
+# NOTE: requires PowerShell Core (`pwsh`) on the Linux host.
+# See deploy/systemd/README.md "Nota PowerShell su Linux".
+ExecStart=/usr/bin/pwsh -NoProfile -NonInteractive -File scripts/Invoke-RetentionPolicy.ps1
+TimeoutStartSec=1h
+Nice=15
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/ci /var/log/ci
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/ci-retention-policy.timer

@@ -0,0 +1,14 @@
+[Unit]
+Description=Local CI/CD — daily timer for ci-retention-policy.service
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+
+[Timer]
+# Equivalent to Windows Task Scheduler:
+#   New-ScheduledTaskTrigger -Daily -At '03:00' -RandomDelay 30min
+OnCalendar=*-*-* 03:00:00
+RandomizedDelaySec=30min
+Persistent=true
+Unit=ci-retention-policy.service
+
+[Install]
+WantedBy=timers.target

deploy/systemd/ci-watch-disk-space.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Local CI/CD — disk space monitor (alert via systemd journal)
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+After=network-online.target
+
+[Service]
+Type=oneshot
+User=ci-runner
+Group=ci-runner
+EnvironmentFile=/etc/ci/environment
+ExecStart=/opt/ci/venv/bin/python -m ci_orchestrator monitor disk
+TimeoutStartSec=5min
+Nice=15
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/ci-watch-disk-space.timer

@@ -0,0 +1,15 @@
+[Unit]
+Description=Local CI/CD — periodic timer for ci-watch-disk-space.service
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+
+[Timer]
+# Equivalent to Windows Task Scheduler:
+#   New-ScheduledTaskTrigger -Once -At '00:00' -RepetitionInterval 15min
+OnBootSec=5min
+OnUnitActiveSec=15min
+Persistent=true
+AccuracySec=30s
+Unit=ci-watch-disk-space.service
+
+[Install]
+WantedBy=timers.target

deploy/systemd/ci-watch-runner-health.service

@@ -0,0 +1,24 @@
+[Unit]
+Description=Local CI/CD — auto-restart act_runner if stopped (rate-limited)
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+After=network-online.target act-runner.service
+
+[Service]
+Type=oneshot
+User=ci-runner
+Group=ci-runner
+EnvironmentFile=/etc/ci/environment
+# `monitor runner` enforces internal rate-limit: max 3 restarts/h
+# (matches Windows CI-RunnerHealth scheduled task semantics).
+ExecStart=/opt/ci/venv/bin/python -m ci_orchestrator monitor runner
+TimeoutStartSec=5min
+Nice=15
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+# NoNewPrivileges intentionally NOT set: monitor may need to call
+# `systemctl restart act-runner.service` via polkit.
+ReadWritePaths=/var/lib/ci /var/log/ci
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/ci-watch-runner-health.timer

@@ -0,0 +1,15 @@
+[Unit]
+Description=Local CI/CD — periodic timer for ci-watch-runner-health.service
+Documentation=file:///opt/ci/local-ci-cd-system/deploy/systemd/README.md
+
+[Timer]
+# Equivalent to Windows Task Scheduler:
+#   New-ScheduledTaskTrigger -Once -At '00:00' -RepetitionInterval 15min
+OnBootSec=3min
+OnUnitActiveSec=15min
+Persistent=true
+AccuracySec=30s
+Unit=ci-watch-runner-health.service
+
+[Install]
+WantedBy=timers.target

docs/ARCHITECTURE.md

@@ -6,8 +6,9 @@ A fully local, isolated CI/CD pipeline running on a Windows host using:
 - **Gitea** as the self-hosted Git server + CI platform
 - **act_runner** as the job executor (runs on the Windows host)
 - **VMware Workstation** for ephemeral build VMs (linked clones)
-- **WinRM / PowerShell Remoting** for communication with build VMs
-- **MSBuild / dotnet CLI** executing inside the guest VM only
+- **WinRM / PowerShell Remoting** for communication with Windows build VMs
+- **SSH / SCP** (`ssh.exe` + `scp.exe`) for communication with Linux build VMs
+- **MSBuild / dotnet CLI** (Windows) and **GCC / Clang / CMake** (Linux) executing inside guest VMs only
 
 The runner host **never executes build tools directly**. Its only role is orchestration: creating, driving, and destroying VMs.
 
@@ -38,10 +39,11 @@ The runner host **never executes build tools directly**. Its only role is orches
 │  │  Orchestrator Scripts (PowerShell)                                │  │
 │  │                                                                   │  │
 │  │  New-BuildVM.ps1 ──► vmrun.exe (linked clone from template)       │  │
-│  │  Wait-VMReady.ps1 ─► Test-WSMan poll loop                         │  │
-│  │  Invoke-RemoteBuild.ps1 ► PSSession + Invoke-Command              │  │
-│  │  Get-BuildArtifacts.ps1 ► Copy-Item -FromSession                  │  │
-│  │  Remove-BuildVM.ps1 ───► vmrun stop + deleteVM                    │  │
+  │  Wait-VMReady.ps1 ─► WinRM poll (Windows) / SSH poll (Linux)      │  │
+  │  Invoke-RemoteBuild.ps1 ► PSSession (Windows) / SSH+SCP (Linux)   │  │
+  │  Get-BuildArtifacts.ps1 ► Copy-Item -FromSession / scp (Linux)    │  │
+  │  Remove-BuildVM.ps1 ───► vmrun stop + deleteVM                    │  │
+  │  _Transport.psm1 ──────► Invoke-SshCommand / Copy-SshItem         │  │
 │  └───────────────────────────────┬───────────────────────────────────┘  │
 │                                  │  vmrun.exe (VMware CLI)              │
 │                                  ▼                                      │
@@ -53,7 +55,7 @@ The runner host **never executes build tools directly**. Its only role is orches
 │  │                                      ├── Clone_Job_002.vmx        │  │
 │  │                                      └── Clone_Job_003.vmx        │  │
 │  └───────────────────────────────────────────────────────────────────┘  │
-│                                  │  WinRM :5985 (192.168.79.0/24 NAT)   │
+│                                  │  WinRM :5986 HTTPS (192.168.79.0/24 NAT) │
 └──────────────────────────────────┼──────────────────────────────────────┘
                                    │
           ┌────────────────────────┼──────────────────────────┐
@@ -103,21 +105,29 @@ The runner host **never executes build tools directly**. Its only role is orches
   - Disk footprint: ~2–5 GB per clone (vs 40–80 GB for full clone)
   - Tradeoff: template snapshot must remain intact
 
-### WinRM / PowerShell Remoting
-- Default transport for remote build execution inside VMs
-- Port: **5985** (HTTP, in-lab use); migrate to 5986/HTTPS for hardened setups
-- Authentication: **Basic** (unencrypted — acceptable for isolated lab)
+### WinRM / PowerShell Remoting (Windows VMs)
+- Transport for remote build execution inside **Windows** build VMs
+- Port: **5986** (HTTPS, self-signed cert, `AllowUnencrypted=false`)
+- Authentication: **Basic over HTTPS** (`-SkipCACheck` for lab self-signed cert)
 - Used for:
   - Transferring source: `Compress-Archive` on host → WinRM copy → `Expand-Archive` in guest
   - Running build commands (`Invoke-Command`)
   - Packaging artifacts (`Compress-Archive` in guest) and collecting via `Copy-Item -FromSession`
 
+### SSH / SCP Transport (Linux VMs)
+- Transport for remote build execution inside **Linux** build VMs
+- Port: **22** (key-based auth, ed25519 key `F:\CI\keys\ci_linux`, user `ci_build`)
+- No password — `BatchMode=yes`, `StrictHostKeyChecking=accept-new`
+- Implemented in `scripts/_Transport.psm1` (exported: `Invoke-SshCommand`, `Copy-SshItem`, `Test-SshReady`)
+- Used by `Wait-VMReady.ps1 -Transport SSH`, `Invoke-RemoteBuild.ps1 -GuestOS Linux`, `Get-BuildArtifacts.ps1 -GuestOS Linux`
+- Selected automatically when `Invoke-CIJob.ps1` detects `guestOS = ubuntu-64` in the cloned VMX
+
 ### Build Toolchain (inside VM only)
 - Visual Studio Build Tools **2026** (MSBuild 18.5.4 / toolset v145)
 - .NET SDK **10.0.203**
 - Python **3.13.3** (per build script personalizzati come `build_plugin.py`)
 - NuGet CLI (optional, dotnet restore covers most cases)
-- Git: NOT installed by default — source arrives via WinRM zip transfer. See TODO.md `-UseGitClone` for the in-VM git clone opt-in path.
+- **Git for Windows 2.54** + **7-Zip 26.01** (Tier-1 toolchain, §6.6 — DONE 2026-05-10): consente l'opt-in `-UseGitClone` di `Invoke-CIJob.ps1` per clonare il repository direttamente in VM (skip host zip transfer, e2e PASS, -25.7% durata pipeline).
 
 ---
 
@@ -133,8 +143,9 @@ Build VMs:
   ...
   Clone_Job_N   → 192.168.79.1xx
 
-WinRM port 5985 (HTTP) on each VM IP.
-VMs have internet access via NAT — required for pip/nuget during build.
+WinRM port 5986 (HTTPS, self-signed) on each Windows VM IP.
+SSH port 22 on each Linux VM IP (key-based, ci_build@<ip>, key: F:\CI\keys\ci_linux).
+VMs have internet access via NAT — required for pip/nuget/apt during build.
 ```
 
 > **Note:** VMnet8 NAT gives VMs internet access. The host detects the VM IP via
@@ -157,7 +168,8 @@ VMs have internet access via NAT — required for pip/nuget during build.
    Duration: ~20–40 seconds boot                    │
                                                     │
 4. READINESS CHECK                                  │
-   Poll: getState=running → ping → Test-WSMan       │
+   Windows: getState=running → ping → Test-WSMan    │
+   Linux:   getState=running → TCP:22 → ssh echo    │
    Duration: ~30–90 seconds total                   │
                                                     │
 5. BUILD                                            │
@@ -191,4 +203,119 @@ VMs have internet access via NAT — required for pip/nuget during build.
 - WinRM credentials are stored in Windows Credential Manager on host (not hardcoded)
 - Each VM is fully destroyed after the job — no state carries between builds
 - Runner host does not expose any ports to the build VM network
-- Source code is transferred via zip (Compress-Archive → WinRM copy → Expand-Archive in guest) — no PAT is ever present inside the VM; VMs have NAT internet for pip/nuget at build time
+- Source code is transferred via zip (Compress-Archive → WinRM copy → Expand-Archive in guest) by default — no PAT is ever present inside the VM; VMs have NAT internet for pip/nuget at build time.
+- With `-UseGitClone` (§3.3, opt-in) il clone avviene dentro la VM via SSH alias `gitea-ci` (forwardato dall'host); la chiave privata SSH dell'host non viene esposta al guest — vedi BEST-PRACTICES.md per il threat model.
+- Linux build VMs usano la chiave SSH `F:\CI\keys\ci_linux` (ed25519, no passphrase), archiviata solo sull'host. Il guest non conosce credenziali WinRM.
+
+---
+
+## Python orchestrator (Phase A)
+
+Phase A of [implementation-plan-A-B](../plans/implementation-plan-A-B.md)
+replaces the PowerShell orchestration scripts with a Python 3.11+ package
+under `src/ci_orchestrator/`. The PS scripts in `scripts/` are now thin
+3-line shims that forward to the Python CLI — the diagram above still
+applies, except that the boxes labelled `*.ps1` are entry-point names,
+not the implementation.
+
+### Package layout
+
+```
+src/ci_orchestrator/
+├── __init__.py
+├── __main__.py                # click entry point: `python -m ci_orchestrator`
+├── config.py                  # Config dataclass + env/TOML loader (OS-aware paths)
+├── credentials.py             # CredentialStore Protocol + KeyringCredentialStore
+│
+├── backends/
+│   ├── __init__.py            # load_backend(config) factory (selector for Phase C)
+│   ├── protocol.py            # VmBackend Protocol + VmHandle dataclass + VmState enum
+│   ├── workstation.py         # WorkstationVmrunBackend (subprocess + vmrun -T ws)
+│   └── errors.py              # BackendError / BackendNotAvailable / BackendOperationFailed
+│
+├── transport/
+│   ├── __init__.py
+│   ├── winrm.py               # WinRM transport via pypsrp (replaces New-PSSession)
+│   ├── ssh.py                 # SSH/SFTP transport via paramiko (replaces ssh.exe/scp.exe)
+│   └── errors.py              # TransportConnectError / TransportCommandError
+│
+└── commands/                  # One module per `click` sub-command group
+    ├── wait.py                # `wait-ready`
+    ├── vm.py                  # `vm new` / `vm remove` / `vm cleanup`
+    ├── build.py               # `build run`
+    ├── artifacts.py           # `artifacts collect`
+    ├── monitor.py             # `monitor disk` / `monitor runner`
+    ├── report.py              # `report job`
+    └── job.py                 # `job` — full end-to-end orchestrator
+```
+
+### `VmBackend` Protocol and the `load_backend(config)` factory
+
+`backends/protocol.py` defines a hypervisor-agnostic Protocol:
+
+```python
+class VmBackend(Protocol):
+    def clone_linked(self, template, snapshot, name, destination=None) -> VmHandle: ...
+    def start(self, handle, headless=True) -> None: ...
+    def stop(self, handle, hard=False) -> None: ...
+    def delete(self, handle) -> None: ...
+    def get_ip(self, handle, timeout=0.0) -> str | None: ...
+    def list_snapshots(self, handle) -> list[str]: ...
+    def is_running(self, handle) -> bool: ...
+```
+
+Names are deliberately neutral (no `vmrun_*` prefixes) and identifiers are
+opaque strings (`VmHandle.identifier`): a VMX path on Workstation, a
+managed object reference on ESXi. `is_running` MUST NOT use guest tools
+(see `AGENTS.md` error #10).
+
+Backends are constructed via `backends.load_backend(config)`. Application
+code (most importantly `commands/job.py`) imports the factory only — never
+`WorkstationVmrunBackend` directly. The factory reads
+`config.backend.type` from `config.toml` (default: `"workstation"`).
+
+### Phase C extension point — adding ESXi without forks
+
+To add an ESXi backend in a future Phase C:
+
+1. Add a new module `backends/esxi.py` implementing the `VmBackend`
+   Protocol via `pyVmomi`. `VmHandle.identifier` becomes the managed
+   object reference; `clone_linked` becomes a `CloneVM_Task` call;
+   `start` becomes `PowerOnVM_Task`.
+2. Register it in `backends/__init__.py` `load_backend(config)` under a
+   new `config.backend.type == "esxi"` branch.
+3. Add `[backend]` keys to `config.example.toml` (host, user, datacenter,
+   datastore, …). The `Config` dataclass already namespaces backend
+   options under `config.backend`.
+4. Transport layers (`winrm.py`, `ssh.py`) and the `commands/*` modules
+   need no change — they consume `VmBackend` and `VmHandle` only.
+
+The single non-trivial constraint is that `commands/vm.py` `vm new`
+currently builds the destination VMX path under `--clone-base-dir` (a
+host-local concept). For ESXi this becomes a datastore folder; the
+parameter rename can be deferred to Phase C as long as the backend
+ignores the value and uses `config.backend.datastore` instead.
+
+### Transport selection
+
+`commands/job.py` auto-detects the guest OS by parsing `guestOS = "..."`
+in the cloned VMX (`ubuntu-*` → Linux/SSH, anything else → Windows/WinRM).
+The Linux branch is wired to `transport/ssh.py` (paramiko) and the
+Windows branch to `transport/winrm.py` (pypsrp). Both transports raise
+typed errors (`TransportConnectError`, `TransportCommandError`) — never
+bare exceptions.
+
+### Validation gates (CI)
+
+Enforced by `gitea/workflows/lint.yml` job `python`:
+
+```powershell
+python -m ruff check src tests\python
+python -m mypy --strict src
+python -m pytest tests\python -q --cov=ci_orchestrator --cov-fail-under=90
+```
+
+Coverage gate is **90%**. Regression tests for
+`AGENTS.md` errors #9–#12 live in
+[tests/python/test_agents_errors.py](../tests/python/test_agents_errors.py).
+

docs/BEST-PRACTICES.md

@@ -4,73 +4,158 @@
 
 ### Do NOT store credentials in scripts or config files
 
-The scripts use `-GuestCredentialTarget` (a Windows Credential Manager target name)
-rather than plaintext username/password parameters. Store credentials once:
+The guest VM credential is referenced by target name (`BuildVMGuest`,
+`GITEA_CI_GUEST_CRED_TARGET`) and read by the Python orchestrator via the
+`keyring` library — never as plaintext parameters.
+
+> **Critical: store it in the LocalSystem vault, not your user vault.**
+> act_runner runs as the `LocalSystem` service account. Windows Credential
+> Manager / keyring vaults are **per-user**. A credential added with
+> `cmdkey` or the Credential Manager UI from an interactive admin session
+> lands in *your* vault and is invisible to the runner, which then fails
+> with `Credential 'BuildVMGuest' not found in keyring`.
+
+> **Username must be host-qualified.** The guest is a workgroup machine;
+> NTLM rejects a bare `ci_build` with `SEC_E_UNKNOWN_CREDENTIALS`. Store
+> it as `WINBUILD-2025\ci_build` (the guest computer name, i.e. the WinRM
+> TLS certificate CN). The WinRM transport forces `auth='ntlm'` for the
+> same reason (Negotiate→Kerberos is meaningless without a domain).
+
+Store (or rotate) the credential with the helper, which writes into the
+SYSTEM vault via the production venv's `keyring` (run elevated):
 
 ```powershell
-# Run on host (once, before first CI job)
-cmdkey /generic:BuildVMGuest /user:MACHINENAME\ci_build /pass:YourStrongPassword
+.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'
 ```
 
-Retrieve in scripts via the `CredentialManager` PowerShell module:
-
-```powershell
-Install-Module CredentialManager -Scope CurrentUser
-$cred = Get-StoredCredential -Target 'BuildVMGuest'
-```
+It prompts for the password securely, writes it to the SYSTEM vault, and
+verifies the read-back as SYSTEM. Diagnose WinRM reachability/auth with
+`.\scripts\Test-CIGuestWinRM.ps1 -IpAddress <guest-ip>`.
 
 ### Rotate credentials quarterly
 
-1. Update password in the template VM (requires rebuilding `BaseClean` snapshot)
-2. Update Windows Credential Manager on the host:
-   ```
-   cmdkey /generic:BuildVMGuest /user:MACHINENAME\ci_build /pass:NewPassword
-   ```
-3. No script changes required — they reference the target name, not the password.
+1. Update the password in the template VM (rebuild the `BaseClean` snapshot).
+2. Re-run `Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'`
+   with the new password.
+3. No code changes required — the orchestrator references the target name.
 
 ---
 
-## 2. WinRM Security
+## 2. WinRM Security — HTTPS/5986 (implementato 2026-05-10)
 
-### Current setup (HTTP / port 5985)
+### Setup attuale (HTTPS / port 5986)
 
-Acceptable for an **isolated lab network** where:
-- Build VMs sono su VMnet8 NAT (192.168.79.0/24) — raggiungibili dall'host, internet via NAT
-- No external traffic reaches port 5985
-- Credentials are managed via Windows Credential Manager
+`Deploy-WinBuild2025.ps1` post-install.ps1 crea un certificato self-signed e configura
+il listener HTTPS/5986 **prima** dello snapshot `BaseClean`. `AllowUnencrypted=false`.
 
-### Recommended upgrade: WinRM over HTTPS (port 5986)
+- Build VMs su VMnet8 NAT (192.168.79.0/24) — accesso solo dall'host
+- Port 5986 firewall rule ristretta a `RemoteAddress '192.168.79.0/24'`
+- Credentials via Windows Credential Manager (target `BuildVMGuest`)
 
+Tutti gli script host usano:
 ```powershell
-# Inside the template VM (before taking BaseClean snapshot):
-
-# Create self-signed certificate
-$cert = New-SelfSignedCertificate `
-    -Subject    "CN=$(hostname)" `
-    -CertStoreLocation Cert:\LocalMachine\My `
-    -KeyUsage   DigitalSignature, KeyEncipherment `
-    -KeyAlgorithm RSA `
-    -KeyLength  2048
-
-# Create HTTPS WinRM listener
-New-WSManInstance WinRM/Config/Listener `
-    -SelectorSet @{ Transport = 'HTTPS'; Address = '*' } `
-    -ValueSet    @{ Hostname = $(hostname); CertificateThumbprint = $cert.Thumbprint }
-
-# Allow port 5986
-New-NetFirewallRule -Name 'WinRM-HTTPS-CI' -DisplayName 'WinRM HTTPS CI' `
-    -Direction Inbound -Protocol TCP -LocalPort 5986 -Action Allow
-```
-
-```powershell
-# On the HOST (in scripts), use HTTPS session options:
 $sessionOptions = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
-$session = New-PSSession -ComputerName $ip -Port 5986 -UseSSL `
+$session = New-PSSession -ComputerName $ip -Port 5986 -UseSSL -Authentication Basic `
     -Credential $cred -SessionOption $sessionOptions
 ```
 
-> `-SkipCACheck` is acceptable for a self-signed cert in an isolated lab. Do NOT
-> use this against externally accessible machines.
+> `-SkipCACheck`/`-SkipCNCheck` sono accettabili per un cert self-signed in lab isolato.
+> Non usare contro macchine accessibili dall'esterno — usare una CA trusted in quel caso.
+
+---
+
+## 2.1. Threat Model — Disabled Security Features
+
+### Current state: Defender, Firewall, and UAC disabled
+
+The template VM disables Windows Defender, Windows Firewall, and User Account Control (UAC).
+This is **intentional** — not a bug, not an oversight. Each has tradeoffs:
+
+| Feature                                 | Disabled? | Why                                                                            | Cost if enabled                                                                        |
+| --------------------------------------- | --------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| **Windows Defender**                    | Yes       | Real-time AV scanning blocks .NET compilation, Python wheels, and npm installs | 5–10 min per build overhead; false positives on dev tools                              |
+| **Windows Firewall**                    | Yes       | Blocks inbound WinRM even with rules; requires Domain/Home profile tuning      | Complex rules; fragile across OS updates                                               |
+| **UAC (LocalAccountTokenFilterPolicy)** | Yes       | Prevents non-elevated WinRM scripts from running builds                        | Requires built-in Administrator account; WinRM behaves like a user with limited rights |
+
+### When this threat model is acceptable
+
+Current threat model is **safe** if **ALL** of these are true:
+
+1. **Isolated lab environment** — Build VMs exist only on VMnet8 (NAT), not on host LAN.
+2. **No shared resources** — Host is not shared with untrusted users or concurrent CI systems.
+3. **Trusted source code** — Code being built is from trusted repositories (internal team only).
+4. **No external access** — VMnet8 is not bridged or exposed to corporate LAN or internet.
+5. **Act_runner is trusted** — The act_runner service token cannot be used to access host resources outside the isolated network.
+
+If all conditions hold, the attack surface is limited to:
+- Network eavesdropping on 192.168.79.0/24 (mitigated: WinRM is HTTPS)
+- Code injection via malicious commits (mitigated: code review process)
+- Privilege escalation from VM to host (mitigated: VMs are ephemeral; no persistence)
+
+### When the model breaks down
+
+**Do NOT use this configuration if:**
+
+- ❌ **Third-party code builds** — Running untrusted vendor code (open-source projects, third-party libraries with build scripts)
+- ❌ **Shared build machine** — Other teams or processes share the host CPU/storage
+- ❌ **LAN-exposed network** — VMnet8 is bridged to corporate LAN or internet
+- ❌ **Host resource sharing** — Build VMs can access host shares, USB drives, or external storage
+- ❌ **Long-lived VMs** — VMs are not destroyed after each build (antivirus blind spot for persistence)
+
+In these scenarios, disabled AV and firewall create **unacceptable risk**.
+
+### Mitigations if constraints change
+
+If you must run in a less-isolated environment, re-enable protections **with cost awareness**:
+
+#### Option 1: Re-enable Firewall only (lowest cost)
+```powershell
+# In template VM via WinRM, before taking BaseClean snapshot:
+Set-NetFirewallProfile -Profile Domain, Public, Private -Enabled $true
+# Add inbound rule for WinRM listener
+New-NetFirewallRule -Name "WinRM-HTTPS" `
+    -DisplayName "Windows Remote Management (HTTPS)" `
+    -Direction Inbound `
+    -LocalPort 5986 `
+    -Protocol TCP `
+    -Action Allow
+```
+**Cost:** 30–60 seconds per build (firewall rule evaluation + logging).  
+**Benefit:** Blocks outbound malware callbacks if VM is compromised.
+
+#### Option 2: Re-enable Defender with exclusions (moderate cost)
+```powershell
+# In template VM, enable Defender but exclude build directories:
+Enable-MpComputerDefault   # Re-enable Defender
+Add-MpPreference -ExclusionPath @(
+    'C:\Build',
+    'C:\Users\ci_build\AppData\Local\Microsoft\dotnet',
+    'C:\Users\ci_build\AppData\Roaming\npm'
+) -Force
+# Reduce scanning aggressiveness:
+Set-MpPreference -DisableRealtimeMonitoring $false -DisableBehaviorMonitoring $true
+```
+**Cost:** 2–5 min per build (initial scan; exclusions help but don't eliminate overhead).  
+**Benefit:** Detects known malware uploaded in build artifacts.
+
+#### Option 3: Enable UAC for elevated builds only (requires refactor)
+```powershell
+# NOT RECOMMENDED without major refactoring.
+# WinRM remote commands run as non-elevated user; builds fail.
+# Requires either:
+#   - Running WinRM as built-in Administrator (security anti-pattern)
+#   - Adding explicit runas prompts (breaks automation)
+#   - Using Windows Task Scheduler instead of WinRM (complexity)
+```
+
+### Audit and sign-off
+
+Before deploying to production or a shared host:
+
+1. **Document the decision:** Update this section with current date and approver name.
+2. **Test the mitigations:** Create test clone, enable firewall/AV, measure build time overhead.
+3. **Establish monitoring:** Run Watch-RunnerHealth.ps1 continuously; alert on service restarts.
+4. **Plan rotation:** Schedule quarterly credential rotation (see §1 Credential Management).
 
 ---
 
@@ -251,7 +336,7 @@ Invoke-Command -Session $session -ScriptBlock {
 ```
 
 Build VMs can reach:
-- The host via VMnet8 gateway (WinRM on port 5985)
+- The host via VMnet8 gateway (WinRM HTTPS on port 5986)
 - Internet via VMware NAT (for pip, nuget, npm at build time)
 - Gitea server if on LAN reachable via NAT gateway
 
@@ -283,3 +368,95 @@ When a new .NET SDK or VS Build Tools version is released:
 6. Take new snapshot: `BaseClean_$(Get-Date -Format yyyyMMdd)`
 7. Update `SnapshotName` in `runner/config.yaml`
 8. Delete the old snapshot after confirming new one works for 1 week
+
+---
+
+## 10. SHA256 Pinning for Tier-1 Toolchain Installers
+
+**Homelab policy**: partial-coverage pinning is acceptable. Pin only the installers
+that are re-downloaded as part of template provisioning (not installers already
+cached in the ISO or in `F:\CI\ISO\`).
+
+Priority targets (descending risk):
+
+| Installer               | Script                                          | Where to pin                                           |
+| ----------------------- | ----------------------------------------------- | ------------------------------------------------------ |
+| Git for Windows `.exe`  | `template/Install-CIToolchain-WinBuild2025.ps1` | `-sha256` param or `Get-FileHash` check after download |
+| 7-Zip `.msi` / `.exe`   | `template/Install-CIToolchain-WinBuild2025.ps1` | same                                                   |
+| Python `.exe`           | `template/Install-CIToolchain-WinBuild2025.ps1` | same                                                   |
+| .NET SDK install script | `template/Install-CIToolchain-WinBuild2025.ps1` | HTTPS only; hash less critical                         |
+| Ubuntu cloud VMDK       | `template/Deploy-LinuxBuild2404.ps1`            | already implemented via `-VmdkSha256` parameter        |
+
+**Implementation pattern** (PS 5.1):
+
+```powershell
+# After downloading $installerPath:
+if ($ExpectedSha256 -ne '') {
+    $actual = (Get-FileHash -Path $installerPath -Algorithm SHA256).Hash
+    if ($actual -ne $ExpectedSha256.ToUpper()) {
+        throw "SHA256 mismatch for $installerPath.`n  Expected: $ExpectedSha256`n  Actual:   $actual"
+    }
+    Write-Host "[Install] SHA256 OK: $installerPath"
+}
+```
+
+Pin values must be updated each time a new installer version is adopted.
+Store the expected hash in the script's parameter default or in a companion
+`.sha256` sidecar file next to the cached installer in `F:\CI\ISO\`.
+
+---
+
+## 11. VMware Shared Folders (HGFS) — Write Semantics and Cache-Poisoning Risk
+
+### What UseSharedCache does
+
+When `Invoke-CIJob.ps1 -UseSharedCache` is set, the composite action enables
+VMware shared folders on the clone VM. The host-side folders (NuGet, pip) are
+mounted read-write inside the guest:
+
+| Host path              | Guest path (Windows)             | Guest path (Linux)        |
+| ---------------------- | -------------------------------- | ------------------------- |
+| `F:\CI\Cache\NuGet`    | `\\vmware-host\Shared Folders\ci-nuget-cache` | `/mnt/hgfs/ci-nuget-cache` |
+| `F:\CI\Cache\pip`      | `\\vmware-host\Shared Folders\ci-pip-cache`   | `/mnt/hgfs/ci-pip-cache`  |
+
+The guest build command reads from (and writes to) these folders directly. This
+avoids re-downloading packages on every build at the cost of shared state.
+
+### Write semantics — what you must understand
+
+**Writes from any guest are immediately visible on the host and in any other
+concurrently running guest that has the same shared folder mounted.**
+
+Consequences:
+1. A compromised or malicious build script can overwrite packages in the cache.
+   The next build that pulls from the same cache will use the poisoned package.
+2. Two concurrent builds writing to the same cache entry (e.g. the same pip
+   wheel filename) will corrupt each other. NuGet and pip use hash-verified
+   filenames so collisions are rare, but not impossible for mutable packages.
+3. Host-side antivirus exclusions for `F:\CI\Cache\` must be maintained if AV
+   is re-enabled (see section 2.1 Threat Model).
+
+### Safe-use rules
+
+- Use `UseSharedCache` **only** for trusted source code (internal team repos).
+  Do NOT enable for workflows that build third-party or unknown code.
+- Treat cache poisoning as a real threat if any of the following is true:
+  - The built repo has external contributors
+  - The repo has `git submodule` paths pointing to external forks
+  - The build script runs `pip install` / `nuget restore` with unpinned versions
+- When in doubt, omit `-UseSharedCache` (the default). Package downloads add
+  1-3 minutes per build but eliminate the shared-state risk entirely.
+
+### Cache invalidation
+
+There is no automatic cache invalidation. To force a clean state:
+```powershell
+# Remove all cached NuGet packages
+Remove-Item 'F:\CI\Cache\NuGet\*' -Recurse -Force
+
+# Remove all cached pip wheels
+Remove-Item 'F:\CI\Cache\pip\*' -Recurse -Force
+```
+
+After any template toolchain upgrade, clear the cache to avoid stale package
+metadata. The next build repopulates it.

docs/CHANGELOG.md

@@ -0,0 +1,151 @@
+# CHANGELOG — Local CI/CD System
+
+Completed sprint work, in reverse-chronological order.
+Open backlog items remain in [TODO.md](../TODO.md).
+
+---
+
+## 2026-05-13 — Sprint 16: Medium/Low hardening (final-master-plan)
+
+- **Watch-DiskSpace.ps1**: Event Log source renamed `CI-DiskAlert` → `CI-DiskSpaceAlert`
+  (aligned with task name registered by `Register-CIScheduledTasks.ps1`).
+- **Watch-RunnerHealth.ps1**: maintenance flag support — if `F:\CI\State\runner-maintenance.flag`
+  exists, restart logic is skipped entirely.
+- **Invoke-CIJob.ps1**:
+  - New `WebhookUrl` parameter (default `''`).
+  - `TemplatePath` sanity check: `Write-Warning` if not under `F:\CI\Templates\`.
+  - 90-minute duration warning: `Start-Job` fires `[WARNING]` webhook after 5400 s; cancelled
+    in `finally` if the build completes first.
+- **BEST-PRACTICES.md** section 11: VMware HGFS shared folder write semantics, cache-poisoning
+  risk model, safe-use rules for `UseSharedCache`, and cache invalidation procedure.
+- **Validate-HostState.ps1** (new): checks SSH key ACLs, Credential Manager target
+  accessibility, CI directory structure, and vmrun.exe availability.
+- **Validate-SetupState.ps1** docblock: `HTTP/Basic` → `HTTPS/Basic, port 5986`.
+- **TEST-PLAN-v1.3-to-HEAD.md** §3.6: benchmark JSONL field names corrected to match actual
+  script output (`cloneSec`, `startSec`, `ipSec`, `winrmSec`, `destroySec`, `totalBootSec`).
+- **CI-FLOW.md** failure table: "collects partial artifacts" replaced with accurate description
+  of `Get-GuestDiagnostics` post-failure collection.
+- **final-master-plan.md**: all Medium and most Low items marked done.
+
+---
+
+## 2026-05-12 — Sprint 15b: Hardcoded path fix
+
+- **action.yml** + **runner/config.yaml**: replaced hardcoded `N:\Code\...` script path with
+  `GITEA_CI_SCRIPT_ROOT` env var injected by the runner. act_runner restarted with labels
+  `windows-build:host dotnet:host msbuild:host linux-build:host`.
+
+---
+
+## 2026-05-11 — Sprint 15: Rename Setup-* → Install-CIToolchain-*
+
+Renamed three guest-side provisioning scripts and updated all references across 14 files:
+
+| Old name                                 | New name                                       |
+| ---------------------------------------- | ---------------------------------------------- |
+| `template/Setup-WinBuild2025.ps1`        | `template/Install-CIToolchain-WinBuild2025.ps1` |
+| `template/Setup-WinBuild2022.ps1`        | `template/Install-CIToolchain-WinBuild2022.ps1` |
+| `template/Setup-LinuxBuild2404.sh`       | `template/Install-CIToolchain-Linux2404.sh`     |
+
+References updated in: Prepare-WinBuild2025/2022.ps1, Prepare-LinuxBuild2404.ps1,
+Deploy-WinBuild2025/2022.ps1, Deploy-LinuxBuild2404.ps1, README.md, TODO.md,
+docs/WINDOWS-TEMPLATE-SETUP.md, docs/LINUX-TEMPLATE-SETUP.md,
+docs/TEST-PLAN-v1.3-to-HEAD.md, gitea/actions/local-ci-build/action.yml.
+
+---
+
+## 2026-05-11 — Sprint 14: §6.4 Build matrix + §6.5 Secret injection
+
+**§6.4** — `build-ns7zip.yml` rewritten with matrix strategy `target: [windows, linux]`.
+Separate artifact dirs; `fail-fast: false`; composite action used for both targets.
+
+**§6.5** — `ExtraGuestEnv [hashtable]` added to `Invoke-CIJob.ps1` and `Invoke-RemoteBuild.ps1`:
+- Windows: `[System.Environment]::SetEnvironmentVariable` in session ScriptBlock.
+- Linux: `export KEY='val'; ` prefix before build command.
+- `action.yml`: `extra-guest-env-json` input (JSON object), never logged.
+
+---
+
+## 2026-05-11 — Sprint 13: §6.2 Composite Action
+
+**action.yml** (`gitea/actions/local-ci-build/action.yml`) fully implemented.
+Inputs: `build-command`, `artifact-source`, `submodules`, `guest-os`, `use-git-clone`,
+`configuration`, `template-path`, `snapshot-name`, `artifact-name`, `artifact-retention-days`,
+`extra-guest-env-json`, `use-shared-cache`, `job-id-suffix`, `repo-url`, `webhook-url`.
+Outputs: `artifact-path`, `artifact-name`.
+Artifact upload included; no orchestration logic required in calling repos.
+
+---
+
+## 2026-05-10 — Sprint 12: §6.1 Linux Build VM
+
+End-to-end Linux build pipeline implemented:
+- `Deploy-LinuxBuild2404.ps1`: Ubuntu 24.04 cloud image deployment via VMware vmrun.
+- `Prepare-LinuxBuild2404.ps1`: SSH key injection, CI dirs, IP reporting service.
+- `Install-CIToolchain-Linux2404.sh`: GCC, G++, Clang, CMake, Ninja, Python 3, Git, 7-Zip.
+- `scripts/_Transport.psm1`: `Invoke-SshCommand`, `Copy-SshItem`, `Test-SshReady` with
+  `StrictHostKeyChecking` and `KnownHostsFile` parametrisation.
+- E2E verified: `nsis7z.dll` 2272 KB on parity with Windows build.
+
+---
+
+## 2026-05-10 — Sprint 11: §6.6 Tier-2 Toolchain (WinBuild2025)
+
+Tier-1 (Step 11) and Tier-2 (Step 12) added to `Install-CIToolchain-WinBuild2025.ps1`:
+
+| Tool             | Version          |
+| ---------------- | ---------------- |
+| Git for Windows  | 2.54.0.windows.1 |
+| 7-Zip            | 26.01            |
+| PowerShell 7     | 7.6.1            |
+| NSIS             | 3.12             |
+| gh CLI           | 2.92.0           |
+| CMake            | 3.31.6           |
+| Node.js LTS      | 22.14.0          |
+| WiX Toolset      | 4.0.5            |
+| Sysinternals     | latest           |
+| vcpkg            | HEAD             |
+
+All tools hash-pinned (SHA256), path-extended machine-wide, validated via `where.exe` in
+`Assert-Step` final gate.
+
+---
+
+## 2026-05-10 — Sprint 10: §7 Refactor Deploy ↔ Setup
+
+Separated OS hardening (Deploy responsibility) from CI toolchain setup (Install-CIToolchain
+responsibility). Setup Steps 1/3/4b/5b/5c converted to assertion-only (`Assert-Step`).
+
+New scripts: `Validate-DeployState.ps1`, `Validate-SetupState.ps1`.
+WU lifecycle strategy B: Deploy sets GPO `NoAutoUpdate`; Install-CIToolchain runs WU then
+disables wuauserv/UsoSvc permanently.
+
+---
+
+## 2026-05-10 — Sprint 9: §3.3 In-VM Git Clone
+
+`-UseGitClone` switch added to `Invoke-CIJob.ps1` and `Invoke-RemoteBuild.ps1`.
+- Skips host git clone + zip + WinRM transfer overhead.
+- PAT injected at runtime, never persisted in snapshot.
+- E2E result: 34 s saving, 25.7% reduction vs baseline on nsis-plugin-ns7zip.
+
+---
+
+## 2026-05-10 — Sprints 1-8: Core infrastructure
+
+| Sprint | Area                          | Key deliverable                                        |
+| ------ | ----------------------------- | ------------------------------------------------------ |
+| 1      | §1.1 WinRM HTTP → HTTPS       | Self-signed cert, port 5986, AllowUnencrypted=false    |
+| 2      | §1.4 IP validation            | Per-octet regex extracted to `_Common.psm1`            |
+| 3      | §1.6 Threat model             | `BEST-PRACTICES.md` §2.1 Threat Model documented       |
+| 4      | §2.1 IP race / lease          | File-based IP allocator in `Invoke-CIJob.ps1`          |
+| 5      | §2.2-2.7 Reliability          | Orphan cleanup, retention, WhatIf, snapshot versioning, backup, health watch |
+| 6      | §3.1 NuGet/pip shared cache   | `Set-TemplateSharedFolders.ps1`, `UseSharedCache` switch |
+| 7      | §3.2 7-Zip compression        | 7-Zip replaces Compress-Archive in `Invoke-RemoteBuild.ps1` |
+| 8      | §3.6 Benchmark baseline       | `Measure-CIBenchmark.ps1` — 5-phase JSONL output       |
+| -      | §4.1 Structured logging       | `Write-JobEvent` + `invoke-ci.jsonl` in `Invoke-CIJob.ps1` |
+| -      | §4.3 Disk alert               | `Watch-DiskSpace.ps1` + scheduled task                 |
+| -      | §4.4 Runbook                  | `docs/RUNBOOK.md` — 5 incident categories              |
+| -      | §5.1 Pester tests             | `tests/` — 4 test files, fake vmrun harness            |
+| -      | §5.2 `_Common.psm1`           | `New-CISessionOption`, `Resolve-VmrunPath`, `Invoke-Vmrun` |
+| -      | §5.4 PSScriptAnalyzer         | `PSScriptAnalyzerSettings.psd1`                        |

docs/CI-FLOW.md

@@ -8,15 +8,17 @@
 
 Before any CI job runs, the following must be in place:
 
-| Component          | State                                                                   |
-| ------------------ | ----------------------------------------------------------------------- |
-| Gitea server       | Running, accessible on LAN                                              |
-| act_runner         | Registered, running as Windows service on host                          |
-| Template VM        | Provisioned, snapshot "BaseClean" taken, VM powered off                 |
-| WinRM              | Enabled on template VM (inherits to all clones)                         |
-| vmrun.exe          | Present at `C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe` |
-| `F:\CI\BuildVMs\`  | Directory exists and writable                                           |
-| `F:\CI\Artifacts\` | Directory exists and writable                                           |
+| Component          | State                                                                         |
+| ------------------ | ----------------------------------------------------------------------------- |
+| Gitea server       | Running, accessible on LAN                                                    |
+| act_runner         | Registered, running as Windows service on host                                |
+| Template VM (Win)  | Provisioned, snapshot "BaseClean" taken, VM powered off                       |
+| Template VM (Lin)  | Ubuntu 24.04 LTS, snapshot "BaseClean-Linux" taken, VM powered off (optional) |
+| WinRM              | Enabled on Windows template VM (inherits to all clones)                       |
+| SSH key            | `F:\CI\keys\ci_linux` (ed25519) present; public key in Linux template         |
+| vmrun.exe          | Present at `C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe`       |
+| `F:\CI\BuildVMs\`  | Directory exists and writable                                                 |
+| `F:\CI\Artifacts\` | Directory exists and writable                                                 |
 
 ---
 
@@ -110,12 +112,19 @@ Wait-VMReady.ps1 -VMPath <clone.vmx> -IPAddress <dynamic-NAT-ip> -TimeoutSeconds
 IP is discovered dynamically via `vmrun getGuestIPAddress` (VMnet8 NAT, subnet 192.168.79.0/24).
 No hardcoded IPs — each clone gets a DHCP-assigned address from VMware NAT.
 
-Three-phase readiness check (retried every 5 seconds, up to 300s timeout):
+Three-phase readiness check (retried every 5 seconds, up to 300s timeout).
+Transport is selected automatically from the VMX `guestOS` field (`-Transport WinRM` for Windows, `-Transport SSH` for Linux):
 
 ```
 Phase 1: vmrun getState → must return "running"
-Phase 2: Test-Connection (ICMP ping) → must succeed
-Phase 3: Test-WSMan → WinRM listener must respond
+
+Windows (-Transport WinRM, default):
+  Phase 2: Test-Connection (ICMP ping) → must succeed
+  Phase 3: Test-WSMan → WinRM listener must respond
+
+Linux (-Transport SSH):
+  Phase 2: Test-NetConnection -Port 22 → must succeed
+  Phase 3: ssh -o ConnectTimeout=5 ... "echo ready" → must return "ready"
 ```
 
 - Total wait is typically **30–90 seconds** after `vmrun start`
@@ -129,17 +138,29 @@ Phase 3: Test-WSMan → WinRM listener must respond
 ```
 Invoke-RemoteBuild.ps1
   -IPAddress   <dynamic-NAT-ip>           # from vmrun getGuestIPAddress
+  -GuestOS     Windows|Linux              # auto-detected from VMX guestOS field
+
+  # Windows path (default):
   -Credential  (from Windows Credential Manager)
   -BuildCommand 'python build_plugin.py --final --dist-dir dist'
   -GuestArtifactSource 'dist'
+
+  # Linux path (-GuestOS Linux):
+  -SshKeyPath  F:\CI\keys\ci_linux
+  -SshUser     ci_build
+  -CloneUrl / -CloneBranch   # always in-VM git clone for Linux
+  -BuildCommand 'make all'
 ```
 
 Sequence inside the PSSession:
 
 ```
 1. New-PSSession  →  open WinRM session to VM
-2. Compress-Archive (host) → copy zip to C:\CI\build.zip (guest) → Expand-Archive to C:\CI\build\
-   (source code è già clonato sull'host in Phase 1 — non si fa git clone nella VM)
+2a. (default) Compress-Archive (host) → copy zip to C:\CI\build.zip (guest) → Expand-Archive to C:\CI\build\
+    (source code è già clonato sull'host in Phase 1 — nessun git clone nella VM)
+2b. (opt-in, `-UseGitClone`, §3.3 DONE 2026-05-10)
+    git clone direttamente in VM tramite `ssh://gitea-ci/...` (richiede Git+7-Zip in template, §6.6 Tier-1)
+    Vantaggio: skip host-zip-transfer, -25.7% durata pipeline (e2e PASS). Verifica SHA commit post-clone.
 3. Invoke-Expression "$BuildCommand" in C:\CI\build\
      Esempio: python build_plugin.py --final --dist-dir dist
        a. Build 4 configurazioni MSBuild in parallelo (x86-unicode, x64-unicode, cli-x86, cli-x64)
@@ -160,14 +181,22 @@ Sequence inside the PSSession:
 ```
 Get-BuildArtifacts.ps1
   -IPAddress       <dynamic-NAT-ip>
-  -Credential      (same as above)
+  -GuestOS         Windows|Linux         # auto-detected from Invoke-CIJob
+
+  # Windows path (default):
+  -Credential      (from Windows Credential Manager)
   -GuestArtifactPath  C:\CI\output\artifacts.zip
+
+  # Linux path (-GuestOS Linux):
+  -SshKeyPath      F:\CI\keys\ci_linux
+  -GuestArtifactPath  /opt/ci/output
+
   -HostArtifactDir    F:\CI\Artifacts\{JobId}\
 ```
 
-- Apre PSSession e copia `C:\CI\output\artifacts.zip` dall'host
-- Valida che il file esista e sia non-vuoto
-- Il zip contiene la struttura `dist/` con tutti gli artifact di build
+- Windows: apre PSSession e copia `C:\CI\output\artifacts.zip` tramite WinRM
+- Linux: `scp -r ci_build@<ip>:/opt/ci/output/. <HostArtifactDir>` tramite `_Transport.psm1`
+- In entrambi i casi valida che almeno un file sia stato trasferito
 
 ---
 
@@ -241,7 +270,7 @@ automatically via `vmrun getGuestIPAddress` — no static assignment required.
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | VM clone fails                         | `Invoke-CIJob.ps1` throws; no VM to destroy; job fails immediately                                                  |
 | VM never reaches ready state (timeout) | `Wait-VMReady.ps1` throws; `finally` destroys the (running) VM                                                      |
-| Build fails inside VM                  | `Invoke-RemoteBuild.ps1` throws; `finally` collects partial artifacts (if any), destroys VM                         |
+| Build fails inside VM                  | `Invoke-RemoteBuild.ps1` throws; `finally` runs `Get-GuestDiagnostics` (best-effort, to `F:\CI\Artifacts\<jobId>\diagnostics\`), destroys VM |
 | Artifact collection fails              | Job marked failed; VM is still destroyed in `finally`                                                               |
 | Host machine loses power mid-job       | `act_runner` resumes on reboot, marks in-flight job as failed; orphan VMs must be cleaned up manually (see TODO.md) |
 

docs/HOST-SETUP.md

@@ -7,15 +7,15 @@ Eseguire **una volta** prima di qualsiasi provisioning del template VM o esecuzi
 
 ## Prerequisiti host
 
-| Componente              | Versione/Note                                                     |
-| ----------------------- | ----------------------------------------------------------------- |
-| OS                      | Windows 11 (host fisico) o Windows Server 2022+                   |
-| VMware Workstation      | Pro 17.x — necessario per `vmrun.exe` e supporto linked clone     |
-| Storage                 | NVMe dedicato (consigliato `F:\` riservato a CI, ≥ 500 GB libero) |
-| RAM                     | ≥ 32 GB (4 VM parallele × 6-8 GB)                                 |
-| Rete                    | VMnet8 (NAT) configurato in VMware Workstation                    |
-| PowerShell              | 5.1+ (built-in) o 7.x                                             |
-| Privilegi               | Account amministrativo per Setup-Host.ps1                         |
+| Componente         | Versione/Note                                                     |
+| ------------------ | ----------------------------------------------------------------- |
+| OS                 | Windows 11 (host fisico) o Windows Server 2022+                   |
+| VMware Workstation | Pro 17.x — necessario per `vmrun.exe` e supporto linked clone     |
+| Storage            | NVMe dedicato (consigliato `F:\` riservato a CI, ≥ 500 GB libero) |
+| RAM                | ≥ 32 GB (4 VM parallele × 6-8 GB)                                 |
+| Rete               | VMnet8 (NAT) configurato in VMware Workstation                    |
+| PowerShell         | 5.1+ (built-in) o 7.x                                             |
+| Privilegi          | Account amministrativo per Setup-Host.ps1                         |
 
 Software opzionali installati on-demand dallo script:
 - **NSSM** — installazione automatica via Chocolatey se presente; altrimenti install manuale da https://nssm.cc
@@ -33,13 +33,18 @@ F:\CI\
 ├── Artifacts\              # output build raccolti dall'host
 ├── Logs\                   # log per-job (retention: 30 giorni)
 ├── Templates\
-│   └── WinBuild\           # VMX template Windows (immutabile dopo snapshot)
+│   ├── WinBuild2025\       # VMX template Windows (immutabile dopo snapshot)
+│   └── LinuxBuild2404\     # VMX template Linux Ubuntu 24.04 (immutabile dopo snapshot)
+├── keys\
+│   ├── ci_linux            # chiave privata SSH per Linux VMs (ed25519, no passphrase)
+│   └── ci_linux.pub        # chiave pubblica corrispondente
+├── config.toml             # configurazione Python orchestrator (ssh_key_path, ecc.)
 ├── act_runner\
 │   ├── act_runner.exe      # binario runner Gitea
 │   ├── config.yaml         # config runner (path, label, capacity)
 │   └── logs\               # stdout/stderr del servizio
 ├── Cache\
-│   └── NuGet\              # cache NuGet condivisa via shared folder (TODO §3.1)
+│   └── NuGet\              # cache NuGet condivisa via shared folder (§3.1 — DONE 2026-05-10, vedi scripts/Set-TemplateSharedFolders.ps1)
 ├── RunnerWork\             # working dir di act_runner (job staging)
 └── ISO\                    # ISO di installazione (Windows Server 2025, ecc.)
 ```
@@ -86,24 +91,50 @@ Apri PowerShell **come Administrator**, poi:
    - Avvia servizio (`SERVICE_AUTO_START`)
 7. **Configura SSH alias `gitea-ci`** in `~/.ssh/config` (HostName, Port, User git)
 
+### Note operative (scoperte in validazione end-to-end)
+
+Setup-Host.ps1 da solo **non basta** per la pipeline Python su runner
+LocalSystem. Dopo Setup-Host:
+
+- **Credenziale guest nel vault SYSTEM, username host-qualificato.** Lo
+  step 4 scrive in Windows Credential Manager dell'utente interattivo →
+  invisibile ad act_runner (LocalSystem). Esegui (elevato):
+  `\.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'`.
+  Bare `ci_build` viene rifiutato da NTLM (`SEC_E_UNKNOWN_CREDENTIALS`):
+  usa il computer name del guest (= CN del cert WinRM). Diagnostica:
+  `\.\scripts\Test-CIGuestWinRM.ps1 -IpAddress <guest-ip>`.
+- **venv di produzione = install non-editable.** Popola
+  `F:\CI\python\venv` con `python -m pip install .` dal repo reale —
+  **mai** `pip install -e .` (il `.pth` punta a un path che LocalSystem
+  non risolve → `No module named ci_orchestrator`). Vedi
+  `plans/PhaseA-user-checklist.md` Passo 1. Nessun workflow CI deve
+  installare in quel venv (lint usa un venv effimero per-job).
+- **Gitea `app.ini`:** imposta `[actions] DEFAULT_ACTIONS_URL = github`
+  e referenzia l'action col **URL completo**
+  (`https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main`)
+  così le action GitHub (checkout, upload-artifact) restano risolvibili
+  e l'action locale punta all'istanza. Il repo `local-ci-cd-system` deve
+  essere **pubblico** (il runner clona l'action senza autenticazione) e
+  l'action deve esistere su `@main` (il ref che il runner clona).
+
 ---
 
 ## Parametri principali
 
-| Parametro                    | Default                          | Note                                  |
-| ---------------------------- | -------------------------------- | ------------------------------------- |
-| `-CIRoot`                    | `F:\CI`                          | Base directory per tutti i dati CI    |
-| `-GuestCredentialTarget`     | `BuildVMGuest`                   | Target Credential Manager             |
-| `-GuestUsername`             | `ci_build`                       | Account build dentro la VM            |
-| `-GuestPassword`             | (prompt)                         | Mai hard-codare                       |
-| `-ActRunnerExe`              | `<CIRoot>\act_runner\act_runner.exe` | Path binario runner               |
-| `-ActRunnerConfigYaml`       | `<repo>\runner\config.yaml`      | Source del config da copiare          |
-| `-GiteaUrl`                  | `http://10.10.20.11:3100`        | URL Gitea per registrazione           |
-| `-GiteaRunnerToken`          | (vuoto)                          | Token registrazione (Admin → Runners) |
-| `-SkipRunnerInstall`         | `$false`                         | Salta installazione servizio          |
-| `-SkipSSHConfig`             | `$false`                         | Salta scrittura SSH alias             |
-| `-GiteaSSHHost`              | `10.10.20.11`                    | Hostname SSH Gitea                    |
-| `-GiteaSSHPort`              | `2222`                           | Porta SSH Gitea                       |
+| Parametro                | Default                              | Note                                  |
+| ------------------------ | ------------------------------------ | ------------------------------------- |
+| `-CIRoot`                | `F:\CI`                              | Base directory per tutti i dati CI    |
+| `-GuestCredentialTarget` | `BuildVMGuest`                       | Target Credential Manager             |
+| `-GuestUsername`         | `ci_build`                           | Account build dentro la VM            |
+| `-GuestPassword`         | (prompt)                             | Mai hard-codare                       |
+| `-ActRunnerExe`          | `<CIRoot>\act_runner\act_runner.exe` | Path binario runner                   |
+| `-ActRunnerConfigYaml`   | `<repo>\runner\config.yaml`          | Source del config da copiare          |
+| `-GiteaUrl`              | `http://10.10.20.11:3100`            | URL Gitea per registrazione           |
+| `-GiteaRunnerToken`      | (vuoto)                              | Token registrazione (Admin → Runners) |
+| `-SkipRunnerInstall`     | `$false`                             | Salta installazione servizio          |
+| `-SkipSSHConfig`         | `$false`                             | Salta scrittura SSH alias             |
+| `-GiteaSSHHost`          | `10.10.20.11`                        | Hostname SSH Gitea                    |
+| `-GiteaSSHPort`          | `2222`                               | Porta SSH Gitea                       |
 
 ---
 
@@ -120,18 +151,42 @@ Allo `Setup-Host.ps1` exit 0:
 
 3. **Configura host WinRM client** (necessario per Prepare-WinBuild2025.ps1):
    ```powershell
-   Set-Item WSMan:\localhost\Client\AllowUnencrypted $true -Force
+   # AllowUnencrypted non serve — Prepare usa HTTPS/5986 (nessun testo in chiaro)
    Set-Item WSMan:\localhost\Client\TrustedHosts -Value '192.168.79.*' -Force -Concatenate
    ```
-   *Note*: Prepare-WinBuild2025.ps1 imposta queste in modo transitorio e le ripristina nel `finally`.
+   *Note*: Prepare-WinBuild2025.ps1 aggiunge l'IP specifico della VM in modo transitorio e lo ripristina nel `finally`.
 
-4. **Provisiona il template VM** — vedi [WINDOWS-TEMPLATE-SETUP.md](WINDOWS-TEMPLATE-SETUP.md)
+4. **Provisiona il template VM Windows** — vedi [WINDOWS-TEMPLATE-SETUP.md](WINDOWS-TEMPLATE-SETUP.md)
 
-5. **Registra chiave SSH con Gitea**:
+5. **(Opzionale) Genera chiave SSH CI per Linux VMs** — necessaria solo se si vuole usare `linux-build`:
+   ```powershell
+   New-Item -ItemType Directory -Force F:\CI\keys | Out-Null
+   ssh-keygen -t ed25519 -f F:\CI\keys\ci_linux -N '""' -C 'ci-linux-runner'
+   # Risultato: F:\CI\keys\ci_linux (privata) + F:\CI\keys\ci_linux.pub (pubblica)
+   ```
+   Poi **provisiona il template VM Linux** — vedi [LINUX-TEMPLATE-SETUP.md](LINUX-TEMPLATE-SETUP.md)
+
+6. **Crea `F:\CI\config.toml`** — necessario affinché il Python orchestrator trovi la chiave SSH e le altre impostazioni:
+   ```powershell
+   Copy-Item N:\Code\Workspace\Local-CI-CD-System\config.example.toml F:\CI\config.toml
+   ```
+   Il file `config.example.toml` contiene già i path corretti per Windows (`F:\CI\...`). Modificare solo se si usa un `$CIRoot` diverso da `F:\CI`.
+
+   Valori chiave configurati:
+
+   | Chiave               | Valore default          | Scopo                                        |
+   | -------------------- | ----------------------- | -------------------------------------------- |
+   | `ssh_key_path`       | `F:/CI/keys/ci_linux`   | Chiave privata per SSH verso Linux guest     |
+   | `guest_cred_target`  | `BuildVMGuest`          | Target Windows Credential Manager (WinRM)    |
+   | `backend.type`       | `workstation`           | Backend VMware (solo `workstation` in Phase A) |
+
+   Le variabili d'ambiente `CI_SSH_KEY_PATH`, `CI_VMRUN_PATH`, `CI_GUEST_CRED_TARGET` sovrascrivono i valori del TOML se presenti.
+
+6. **Registra chiave SSH con Gitea**:
    - Gitea UI → User Settings → SSH Keys → Add Key
    - Chiave pubblica: `%USERPROFILE%\.ssh\id_rsa.pub`
 
-6. **Verifica runner online** in Gitea:
+7. **Verifica runner online** in Gitea:
    - `<GiteaUrl>/-/admin/runners`
    - Status atteso: **Online**, label `windows-build:host,dotnet:host,msbuild:host`
 
@@ -145,8 +200,12 @@ Allo `Setup-Host.ps1` exit 0:
 | act_runner exe            | `F:\CI\act_runner\act_runner.exe` (servizio: `act_runner`)   |
 | act_runner config         | `F:\CI\act_runner\config.yaml`                               |
 | act_runner logs           | `F:\CI\act_runner\logs\` (stdout.log, stderr.log)            |
-| Template VMX              | `F:\CI\Templates\WinBuild\CI-WinBuild.vmx`                   |
-| Snapshot name             | `BaseClean`                                                  |
+| Template VMX (Windows)    | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`              |
+| Template VMX (Linux)      | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx`          |
+| Snapshot name (Windows)   | `BaseClean`                                                  |
+| Snapshot name (Linux)     | `BaseClean-Linux`                                            |
+| SSH key (Linux VMs)       | `F:\CI\keys\ci_linux` (privata), `F:\CI\keys\ci_linux.pub`   |
+| Orchestrator config TOML  | `F:\CI\config.toml` (copia di `config.example.toml`)         |
 | Clone base dir            | `F:\CI\BuildVMs\`                                            |
 | Artifact dir              | `F:\CI\Artifacts\`                                           |
 | Log dir                   | `F:\CI\Logs\` (retention: 30 giorni)                         |
@@ -161,23 +220,24 @@ Allo `Setup-Host.ps1` exit 0:
 
 ## Maintenance & operational tasks
 
-Voci di backlog (vedi [TODO.md](../TODO.md)):
+Task schedulati (vedi `scripts/Register-CIScheduledTasks.ps1` per il bootstrap):
 
-- **§2.2** Cleanup VM orfane schedulato (`scripts/Cleanup-OrphanedBuildVMs.ps1` ogni 6h, `-MaxAgeHours 4`)
-- **§2.3** Retention artifact + log (Artifacts > 30 gg, Logs > 30 gg, guard libero < 50 GB)
-- **§2.7** Health check runner (query API Gitea ogni 15 min, restart su offline)
-- **§4.3** Disk space alert (`F:` < 50 GB → eventcreate/webhook)
-- **§1.2** Restringere `TrustedHosts` da `*` a `192.168.79.*`
+- **§2.2** Cleanup VM orfane (`scripts/Cleanup-OrphanedBuildVMs.ps1`, ogni 6h, `-MaxAgeHours 4`)
+- **§2.3** Retention artifact + log (`scripts/Invoke-RetentionPolicy.ps1`, daily)
+- **§2.6** Backup template (`scripts/Backup-CITemplate.ps1`, weekly)
+- **§2.7** Health check runner (`scripts/Watch-RunnerHealth.ps1`, ogni 15 min)
+- **§4.3** Disk space alert (`scripts/Watch-DiskSpace.ps1`, ogni ora)
 
 ---
 
 ## Troubleshooting
 
-| Sintomo                                 | Diagnosi / Fix                                                       |
-| --------------------------------------- | -------------------------------------------------------------------- |
-| `vmrun.exe NOT found`                   | Installa VMware Workstation Pro, riesegui                            |
-| `NSSM not available`                    | Install manuale da https://nssm.cc, aggiungi a PATH, riesegui        |
-| Runner registration `exit != 0`         | Verifica token Gitea + URL raggiungibile da host                     |
-| Service `act_runner` non parte          | Check `F:\CI\act_runner\logs\stderr.log`                             |
-| `New-StoredCredential` fail             | Verifica modulo CredentialManager importato + scope corretto         |
-| Job CI fallisce su `Test-WSMan`         | TrustedHosts host non include subnet VM, AllowUnencrypted=$false     |
+| Sintomo                         | Diagnosi / Fix                                                   |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `vmrun.exe NOT found`           | Installa VMware Workstation Pro, riesegui                        |
+| `NSSM not available`            | Install manuale da https://nssm.cc, aggiungi a PATH, riesegui    |
+| Runner registration `exit != 0` | Verifica token Gitea + URL raggiungibile da host                 |
+| Service `act_runner` non parte  | Check `F:\CI\act_runner\logs\stderr.log`                         |
+| `New-StoredCredential` fail     | Verifica modulo CredentialManager importato + scope corretto     |
+| Job CI fallisce su `Test-WSMan` | TrustedHosts host non include subnet VM, AllowUnencrypted=$false |
+| `wait-ready` SSH: `No authentication methods available` | `F:\CI\config.toml` mancante o `ssh_key_path` non configurato. Crea il file (vedi step 6) oppure passa `--ssh-key-path F:\CI\keys\ci_linux` |

docs/LINUX-TEMPLATE-SETUP.md

@@ -1,346 +1,427 @@
-# Linux Template VM Setup — DRAFT / TODO
+# Linux Template VM Setup  Piano di implementazione
 
-> **Status**: bozza. Non implementato. Vedi [TODO.md §6.1](../TODO.md) (P2).
-> Documento di pianificazione per estendere il sistema CI con build su Linux,
-> in parallelo al template Windows già operativo.
+> **Status**: implementato (2026-05-11) — Fasi A-E complete. Fase F (test e2e) richiede provisioning fisico VM. Vedi [TODO.md §6.1](../TODO.md) (P2).
+> Distro scelta: **Ubuntu 24.04 LTS** (cloud image, cloud-init). Approccio simmetrico a Windows.
 
 ---
 
-## Obiettivo
+## Architettura: tre script + modulo transport
 
-Aggiungere supporto a build su Linux per:
-- Compilazione cross-platform (es. versione Linux di plugin C/C++, build check con GCC/Clang)
-- Test su distro Linux per progetti che lo richiedono
-- Build matrix `[windows, linux]` nei workflow Gitea
+| Script / Modulo                             | Dove gira        | Ruolo                                                                       |
+| ------------------------------------------- | ---------------- | --------------------------------------------------------------------------- |
+| `template/Deploy-LinuxBuild2404.ps1`        | **Host** (PS)    | Crea VM da cloud image VMDK, genera seed ISO cloud-init, avvia, aspetta SSH |
+| `template/Prepare-LinuxBuild2404.ps1`       | **Host** (PS)    | Copia + esegue setup via SSH, valida stato, prende snapshot                 |
+| `template/Install-CIToolchain-Linux2404.sh` | **Guest** (Bash) | Installa toolchain CI, dirs, hardening, gate finale                         |
+| `scripts/_Transport.psm1`                   | **Host** (PS)    | Funzioni SSH-only per il branch Linux (WinRM esistente invariato per ora)   |
 
-Architettura simmetrica al template Windows: VM template → snapshot `BaseClean-Linux` →
-linked clone per ogni job → cleanup automatico.
+Perche tre script separati (non tutto-in-uno): cloud-init copre solo il bootstrap OS
+(utente, SSH key, pacchetti base). Il toolchain CI e le validazioni per step sono piu
+leggibili e manutenibili in un secondo script dedicato  identico alla divisione
+Deploy/Setup/Prepare di Windows.
 
 ---
 
-## Decisioni di design (da validare)
+## Specifiche VM
 
-### Distro
+| Parametro     | Valore                                               |
+| ------------- | ---------------------------------------------------- |
+| OS            | Ubuntu 24.04 LTS (cloud image, non ISO installer)    |
+| Immagine base | `noble-server-cloudimg-amd64.vmdk`                   |
+| Download      | `https://cloud-images.ubuntu.com/noble/current/`     |
+| vCPU          | 4                                                    |
+| RAM           | 4096 MB                                              |
+| Disco         | 40 GB thin (resize del cloud VMDK)                   |
+| NIC           | VMnet8 (NAT)  vmxnet3 diretto (driver nativo kernel) |
+| VMX path      | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx`  |
+| Snapshot name | `BaseClean-Linux`                                    |
 
-| Opzione                  | Pro                                                                | Contro                                       |
-| ------------------------ | ------------------------------------------------------------------ | -------------------------------------------- |
-| **Ubuntu 24.04 LTS**     | Toolchain recente, supporto LTS fino al 2029, cloud-init ottimo    | Snap default (lento per CI)                  |
-| Debian 12                | Stabile, leggero, no snap                                          | Toolchain meno recente                       |
-| Rocky Linux 9 / Alma 9   | RHEL-compat, glibc moderno, dnf                                    | Meno comune in workflow CI tipici            |
-
-**Scelta proposta**: Ubuntu 24.04 LTS minimal. Rationale: maggior parità con runner GitHub
-ufficiali (`ubuntu-latest` mappa a 22.04/24.04), toolchain recente out-of-box, cloud-init
-maturo per provisioning automatico.
-
-### Transport host → VM
-
-| Opzione                  | Pro                                                                | Contro                                       |
-| ------------------------ | ------------------------------------------------------------------ | -------------------------------------------- |
-| **SSH (chiave pubblica)**| Standard Linux, supporto nativo OpenSSH su Win11/Server 2025       | Diversa API rispetto WinRM (PSSession)       |
-| WinRM su Linux (PSCore)  | Codice script unificato                                            | Setup complesso, non standard, fragile       |
-
-**Scelta proposta**: SSH key-based con `ssh.exe` + `scp.exe` (built-in Windows 10+) o
-modulo `Posh-SSH`. WinRM su Linux non è production-ready.
-
-### Layer di astrazione
-
-Aggiungere `scripts/_Transport.psm1` con interfaccia comune:
-
-```powershell
-# Pseudo-API
-function Invoke-RemoteCommand {
-    param($Target, $ScriptBlock, $Args, [ValidateSet('WinRM','SSH')] $Transport)
-}
-function Copy-RemoteItem {
-    param($Source, $Destination, $Target, $Direction, $Transport)
-}
-function Test-RemoteReady {
-    param($Target, $TimeoutSec, $Transport)
-}
-```
-
-Implementazioni:
-- **WinRM** wrapper: `New-PSSession` + `Invoke-Command` + `Copy-Item -ToSession`
-- **SSH** wrapper: `ssh.exe` + `scp.exe` con `-i $keyfile -o StrictHostKeyChecking=accept-new`
-
-`Invoke-CIJob.ps1` riceve `-GuestOS Windows|Linux` (o auto-detect dal VMX `guestOS`),
-sceglie transport.
+Differenza chiave da Windows: l'immagine di partenza e gia installata (cloud VMDK,
+~600 MB). Nessuna fase di installazione OS  cloud-init provvede al bootstrap al primo
+boot in 30-60 secondi. La NIC non richiede lo swap e1000e  vmxnet3 perche il kernel
+Linux ha il driver vmxnet3 nativo.
 
 ---
 
-## Specifiche VM proposte
+## Prerequisiti host
 
-| Parametro               | Valore                                                          |
-| ----------------------- | --------------------------------------------------------------- |
-| OS                      | Ubuntu Server 24.04 LTS minimal                                 |
-| vCPU                    | 4                                                               |
-| RAM                     | 4096 MB (4 GB) — meno di Windows, footprint Linux più snello    |
-| Disco                   | 40 GB thin                                                      |
-| NIC                     | VMnet8 (NAT) — internet per `apt`                               |
-| VMX path                | `F:\CI\Templates\LinuxBuild\LinuxBuild.vmx`                     |
-| ISO                     | `ubuntu-24.04.x-live-server-amd64.iso` (in `F:\CI\ISO\`)        |
-| Snapshot name           | `BaseClean-Linux`                                               |
+- [x] **SSH key CI dedicata**  generare una volta sola (no passphrase):
+  ```powershell
+  New-Item -ItemType Directory -Force F:\CI\keys | Out-Null
+  ssh-keygen -t ed25519 -f F:\CI\keys\ci_linux -N '""' -C 'ci-linux-runner'
+  # Risultato: F:\CI\keys\ci_linux (privata) + F:\CI\keys\ci_linux.pub (pubblica)
+  ```
+- [x] **OpenSSH client** verificato presente sull'host (default su Windows 11):
+  ```powershell
+  Get-WindowsCapability -Online -Name OpenSSH.Client* | Select-Object State
+  # Atteso: State = Installed
+  ```
+- [x] **`F:\CI\Templates\LinuxBuild2404\`** creata (Setup-Host.ps1 o manuale)
+- [x] **`F:\CI\ISO\`** creata (il VMDK viene scaricato automaticamente da Deploy se mancante)
 
 ---
 
-## TODO — Implementazione
+## Fase A  Deploy-LinuxBuild2404.ps1
 
-### Pre-requisiti host
+Script host-side. Produce una VM pronta con cloud-init completato e SSH raggiungibile.
+Non richiede installazione OS  parte dal cloud VMDK pre-built.
 
-- [ ] **OpenSSH client** verificato presente su host (default Win11/Server 2025)
-      ```powershell
-      Get-WindowsCapability -Online -Name OpenSSH.Client*
-      ```
-- [ ] **Genera SSH key dedicata** per CI (no passphrase, separata da chiavi utente):
-      ```powershell
-      ssh-keygen -t ed25519 -f F:\CI\keys\ci_linux -N '""' -C 'ci-linux-runner'
-      ```
-- [ ] **Aggiungere a `Setup-Host.ps1`** uno step opzionale `-GenerateLinuxCIKey` che crea
-      la chiave e la archivia con permessi corretti (`F:\CI\keys\` con ACL ristretta)
+- [x] **Step 1  Validate prerequisites**
+  - Parametro `-VMwareWorkstationDir` (default `C:\Program Files (x86)\VMware\VMware Workstation`) — stesso pattern di Deploy-WinBuild2025.ps1
+  - `vmrun.exe` presente in `$VMwareWorkstationDir`
+  - `vmware-vdiskmanager.exe` presente in `$VMwareWorkstationDir`
+    (`$vdiskMgr = Join-Path $VMwareWorkstationDir 'vmware-vdiskmanager.exe'`)
+  - SSH key `F:\CI\keys\ci_linux.pub` presente
+  - Cartella destinazione VMX non gia occupata (o `-Force` per sovrascrivere)
+  - (il VMDK sorgente viene gestito in Step 1b — nessun prerequisito manuale)
 
-### Fase A — Crea VM e installa Ubuntu
-
-- [ ] Crea nuova VM in VMware Workstation (4 vCPU, 4 GB RAM, 40 GB thin)
-- [ ] NIC: VMnet8 (NAT)
-- [ ] Boot da ISO Ubuntu Server 24.04 LTS minimal
-- [ ] Durante install scegli:
-  - [ ] **Minimal install** (no extra packages)
-  - [ ] OpenSSH server: **Yes**
-  - [ ] Username: `ci_build`
-  - [ ] Hostname: `ci-linux-template`
-  - [ ] LVM: opzionale (non necessario per template)
-- [ ] Annota IP DHCP (`ip a`)
-
-### Fase B — Provisioning iniziale (manuale, una volta)
-
-Dentro la VM, come `ci_build`:
-
-- [ ] **Disabilita swap permanente** (overhead I/O su NVMe condivisa):
-  ```bash
-  sudo swapoff -a
-  sudo sed -i '/ swap / s/^/#/' /etc/fstab
-  ```
-
-- [ ] **Disabilita servizi non necessari** (snap, motd-news, ecc.):
-  ```bash
-  sudo systemctl disable --now snapd.service snapd.socket snapd.seeded.service 2>/dev/null
-  sudo systemctl disable --now motd-news.timer 2>/dev/null
-  sudo systemctl disable --now apt-daily.timer apt-daily-upgrade.timer
-  ```
-  Rationale: snap e timer apt rallentano boot e mangiano CPU su VM efimere.
-
-- [ ] **Sudo passwordless** per `ci_build` (parità con WinRM admin senza prompt UAC):
-  ```bash
-  echo 'ci_build ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/90-ci_build
-  sudo chmod 440 /etc/sudoers.d/90-ci_build
-  ```
-
-- [ ] **Authorized SSH key** dell'host CI:
-  ```bash
-  mkdir -p ~/.ssh && chmod 700 ~/.ssh
-  # Incolla la chiave pubblica generata su host (F:\CI\keys\ci_linux.pub)
-  echo 'ssh-ed25519 AAAA... ci-linux-runner' >> ~/.ssh/authorized_keys
-  chmod 600 ~/.ssh/authorized_keys
-  ```
-
-- [ ] **SSH hardening** per template (ma non così stretto da bloccare CI):
-  ```bash
-  sudo sed -i 's/^#*PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
-  sudo sed -i 's/^#*PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
-  sudo systemctl restart sshd
-  ```
-
-### Fase C — Setup-LinuxTemplateVM.sh (script equivalente a Setup-WinBuild2025.ps1)
-
-Da creare: `template/Setup-LinuxTemplateVM.sh` con `set -euo pipefail` + `assert_step()` helper.
-
-- [ ] **Helper `assert_step`** (throw on fail, log su success):
-  ```bash
-  assert_step() {
-      local step="$1"; local desc="$2"; shift 2
-      if "$@" >/dev/null 2>&1; then
-          echo "  [OK] [$step] $desc"
-      else
-          echo "  [FAIL] [$step] $desc" >&2; exit 1
-      fi
+- [x] **Step 1b  Download cloud VMDK se assente** (`F:\CI\ISO\` come cache locale)
+  ```powershell
+  $VmdkUrl  = 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.vmdk'
+  $VmdkPath = 'F:\CI\ISO\noble-server-cloudimg-amd64.vmdk'
+  if (-not (Test-Path $VmdkPath)) {
+      Write-Host "[Deploy] VMDK non trovato, avvio download..."
+      New-Item -ItemType Directory -Force F:\CI\ISO | Out-Null
+      $tmp = "$VmdkPath.part"
+      try {
+          Invoke-WebRequest -Uri $VmdkUrl -OutFile $tmp -UseBasicParsing
+          Move-Item $tmp $VmdkPath
+          Write-Host "[Deploy] Download completato: $VmdkPath"
+      } catch {
+          Remove-Item $tmp -ErrorAction SilentlyContinue
+          throw "[Deploy] Download VMDK fallito: $_"
+      }
+  } else {
+      Write-Host "[Deploy] VMDK trovato in cache: $VmdkPath"
   }
   ```
+  - Usa `Invoke-WebRequest` (nativo PowerShell, no dipendenze esterne)
+  - Scrittura atomica: file `.part` durante download, rinomina solo a completamento
+  - In caso di errore: il file `.part` viene rimosso, l'eccezione termina lo script
+  - Parametro opzionale `-VmdkUrl` per sovrascrivere l'URL (es. mirror locale)
 
-- [ ] **Step 1 — `apt update` + upgrade**
+- [x] **Step 2  Genera cloud-init user-data + meta-data** (inline, no template esterno)
+  - `meta-data`: `instance-id: linuxbuild-001`, `local-hostname: ci-linux-template`
+  - `user-data` (YAML):
+    - `hostname: ci-linux-template`
+    - `users`: utente `ci_build`, shell `/bin/bash`, `sudo: ALL=(ALL) NOPASSWD:ALL`,
+      `ssh_authorized_keys` con contenuto di `ci_linux.pub`
+    - Nessun `packages`, nessun `package_update`, nessun `runcmd`:
+      tutto il provisioning (apt, toolchain, SSH hardening, swap) e' delegato a
+      `Prepare-LinuxBuild2404.ps1` via `Install-CIToolchain-Linux2404.sh`
+    - Nessun `power_state`: il reboot non e' necessario, cloud-init completa tutto al primo boot
+
+- [x] **Step 3  Costruisce seed ISO nocloud** via IMAPI2FS COM
+  - Due file: `user-data` + `meta-data` (volume label: `cidata`)
+  - Stesso codice COM gia usato in Deploy-WinBuild2025.ps1 Step 3
+  - Output: `F:\CI\Templates\LinuxBuild2404\cloud-init-seed.iso`
+
+- [x] **Step 4  Converti e ridimensiona cloud VMDK**
+  - Il cloud VMDK e' in formato **streamOptimized** (distribuzione), non direttamente resizeable.
+  - Converti a **monolithicSparse** (tipo 0) contestualmente alla copia:
+    `& $vdiskMgr -r noble-server-cloudimg-amd64.vmdk -t 0 LinuxBuild2404.vmdk`
+  - Ridimensiona a 40 GB: `& $vdiskMgr -x 40GB LinuxBuild2404.vmdk`
+    (stessa variabile `$vdiskMgr` di Deploy-WinBuild2025.ps1, valorizzata in Step 1)
+  - Il resize avviene PRIMA del primo boot: l'immagine Ubuntu 24.04 ha i moduli
+    cloud-init `growpart` + `resizefs` abilitati di default — espandono automaticamente
+    la partizione root e il filesystem durante il primo avvio, senza `runcmd` aggiuntivi
+
+- [x] **Step 5  Genera .vmx**
+  - `guestOS = "ubuntu-64"`, `firmware = "efi"`
+    (Ubuntu 24.04 cloud image usa GPT con partizione EFI; il boot sotto BIOS legacy fallirebbe)
+  - NIC: `vmxnet3`, VMnet8
+  - Disco: `LinuxBuild2404.vmdk` (scsi0:0)
+  - CD-ROM secondario: `cloud-init-seed.iso` (connesso)
+  - Nessun USB controller, nessuna sound card
+  - `memsize = 4096`, `numvcpus = 4`
+
+- [x] **Step 6  Power on** (`vmrun start nogui`)
+
+- [x] **Step 7  Polling SSH port 22** fino a ready
+  - `Test-NetConnection -ComputerName $IP -Port 22` ogni 10 secondi
+  - Timeout: 5 minuti (cloud-init + reboot finale)
+  - IP rilevato via `vmrun getGuestIPAddress`
+
+  > open-vm-tools e pre-installato nell'Ubuntu 24.04 cloud image.
+  > `vmrun getGuestIPAddress` funziona senza installazione aggiuntiva.
+
+- [x] **Step 8  Verifica cloud-init completato**
+  ```powershell
+  ssh -i F:\CI\keys\ci_linux -o StrictHostKeyChecking=accept-new `
+      -o ConnectTimeout=5 ci_build@$IP `
+      "test -f /var/lib/cloud/instance/boot-finished && echo OK"
+  # Atteso: OK
+  ```
+
+- [x] **Step 9  Rimuove seed ISO dal VMX**
+  - Setta `ide1:0.present = "FALSE"` nel VMX
+  - Evita che linked clone ricevano il seed ISO e ri-eseguano cloud-init
+
+- [x] **Step 10  Print summary** (VMX path, IP, SSH fingerprint)
+
+---
+
+## Fase B  Prepare-LinuxBuild2404.ps1
+
+Script host-side. Copia il setup script, lo esegue via SSH, valida stato, prende snapshot.
+Equivalente di `Prepare-WinBuild2025.ps1` con SSH al posto di WinRM.
+
+- [x] **Step 1  Pre-flight**
+  - VMX presente; se VM spenta, avvia con `vmrun start nogui`
+  - SSH key `F:\CI\keys\ci_linux` presente
+  - `ssh.exe` e `scp.exe` nel PATH host
+  - TCP/22 raggiungibile (`Test-NetConnection`)
+
+- [x] **Step 2  Auto-detect IP** via `vmrun getGuestIPAddress $VMXPath`
+  - Se `-VMIPAddress` e fornito esplicitamente, salta il rilevamento automatico
+
+- [x] **Step 3  Aggiungi host key a known_hosts**
+  ```powershell
+  ssh -i F:\CI\keys\ci_linux -o StrictHostKeyChecking=accept-new `
+      ci_build@$IP "echo connected" | Out-Null
+  ```
+  Solo al primo run; idempotente se gia presente.
+
+- [x] **Step 4  Copia Install-CIToolchain-Linux2404.sh in VM**
+  ```powershell
+  scp -i F:\CI\keys\ci_linux `
+      "$PSScriptRoot\Install-CIToolchain-Linux2404.sh" `
+      "ci_build@${IP}:/tmp/Install-CIToolchain-Linux2404.sh"
+  ```
+  Valida: confronta size locale vs remota via `ssh ... stat -c %s /tmp/...`
+
+- [x] **Step 5  Esegui setup script** nel guest
+  ```powershell
+  ssh -i F:\CI\keys\ci_linux ci_build@$IP `
+      "chmod +x /tmp/Install-CIToolchain-Linux2404.sh && sudo /tmp/Install-CIToolchain-Linux2404.sh"
+  # Cattura exit code; != 0 => abort con errore leggibile
+  ```
+  Flag opzionali passabili: `--skip-update`, `--dotnet`, `--mingw`
+
+- [x] **Step 6  Post-setup remote validation** (batch via singola sessione SSH)
+  - `systemctl is-active ssh` = `active`
+  - `id ci_build` contiene `sudo`
+  - `sudo -n true` exit 0 (passwordless sudo)
+  - `which gcc g++ clang cmake python3 git 7z` tutti trovati
+  - `test -d /opt/ci/build -a -d /opt/ci/output -a -d /opt/ci/scripts` exit 0
+  - `swapon --show` output vuoto (swap disabilitato)
+  - `grep -q "^PasswordAuthentication no" /etc/ssh/sshd_config`
+
+- [x] **Step 7  Shutdown VM**
+  ```powershell
+  & $vmrun stop $VMXPath soft
+  # Polling vmrun list fino a VM non piu presente
+  ```
+
+- [x] **Step 8  Snapshot BaseClean-Linux**
+  ```powershell
+  & $vmrun snapshot $VMXPath 'BaseClean-Linux'
+  ```
+
+- [x] **Final  Print summary** (VMX, snapshot name, toolchain versions rilevate)
+
+---
+
+## Fase C  Install-CIToolchain-Linux2404.sh
+
+Script guest-side (Bash). Installazione toolchain CI e hardening.
+Eseguito da Prepare via SSH come `ci_build` con sudo.
+
+Header: `#!/usr/bin/env bash` + `set -euo pipefail`
+Helper `assert_step()`: stampa `[OK] [Step N] desc` su successo, `exit 1` su fallimento.
+
+- [x] **Step 1  apt update + upgrade** (saltabile con `--skip-update`)
   ```bash
   sudo DEBIAN_FRONTEND=noninteractive apt-get update -qq
   sudo DEBIAN_FRONTEND=noninteractive apt-get upgrade -y -qq
-  assert_step 'apt' 'no errors' true
   ```
 
-- [ ] **Step 2 — Toolchain build essentials**
+- [x] **Step 2  Toolchain build essentials**
   ```bash
   sudo apt-get install -y -qq \
       build-essential gcc g++ clang \
       make cmake ninja-build \
-      pkg-config autoconf automake libtool \
-      git curl wget ca-certificates \
-      python3 python3-pip python3-venv \
-      unzip zip xz-utils
-  assert_step 'toolchain' 'gcc presente'   command -v gcc
-  assert_step 'toolchain' 'clang presente' command -v clang
-  assert_step 'toolchain' 'cmake presente' command -v cmake
-  assert_step 'toolchain' 'python3 presente' command -v python3
+      pkg-config autoconf automake libtool
   ```
+  - assert: `command -v gcc`, `command -v clang`, `command -v cmake`
 
-- [ ] **Step 3 — Toolchain extra opzionale**
-  - [ ] **mingw-w64** se serve cross-compile per Windows: `sudo apt-get install -y mingw-w64`
-  - [ ] **.NET SDK** (per parità Windows): script `dotnet-install.sh` con channel pinned
-  - [ ] **Node.js** se workflow lo richiede: nvm o nodesource repo
+- [x] **Step 3  Python**
+  ```bash
+  sudo apt-get install -y -qq python3 python3-pip python3-venv
+  sudo ln -sf /usr/bin/python3 /usr/local/bin/python
+  ```
+  - assert: `python3 --version`, `pip3 --version`
 
-- [ ] **Step 4 — CI working directories**
+- [x] **Step 4  Tier-1 Toolchain** (speculare a §6.6 Windows: Git + 7-Zip)
+  ```bash
+  sudo apt-get install -y -qq git p7zip-full curl wget ca-certificates
+  ```
+  - assert: `command -v git`, `command -v 7z`
+
+- [x] **Step 4b  .NET SDK** (opzionale, flag `--dotnet`)
+  ```bash
+  curl -fsSL https://dotnet.microsoft.com/download/dotnet/scripts/v1/dotnet-install.sh \
+      | sudo bash -s -- --channel 10.0 --install-dir /usr/local/dotnet
+  sudo ln -sf /usr/local/dotnet/dotnet /usr/local/bin/dotnet
+  ```
+  - assert: `dotnet --version`
+
+- [x] **Step 4c  mingw-w64** (opzionale, flag `--mingw`  cross-compile per Windows)
+  ```bash
+  sudo apt-get install -y -qq mingw-w64
+  ```
+  - assert: `command -v x86_64-w64-mingw32-gcc`
+
+- [x] **Step 5  CI directories**
   ```bash
   sudo mkdir -p /opt/ci/{build,output,scripts,cache}
   sudo chown -R ci_build:ci_build /opt/ci
-  assert_step 'dirs' 'tutte presenti' test -d /opt/ci/build -a -d /opt/ci/output
   ```
+  - assert: `test -d /opt/ci/build`, `test -d /opt/ci/output`, `test -d /opt/ci/scripts`
 
-- [ ] **Step 5 — Disabilita auto-update apt** (no surprise reboot/lock):
+- [x] **Step 6  SSH hardening** (PasswordAuth off  gia impostato da cloud-init, ri-validato)
   ```bash
-  sudo apt-get remove -y unattended-upgrades 2>/dev/null
-  sudo systemctl mask apt-daily.service apt-daily-upgrade.service
+  sudo sed -i 's/^#*PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
+  sudo sed -i 's/^#*PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config
+  sudo systemctl restart sshd
+  ```
+  - assert: `grep -q "^PasswordAuthentication no" /etc/ssh/sshd_config`
+
+- [x] **Step 7  Disabilita swap permanente**
+  ```bash
+  sudo swapoff -a
+  sudo sed -i '/ swap / s/^/#/' /etc/fstab
+  ```
+  - assert: `swapon --show` output vuoto
+
+- [x] **Step 8  Disabilita apt auto-update** (no lock durante build)
+  ```bash
+  sudo systemctl mask apt-daily.service apt-daily-upgrade.service \
+      apt-daily.timer apt-daily-upgrade.timer
+  sudo apt-get remove -y unattended-upgrades 2>/dev/null || true
   ```
 
-- [ ] **Step 6 — Cleanup pre-snapshot**
+- [x] **Step 9  Cleanup pre-snapshot**
   ```bash
   sudo apt-get clean
   sudo rm -rf /var/lib/apt/lists/*
   sudo journalctl --vacuum-time=1d
   sudo rm -rf /tmp/* /var/tmp/*
-  history -c && cat /dev/null > ~/.bash_history
-  # Zero free space (riduce dim VMDK dopo compact, opzionale)
-  # sudo dd if=/dev/zero of=/zero bs=1M; sudo rm /zero
+  history -c
+  cat /dev/null > ~/.bash_history
   ```
 
-- [ ] **Step 7 — Final pre-snapshot validation**
-  - SSH server abilitato e in ascolto su 22
-  - `sudo` passwordless funzionante per `ci_build`
-  - Tutti i tool elencati (`gcc --version`, `cmake --version`, ecc.) ritornano exit 0
-  - `/opt/ci/{build,output,scripts}` esistono con owner corretto
-  - No leftover `/tmp/*`, history vuota
+- [x] **Final  Gate pre-snapshot** (exit 1 se qualcosa manca)
+  - Ogni tool richiesto raggiungibile con `command -v`
+  - `/opt/ci/{build,output,scripts}` esistenti con owner `ci_build`
+  - `swapon --show` vuoto
+  - `sshd` attivo
+  - `PasswordAuthentication no` in sshd_config
+  - Root filesystem >= 38 GB (verifica che cloud-init `growpart` abbia funzionato):
+    ```bash
+    df -BG / | awk 'NR==2{gsub("G","",$2); if ($2+0 < 38) {print "FAIL: root fs too small"; exit 1}}'
+    ```
+  - Nessun installer residuo in `/tmp`
 
-### Fase D — Prepare-LinuxTemplateSetup.ps1 (orchestratore host-side)
+---
 
-Equivalente di `Prepare-WinBuild2025.ps1` per Linux. Usa SSH invece di WinRM.
+## Fase D  Adattamento script CI
 
-- [ ] **Pre-flight host**:
-  - SSH key esiste (`F:\CI\keys\ci_linux`)
-  - `ssh.exe` e `scp.exe` raggiungibili
-  - IP target risponde a `Test-NetConnection -Port 22`
-
-- [ ] **Copia script in VM**:
+- [x] **`scripts/_Transport.psm1`**  nuovo modulo SSH-only per il branch Linux.
+  Gli script Windows esistenti NON vengono modificati ora; il refactoring WinRM e' rinviato.
   ```powershell
-  scp -i F:\CI\keys\ci_linux -o StrictHostKeyChecking=accept-new `
-      template\Setup-LinuxTemplateVM.sh ci_build@${VMIPAddress}:/tmp/
+  function Invoke-SshCommand { param($IP, $User, $KeyPath, $Command, ...) }
+  function Copy-SshItem      { param($Source, $Dest, $IP, $User, $KeyPath, [ValidateSet('ToGuest','FromGuest')] $Direction, ...) }
+  function Test-SshReady     { param($IP, $User, $KeyPath, $TimeoutSec, ...) }
   ```
+  Gli script CI (`Invoke-CIJob`, `Invoke-RemoteBuild`, `Get-BuildArtifacts`) chiameranno
+  queste funzioni nel branch Linux senza toccare il branch WinRM esistente.
 
-- [ ] **Esegui script in VM**:
-  ```powershell
-  ssh -i F:\CI\keys\ci_linux ci_build@${VMIPAddress} `
-      "chmod +x /tmp/Setup-LinuxTemplateVM.sh && sudo /tmp/Setup-LinuxTemplateVM.sh"
-  ```
-  Cattura stdout + exit code, parse `[OK]`/`[FAIL]` lines.
+- [x] **`scripts/Invoke-CIJob.ps1`**  aggiungere parametro `-GuestOS Windows|Linux`
+  - Auto-detect da VMX `guestOS` field se non fornito
+  - Branch su transport (WinRM vs SSH) in ogni fase
 
-- [ ] **Post-setup remote validation** (parità Windows): query SSH per state checks:
-  - `systemctl is-active ssh` = active
-  - `id ci_build` ritorna gruppo + sudo
-  - `gcc --version`, `cmake --version`, `python3 --version` exit 0
-  - `test -d /opt/ci/build` exit 0
+- [x] **`scripts/Wait-VMReady.ps1`**  aggiungere `-Transport SSH`
+  - Probe: `Test-NetConnection -Port 22` + `ssh -o ConnectTimeout=5 ... "echo ok"`
 
-### Fase E — Snapshot
+- [x] **`scripts/Invoke-RemoteBuild.ps1`**  branch SSH+scp per Linux
+  - Transfer: `scp` invece di `Copy-Item -ToSession`
+  - Build: `ssh ... "cd /opt/ci/build && $BuildCommand"`
 
-- [ ] Solo se Prepare exit 0 → power off VM:
-  ```bash
-  sudo shutdown -h now
-  ```
-- [ ] Take snapshot in VMware Workstation: **`BaseClean-Linux`** (case-sensitive)
+- [x] **`scripts/Get-BuildArtifacts.ps1`**  branch `scp` per Linux
+  - `scp -r ci_build@$IP:/opt/ci/output/* $LocalArtifactDir\`
 
-### Fase F — Adattamento script CI
+- [ ] **`scripts/New-BuildVM.ps1`**  gia OS-agnostic (vmrun clone)
+  - Verificare che `-SnapshotName BaseClean-Linux` funzioni correttamente
 
-- [ ] **`scripts/_Transport.psm1`** (nuovo modulo) con interfaccia comune
-- [ ] **`scripts/Invoke-CIJob.ps1`** — aggiungere `-GuestOS Windows|Linux`, branching su transport
-- [ ] **`scripts/Wait-VMReady.ps1`** — supporto SSH probe (`Test-NetConnection -Port 22` + `ssh -o ConnectTimeout=5 ...`)
-- [ ] **`scripts/Invoke-RemoteBuild.ps1`** — branch SSH+scp per Linux
-- [ ] **`scripts/Get-BuildArtifacts.ps1`** — `scp` per Linux invece di `Copy-Item -FromSession`
-- [ ] **`scripts/New-BuildVM.ps1`** — already OS-agnostic (vmrun clone), verificare che `BaseClean-Linux` sia parametrizzabile
-- [ ] **`scripts/Remove-BuildVM.ps1`** — already OS-agnostic
+- [ ] **`scripts/Remove-BuildVM.ps1`**  gia OS-agnostic, nessuna modifica prevista
 
-### Fase G — Workflow Gitea
+---
 
-- [ ] **Registrare label `linux-build`** sul runner (oppure secondo runner dedicato):
+## Fase E  Runner e workflow Gitea
+
+- [x] **Label `linux-build`** aggiunta al runner in `runner/config.yaml`:
   ```yaml
-  # runner/config.yaml — aggiungere a labels esistenti
   labels:
     - 'windows-build:host'
     - 'linux-build:host'
   ```
 
-- [ ] **Workflow matrix**:
+- [x] **Variabile d'ambiente** `GITEA_CI_LINUX_TEMPLATE_PATH` nel servizio act_runner:
+  `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx`
+
+- [x] **Workflow matrix** di esempio (`gitea/workflow-example.yml` aggiornato):
   ```yaml
-  jobs:
-    build:
-      strategy:
-        matrix:
-          target: [windows, linux]
-      runs-on: ${{ matrix.target }}-build
-      steps:
-        - uses: actions/checkout@v4
-        - run: pwsh -File scripts/Invoke-CIJob.ps1 -GuestOS ${{ matrix.target }}
+  strategy:
+    matrix:
+      target: [windows, linux]
+  runs-on: ${{ matrix.target }}-build
   ```
 
-### Fase H — Test e2e
+---
 
-- [ ] **Smoke test** clone + SSH ready:
+## Fase F  Test e2e
+
+- [ ] **Smoke test**  linked clone + SSH ready:
   ```powershell
-  .\scripts\New-BuildVM.ps1 -JobId 'linux-smoke' -SnapshotName 'BaseClean-Linux'
-  .\scripts\Wait-VMReady.ps1 -JobId 'linux-smoke' -Transport SSH
-  .\scripts\Remove-BuildVM.ps1 -JobId 'linux-smoke'
+  .\scripts\New-BuildVM.ps1 -JobId 'linux-smoke-001' `
+      -TemplatePath 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
+      -SnapshotName 'BaseClean-Linux'
   ```
 
-- [ ] **Build reale**: scegliere repo con build Linux nativo (es. `cmake` based) e
-      eseguire job e2e via `Invoke-CIJob.ps1 -GuestOS Linux`
+- [ ] **Build test**  comando reale nella VM:
+  ```powershell
+  .\scripts\Invoke-CIJob.ps1 -JobId 'linux-e2e-001' -GuestOS Linux `
+      -RepoUrl 'ssh://gitea-ci/Simone/<repo>.git' -Branch 'main' `
+      -TemplatePath 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
+      -BuildCommand 'make -C /opt/ci/build all' `
+      -GuestArtifactSource '/opt/ci/output'
+  ```
 
-- [ ] **Confronto artifact**: build dello stesso repo target Windows vs Linux,
-      verifica che entrambi vengano raccolti in `F:\CI\Artifacts\<jobId>\`
+- [ ] **Cleanup**  linked clone rimosso dopo build (`Remove-BuildVM.ps1`)
+- [ ] **Matrix build**  run parallela Windows + Linux sullo stesso push
 
 ---
 
-## Differenze chiave rispetto al template Windows
+## Differenze da Windows  riepilogo
 
-| Aspetto                 | Windows                                | Linux                                       |
-| ----------------------- | -------------------------------------- | ------------------------------------------- |
-| Transport               | WinRM HTTP/5985 + Basic                | SSH/22 + ed25519 key                        |
-| Auth fluid              | `ci_build` admin + UAC off + LATFP=1   | `ci_build` + sudoers NOPASSWD               |
-| Trasferimento file      | `Copy-Item -ToSession`                 | `scp` o `rsync`                             |
-| Esecuzione remota       | `Invoke-Command -Session`              | `ssh user@host 'cmd'`                       |
-| AV/Firewall disable     | Defender + Win Firewall off            | ufw inattivo (default), no AV               |
-| Update package          | Windows Update (COM API + sched task)  | `apt-get update && upgrade` non-interactive |
-| Toolchain               | VS Build Tools 2026 + .NET SDK         | gcc/g++/clang + cmake (+ .NET SDK opt)      |
-| Snapshot name           | `BaseClean`                            | `BaseClean-Linux`                           |
-| Footprint VM            | 6 GB RAM, 80 GB disk                   | 4 GB RAM, 40 GB disk                        |
-| Boot time               | ~30-60 s post-clone                    | ~10-20 s post-clone (atteso)                |
+| Aspetto                 | Windows                                               | Linux                                          |
+| ----------------------- | ----------------------------------------------------- | ---------------------------------------------- |
+| Immagine di partenza    | ISO installer (Deploy ~60-90 min unattended)          | Cloud VMDK pre-built (boot + cloud-init ~60 s) |
+| Provisioning unattended | `autounattend.xml` (Windows Setup)                    | cloud-init `user-data` (seed ISO nocloud)      |
+| Transport host  VM      | WinRM HTTPS/5986 + PSSession                          | `ssh.exe` + `scp.exe` (built-in Windows 11)    |
+| NIC strategia           | e1000e install  vmxnet3 swap post-Tools               | vmxnet3 diretto (driver nativo kernel)         |
+| Setup script            | `.ps1` (PowerShell, via WinRM)                        | `.sh` (Bash, via SSH)                          |
+| Rilevamento IP          | `vmrun getGuestIPAddress` (VMware Tools)              | `vmrun getGuestIPAddress` (open-vm-tools)      |
+| Wait completamento      | polling flag file via `vmrun copyFileFromGuestToHost` | polling SSH + `boot-finished` cloud-init       |
+| CI dirs                 | `C:\CI\{build,output,scripts}`                        | `/opt/ci/{build,output,scripts,cache}`         |
+| Snapshot name           | `BaseClean`                                           | `BaseClean-Linux`                              |
 
 ---
 
-## Backlog correlato (TODO.md)
+## Riferimenti
 
-- **§6.1 [P2]** Linux Build VM — entry parent
-- **§6.4 [P3]** Build matrix `[windows, linux]` nel workflow
-- **§6.3 [P3]** Multi-host runner federation (se 4 VM Linux + 4 Windows non bastano)
-- **§5.2 [P2]** Modulo `_Transport.psm1` condiviso (prerequisito architetturale)
+- [ARCHITECTURE.md](ARCHITECTURE.md)  diagramma componenti (aggiornare dopo implementazione)
+- [CI-FLOW.md](CI-FLOW.md)  flusso pipeline (aggiornare Step 0 prerequisites)
+- [HOST-SETUP.md](HOST-SETUP.md)  Setup-Host.ps1 (aggiungere step generazione SSH key)
+- [TODO.md §6.1](../TODO.md)  tracking implementazione
 
----
-
-## Domande aperte
-
-1. **.NET SDK su Linux** — sempre installato o solo se workflow lo richiede?
-   Decisione: installare **se** workload richiede parità di build. Default off, opt-in via flag.
-2. **Image size** — Ubuntu minimal + toolchain ≈ 5 GB. Compact post-snapshot per ridurre footprint VMDK?
-   Decisione: sì, `dd if=/dev/zero` + `vmware-vdiskmanager -k` (manuale, una tantum).
-3. **Pre-warm pool Linux** — boot Linux è veloce, beneficio minore. Decisione: implementare solo se profile dimostra > 30% overhead.
-4. **Cloud-init vs script manuale** — cloud-init richiede ISO seed o NoCloud datasource. Più pulito ma overhead di setup. Decisione: script bash diretto (parità con flusso Windows). Cloud-init valutabile in v2.

docs/OPTIMIZATION.md

@@ -104,7 +104,7 @@ F:\CI\Cache\NuGet\   ← shared folder on host
 
 ### VMware Shared Folder Configuration (in template VMX)
 
-Add to `WinBuild.vmx` before taking the `BaseClean` snapshot:
+Add to `WinBuild2025.vmx` before taking the `BaseClean` snapshot:
 ```ini
 sharedFolder0.present = "TRUE"
 sharedFolder0.enabled = "TRUE"

docs/RUNBOOK.md

@@ -0,0 +1,351 @@
+# CI System Runbook
+
+Triage guide for the local CI/CD system. Each entry: symptom → triage commands → fix → escalation.
+
+---
+
+## 1. Runner offline in Gitea UI
+
+**Symptom**: `http://10.10.20.11:3100/admin/runners` shows `local-windows-runner` as offline.
+Queued jobs stay pending indefinitely.
+
+**Triage**:
+```powershell
+# Check service state
+Get-Service act_runner
+
+# Last 50 lines of runner log
+Get-Content 'F:\CI\act_runner\logs\act_runner.log' -Tail 50
+
+# Check registration file is intact
+Test-Path 'F:\CI\act_runner\.runner'
+```
+
+**Fix**:
+```powershell
+# Restart the service
+Restart-Service act_runner
+
+# Verify it came back online (wait ~10s then check Gitea UI)
+Get-Service act_runner | Select-Object Status, StartType
+
+# If service won't start, check NSSM log
+& 'C:\nssm\nssm.exe' status act_runner
+```
+
+If the `.runner` registration file is missing or corrupt, re-register:
+```powershell
+cd F:\CI\act_runner
+.\act_runner.exe register --no-interactive `
+    --instance http://10.10.20.11:3100 `
+    --token <token-from-gitea-admin> `
+    --name local-windows-runner `
+    --labels "windows-build:host,dotnet:host,msbuild:host"
+```
+
+**Escalation**: If the runner restarts but goes offline again within minutes, check Event Viewer → Application for `act_runner` errors and inspect `F:\CI\act_runner\logs\`.
+
+---
+
+## 2. All builds fail in Phase 2 (VM clone / start)
+
+**Symptom**: `Invoke-CIJob.ps1` fails at Phase 2 with errors like:
+- `vmrun clone failed`
+- `vmrun start failed`
+- `Template VMX not found`
+- `Could not detect VM IP address`
+
+**Triage**:
+```powershell
+# List all running VMs
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' -T ws list
+
+# Check template VMX exists and is accessible
+Test-Path 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+
+# Check for orphaned clones that may be consuming disk
+Get-ChildItem 'F:\CI\BuildVMs\' -Directory | Select-Object Name, LastWriteTime
+
+# Check disk free space
+Get-PSDrive F | Select-Object Name, Free, Used
+
+# Check for a stuck vm-start lock from a crashed job
+Test-Path 'F:\CI\State\vm-start.lock'
+```
+
+**Fix** — by root cause:
+
+*Template VMX missing/moved*: check `GITEA_CI_TEMPLATE_PATH` in `F:\CI\act_runner\config.yaml`.
+
+*Parent VMDK locked* (VMware left a lock file after host crash):
+```powershell
+# Stop all VMs
+& vmrun.exe -T ws stop 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' hard
+# Delete lock files
+Remove-Item 'F:\CI\Templates\WinBuild2025\*.lck' -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+*Snapshot missing* (`BaseClean` was deleted or renamed):
+```powershell
+# List snapshots on template VM
+& vmrun.exe -T ws listSnapshots 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+# Update GITEA_CI_SNAPSHOT_NAME in config.yaml to match the available snapshot name
+```
+
+*Disk full* (clone delta files need space):
+```powershell
+# Emergency cleanup — remove all orphaned clones
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Cleanup-OrphanedBuildVMs.ps1' -MaxAgeHours 0
+# Then run retention
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-RetentionPolicy.ps1' -AggressiveRetentionDays 3
+```
+
+*Stale vm-start lock* (from a job that crashed without cleanup):
+```powershell
+Remove-Item 'F:\CI\State\vm-start.lock' -Force
+Remove-Item 'F:\CI\State\ip-leases\*.lease' -Force
+```
+
+**Escalation**: If `vmrun clone` fails with exit code -1 even after clearing locks and confirming disk space, re-open VMware Workstation UI and check the template VM is intact and the snapshot is listed.
+
+---
+
+## 3. Builds are slow
+
+**Symptom**: jobs that previously completed in ~3 min now take 8+ min.
+Phase durations visible in `F:\CI\Logs\<jobId>\invoke-ci.jsonl`.
+
+**Triage**:
+```powershell
+# Check disk free space (below 50 GB = fragmented writes)
+Get-PSDrive F | Select-Object @{n='FreeGB';e={[math]::Round($_.Free/1GB,1)}}
+
+# Check active VM CPU usage (Task Manager or:)
+Get-Process vmware-vmx | Select-Object CPU, WorkingSet | Sort-Object CPU -Descending
+
+# Check VMnet8 NAT adapter status
+Get-NetAdapter | Where-Object { $_.Name -like 'VMware*' }
+
+# Parse JSONL for per-phase durations (requires jq or manual inspection)
+# Each phase has a 'start' and 'success' event — diff the 'ts' fields.
+Get-Content 'F:\CI\Logs\<jobId>\invoke-ci.jsonl' | ConvertFrom-Json | Format-Table ts,phase,status
+```
+
+**Fix** — by root cause:
+
+*Low disk space → fragmented VMDKs*: run retention policy, then consider `vmware-vdiskmanager -d` to defragment the template VMDK.
+
+*High vmware-vmx CPU with many VMs*: reduce `capacity` in `config.yaml` from 4 to 2.
+
+*VMnet8 NAT bottleneck* (slow pip/nuget downloads inside VM): check `Services.msc` → `VMware NAT Service` is running.
+
+*NVMe saturation*: if the host NVMe is at 100% I/O (Task Manager → Performance → Disk), all four concurrent VMs are competing. Reduce `capacity: 2`.
+
+**Escalation**: Use `invoke-ci.jsonl` to identify which phase is slow across multiple jobs. Phase 1 slow = host git or network. Phase 2-3b slow = disk I/O. Phase 5 slow = build itself (not a CI infra problem).
+
+---
+
+## 4. Template VMX corrupt after host crash
+
+**Symptom**: After an unclean host shutdown, `vmrun clone` or `vmrun start` on the template fails. VMware Workstation shows the template in an error state.
+
+**Triage**:
+```powershell
+# Try starting the template directly in VMware Workstation UI
+# If it reports "configuration file error" or "disk lock", proceed below.
+
+# Check for lock files
+Get-ChildItem 'F:\CI\Templates\WinBuild2025\' -Recurse -Filter '*.lck'
+
+# Check if backup exists
+Get-ChildItem 'F:\CI\Backups\' -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 5
+```
+
+**Fix**:
+
+*Lock files only* (common after hard shutdown):
+```powershell
+# Ensure no VMware processes are running
+Get-Process vmware*, vmrun -ErrorAction SilentlyContinue | Stop-Process -Force
+# Remove locks
+Remove-Item 'F:\CI\Templates\WinBuild2025\*.lck' -Recurse -Force
+# Test clone
+& vmrun.exe -T ws listSnapshots 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+```
+
+*VMX or VMDK truly corrupt — restore from backup*:
+```powershell
+# Stop all CI activity first
+Stop-Service act_runner
+
+# Identify latest backup
+$latest = Get-ChildItem 'F:\CI\Backups\' -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+Write-Host "Restoring from: $($latest.FullName)"
+
+# Replace template directory
+Remove-Item 'F:\CI\Templates\WinBuild2025\' -Recurse -Force
+Copy-Item $latest.FullName 'F:\CI\Templates\WinBuild2025\' -Recurse
+
+# Restart runner
+Start-Service act_runner
+```
+
+*No backup exists*: must re-provision the template from scratch.
+Follow `docs/WINDOWS-TEMPLATE-SETUP.md` → Fase A (Deploy) → Fase B (Prepare).
+Estimated time: 2-4 hours including Windows Update.
+
+**Escalation**: If VMware Workstation itself is damaged (rare), reinstall VMware and re-import the template VMX. The VMDK files survive a VMware reinstall as long as the disk is intact.
+
+---
+
+## Quick Reference
+
+| Symptom             | First command                                                      |
+| ------------------- | ------------------------------------------------------------------ |
+| Runner offline      | `Get-Service act_runner`, then `Restart-Service act_runner`        |
+| Phase 2 clone fails | `Test-Path F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`          |
+| Disk full           | `Get-PSDrive F \| Select Free`; run `Invoke-RetentionPolicy.ps1`   |
+| Stale lock          | `Remove-Item F:\CI\State\vm-start.lock`                            |
+| Slow builds         | Check `invoke-ci.jsonl` phase timestamps; check disk I/O           |
+| Template corrupt    | Remove `*.lck` files; if persistent, restore from `F:\CI\Backups\` |
+| Snapshot missing    | `vmrun listSnapshots <vmx>`; update `GITEA_CI_SNAPSHOT_NAME`       |
+| IP collision        | `Remove-Item F:\CI\State\ip-leases\*.lease`; lower `capacity`      |
+
+---
+
+## 5. Template Refresh Procedure
+
+Use this procedure when the template OS needs updated packages, toolchain upgrades, or
+a new snapshot.  Run on the **host** with an elevated PowerShell 5.1 session.
+
+### 5.1 Pre-flight
+
+```powershell
+# Stop the runner so no CI jobs start during the refresh
+Stop-Service act_runner
+
+# Verify no clone VMs are running
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' list
+# Expected: "Total running VMs: 0"
+
+# Backup the existing template (keeps last 3 by default)
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Backup-CITemplate.ps1' -AllTemplates
+```
+
+### 5.2 Boot the template
+
+**Windows (WinBuild2025)**:
+```powershell
+$vmx = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' start $vmx gui
+```
+
+**Linux (LinuxBuild2404)**:
+```powershell
+$vmx = 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx'
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' start $vmx gui
+```
+
+### 5.3 Apply updates inside the template
+
+**Windows** — connect via WinRM or open the VMware console, then run the Prepare
+script from the host:
+```powershell
+$vmxWin   = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+$credTgt  = 'BuildVMGuest'    # Windows Credential Manager target
+$cred     = Get-StoredCredential -Target $credTgt   # requires CredentialManager module
+& 'N:\Code\Workspace\Local-CI-CD-System\template\Prepare-WinBuild2025.ps1' `
+    -VMXPath    $vmxWin `
+    -Credential $cred
+```
+
+**Linux** — SSH into the template and run the toolchain script:
+```powershell
+$vmxLin = 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx'
+# Get IP (wait for VMware Tools if needed)
+$ip = & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' getGuestIPAddress $vmxLin -wait
+# Apply updates
+& 'N:\Code\Workspace\Local-CI-CD-System\template\Prepare-LinuxBuild2404.ps1' `
+    -VMXPath  $vmxLin `
+    -SshKeyPath 'F:\CI\keys\ci_linux'
+```
+
+Alternatively, run `Install-CIToolchain-WinBuild2025.ps1` / `Install-CIToolchain-Linux2404.sh`
+manually inside the guest to apply only toolchain changes without the full Prepare script.
+
+### 5.4 Shut down and snapshot
+
+```powershell
+# Shut down gracefully (wait up to 120 s)
+$vmx = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'   # or Linux vmx
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' stop $vmx soft
+
+# Name: BaseClean_yyyyMMdd  (keeps old name for rollback reference)
+$snapshotName = "BaseClean_$(Get-Date -Format 'yyyyMMdd')"
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' snapshot $vmx $snapshotName
+Write-Host "Snapshot created: $snapshotName"
+```
+
+Confirm no `.vmem` / `.vmsn` files exist before snapshotting (see AGENTS.md item 9):
+```powershell
+Get-ChildItem (Split-Path $vmx) -Filter '*.vmem'  # must be empty
+```
+
+### 5.5 Validate
+
+```powershell
+# Run the validation script
+& 'N:\Code\Workspace\Local-CI-CD-System\template\Validate-DeployState.ps1' `
+    -VMXPath $vmx -SnapshotName $snapshotName
+```
+
+For Linux, also run a quick SSH smoke-test from the host:
+```powershell
+Import-Module 'N:\Code\Workspace\Local-CI-CD-System\scripts\_Transport.psm1' -Force
+$result = Invoke-SshCommand -IP $ip -KeyPath 'F:\CI\keys\ci_linux' `
+    -Command 'gcc --version && cmake --version' -PassThru
+$result.Output
+```
+
+### 5.6 Run a smoke workflow
+
+Push a trivial commit to a test repo or trigger a manual workflow run via Gitea UI.
+Confirm the job uses the new snapshot and completes successfully.
+
+### 5.7 Promote the new snapshot
+
+Update `GITEA_CI_SNAPSHOT_NAME` in `runner/config.yaml` and redeploy:
+```powershell
+# Edit runner/config.yaml: set GITEA_CI_SNAPSHOT_NAME to $snapshotName
+notepad 'N:\Code\Workspace\Local-CI-CD-System\runner\config.yaml'
+
+# Deploy config and restart runner
+Copy-Item 'N:\Code\Workspace\Local-CI-CD-System\runner\config.yaml' `
+          'F:\CI\act_runner\config.yaml' -Force
+Restart-Service act_runner
+```
+
+### 5.8 Retain old snapshot 7 days, then delete
+
+Keep the previous `BaseClean_*` snapshot for 7 days as a rollback point:
+```powershell
+# List existing snapshots
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' listSnapshots $vmx
+
+# After 7 days, delete the old snapshot (replace OLDNAME with actual name)
+# & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' deleteSnapshot $vmx OLDNAME
+```
+
+### 5.9 Rollback procedure
+
+If a smoke-test failure is discovered after promotion:
+```powershell
+# Revert runner/config.yaml to prior GITEA_CI_SNAPSHOT_NAME
+# (or set it back to 'BaseClean' for the permanent base)
+Copy-Item 'N:\Code\Workspace\Local-CI-CD-System\runner\config.yaml' `
+          'F:\CI\act_runner\config.yaml' -Force
+Restart-Service act_runner
+# The prior snapshot is still in the template — jobs will use it immediately.
+```
+
+

docs/Setup-GiteaSSH.md

@@ -1,6 +1,6 @@
 # Configurazione accesso SSH a Gitea
 
-**Target**: clone da `git@gitea.emulab.it:Simone/nsis-plugin-nsinnounp.git`  
+**Target**: clone da `git@gitea.emulab.it:Simone/nsis-plugin-ns7zip.git`  
 **Gitea**: `http://10.10.20.11:3100` / `https://gitea.emulab.it`
 
 ---
@@ -83,13 +83,13 @@ Hi there, Simone! You've successfully authenticated with the key named ci-build@
 Usare l'alias `gitea-ci` definito in `~\.ssh\config`:
 
 ```powershell
--RepoUrl 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git'
+-RepoUrl 'ssh://gitea-ci/Simone/nsis-plugin-ns7zip.git'
 ```
 
 Oppure con IP/porta espliciti (equivalente):
 
 ```powershell
--RepoUrl 'ssh://git@10.10.20.11:2222/Simone/nsis-plugin-nsinnounp.git'
+-RepoUrl 'ssh://git@10.10.20.11:2222/Simone/nsis-plugin-ns7zip.git'
 ```
 
 ---

docs/WINDOWS-TEMPLATE-SETUP.md

@@ -1,4 +1,4 @@
-# Windows Template VM Setup
+# Windows Template VM Setup
 
 Procedura di provisioning della template VM **Windows Server 2025** che alimenta i linked
 clone usati per ogni job CI. Il template viene creato **una volta**; lo snapshot
@@ -11,34 +11,37 @@ credenziali archiviate, ISO Windows Server presente).
 
 ## Architettura: tre script
 
-| Script                                   | Dove gira       | Scopo                                                               |
-| ---------------------------------------- | --------------- | ------------------------------------------------------------------- |
-| `template/Deploy-WinBuild2025.ps1`      | **Host**        | Opzionale: crea VM e installa Windows unattended da ISO             |
-| `template/Prepare-WinBuild2025.ps1`     | **Host**        | Orchestratore: copia + esegue Setup nel guest via WinRM             |
-| `template/Setup-WinBuild2025.ps1`       | **Dentro VM**   | CI toolchain (user, .NET, Python, VS) + validazione hardening Deploy |
-| `template/Validate-DeployState.ps1`     | **Host**        | Valida stato post-Deploy prima di eseguire Prepare                  |
-| `template/Validate-SetupState.ps1`      | **Host**        | Valida stato post-Setup (Deploy + Setup) prima dello snapshot       |
+| Script                                          | Dove gira     | Scopo                                                                |
+| ----------------------------------------------- | ------------- | -------------------------------------------------------------------- |
+| `template/Deploy-WinBuild2025.ps1`              | **Host**      | Opzionale: crea VM e installa Windows Server 2025 unattended da ISO  |
+| `template/Prepare-WinBuild2025.ps1`             | **Host**      | Orchestratore: copia + esegue Setup nel guest via WinRM (2025)       |
+| `template/Install-CIToolchain-WinBuild2025.ps1` | **Dentro VM** | CI toolchain (user, .NET, Python, VS) + validazione hardening Deploy |
+| `template/Deploy-WinBuild2022.ps1`              | **Host**      | Opzionale: crea VM e installa Windows Server 2022 unattended da ISO  |
+| `template/Prepare-WinBuild2022.ps1`             | **Host**      | Orchestratore: copia + esegue Setup nel guest via WinRM (2022)       |
+| `template/Install-CIToolchain-WinBuild2022.ps1` | **Dentro VM** | CI toolchain per Windows Server 2022 (stesso flusso del 2025)        |
+| `template/Validate-DeployState.ps1`             | **Host**      | Valida stato post-Deploy prima di eseguire Prepare (2025 e 2022)     |
+| `template/Validate-SetupState.ps1`              | **Host**      | Valida stato post-Setup (Deploy + Setup) prima dello snapshot        |
 
 **Confine Deploy / Setup** (refactor §7, 2026-05-10):
 - `Deploy-WinBuild2025.ps1` si occupa dell'**OS hardening** (Firewall, WinRM, UAC, Defender, UX tweaks, autologin Administrator, WU GPO locks). Se usato, Setup valida questi come Assert-Step senza re-applicarli.
-- `Setup-WinBuild2025.ps1` si occupa della **CI customization** (utente `ci_build`, cartelle `C:\CI`, toolchain .NET/Python/VS, Windows Update lifecycle, cleanup, final gate).
+- `Install-CIToolchain-WinBuild2025.ps1` si occupa della **CI customization** (utente `ci_build`, cartelle `C:\CI`, toolchain .NET/Python/VS, Windows Update lifecycle, cleanup, final gate).
 
-`Prepare-WinBuild2025.ps1` apre una WinRM session, copia `Setup-WinBuild2025.ps1` in
+`Prepare-WinBuild2025.ps1` apre una WinRM session, copia `Install-CIToolchain-WinBuild2025.ps1` in
 `C:\CI\`, lo esegue, raccoglie l'exit code, valida lo stato del guest.
 
 ---
 
 ## Specifiche VM
 
-| Parametro               | Valore                                                          |
-| ----------------------- | --------------------------------------------------------------- |
-| OS                      | Windows Server 2025 Standard/Datacenter (Core o Desktop OK)     |
-| vCPU                    | 4                                                               |
-| RAM                     | 6144 MB (6 GB)                                                  |
-| Disco                   | 80 GB thin provisioned                                          |
-| NIC                     | **VMnet8 (NAT)** — internet richiesto per WU + installer        |
-| VMX path                | `F:\CI\Templates\WinBuild\CI-WinBuild.vmx`                      |
-| ISO                     | Windows Server 2025 (da `F:\CI\ISO\`)                           |
+| Parametro | Valore                                                      |
+| --------- | ----------------------------------------------------------- |
+| OS        | Windows Server 2025 Standard/Datacenter (Core o Desktop OK) |
+| vCPU      | 4                                                           |
+| RAM       | 6144 MB (6 GB)                                              |
+| Disco     | 80 GB thin provisioned                                      |
+| NIC       | **VMnet8 (NAT)** — internet richiesto per WU + installer    |
+| VMX path  | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`             |
+| ISO       | Windows Server 2025 (da `F:\CI\ISO\`)                       |
 
 ---
 
@@ -48,7 +51,7 @@ credenziali archiviate, ISO Windows Server presente).
 - File → New Virtual Machine → Custom
 - Hardware: 4 vCPU, 6144 MB, 80 GB thin
 - Network: **VMnet8 (NAT)**
-- VMX: `F:\CI\Templates\WinBuild\CI-WinBuild.vmx`
+- VMX: `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
 - CD/DVD: monta ISO Windows Server 2025
 
 ### A.2 Installa Windows Server 2025
@@ -65,7 +68,8 @@ winrm quickconfig -q
 ```powershell
 Enable-PSRemoting -Force -SkipNetworkProfileCheck
 Set-Item WSMan:\localhost\Service\Auth\Basic $true -Force
-Set-Item WSMan:\localhost\Service\AllowUnencrypted $true -Force
+# AllowUnencrypted left false — Deploy post-install.ps1 creates HTTPS/5986 listener
+# Basic auth is secure over HTTPS; host connects on port 5986 with -SkipCACheck
 Set-Item WSMan:\localhost\Client\TrustedHosts -Value '*' -Force
 ```
 
@@ -110,15 +114,15 @@ cd N:\Code\Workspace\Local-CI-CD-System\template
 
 Ogni step ha validazione `Assert-Step` (throw on failure, `[OK]` su pass):
 
-1. **Pre-flight**: script dir presente, `Setup-WinBuild2025.ps1` presente, IP ottetti 0-255, TCP/5985 reachable
-2. **Configura host WinRM client**: `AllowUnencrypted=true`, aggiunge `$VMIPAddress` ai `TrustedHosts`
-   - Salva valori precedenti, ripristinati nel `finally` (host posture invariata)
-3. **Validazione host WinRM**: `AllowUnencrypted=true`, `TrustedHosts` include IP
-4. **Test connettività**: `Test-WSMan -Authentication Basic` con credenziali admin
-5. **Apre PSSession** verso la VM
+1. **Pre-flight**: script dir presente, `Install-CIToolchain-WinBuild2025.ps1` presente, IP ottetti 0-255, TCP/5986 reachable
+2. **Configura host WinRM client**: aggiunge `$VMIPAddress` ai `TrustedHosts` (no `AllowUnencrypted` — HTTPS non lo richiede)
+   - Salva valore precedente, ripristinato nel `finally` (host posture invariata)
+3. **Validazione host WinRM**: `TrustedHosts` include IP
+4. **Test connettività**: `Test-WSMan -Port 5986 -UseSSL -Authentication Basic` con credenziali admin
+5. **Apre PSSession** `-UseSSL -Port 5986` verso la VM
 6. **Crea `C:\CI`** in guest, valida creazione
-7. **Copia `Setup-WinBuild2025.ps1`** in `C:\CI\Setup-WinBuild2025.ps1`, valida size match
-8. **Esegue `Setup-WinBuild2025.ps1`** dentro la VM (vedi Fase C)
+7. **Copia `Install-CIToolchain-WinBuild2025.ps1`** in `C:\CI\Install-CIToolchain-WinBuild2025.ps1`, valida size match
+8. **Esegue `Install-CIToolchain-WinBuild2025.ps1`** dentro la VM (vedi Fase C)
 9. **Gestisce reboot 3010**: se WU richiede reboot, riavvia VM e suggerisce re-run con `-SkipWindowsUpdate`
 10. **Post-setup remote validation** (9 check via singola `Invoke-Command`):
     - WinRM Running
@@ -133,21 +137,21 @@ Ogni step ha validazione `Assert-Step` (throw on failure, `[OK]` su pass):
 
 ### Parametri principali
 
-| Parametro             | Default        | Note                                                                          |
-| --------------------- | -------------- | ----------------------------------------------------------------------------- |
-| `-VMIPAddress`        | (mandatory)    | IP DHCP della VM su VMnet8                                                    |
-| `-AdminUsername`      | Administrator  | Account admin built-in nella VM                                               |
-| `-AdminPassword`      | (prompt)       | Se vuoto, prompt SecureString                                                 |
-| `-BuildPassword`      | (prompt)       | Password per `ci_build` — mai hard-codare                                     |
-| `-BuildUsername`      | ci_build       | Account CI dentro la VM                                                       |
-| `-DotNetSdkVersion`   | 10.0           | Channel .NET SDK                                                              |
-| `-SkipWindowsUpdate`  | (off)          | Pass-through a Setup-WinBuild2025.ps1                                         |
-| `-StoreCredential`    | (off)          | Registra `BuildUsername`/`BuildPassword` in Windows Credential Manager       |
-| `-CredentialTarget`   | BuildVMGuest   | Target Credential Manager (deve corrispondere a quanto usato da Invoke-CIJob) |
+| Parametro            | Default       | Note                                                                          |
+| -------------------- | ------------- | ----------------------------------------------------------------------------- |
+| `-VMIPAddress`       | (mandatory)   | IP DHCP della VM su VMnet8                                                    |
+| `-AdminUsername`     | Administrator | Account admin built-in nella VM                                               |
+| `-AdminPassword`     | (prompt)      | Se vuoto, prompt SecureString                                                 |
+| `-BuildPassword`     | (prompt)      | Password per `ci_build` — mai hard-codare                                     |
+| `-BuildUsername`     | ci_build      | Account CI dentro la VM                                                       |
+| `-DotNetSdkVersion`  | 10.0          | Channel .NET SDK                                                              |
+| `-SkipWindowsUpdate` | (off)         | Pass-through a Install-CIToolchain-WinBuild2025.ps1                           |
+| `-StoreCredential`   | (off)         | Registra `BuildUsername`/`BuildPassword` in Windows Credential Manager        |
+| `-CredentialTarget`  | BuildVMGuest  | Target Credential Manager (deve corrispondere a quanto usato da Invoke-CIJob) |
 
 ---
 
-## Fase C — Cosa fa `Setup-WinBuild2025.ps1` (dentro la VM)
+## Fase C — Cosa fa `Install-CIToolchain-WinBuild2025.ps1` (dentro la VM)
 
 Eseguito automaticamente da Prepare in Fase B. Steps 1/2/3/4b/5b/5c sono
 **validation-only** — verificano che Deploy abbia già applicato l'hardening OS.
@@ -189,23 +193,23 @@ Final    Pre-snapshot gate — 7 check cross-cutting + no installer leftover
 
 ### Validazioni per step (sintesi)
 
-| Step | Natura     | Check chiave                                                                   |
-| ---- | ---------- | ------------------------------------------------------------------------------ |
-| 1    | Assert     | `Get-NetFirewallProfile -Profile Domain/Private/Public → Enabled=False`        |
-| 2    | Assert     | GPO DisableAntiSpyware=1 (set da Deploy)                                       |
-| 3    | Assert     | WinRM Running+Automatic, AllowUnencrypted=true, Auth/Basic=true, MaxMem≥2048   |
-| 4    | Operativo  | User exists, enabled, PasswordNeverExpires, member of Administrators           |
-| 4b   | Assert     | EnableLUA=0, LocalAccountTokenFilterPolicy=1                                   |
-| 5    | Operativo  | Ogni dir Test-Path -PathType Container                                         |
-| 5b   | Assert     | HKCU LaunchTo=1                                                                |
-| 5c   | Assert+Op  | NoLockScreen=1, SM policy DoNotOpenAtLogon=1, SM task Disabled, DisableCAD=1, OOBE DisablePrivacyExperience=1, AllowTelemetry=0; AutoAdminLogon=1+DefaultUserName=Administrator re-affermati se assenti (Windows OOBE può resettarli al primo boot) |
-| 6    | Operativo  | ResultCode ∈ {0,2,3}, no reboot required (else exit 3010)                      |
-| 6b   | Operativo  | wuauserv StartType=Disabled, NoAutoUpdate=1, DisableWindowsUpdateAccess=1      |
-| 7    | Operativo  | `dotnet --version` channel match, machine PATH contiene `C:\dotnet`            |
-| 8    | Operativo  | `C:\Python\python.exe` esiste, version match esatto, PATH contiene `C:\Python` |
-| 9    | Operativo  | MSBuild.exe esiste, esegue, PATH, `\VC\` dir presente                          |
-| 10   | Operativo  | dotnet+python+msbuild tutti risolvibili (throw)                                |
-| Final| Cross-cut  | WinRM, firewall, user+admin, UAC, WU disabled, tutti tool, no leftover installer in `C:\CI` |
+| Step  | Natura    | Check chiave                                                                                                                                                                                                                                        |
+| ----- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1     | Assert    | `Get-NetFirewallProfile -Profile Domain/Private/Public → Enabled=False`                                                                                                                                                                             |
+| 2     | Assert    | GPO DisableAntiSpyware=1 (set da Deploy)                                                                                                                                                                                                            |
+| 3     | Assert    | WinRM Running+Automatic, AllowUnencrypted=false (HTTPS-only), Auth/Basic=true, MaxMem≥2048                                                                                                                                                          |
+| 4     | Operativo | User exists, enabled, PasswordNeverExpires, member of Administrators                                                                                                                                                                                |
+| 4b    | Assert    | EnableLUA=0, LocalAccountTokenFilterPolicy=1                                                                                                                                                                                                        |
+| 5     | Operativo | Ogni dir Test-Path -PathType Container                                                                                                                                                                                                              |
+| 5b    | Assert    | HKCU LaunchTo=1                                                                                                                                                                                                                                     |
+| 5c    | Assert+Op | NoLockScreen=1, SM policy DoNotOpenAtLogon=1, SM task Disabled, DisableCAD=1, OOBE DisablePrivacyExperience=1, AllowTelemetry=0; AutoAdminLogon=1+DefaultUserName=Administrator re-affermati se assenti (Windows OOBE può resettarli al primo boot) |
+| 6     | Operativo | ResultCode ∈ {0,2,3}, no reboot required (else exit 3010)                                                                                                                                                                                           |
+| 6b    | Operativo | wuauserv StartType=Disabled, NoAutoUpdate=1, DisableWindowsUpdateAccess=1                                                                                                                                                                           |
+| 7     | Operativo | `dotnet --version` channel match, machine PATH contiene `C:\dotnet`                                                                                                                                                                                 |
+| 8     | Operativo | `C:\Python\python.exe` esiste, version match esatto, PATH contiene `C:\Python`                                                                                                                                                                      |
+| 9     | Operativo | MSBuild.exe esiste, esegue, PATH, `\VC\` dir presente                                                                                                                                                                                               |
+| 10    | Operativo | dotnet+python+msbuild tutti risolvibili (throw)                                                                                                                                                                                                     |
+| Final | Cross-cut | WinRM, firewall, user+admin, UAC, WU disabled, tutti tool, no leftover installer in `C:\CI`                                                                                                                                                         |
 
 ---
 
@@ -218,7 +222,7 @@ Final    Pre-snapshot gate — 7 check cross-cutting + no installer leftover
    - VM → Snapshot → Take Snapshot
    - **Nome esatto: `BaseClean`** (case-sensitive, usato da `New-BuildVM.ps1`)
 3. **Lascia la VM spenta** — non modificarla mai più dopo lo snapshot
-4. **Verifica `runner/config.yaml`**: `GITEA_CI_TEMPLATE_PATH=F:\CI\Templates\WinBuild\CI-WinBuild.vmx`
+4. **Verifica `runner/config.yaml`**: `GITEA_CI_TEMPLATE_PATH=F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
 
 ---
 
@@ -288,15 +292,15 @@ toolchain (.NET, VS Build Tools, Python).
 
 ## Troubleshooting
 
-| Sintomo                                     | Diagnosi / Fix                                                          |
-| ------------------------------------------- | ----------------------------------------------------------------------- |
-| `Cannot reach $VMIPAddress via WinRM`       | VM non avviata, WinRM non abilitato, IP errato — verifica con ipconfig  |
-| `Setup-WinBuild2025.ps1 exited with code 3010`| Reboot richiesto post-WU. Re-run con `-SkipWindowsUpdate`               |
-| `[Defender] Validation failed: GPO key`     | Defender riattivato da Windows Update — disabilita via gpedit + reboot  |
-| `VS Build Tools installation timed out`     | Network slow o cache corrotta. Re-run con cache pulita (`C:\ProgramData\Microsoft\VisualStudio\Packages`) |
-| `Python version match` fail                 | `$PythonVersion` ≠ versione installata. Aggiorna param o reinstalla     |
-| Post-setup `MSBuild not found`              | VS install fallita silenziosa. Check `C:\CI\vs_log.txt`                 |
-| Pre-snapshot Final check fail               | Stato VM rotto — non prendere snapshot. Re-run o ricomincia da zero     |
+| Sintomo                                                      | Diagnosi / Fix                                                                                            |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `Cannot reach $VMIPAddress via WinRM`                        | VM non avviata, WinRM non abilitato, IP errato — verifica con ipconfig                                    |
+| `Install-CIToolchain-WinBuild2025.ps1 exited with code 3010` | Reboot richiesto post-WU. Re-run con `-SkipWindowsUpdate`                                                 |
+| `[Defender] Validation failed: GPO key`                      | Defender riattivato da Windows Update — disabilita via gpedit + reboot                                    |
+| `VS Build Tools installation timed out`                      | Network slow o cache corrotta. Re-run con cache pulita (`C:\ProgramData\Microsoft\VisualStudio\Packages`) |
+| `Python version match` fail                                  | `$PythonVersion` ≠ versione installata. Aggiorna param o reinstalla                                       |
+| Post-setup `MSBuild not found`                               | VS install fallita silenziosa. Check `C:\CI\vs_log.txt`                                                   |
+| Pre-snapshot Final check fail                                | Stato VM rotto — non prendere snapshot. Re-run o ricomincia da zero                                       |
 
 ---
 
@@ -308,3 +312,4 @@ toolchain (.NET, VS Build Tools, Python).
 - **§2.5 [P1]** Snapshot versionato `BaseClean_<yyyyMMdd>` (rollback in caso di refresh rotto)
 - **§2.6 [P2]** Backup automatico VMDK template pre-snapshot
 - **In-VM Git Clone** — installare Git for Windows + 7-Zip nel template per ottimizzare flusso
+

docs/WORKFLOW-AUTHORING.md

@@ -0,0 +1,578 @@
+# Workflow Authoring Reference
+
+> Reference document for AI agents and developers writing Gitea Actions workflows
+> for the Local CI/CD System.
+> Keep this document in sync with `runner/config.yaml` and `scripts/Invoke-CIJob.ps1`.
+
+---
+
+## Table of Contents
+
+- [Workflow Authoring Reference](#workflow-authoring-reference)
+  - [Table of Contents](#table-of-contents)
+  - [1. System Overview](#1-system-overview)
+  - [2. Runner Labels](#2-runner-labels)
+  - [3. Shell Requirement](#3-shell-requirement)
+  - [4. Environment Variables (Injected by Runner)](#4-environment-variables-injected-by-runner)
+  - [5. Invoke-CIJob.ps1 Parameter Reference](#5-invoke-cijobps1-parameter-reference)
+    - [Mandatory parameters](#mandatory-parameters)
+    - [Optional parameters](#optional-parameters)
+  - [6. URL Conventions](#6-url-conventions)
+    - [Host-clone mode (default, no `-UseGitClone`)](#host-clone-mode-default-no--usegitclone)
+    - [UseGitClone mode (`-UseGitClone`)](#usegitclone-mode--usegitclone)
+    - [Quick reference](#quick-reference)
+  - [7. Artifact Path Convention](#7-artifact-path-convention)
+  - [8. Workflow Patterns](#8-workflow-patterns)
+    - [8.1 Windows build (host-clone mode)](#81-windows-build-host-clone-mode)
+    - [8.2 Linux build (host-clone mode)](#82-linux-build-host-clone-mode)
+    - [8.3 Windows build (UseGitClone mode)](#83-windows-build-usegitclone-mode)
+    - [8.4 Linux build (UseGitClone mode)](#84-linux-build-usegitclone-mode)
+    - [8.5 PSScriptAnalyzer lint](#85-psscriptanalyzer-lint)
+    - [8.6 Matrix build (multiple configs)](#86-matrix-build-multiple-configs)
+  - [9. Checkout Step](#9-checkout-step)
+  - [10. Timeouts](#10-timeouts)
+  - [11. Common Mistakes](#11-common-mistakes)
+
+---
+
+## 1. System Overview
+
+The CI system runs entirely on a local Windows 11 host. Gitea triggers jobs; act_runner
+executes them. Every build step runs inside an ephemeral VMware VM — the runner host
+itself never invokes compilers or build tools. The entire VM lifecycle is managed by
+`Invoke-CIJob.ps1`.
+
+```
+git push → Gitea → act_runner (host) → Invoke-CIJob.ps1 → VM lifecycle
+                                                           ├── New-BuildVM
+                                                           ├── Wait-VMReady
+                                                           ├── Invoke-RemoteBuild
+                                                           ├── Get-BuildArtifacts
+                                                           └── Remove-BuildVM (always)
+```
+
+Supported guest OS: Windows Server 2025 / 2022 (WinRM transport), Ubuntu 24.04 (SSH transport).
+
+---
+
+## 2. Runner Labels
+
+| Label           | Configured as        | Use for                                    |
+| --------------- | -------------------- | ------------------------------------------ |
+| `windows-build` | `windows-build:host` | Windows VM builds, Windows-only tools      |
+| `linux-build`   | `linux-build:host`   | Linux VM builds (cross-compile, GCC/Clang) |
+| `dotnet`        | `dotnet:host`        | Alias for windows-build (legacy)           |
+| `msbuild`       | `msbuild:host`       | Alias for windows-build (legacy)           |
+
+Both `windows-build` and `linux-build` run on the same physical host. Only the
+template VM used differs. Use `windows-build` unless you specifically need a Linux
+guest (cross-compile, GCC, CMake, Python/Linux toolchains).
+
+---
+
+## 3. Shell Requirement
+
+**Always use `shell: powershell`** (Windows PowerShell 5.1).
+
+Never use `shell: pwsh` — that invokes PowerShell Core 7+ which is not the
+required runtime and may not be present on the host.
+
+```yaml
+# CORRECT
+- name: Build
+  shell: powershell
+  run: |
+    ...
+
+# WRONG — do not use
+- name: Build
+  shell: pwsh     # PowerShell 7+ — not supported
+  run: |
+    ...
+```
+
+---
+
+## 4. Environment Variables (Injected by Runner)
+
+These variables are automatically available in every job step. Do not redeclare them
+in the workflow unless you need to override the default.
+
+| Variable                       | Value (default)                                     | Description                            |
+| ------------------------------ | --------------------------------------------------- | -------------------------------------- |
+| `GITEA_CI_TEMPLATE_PATH`       | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`     | Windows 2025 template VMX path         |
+| `GITEA_CI_LINUX_TEMPLATE_PATH` | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` | Ubuntu 24.04 template VMX path         |
+| `GITEA_CI_CLONE_BASE_DIR`      | `F:\CI\BuildVMs`                                    | Directory for ephemeral VM clones      |
+| `GITEA_CI_ARTIFACT_DIR`        | `F:\CI\Artifacts`                                   | Root directory for job artifacts       |
+| `GITEA_CI_GUEST_CRED_TARGET`   | `BuildVMGuest`                                      | Credential Manager target for guest VM |
+| `GITEA_CI_SSH_KEY_PATH`        | `F:\CI\keys\ci_linux`                               | SSH private key for Linux guest access |
+
+Invoke-CIJob.ps1 reads `GITEA_CI_TEMPLATE_PATH` and `GITEA_CI_CLONE_BASE_DIR`
+automatically if `-TemplatePath` and `-CloneBaseDir` are not passed explicitly.
+
+---
+
+## 5. Invoke-CIJob.ps1 Parameter Reference
+
+Script location (fixed on host): `N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1`
+
+### Mandatory parameters
+
+| Parameter  | Type   | Description                                                        |
+| ---------- | ------ | ------------------------------------------------------------------ |
+| `-JobId`   | string | Unique job ID. Use `${{ github.run_id }}` or `run_id-run_attempt`. |
+| `-RepoUrl` | string | Git URL of the repository to clone/build. See Section 6.           |
+| `-Branch`  | string | Branch to build. Use `${{ github.ref_name }}`.                     |
+
+### Optional parameters
+
+| Parameter                | Type   | Default                        | Description                                                      |
+| ------------------------ | ------ | ------------------------------ | ---------------------------------------------------------------- |
+| `-Commit`                | string | `''`                           | Specific commit SHA. Use `${{ github.sha }}`. Empty = HEAD.      |
+| `-TemplatePath`          | string | `$env:GITEA_CI_TEMPLATE_PATH`  | Full path to template VMX.                                       |
+| `-SnapshotName`          | string | `BaseClean`                    | Template snapshot name to clone from.                            |
+| `-GuestOS`               | string | `Auto`                         | `Windows`, `Linux`, or `Auto` (detected from VMX guestOS field). |
+| `-BuildCommand`          | string | `''`                           | Shell command to run inside VM. Empty = `dotnet build`.          |
+| `-GuestArtifactSource`   | string | `dist`                         | Path inside VM guest from which artifacts are collected.         |
+| `-Submodules`            | switch | off                            | Pass to clone with `--recurse-submodules`.                       |
+| `-UseGitClone`           | switch | off                            | Skip host-side clone; let the guest VM clone directly via HTTPS. |
+| `-GiteaCredentialTarget` | string | `GiteaPAT`                     | Credential Manager target for Gitea PAT (UseGitClone only).      |
+| `-GuestCredentialTarget` | string | `BuildVMGuest`                 | Credential Manager target for Windows guest VM login.            |
+| `-SshKeyPath`            | string | `F:\CI\keys\ci_linux`          | SSH key for Linux guest (ignored for Windows).                   |
+| `-SshUser`               | string | `ci_build`                     | SSH username for Linux guest (ignored for Windows).              |
+| `-CloneBaseDir`          | string | `$env:GITEA_CI_CLONE_BASE_DIR` | Directory for VM clone files.                                    |
+| `-ArtifactBaseDir`       | string | `F:\CI\Artifacts`              | Root artifact directory on host.                                 |
+| `-VMIPAddress`           | string | `''`                           | Override guest IP. Empty = auto-detected via vmrun.              |
+| `-LogDir`                | string | `F:\CI\Logs`                   | Directory for per-job transcripts and JSONL logs.                |
+| `-LogRetentionDays`      | int    | `30`                           | Days before log directories are purged. `0` = disabled.          |
+
+Exit codes: `0` = success, `1` = failure (VM is always destroyed regardless).
+
+---
+
+## 6. URL Conventions
+
+The `-RepoUrl` value depends on the build mode.
+
+### Host-clone mode (default, no `-UseGitClone`)
+
+The host runner clones the repo using the **SSH alias** defined in `~/.ssh/config`:
+
+```
+ssh://gitea-ci/<owner>/<repo>.git
+```
+
+- `gitea-ci` is a Host alias in the runner's SSH config pointing to Gitea's SSH port.
+- This URL is reachable **only from the host**, not from inside guest VMs.
+- After clone, source is transferred to the guest via WinRM (Windows) or tar+scp (Linux).
+
+### UseGitClone mode (`-UseGitClone`)
+
+The guest VM clones the repo directly via **HTTPS**:
+
+```
+https://gitea.emulab.it/<owner>/<repo>.git
+```
+
+- This URL must be reachable from inside the VM's NAT network.
+- For private repos, the Gitea PAT is injected from Credential Manager (`GiteaPAT` target).
+- Do not use the SSH alias URL with `-UseGitClone` — it is not accessible inside VMs.
+
+### Quick reference
+
+| Mode              | RepoUrl to use                               |
+| ----------------- | -------------------------------------------- |
+| Default (Windows) | `ssh://gitea-ci/<owner>/<repo>.git`          |
+| Default (Linux)   | `ssh://gitea-ci/<owner>/<repo>.git`          |
+| UseGitClone       | `https://gitea.emulab.it/<owner>/<repo>.git` |
+
+---
+
+## 7. Artifact Path Convention
+
+Artifacts are written to:
+
+```
+F:\CI\Artifacts\<JobId>\
+```
+
+Where `<JobId>` is the value passed to `-JobId`.
+
+In `upload-artifact` steps use:
+
+```yaml
+path: F:\CI\Artifacts\${{ github.run_id }}\
+```
+
+Or for single-file artifact:
+
+```yaml
+path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
+```
+
+`Invoke-CIJob.ps1` always produces an `artifacts.zip` at the job artifact root,
+plus the raw files extracted from the guest under the same directory.
+
+---
+
+## 8. Workflow Patterns
+
+Place workflow files in `.gitea/workflows/` in the project repository.
+
+### 8.1 Windows build (host-clone mode)
+
+Standard Windows build. Host clones the repo and transfers source to the Windows VM
+via WinRM/zip transfer.
+
+```yaml
+name: Build (Windows)
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-build
+    timeout-minutes: 90
+
+    steps:
+      - name: Run CI Job
+        shell: powershell
+        run: |
+          & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+            -JobId               '${{ github.run_id }}' `
+            -RepoUrl             'ssh://gitea-ci/<owner>/<repo>.git' `
+            -Branch              '${{ github.ref_name }}' `
+            -Commit              '${{ github.sha }}' `
+            -Submodules `
+            -BuildCommand        'python build_plugin.py --final --dist-dir dist' `
+            -GuestArtifactSource 'dist'
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Upload artifacts
+        if: success()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-${{ github.ref_name }}
+          path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
+          if-no-files-found: error
+
+      - name: Upload logs on failure
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-logs-${{ github.run_id }}
+          path: F:\CI\Artifacts\${{ github.run_id }}\*.log
+          if-no-files-found: ignore
+          retention-days: 3
+```
+
+### 8.2 Linux build (host-clone mode)
+
+Host clones the repo, compresses it with tar, and transfers it to the Ubuntu 24.04
+VM via scp. Build runs under `ci_build` user.
+
+```yaml
+name: Build (Linux)
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: linux-build
+    timeout-minutes: 60
+
+    steps:
+      - name: Run CI Job (Linux)
+        shell: powershell
+        run: |
+          & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+            -JobId               '${{ github.run_id }}' `
+            -RepoUrl             'ssh://gitea-ci/<owner>/<repo>.git' `
+            -Branch              '${{ github.ref_name }}' `
+            -Commit              '${{ github.sha }}' `
+            -Submodules `
+            -GuestOS             'Linux' `
+            -TemplatePath        $env:GITEA_CI_LINUX_TEMPLATE_PATH `
+            -SshKeyPath          $env:GITEA_CI_SSH_KEY_PATH `
+            -BuildCommand        'python3 build_plugin.py --host linux --verbose' `
+            -GuestArtifactSource 'dist'
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Upload artifacts
+        if: success()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-linux-${{ github.ref_name }}
+          path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
+          if-no-files-found: error
+```
+
+Notes:
+- `-GuestOS 'Linux'` can be omitted if `Auto` detection is sufficient (reads VMX `guestOS` field).
+- `-TemplatePath $env:GITEA_CI_LINUX_TEMPLATE_PATH` selects the Ubuntu template.
+- `-SshKeyPath $env:GITEA_CI_SSH_KEY_PATH` uses the injected key path.
+- The default snapshot name for Linux templates is `BaseClean-Linux`. If you rely on
+  `Auto`, add `-SnapshotName 'BaseClean-Linux'` explicitly.
+
+### 8.3 Windows build (UseGitClone mode)
+
+The Windows guest VM clones the repository directly via HTTPS. Requires Git for Windows
+in the template and the `GiteaPAT` Credential Manager entry on the host (for private repos).
+
+```yaml
+name: Build (Windows, in-VM clone)
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-build
+    timeout-minutes: 90
+
+    steps:
+      - name: Run CI Job
+        shell: powershell
+        run: |
+          & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+            -JobId               '${{ github.run_id }}' `
+            -RepoUrl             'https://gitea.emulab.it/<owner>/<repo>.git' `
+            -Branch              '${{ github.ref_name }}' `
+            -Commit              '${{ github.sha }}' `
+            -Submodules `
+            -UseGitClone `
+            -GiteaCredentialTarget 'GiteaPAT' `
+            -BuildCommand        'python build_plugin.py --final --dist-dir dist' `
+            -GuestArtifactSource 'dist'
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Upload artifacts
+        if: success()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-${{ github.ref_name }}
+          path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
+          if-no-files-found: error
+```
+
+### 8.4 Linux build (UseGitClone mode)
+
+Linux guest clones directly. Useful when the host SSH agent is unavailable or for
+testing the full HTTPS clone path.
+
+```yaml
+name: Build (Linux, in-VM clone)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: linux-build
+    timeout-minutes: 60
+
+    steps:
+      - name: Run CI Job (Linux, UseGitClone)
+        shell: powershell
+        run: |
+          & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+            -JobId               '${{ github.run_id }}' `
+            -RepoUrl             'https://gitea.emulab.it/<owner>/<repo>.git' `
+            -Branch              '${{ github.ref_name }}' `
+            -Commit              '${{ github.sha }}' `
+            -Submodules `
+            -UseGitClone `
+            -GiteaCredentialTarget 'GiteaPAT' `
+            -GuestOS             'Linux' `
+            -TemplatePath        $env:GITEA_CI_LINUX_TEMPLATE_PATH `
+            -SshKeyPath          $env:GITEA_CI_SSH_KEY_PATH `
+            -SnapshotName        'BaseClean-Linux' `
+            -BuildCommand        'python3 build_plugin.py --host linux --verbose' `
+            -GuestArtifactSource 'dist'
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Upload artifacts
+        if: success()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-linux-${{ github.ref_name }}
+          path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
+          if-no-files-found: error
+```
+
+### 8.5 PSScriptAnalyzer lint
+
+Runs on every push or PR that touches `.ps1` / `.psm1` files.
+
+```yaml
+name: Lint (PSScriptAnalyzer)
+
+on:
+  push:
+    paths:
+      - '**.ps1'
+      - '**.psm1'
+  pull_request:
+    paths:
+      - '**.ps1'
+      - '**.psm1'
+
+jobs:
+  lint:
+    runs-on: windows-build
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run PSScriptAnalyzer
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+
+          if (-not (Get-Module -ListAvailable PSScriptAnalyzer)) {
+            Install-Module PSScriptAnalyzer -Scope CurrentUser -Force -AllowClobber
+          }
+
+          $paths = @('scripts', 'template', 'runner', 'Setup-Host.ps1')
+          $results = $paths | ForEach-Object {
+            if (Test-Path $_) {
+              Invoke-ScriptAnalyzer -Path $_ -Recurse -Severity Error,Warning
+            }
+          }
+
+          if ($results) {
+            $results | Format-Table -AutoSize
+            Write-Error "PSScriptAnalyzer found $($results.Count) issue(s)."
+            exit 1
+          }
+          Write-Host "PSScriptAnalyzer: no issues found."
+```
+
+Note: The lint job uses `actions/checkout@v4` because it analyzes files inside the
+project repo (the checked-out workspace), not the CI scripts repo.
+
+### 8.6 Matrix build (multiple configs)
+
+```yaml
+name: Build (matrix)
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: windows-build
+    timeout-minutes: 90
+
+    strategy:
+      matrix:
+        config: [x86-ansi, x86-unicode, x64-unicode]
+      fail-fast: false
+
+    steps:
+      - name: Run CI Job
+        shell: powershell
+        run: |
+          & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+            -JobId               '${{ github.run_id }}-${{ matrix.config }}' `
+            -RepoUrl             'ssh://gitea-ci/<owner>/<repo>.git' `
+            -Branch              '${{ github.ref_name }}' `
+            -Commit              '${{ github.sha }}' `
+            -Submodules `
+            -BuildCommand        "python build_plugin.py --config ${{ matrix.config }}" `
+            -GuestArtifactSource 'dist'
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+      - name: Upload artifacts
+        if: success()
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-${{ matrix.config }}-${{ github.ref_name }}
+          path: F:\CI\Artifacts\${{ github.run_id }}-${{ matrix.config }}\artifacts.zip
+          if-no-files-found: error
+```
+
+Note: With `runner.capacity: 4`, up to 4 matrix jobs run in parallel. Each gets its
+own ephemeral VM. Ensure `-JobId` is unique per matrix cell.
+
+---
+
+## 9. Checkout Step
+
+**Do not add `actions/checkout@v4` to build steps** unless the workflow itself needs
+access to repository files on the host (e.g. lint, static analysis).
+
+For build jobs, `Invoke-CIJob.ps1` handles all source acquisition — either by cloning
+on the host and transferring to the VM, or by having the VM clone directly.
+
+The CI scripts are at a fixed path on the runner host and do not need a checkout:
+
+```yaml
+# CORRECT — direct path to CI scripts, no checkout needed
+- name: Run CI Job
+  shell: powershell
+  run: |
+    & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' ...
+
+# WRONG — CI scripts are not in the project repo
+- name: Checkout
+  uses: actions/checkout@v4   # this checks out the PROJECT repo, not CI scripts
+- name: Run CI Job
+  shell: powershell
+  run: |
+    & "$env:GITHUB_WORKSPACE\scripts\Invoke-CIJob.ps1" ...  # path doesn't exist
+```
+
+---
+
+## 10. Timeouts
+
+| Build type                 | Recommended `timeout-minutes` |
+| -------------------------- | ----------------------------- |
+| Windows build (typical)    | 90                            |
+| Windows build (large/slow) | 120                           |
+| Linux build (typical)      | 60                            |
+| Lint / static analysis     | 10                            |
+| Template provisioning      | 180                           |
+
+The runner-level timeout is `2h` (from `runner/config.yaml`). Keep job timeouts
+below that value. If a job timeout fires, the VM may not be cleanly destroyed —
+the cleanup task `Cleanup-OrphanedBuildVMs.ps1` handles these cases.
+
+---
+
+## 11. Common Mistakes
+
+| Mistake                                                          | Correct approach                                                           |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `shell: pwsh`                                                    | Use `shell: powershell` (PS 5.1, not Core)                                 |
+| SSH alias URL with `-UseGitClone`                                | Use `https://gitea.emulab.it/...` for UseGitClone; SSH alias is host-only  |
+| HTTPS URL without `-UseGitClone`                                 | SSH alias `ssh://gitea-ci/...` for host-clone mode                         |
+| `$env:GITHUB_WORKSPACE` to find CI scripts                       | Use hardcoded `N:\Code\Workspace\Local-CI-CD-System\scripts\`              |
+| `actions/checkout@v4` in build jobs                              | Omit it; source is handled by Invoke-CIJob.ps1                             |
+| `runs-on: ubuntu-latest` or `windows-latest`                     | Use `windows-build` or `linux-build` — cloud runners are not available     |
+| `&&` in PowerShell run blocks                                    | Not valid in PS 5.1; use `if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }` |
+| Hardcoded IP in `-VMIPAddress`                                   | Omit it; auto-detected via `vmrun getGuestIPAddress`                       |
+| `-TemplatePath` for Linux without `GITEA_CI_LINUX_TEMPLATE_PATH` | Pass `$env:GITEA_CI_LINUX_TEMPLATE_PATH` or the full path explicitly       |
+| Forgetting `-SnapshotName 'BaseClean-Linux'` for Linux           | Linux template uses a different snapshot name than Windows (`BaseClean`)   |
+| Same `-JobId` for matrix jobs                                    | Append matrix key: `${{ github.run_id }}-${{ matrix.config }}`             |
+| `actions/upload-artifact@v4` / `download-artifact@v4`            | Use `@v3`. Gitea reports as GHES; @v4 (`@actions/artifact` v2 / Twirp API) fails with `GHESNotSupportedError`. |
+| Short action ref `Simone/local-ci-cd-system/...@main`            | Use the full URL `https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main`; with `[actions] DEFAULT_ACTIONS_URL = github` in Gitea's app.ini this keeps GitHub actions (checkout, upload-artifact) resolvable while pointing the composite action at the local instance. The action repo must be on `@main` (the ref the runner clones). |
+| Composite action referenced from a private/internal repo         | The runner clones the action repo unauthenticated. Make `local-ci-cd-system` public, or the clone fails with `authentication required: Unauthorized`. |

docs/archived/2026-05-10/PLAN.md

@@ -16,7 +16,7 @@
 - Gitea self-hosted — `http://10.10.20.11:3100`
 - act_runner v1.0.2 — Windows service su host, label `windows-build`
 - Build VMs: subnet VMnet8 NAT — `192.168.79.0/24`
-- WinRM HTTP/5985 (Basic auth, lab-only)
+- WinRM HTTPS/5986 (Basic auth over HTTPS, self-signed cert, SkipCACheck lab-only)
 
 ### Architettura implementata
 1. Gitea Actions enqueue job → act_runner lo prende

docs/archived/2026-05-10/README.md

@@ -0,0 +1,44 @@
+# Archived Documentation
+
+Date: 2026-05-10
+
+## Archived Files
+
+### PLAN.md (archived 2026-05-10)
+**Reason**: Pianificazione iniziale (ultimo update 2026-05-08) superata dallo stato post Sprint 8.
+Stato corrente del sistema, decisioni tecniche e roadmap sono ora distribuiti tra:
+- `TODO.md` (root) per audit trail, summary status e backlog
+- `docs/ARCHITECTURE.md` per il design del sistema
+- `docs/CI-FLOW.md` per il flusso operativo
+- `docs/RUNBOOK.md` per il triage incident
+
+Resta come riferimento storico.
+
+### TEST-7.4-e2e.md
+**Reason**: Sprint 7.4 refactor validation document. Specific to §7.4 Deploy↔Setup refactor completion testing.
+**When to revive**: As a reference template for validating future template refactors. Contains reusable patterns for:
+- Deploy script validation on fresh VM
+- Setup script validation (idempotency, state verification)
+- Post-refactor sign-off checklist
+**Useful for**: §6.6 (Toolchain Tier-1) template updates, Linux template setup (§6.1)
+
+## De-archived
+
+### Setup-GiteaSSH.md (restored 2026-05-10)
+Originariamente archiviato come "obsolete (HTTP+credential manager)" ma di fatto il workflow
+live (`gitea/workflows/build-nsis.yml`) e `Setup-Host.ps1` continuano a usare l'alias SSH
+`gitea-ci` (porta 2222) per i clone Git. Ripristinato in `docs/Setup-GiteaSSH.md`.
+
+## Active Documentation
+
+All current, operational docs remain in parent directory:
+- ARCHITECTURE.md
+- BEST-PRACTICES.md
+- CI-FLOW.md
+- HOST-SETUP.md
+- WINDOWS-TEMPLATE-SETUP.md
+- LINUX-TEMPLATE-SETUP.md (draft for §6.1)
+- OPTIMIZATION.md
+- RUNBOOK.md
+- TEST-PLAN-v1.3-to-HEAD.md
+- Setup-GiteaSSH.md

docs/archived/2026-05-10/TEST-7.4-e2e.md

@@ -74,15 +74,15 @@ Invoke-Command -ComputerName $ip -Credential $cred `
 ```
 
 **Atteso**:
-| Check | Valore atteso |
-|---|---|
-| Firewall tutti profili | `Enabled=False` |
-| `wuauserv` StartType | `Manual` |
-| `UsoSvc` StartType | `Manual` |
-| `NoAutoUpdate` | `1` |
-| `DisableWindowsUpdateAccess` | `1` |
-| `MaxMemoryPerShellMB` | `>= 2048` |
-| `EnableLUA` | `0` |
+| Check                        | Valore atteso   |
+| ---------------------------- | --------------- |
+| Firewall tutti profili       | `Enabled=False` |
+| `wuauserv` StartType         | `Manual`        |
+| `UsoSvc` StartType           | `Manual`        |
+| `NoAutoUpdate`               | `1`             |
+| `DisableWindowsUpdateAccess` | `1`             |
+| `MaxMemoryPerShellMB`        | `>= 2048`       |
+| `EnableLUA`                  | `0`             |
 
 ---
 

docs/archived/2026-05-13/TEST-PLAN-v1.3-to-HEAD.md

@@ -0,0 +1,848 @@
+# Test Plan: v1.3 → HEAD
+
+Complete validation of all features added since v1.3 tag (2026-05-10).
+Organized by sprint area with pre-requisites, test steps, and pass/fail criteria.
+
+---
+
+## Overview
+
+| Area                          | Items                   | Status   | Baseline                                                                  |
+| ----------------------------- | ----------------------- | -------- | ------------------------------------------------------------------------- |
+| **Sprint 2** (Reliability)    | 2.1/2.2/2.3/2.5         | Partial  | §2.2/§2.3 validated locally 2026-05-10; §2.1/§2.5 need real VMs           |
+| **Sprint 3** (Observability)  | 4.1/4.3/4.4             | Partial  | §4.3/§4.4 validated locally 2026-05-10; §4.1 (JSONL) needs real build job |
+| **Sprint 4-6** (Quality/Perf) | 1.4/3.1/3.6/5.2/5.3/5.4 | Partial  | §1.4/§5.2/§5.3/§5.4 validated 2026-05-10; §3.1/§3.6 need real VMs         |
+| **Sprint 7** (Testing)        | 5.1                     | [x] Done | 22/22 Pester tests passing in 12.9s (re-validated 2026-05-11)             |
+| **§1.6** (Docs)               | Threat model            | [x] Done | BEST-PRACTICES.md verified 2026-05-10                                     |
+| **§3.2** (Perf)               | 7-Zip compression       | Partial  | Fallback path validated; in-VM 7-Zip speed test needs real VM             |
+| **§5.4** (PSScriptAnalyzer)   | 0 errors, 298 warnings  | [x] Done | All 6 actionable warnings fixed 2026-05-11; 0 Error severity violations   |
+| **§6.1** (Linux Build VM)     | Deploy/Prepare/e2e      | [x] Done | Test-Ns7zipBuild-Linux.ps1 4xPASS 2026-05-11 — nsis7z.dll 2272 KB         |
+
+---
+
+## Pre-Test Checklist
+
+- [x] Host Windows 11 with VMware Workstation 17+
+- [x] Template VM `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` exists + BaseClean snapshot present (verified 2026-05-10)
+- [x] `F:\CI\` directory structure intact (BuildVMs, Artifacts, Logs, Cache, State) (verified 2026-05-10)
+- [x] act_runner service running (`Get-Service act_runner | Select Status`) (verified 2026-05-10)
+- [x] Gitea available at `http://10.10.20.11:3100` or `https://gitea.emulab.it`
+- [x] PowerShell ≥5.1, Pester v5 installed (`Install-Module Pester -MinimumVersion 5.0 -Force`) (Pester 5.7.1 installed 2026-05-10)
+- [x] CredentialManager module installed (`Install-Module CredentialManager`) (verified 2026-05-10)
+- [x] **[NEW 2026-05-10]** Template includes §6.6 Tier-1 Toolchain: Git for Windows + 7-Zip (Step 11 in Install-CIToolchain-WinBuild2025.ps1)
+
+---
+
+## Sprint 2 — Reliability & Resilience (§2.1/2.2/2.3/2.5)
+
+### 2.1 IP Allocation Race Prevention
+
+**What changed**: Exclusive file-based IP lease allocation to prevent race condition where
+two parallel clones receive the same IP from DHCP.
+
+**Files affected**:
+- `scripts/Invoke-CIJob.ps1` (lines 244-253: IP leak management)
+- `runner/config.yaml` (capacity = 4 for parallel jobs)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify IP state directory exists
+Test-Path F:\CI\State\ip-leases\
+# Expected: True
+
+# 2. Start 4 parallel jobs on nsis-plugin-nsinnounp (or similar)
+# Simulate via (PS 5.1 — Start-Job, not ForEach-Object -Parallel):
+$jobs = 1..4 | ForEach-Object {
+    $i = $_
+    Start-Job -ScriptBlock {
+        & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+            -RepoUrl 'http://10.10.20.11:3100/Simone/nsis-plugin-nsinnounp' `
+            -JobId "test-parallel-$using:i" `
+            -Branch main
+    }
+}
+$jobs | Wait-Job | Receive-Job
+
+# 3. Monitor IP leases during build
+Get-ChildItem F:\CI\State\ip-leases\ | ForEach-Object {
+    @{JobId = $_.BaseName; IP = (Get-Content $_.FullName) }
+}
+# Expected: 4 unique IPs in range 192.168.79.100-192.168.79.104
+# (No duplicate IPs across jobs)
+
+# 4. After builds complete, leases should be released
+Get-ChildItem F:\CI\State\ip-leases\
+# Expected: Empty (all cleaned up in finally block)
+```
+
+**Pass Criteria**:
+- [x] All 4 jobs complete successfully
+- [x] No WinRM "connection to wrong VM" errors
+- [x] Each job receives unique IP
+- [x] Leases cleaned up after completion
+
+---
+
+### 2.2 Orphaned VM Cleanup (Scheduled)
+
+**What changed**: Automated cleanup script + scheduled task to remove stale clones
+if host crashes mid-job or act_runner dies.
+
+**Files affected**:
+- `scripts/Cleanup-OrphanedBuildVMs.ps1` (main cleanup logic)
+- `scripts/Register-CIScheduledTasks.ps1` (task registration: `CI-CleanupOrphans` every 6 hours)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify scheduled task exists
+Get-ScheduledTask -TaskName 'CI-CleanupOrphans' | Select Name, State, NextRunTime
+# Expected: Task exists, State = Ready
+
+# 2. Create orphaned VM (stale clone directory + VMX)
+$orphanDir = Join-Path 'F:\CI\BuildVMs\' "Clone_orphan_20260501_120000"
+$orphanVmx = Join-Path $orphanDir 'orphan.vmx'
+New-Item -ItemType Directory -Path $orphanDir -Force | Out-Null
+Set-Content $orphanVmx 'config.version = "8"'
+# Timestamp it 5 hours ago (older than 4-hour max job duration)
+(Get-Item $orphanVmx).LastWriteTime = (Get-Date).AddHours(-5)
+
+# 3. Run cleanup manually
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Cleanup-OrphanedBuildVMs.ps1' -Verbose
+
+# 4. Verify orphan removed
+Test-Path $orphanDir
+# Expected: False (cleaned up)
+```
+
+**Pass Criteria**:
+- [x] Scheduled task runs without error
+- [x] Orphaned VM detected and removed
+- [x] Recent clones (< 4 hours old) preserved
+- [x] Event log shows cleanup action
+
+---
+
+### 2.3 Artifact + Log Retention
+
+**What changed**: Automated retention policy to prune artifacts older than 30 days
+and logs, preventing F:\ from filling.
+
+**Files affected**:
+- `scripts/Invoke-RetentionPolicy.ps1` (main policy)
+- `scripts/Register-CIScheduledTasks.ps1` (task registration: `CI-RetentionPolicy` daily at 4am)
+
+**Test Steps**:
+
+```powershell
+# 1. Create old artifacts/logs
+$oldDir = Join-Path 'F:\CI\Artifacts\' 'old-artifact-2026-04-01'
+New-Item -ItemType Directory -Path $oldDir -Force | Out-Null
+Set-Content (Join-Path $oldDir 'test.txt') 'old artifact'
+(Get-Item $oldDir).LastWriteTime = (Get-Date).AddDays(-31)
+
+# 2. Run retention policy manually
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-RetentionPolicy.ps1' -Verbose
+
+# 3. Verify old artifact removed, recent preserved
+Test-Path $oldDir
+# Expected: False
+
+$recentDir = Join-Path 'F:\CI\Artifacts\' 'recent-artifact'
+New-Item -ItemType Directory -Path $recentDir -Force | Out-Null
+Test-Path $recentDir  # After running retention policy
+# Expected: True (recent artifacts kept)
+
+# 4. Monitor disk space alert
+$diskFree = (Get-PSDrive F).Free / 1GB
+if ($diskFree -lt 50) {
+    # Retention should have triggered aggressive 7-day cleanup
+    Get-EventLog -LogName Application -Source 'CI-Retention' -Newest 1
+}
+```
+
+**Pass Criteria**:
+- [x] Artifacts older than 30 days removed
+- [x] Recent artifacts preserved
+- [x] Aggressive (7-day) cleanup if free space < 50 GB
+- [x] Event log entry created for cleanup action
+
+---
+
+### 2.5 Snapshot Versioning
+
+**What changed**: Snapshots named `BaseClean_YYYYMMDD` instead of static `BaseClean`
+to support rollback during template refresh.
+
+**Files affected**:
+- `runner/config.yaml` (new env var `GITEA_CI_SNAPSHOT_NAME`)
+- `scripts/Invoke-CIJob.ps1` (line 100: reads env, defaults to `BaseClean`)
+- `docs/BEST-PRACTICES.md` (snapshot versioning strategy)
+
+**Test Steps**:
+
+```powershell
+# 1. Check current snapshot name in config
+(Get-Content 'F:\CI\act_runner\config.yaml' | Select-String 'GITEA_CI_SNAPSHOT_NAME').Line
+# Expected: Should show GITEA_CI_SNAPSHOT_NAME value or be empty (uses default)
+
+# 2. Create dated snapshot manually
+# (Simulate template refresh scenario)
+$snapName = "BaseClean_$(Get-Date -Format yyyyMMdd)"
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' -T ws snapshot `
+    'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' $snapName
+# Expected: Success, snapshot created
+
+# 3. Verify old and new snapshots coexist
+& 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' -T ws listSnapshots `
+    'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+# Expected: Output shows both BaseClean (old) and BaseClean_YYYYMMDD (new)
+
+# 4. Update config to use new snapshot
+# Edit F:\CI\act_runner\config.yaml:
+# envs:
+#   GITEA_CI_SNAPSHOT_NAME: BaseClean_20260510
+
+# 5. Verify job uses new snapshot
+# Start a fresh build and check phase logs for "Reverting to snapshot: BaseClean_20260510"
+```
+
+**Pass Criteria**:
+- [x] Multiple dated snapshots can exist simultaneously
+- [x] Jobs respect GITEA_CI_SNAPSHOT_NAME env var
+- [x] Default fallback to `BaseClean` if env var not set
+- [x] Rollback possible by reverting config to old snapshot name
+
+---
+
+## Sprint 3 — Observability & Maintenance (§4.1/4.3/4.4)
+
+### 4.1 JSONL Structured Logging
+
+**What changed**: Phase transitions now emit JSONL events (one line per phase) in addition
+to text transcript, enabling machine parsing and future Loki/Grafana integration.
+
+**Files affected**:
+- `scripts/Invoke-CIJob.ps1` (lines 178-187: phase event logging)
+
+**Test Steps**:
+
+```powershell
+# 1. Run a complete build and capture job ID
+$jobId = 'test-jsonl-logging'
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+    -RepoUrl 'http://10.10.20.11:3100/Simone/nsis-plugin-nsinnounp' `
+    -JobId $jobId `
+    -Branch main
+
+# 2. Check for JSONL log file
+$jsonLog = Get-ChildItem 'F:\CI\Logs\' -Filter "*${jobId}*.jsonl" | Select-Object -First 1
+Test-Path $jsonLog.FullName
+# Expected: True
+
+# 3. Parse JSONL and validate structure
+$events = Get-Content $jsonLog.FullName | ConvertFrom-Json | Select-Object -First 5
+$events | Select ts, jobId, phase, status, data
+# Expected: Each line is valid JSON with fields: ts (ISO), jobId, phase, status, data object
+
+# 4. Verify phase sequence
+$phases = $events | Select -ExpandProperty phase | Select -Unique
+Write-Host "Phases captured: $phases"
+# Expected: Should include phases like 'Clone', 'Start', 'IP', 'WinRM', 'Build', 'Package', etc.
+```
+
+**Pass Criteria**:
+- [x] JSONL file created alongside text transcript
+- [x] Each phase emits valid JSON event
+- [x] Timestamps are ISO format (parseable)
+- [x] Job ID correctly recorded in events
+- [x] Status values are consistent (success/failure/started)
+
+---
+
+### 4.3 Disk Space Monitoring & Alert
+
+**What changed**: New `Watch-DiskSpace.ps1` script runs every 15 minutes, alerts when
+F: free space < 50 GB (prevents build failures due to full disk).
+
+**Files affected**:
+- `scripts/Watch-DiskSpace.ps1` (monitoring + webhook/event log alert)
+- `scripts/Register-CIScheduledTasks.ps1` (task registration: `CI-DiskSpace` every 15 min)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify scheduled task
+Get-ScheduledTask -TaskName 'CI-DiskSpace' | Select Name, State, NextRunTime
+# Expected: Exists, State = Ready
+
+# 2. Check current disk free space
+$diskFree = (Get-PSDrive F).Free / 1GB
+Write-Host "F: free space: ${diskFree} GB"
+
+# 3. Run disk watch manually to see alert logic
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Watch-DiskSpace.ps1' -Verbose
+
+# 4. Check for event log entry if space is low
+Get-EventLog -LogName Application -Source 'CI-DiskSpace' -Newest 5 | Select TimeGenerated, EventID, Message
+
+# 5. If webhook configured, verify it receives alert
+# (Check Discord/Gitea webhook logs if configured)
+```
+
+**Pass Criteria**:
+- [x] Scheduled task runs without error
+- [x] Alert triggered if F: free < 50 GB
+- [x] Event log entry (ID 1003 for warning, 1004+ for error) created
+- [x] Webhook POST succeeds if configured
+- [x] No alert if F: free > 50 GB
+
+---
+
+### 4.4 Runbook Documentation
+
+**What changed**: New `docs/RUNBOOK.md` with troubleshooting steps for common incidents.
+
+**Files affected**:
+- `docs/RUNBOOK.md` (incident playbooks)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify file exists
+Test-Path 'N:\Code\Workspace\Local-CI-CD-System\docs\RUNBOOK.md'
+# Expected: True
+
+# 2. Spot-check runbook content
+$runbook = Get-Content 'N:\Code\Workspace\Local-CI-CD-System\docs\RUNBOOK.md' -Raw
+# Should contain sections: runner offline, build phase failures, slow builds, corrupted VMX
+
+# 3. Test one runbook procedure: "Runner offline in Gitea UI"
+# Run the triage steps from runbook:
+Get-Service act_runner | Select Status, StartType
+Get-EventLog -LogName Application -Source 'act_runner' -Newest 5
+# (Follow runbook steps to verify syntax/commands work)
+
+# 4. Verify incident reference links
+Get-ChildItem 'N:\Code\Workspace\Local-CI-CD-System\docs\' | Where Name -Match 'BEST-PRACTICES|OPTIMIZATION'
+# Expected: Links in runbook resolve to actual docs
+```
+
+**Pass Criteria**:
+- [x] Runbook file exists and is readable
+- [x] All diagnostic commands execute without error
+- [x] At least 3 incident types documented with clear symptom→triage→fix flow
+- [x] External references (log paths, service names) accurate and tested
+
+---
+
+## Sprint 4-6 — Quality, Reliability, Performance
+
+### 1.4 IP Validation (Per-Octet Regex)
+
+**What changed**: IP validation uses per-octet regex in all 4 relevant scripts
+instead of loose pattern.
+
+**Files affected**:
+- `scripts/Invoke-RemoteBuild.ps1` (param validation)
+- `scripts/Get-BuildArtifacts.ps1` (param validation)
+- `scripts/Wait-VMReady.ps1` (param validation)
+- `scripts/Invoke-CIJob.ps1` (IP validation in phase 3)
+
+**Test Steps**:
+
+```powershell
+# 1. Test valid IP in script parameter binding
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Wait-VMReady.ps1' `
+    -VMPath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+    -IPAddress '192.168.79.101' `
+    -VmrunPath 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
+    -TimeoutSeconds 5 `
+    -SkipPing
+# Expected: Script runs (may timeout OK since VM not actually running, but IP validation passes)
+
+# 2. Test invalid IPs (should fail parameter validation)
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Wait-VMReady.ps1' `
+    -VMPath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+    -IPAddress '999.999.999.999' `
+    -VmrunPath 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
+# Expected: Error message like "Cannot validate argument on parameter 'IPAddress'"
+
+# 3. Test edge case IPs
+@('0.0.0.0', '255.255.255.255', '192.168.1.1', '10.0.0.256') | ForEach-Object {
+    try {
+        & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Wait-VMReady.ps1' `
+            -VMPath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+            -IPAddress $_ `
+            -VmrunPath 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
+            -TimeoutSeconds 1 `
+            -SkipPing -ErrorAction SilentlyContinue
+        Write-Host "$_ : ACCEPTED"
+    } catch {
+        Write-Host "$_ : REJECTED"
+    }
+}
+# Expected: 0.0.0.0/255.255.255.255/192.168.1.1 ACCEPTED (valid), 10.0.0.256 REJECTED
+```
+
+**Pass Criteria**:
+- [x] Valid IPs (0-255 per octet) accepted
+- [x] Invalid IPs (256+, non-numeric, malformed) rejected before script logic
+- [x] Error message clear ("Cannot validate argument")
+- [x] All 4 scripts enforce same pattern
+
+---
+
+### 3.1 Shared Cache (NuGet + Pip)
+
+**What changed**: Host-side cache directories (F:\CI\Cache\NuGet, F:\CI\Cache\pip)
+mounted as VMware shared folders in template, available at `\\vmware-host\Shared Folders\<cache>`.
+
+**Files affected**:
+- `scripts/Set-TemplateSharedFolders.ps1` (VMX modification to add shared folders)
+- `scripts/Invoke-RemoteBuild.ps1` (new `-UseSharedCache` switch, env var injection)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify shared folder configuration exists in template VMX
+$vmxPath = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+$vmx = Get-Content $vmxPath
+$vmx | Select-String 'sharedFolder' | Select -First 3
+# Expected: Lines like "sharedFolder0 = ...", "sharedFolder1 = ..."
+
+# 2. Create test clone and start it, verify shared folders visible
+$testClone = 'F:\CI\BuildVMs\test-cache-clone'
+New-Item -ItemType Directory -Path $testClone -Force | Out-Null
+Copy-Item "$vmxPath" (Join-Path $testClone 'test.vmx') -Force
+
+# Boot clone (or inspect VMX directly)
+$vmx = Get-Content (Join-Path $testClone 'test.vmx')
+$vmx | Select-String -Pattern 'sharedFolder\d+' | ForEach-Object {
+    if ($_ -match 'nuget-cache|pip-cache') {
+        Write-Host "[x] Cache folder found: $_"
+    }
+}
+# Expected: Both nuget-cache and pip-cache in VMX
+
+# 3. Run build with -UseSharedCache flag
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-RemoteBuild.ps1' `
+    -IPAddress '192.168.79.101' `
+    -Credential (Get-StoredCredential -Target 'BuildVMGuest') `
+    -HostSourceDir 'C:\Users\user\AppData\Local\Temp\ci-src-<jobid>' `
+    -UseSharedCache `
+    -Verbose
+
+# 4. Verify cache environment variables set inside VM
+# (Check build logs for NUGET_PACKAGES and PIP_CACHE_DIR references)
+```
+
+**Pass Criteria**:
+- [x] VMX contains sharedFolder entries for NuGet and pip
+- [x] `-UseSharedCache` flag accepted without error
+- [x] Build logs show NUGET_PACKAGES/PIP_CACHE_DIR env vars set
+- [x] Cache directories persist across builds (not recreated)
+- [x] Performance improvement visible on second build (packages already cached)
+
+---
+
+### 3.6 Benchmark Baseline
+
+**What changed**: New `Measure-CIBenchmark.ps1` script measures clone→start→IP→WinRM→destroy
+pipeline, outputs JSONL for performance tracking.
+
+**Files affected**:
+- `scripts/Measure-CIBenchmark.ps1` (benchmarking harness)
+
+**Test Steps**:
+
+```powershell
+# 1. Run baseline benchmark (5 iterations for quick turnaround)
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Measure-CIBenchmark.ps1' `
+    -TemplatePath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+    -SnapshotName 'BaseClean' `
+    -CloneBaseDir 'F:\CI\BuildVMs\' `
+    -Iterations 5 `
+    -Verbose
+
+# 2. Check output files
+Test-Path 'F:\CI\Logs\benchmark.jsonl'
+# Expected: True, file has 5 lines (one per iteration)
+
+# 3. Parse JSONL and examine timing breakdown
+# Fields: iteration, template, snapshot, cloneSec, startSec, ipSec, winrmSec, destroySec, totalBootSec, vmIP, error
+$benchmarks = Get-Content 'F:\CI\Logs\benchmark.jsonl' | ConvertFrom-Json
+$benchmarks | Select-Object iteration, cloneSec, startSec, ipSec, winrmSec, destroySec, totalBootSec | Format-Table
+# Expected: one row per iteration; all Sec fields populated; totalBootSec = cloneSec+startSec+ipSec+winrmSec
+
+# 4. Calculate clone statistics (values in seconds)
+$cloneTimes = $benchmarks | Select-Object -ExpandProperty cloneSec
+$avg = ($cloneTimes | Measure-Object -Average).Average
+$min = ($cloneTimes | Measure-Object -Minimum).Minimum
+$max = ($cloneTimes | Measure-Object -Maximum).Maximum
+Write-Host "Clone phase: avg=${avg}s, min=${min}s, max=${max}s"
+```
+
+**Pass Criteria**:
+- [x] Script completes N iterations without error
+- [x] JSONL output created with correct structure
+- [x] Five phase fields present (cloneSec, startSec, ipSec, winrmSec, destroySec)
+- [x] Durations reasonable (clone 1-5s, start 2-5s, IP <5s, WinRM 1-3s, destroy <2s)
+- [x] Variance visible across iterations (natural fluctuation)
+
+---
+
+### 5.2/5.3/5.4 Code Quality (Module, Uniform vmrun, PSScriptAnalyzer)
+
+**What changed**:
+- **5.2**: Extract shared functions into `_Common.psm1` module (New-CISessionOption, Resolve-VmrunPath, Invoke-Vmrun)
+- **5.3**: All scripts use `Invoke-Vmrun` wrapper with uniform error handling
+- **5.4**: PSScriptAnalyzer rules in `PSScriptAnalyzerSettings.psd1`
+
+**Files affected**:
+- `scripts/_Common.psm1` (reusable functions)
+- `scripts/Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `New-BuildVM.ps1` (Import-Module + use _Common functions)
+- `PSScriptAnalyzerSettings.psd1` (linting rules)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify module exports correct functions
+Import-Module 'N:\Code\Workspace\Local-CI-CD-System\scripts\_Common.psm1' -Force
+Get-Command -Module '_Common' | Select Name
+# Expected: New-CISessionOption, Resolve-VmrunPath, Invoke-Vmrun
+
+# 2. Test module functions
+$sessionOpt = New-CISessionOption
+$sessionOpt | Select SkipCACheck, SkipCNCheck, SkipRevocationCheck
+# Expected: All True
+
+# 3. Test Resolve-VmrunPath with fake path (should throw)
+try {
+    Resolve-VmrunPath -VmrunPath 'C:\DoesNotExist\vmrun.exe'
+} catch {
+    Write-Host "[x] Correctly threw: $_"
+}
+
+# 4. Test Invoke-Vmrun with fake vmrun.cmd
+$fakeVmrun = 'fake-vmrun-test.cmd'
+Set-Content $fakeVmrun '@echo off & exit /b 0'
+$result = Invoke-Vmrun -VmrunPath $fakeVmrun -Operation 'test'
+$result | Select ExitCode, Output
+# Expected: ExitCode = 0
+
+# 5. Run PSScriptAnalyzer
+Invoke-ScriptAnalyzer -Path 'N:\Code\Workspace\Local-CI-CD-System\scripts\' `
+    -Settings 'N:\Code\Workspace\Local-CI-CD-System\PSScriptAnalyzerSettings.psd1' |
+    Select RuleName, Severity, Line | Format-Table
+# Expected: Only approved suppressions (PSAvoidUsingWriteHost), no critical issues
+
+# 6. Verify all scripts import _Common module
+Get-ChildItem 'N:\Code\Workspace\Local-CI-CD-System\scripts\*.ps1' -Exclude '_Common.psm1' |
+    Select-String 'Import-Module.*_Common' | Select Filename
+# Expected: Invoke-RemoteBuild.ps1, Get-BuildArtifacts.ps1, New-BuildVM.ps1
+```
+
+**Pass Criteria**:
+- [x] _Common.psm1 exports 3 functions
+- [x] Functions work in isolation (parameters accepted, errors thrown appropriately)
+- [x] All production scripts import _Common
+- [x] PSScriptAnalyzer finds 0 critical violations
+- [x] Uniform vmrun invocation via Invoke-Vmrun (no direct `&vmrun` calls)
+
+---
+
+## Sprint 7 — Testing (§5.1)
+
+### 5.1 Pester Unit Tests (Fake vmrun, No Real VMs)
+
+**What changed**: Comprehensive Pester v5 test suite covering core scripts using fake
+executables instead of real VMs (fast, reliable, no infrastructure overhead).
+
+**Files affected**:
+- `tests/_Common.Tests.ps1` (3.1 module functions)
+- `tests/New-BuildVM.Tests.ps1` (clone creation, naming, error handling)
+- `tests/Remove-BuildVM.Tests.ps1` (clone destruction, -WhatIf support)
+- `tests/Wait-VMReady.Tests.ps1` (IP validation, timeout, vmrun missing)
+
+**Test Steps**:
+
+```powershell
+# 1. Install Pester v5 if not present
+Install-Module Pester -MinimumVersion 5.0 -Force -Scope CurrentUser
+
+# 2. Run all Pester tests with detailed output
+Invoke-Pester -Path 'N:\Code\Workspace\Local-CI-CD-System\tests\' `
+    -Output Detailed
+
+# Expected output: 4 files, ~25 tests total, all passing
+
+# 3. Examine individual test results
+Invoke-Pester -Path 'N:\Code\Workspace\Local-CI-CD-System\tests\' `
+    -Output Detailed | Select -ExpandProperty Tests |
+    Select Describe, Name, Result | Format-Table
+
+# 4. Verify fake vmrun.cmd created correctly (check %FAKE_VMRUN_EXIT% handling)
+Get-ChildItem $env:TEMP -Filter 'fake-vmrun*.cmd' | Select Name, Length
+# (These are cleaned up after tests, but if test fails, can verify content)
+
+# 5. Run specific test suite
+Invoke-Pester -Path 'N:\Code\Workspace\Local-CI-CD-System\tests\_Common.Tests.ps1' -Output Detailed
+# Expected: 3 test groups (New-CISessionOption, Resolve-VmrunPath, Invoke-Vmrun), all passing
+
+# 6. Test output capture (verify errors work)
+Invoke-Pester -Path 'N:\Code\Workspace\Local-CI-CD-System\tests\' `
+    -Output Detailed | Where Result -eq Failed
+# Expected: 0 failed (or only expected failures documented)
+```
+
+**Pass Criteria**:
+- [x] All 4 test files execute without compilation errors
+- [x] Total passed: ≥20 tests
+- [x] Total failed: 0 (all pass)
+- [x] Test duration: <30 seconds (fast, no VM overhead)
+- [x] No temp files left behind after tests complete
+- [x] Fake vmrun behavior matches real vmrun for tested scenarios
+
+---
+
+## §1.6 — Threat Model Documentation
+
+**What changed**: New BEST-PRACTICES.md §2.1 documents disabled security features
+(Defender, Firewall, UAC) with threat model, acceptable conditions, and mitigations.
+
+**Files affected**:
+- `docs/BEST-PRACTICES.md` (§2.1 Threat Model — Disabled Security Features)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify section exists and is readable
+$bp = Get-Content 'N:\Code\Workspace\Local-CI-CD-System\docs\BEST-PRACTICES.md' -Raw
+$bp | Select-String -Pattern '2\.1.*Threat Model' -Context 1, 50 | Select -First 1
+# Expected: Found
+
+# 2. Spot-check content structure
+$sections = @('Current state', 'Acceptable', 'Breaking', 'Mitigations')
+$sections | ForEach-Object {
+    if ($bp -match $_) { Write-Host "[x] Section: $_" }
+    else { Write-Host "✗ Missing: $_" }
+}
+
+# 3. Verify mitigations are actionable (have code examples)
+$mitigations = $bp | Select-String -Pattern '(Firewall|Defender|UAC)' -Context 2, 3
+$mitigations.Matches.Count
+# Expected: At least 3+ sections with mitigations
+
+# 4. Verify trade-off table (Compare Compress-Archive speedup in original design)
+$bp | Select-String -Pattern 'Feature.*Disabled.*Why.*Cost' -Context 0, 10
+# Expected: Structured comparison found
+```
+
+**Pass Criteria**:
+- [x] §2.1 section present in BEST-PRACTICES.md
+- [x] Explains why features disabled (AV overhead, firewall complexity, UAC elevation)
+- [x] Documents acceptable conditions (isolated lab, trusted code)
+- [x] Documents breaking conditions (shared host, LAN exposure)
+- [x] Provides step-by-step mitigations (code examples) if conditions change
+- [x] References existing features (HGFS, WinRM HTTPS) that work with protections
+
+---
+
+## §3.2 — 7-Zip Compression Acceleration
+
+**What changed**: Replaced single-threaded Compress-Archive with multi-threaded 7-Zip
+(3 call sites: host source compression, custom build artifacts, dotnet build output).
+Falls back to Compress-Archive if 7-Zip not found.
+
+**Files affected**:
+- `scripts/Invoke-RemoteBuild.ps1` (3 replacements + new `Compress-BuildArtifact` helper)
+
+**Test Steps**:
+
+```powershell
+# 1. Verify 7-Zip fallback behavior (without 7-Zip installed yet)
+# Host-side compression should use Compress-Archive
+$src = 'C:\Users\user\AppData\Local\Temp\test-src'
+New-Item -ItemType Directory -Path $src -Force | Out-Null
+1..100 | ForEach-Object { Set-Content (Join-Path $src "file-$_.txt") 'test' }
+
+$zip = 'C:\Users\user\AppData\Local\Temp\test-no7z.zip'
+$sw = [System.Diagnostics.Stopwatch]::StartNew()
+
+# Simulate what Compress-BuildArtifact does (without 7-Zip)
+Compress-Archive -Path "$src\*" -DestinationPath $zip -CompressionLevel Fastest -Force
+
+$sw.Stop()
+Write-Host "Compress-Archive on 100 files: $($sw.ElapsedMilliseconds) ms"
+# Expected: Takes ~500-2000 ms (single-threaded)
+
+# 2. Once 7-Zip is installed in template (§6.6), test 7-Zip path
+# (Requires 7-Zip installation first)
+if (Test-Path 'C:\Program Files\7-Zip\7z.exe') {
+    $sw = [System.Diagnostics.Stopwatch]::StartNew()
+    & 'C:\Program Files\7-Zip\7z.exe' a -mmt=on -mx1 'C:\Users\user\AppData\Local\Temp\test-7z.7z' "$src\*"
+    $sw.Stop()
+    Write-Host "7-Zip on 100 files: $($sw.ElapsedMilliseconds) ms"
+    # Expected: Faster than Compress-Archive (multi-threaded, should be 50-70% reduction)
+}
+
+# 3. Test fallback logic in actual script
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-RemoteBuild.ps1' `
+    -IPAddress '192.168.79.101' `
+    -Credential (Get-StoredCredential -Target 'BuildVMGuest') `
+    -HostSourceDir 'C:\Users\user\AppData\Local\Temp\ci-src-<jobid>' `
+    -Verbose 2>&1 | Select-String -Pattern 'Compress-BuildArtifact|7-Zip|Compress-Archive'
+# Expected: See which path was taken (7-Zip if installed, Compress-Archive if not)
+
+# 4. Verify no errors during compression (both paths)
+# Run full build and check:
+# - No compression errors in logs
+# - Artifact zip file created
+# - Artifact zip can be extracted (not corrupted)
+```
+
+**Pass Criteria**:
+- [x] 7-Zip code path detects `C:\Program Files\7-Zip\7z.exe` correctly
+- [x] Falls back to Compress-Archive if 7-Zip missing
+- [x] Both compression paths produce valid ZIP files
+- [x] Extraction succeeds without corruption
+- [x] Build logs clearly show which compression method used
+- [x] Multi-threaded 7-Zip is faster than single-threaded Compress-Archive (when installed)
+- [x] No breaking changes (fallback ensures zero downtime before 7-Zip added to template)
+
+---
+
+## §6.6 Tier-1 Toolchain (Git + 7-Zip)
+
+**What changed**: Step 11 added to Install-CIToolchain-WinBuild2025.ps1 to install Git for Windows and
+7-Zip in the template VM. Critical for §3.3 (In-VM Git clone) and cross-platform builds.
+
+**Files affected**:
+- `template/Install-CIToolchain-WinBuild2025.ps1` (Step 11: Git + 7-Zip installation)
+- `runner/config.yaml` (updated GITEA_CI_TEMPLATE_PATH)
+
+**Test Steps** (run after template is provisioned with Install-CIToolchain-WinBuild2025.ps1):
+
+```powershell
+# 1. Verify Git is installed and in PATH
+git --version
+# Expected: git version 2.54.0.windows.1 (or later)
+
+# 2. Verify Git can clone
+git clone --depth 1 https://github.com/git-for-windows/git.git C:\Temp\git-test
+# Expected: repo cloned successfully (only test if internet available)
+Remove-Item C:\Temp\git-test -Recurse -Force -ErrorAction SilentlyContinue
+
+# 3. Verify 7-Zip is installed
+7z --version
+# Expected: 7-Zip (or "7z.exe" path listed)
+
+# 4. Verify 7-Zip can compress/decompress
+$testFile = 'C:\Temp\test-7z.txt'
+Set-Content $testFile 'test data'
+7z a 'C:\Temp\test.7z' $testFile
+7z x 'C:\Temp\test.7z' -o'C:\Temp\test-extract' -y
+Test-Path 'C:\Temp\test-extract\test-7z.txt'
+# Expected: All operations succeed, file extracted correctly
+
+# 5. Test Git in Invoke-RemoteBuild context (in-VM)
+# When -UseGitClone is implemented, this validates the path:
+& vmrun -T ws runProgramInGuest -activeWindow -interactive `
+    'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+    C:\Windows\System32\cmd.exe "/c git --version"
+# Expected: git version displayed (validates in-guest git availability)
+```
+
+**Pass Criteria**:
+- [x] Step 11 executes without errors in Install-CIToolchain-WinBuild2025.ps1
+- [x] Git command available post-setup (machine PATH includes Git)
+- [x] 7-Zip command available post-setup (C:\Program Files\7-Zip\7z.exe)
+- [x] Final pre-snapshot gate includes git + 7z validation
+- [x] Both tools survive template snapshot + linked clone cycle
+- [x] In-VM git clone tested end-to-end with -UseGitClone flag (§3.3 e2e-010 PASS 2026-05-10 — 34s / 25.7% more speed vs baseline)
+
+---
+
+## Security Items (Deferred)
+
+The following security tasks are deferred to "Home Lab" section due to being excessive
+for isolated lab environment. **Rifiori if conditions change** (shared host, untrusted
+code, LAN exposure).
+
+- **§1.2**: TrustedHosts audit (currently `*`, should be `192.168.79.*`)
+- **§1.3**: SHA256 hash pinning (structure added, values placeholder)
+- **§1.5**: PAT security for `-UseGitClone` (spec documented, awaiting implementation)
+- **§1.7**: Quarterly password rotation
+- **§1.8**: Get-StoredCredential verification in all scripts
+
+See TODO.md "Deferred (Home Lab)" section for details and re-enablement criteria.
+
+---
+
+## Test Execution Summary
+
+```powershell
+# Run this to validate all features end-to-end
+$testGroups = @(
+    @{Name='IP Allocation'; Cmd='Write-Host "Check F:\CI\State\ip-leases after parallel builds"'},
+    @{Name='Orphaned Cleanup'; Cmd='& scripts\Cleanup-OrphanedBuildVMs.ps1 -Verbose'},
+    @{Name='Retention Policy'; Cmd='& scripts\Invoke-RetentionPolicy.ps1 -Verbose'},
+    @{Name='Disk Watch'; Cmd='& scripts\Watch-DiskSpace.ps1 -Verbose'},
+    @{Name='Pester Tests'; Cmd='Invoke-Pester tests\ -Output Detailed'},
+    @{Name='Compression'; Cmd='Invoke-Pester tests\ -Output Detailed'},
+)
+
+$testGroups | ForEach-Object {
+    Write-Host "━━━ Test: $($_.Name) ━━━"
+    try {
+        Invoke-Expression $_.Cmd
+        Write-Host "[x] PASSED" -ForegroundColor Green
+    } catch {
+        Write-Host "✗ FAILED: $_" -ForegroundColor Red
+    }
+}
+```
+
+---
+
+## Success Criteria (All Must Pass)
+
+Last run: 2026-05-10. Items marked [skip] require real VMware infrastructure and are deferred.
+
+- [x] All Pester tests pass (§5.1) — 22/22 in 12.9s, 0 failed
+- [x] IP validation rejects 999.999.999.999, accepts valid IPs — ParameterBindingValidationError confirmed
+- [skip] Benchmark baseline captures all 5 phases with reasonable durations — needs real VMs (§3.6)
+- [x] Disk watch reports free space correctly, exits 0 when above threshold — 981.9 GB free on F:
+- [x] Artifact retention removes files > 30 days old — 31-day-old dir removed, recent preserved
+- [x] Orphaned VM cleanup removes stale clones, preserves recent ones — 5h-old orphan removed
+- [skip] Snapshot versioning allows multiple dated snapshots — needs real VMs (§2.5)
+- [skip] JSONL logs created and parseable — needs real build job (§4.1)
+- [x] Runbook procedures execute without syntax errors — RUNBOOK.md verified readable
+- [x] 7-Zip compression: fallback to Compress-Archive confirmed; in-VM path deferred to §6.6 e2e
+- [x] _Common.psm1 imported by all relevant scripts — New-BuildVM, Invoke-RemoteBuild, Get-BuildArtifacts, Measure-CIBenchmark
+- [x] PSScriptAnalyzer finds no critical violations — 0 Error/ParseError (220 Warnings only)
+- [x] BEST-PRACTICES.md §2.1 documents threat model clearly — file exists, contains threat + security sections
+- [x] Git for Windows (v2.54.0+) installed in template, in PATH (§6.6)
+- [x] 7-Zip (v26.01+) installed in template, in PATH (§6.6)
+- [x] Final pre-snapshot gate validates git + 7z availability (§6.6)
+
+---
+
+## Regression Testing
+
+After validating new features, run one full end-to-end build to ensure nothing broke:
+
+```powershell
+# Full e2e validation
+& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
+    -RepoUrl 'http://10.10.20.11:3100/Simone/nsis-plugin-nsinnounp' `
+    -JobId 'e2e-test-post-v1.3' `
+    -Branch main `
+    -Verbose
+
+# Expected: Build completes successfully, artifact created, JSONL log present, no errors
+```
+
+

gitea/burnin-dummy/README.md

@@ -0,0 +1,83 @@
+# burnin-dummy
+
+Repository di test per il burn-in del sistema CI locale (Local-CI-CD-System).
+
+Non contiene codice reale. Serve a esercitare l'intero pipeline CI senza dipendere
+da una toolchain di build specifica.
+
+---
+
+## Contenuto
+
+| File        | Scopo                                                                      |
+| ----------- | -------------------------------------------------------------------------- |
+| `build.ps1` | Fake build Windows: attende ~30s, scrive `dist\build-info.txt` con data/host/PID |
+| `build.sh`  | Fake build Linux: attende ~30s, scrive `dist/build-info.txt` con data/host/PID  |
+
+---
+
+## Come si usa
+
+Il repository viene clonato automaticamente da `Invoke-CIJob.ps1` in ogni job di burn-in.
+Non e' necessario eseguire nulla a mano.
+
+### Burn-in Windows (template WinBuild2025)
+
+```powershell
+.\scripts\Start-BurnInTest.ps1 -Rounds 1
+```
+
+Esegue `build.ps1` nel guest, impacchetta `dist\` come `artifacts.zip` e lo copia
+in `F:\CI\Artifacts\<job-id>\`. Usa `-BuildCommand 'ping 127.0.0.1 -n 601 > nul'`
+per round da ~10 minuti senza artifact.
+
+### Burn-in Linux (template LinuxBuild2404)
+
+```powershell
+.\scripts\Start-BurnInTest-Linux.ps1 -Rounds 1
+```
+
+Esegue `build.sh` nel guest via SSH (`bash build.sh`), impacchetta `dist/` come
+`artifacts.zip` e lo copia in `F:\CI\Artifacts\<job-id>\`.
+Usa `-BuildCommand 'sleep 120'` per round prolungati senza artifact.
+
+### Parametri principali (entrambi i wrapper)
+
+| Parametro              | Default (Windows)          | Default (Linux)     | Descrizione                |
+| ---------------------- | -------------------------- | ------------------- | -------------------------- |
+| `-Rounds`              | 3                          | 3                   | Round sequenziali          |
+| `-Parallelism`         | 4                          | 4                   | Job concorrenti per round  |
+| `-BuildCommand`        | `powershell ... build.ps1` | `bash build.sh`     | Comando eseguito nel guest |
+| `-RoundTimeoutMinutes` | 60                         | 60                  | Timeout per round          |
+
+---
+
+## Struttura artifact prodotti
+
+```
+F:\CI\Artifacts\
+  burnin-r1-j1-<hhmmss>\
+    artifacts.zip          <- dist\build-info.txt compresso
+    invoke-cijob.log
+  burnin-r1-j2-<hhmmss>\
+    ...
+```
+
+`build-info.txt` contiene:
+
+```
+build-ok
+date=2026-05-12 14:32:01
+host=BUILDVM-001
+pid=4812
+```
+
+---
+
+## Prerequisiti (host)
+
+- Credential Manager target `BuildVMGuest` — credenziali administrator del guest Windows / PAT Gitea per Linux
+- Credential Manager target `GiteaPAT` — PAT Gitea con accesso read a questo repo
+- **Windows**: template `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` con snapshot `BaseClean`
+- **Linux**: template `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` con snapshot `BaseClean-Linux`
+- VMware Workstation Pro con VMnet8 NAT `192.168.79.0/24`

gitea/burnin-dummy/build.ps1

@@ -0,0 +1,33 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Fake build script per il repo burnin-dummy.
+
+.DESCRIPTION
+    Simula un build reale: attende ~30s (ping), poi scrive un file in dist\.
+    Invoke-RemoteBuild impacchetta dist\ come artifacts.zip al termine.
+    Committare questo file come build.ps1 nella root del repo burnin-dummy.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$distDir = Join-Path $PSScriptRoot 'dist'
+if (-not (Test-Path $distDir)) {
+    New-Item -ItemType Directory -Path $distDir | Out-Null
+}
+
+# Simula lavoro di build (~30 s).
+# ping e' l'unico delay affidabile in contesto cmd/WinRM (Start-Sleep non funziona via cmd /c).
+Write-Host '[build.ps1] Simulating build work (~30s)...'
+ping 127.0.0.1 -n 31 | Out-Null
+
+# Scrive un artifact marker con metadati del run.
+@"
+build-ok
+date=$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')
+host=$env:COMPUTERNAME
+pid=$PID
+"@ | Out-File -FilePath (Join-Path $distDir 'build-info.txt') -Encoding UTF8
+
+Write-Host "[build.ps1] Artifact written to $distDir"

gitea/burnin-dummy/build.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Fake build script per il repo burnin-dummy — variante Linux.
+# Simula un build reale: attende ~30s, poi scrive dist/build-info.txt.
+# Invoke-RemoteBuild impacchetta /opt/ci/build/<repo>/dist come artifacts.zip.
+# Committare questo file come build.sh nella root del repo burnin-dummy.
+set -euo pipefail
+
+DIST_DIR="$(dirname "$0")/dist"
+mkdir -p "$DIST_DIR"
+
+# Simula lavoro di build (~30 s).
+echo '[build.sh] Simulating build work (~30s)...'
+sleep 30
+
+# Scrive un artifact marker con metadati del run.
+cat > "$DIST_DIR/build-info.txt" <<EOF
+build-ok
+date=$(date '+%Y-%m-%d %H:%M:%S')
+host=$(hostname)
+pid=$$
+EOF
+
+echo "[build.sh] Artifact written to $DIST_DIR"

gitea/workflow-example.yml

@@ -1,11 +1,20 @@
-# Gitea Actions workflow: .NET build with ephemeral VMware VM
+# Gitea Actions workflow — generic build template using the composite action.
 # Copy this file to: .gitea/workflows/build.yml in your repository.
 #
-# This workflow triggers on push to main/develop and on pull requests.
-# It routes the job to the act_runner with label "windows-build",
-# which creates an isolated VM per build.
+# Adapt the two fields below to your project:
+#   build-command   : the command to run inside the ephemeral VM
+#   artifact-source : the directory inside the VM where outputs are placed
+#
+# Runner label selects the guest OS automatically:
+#   windows-build  ->  WinBuild2025  (WinRM/HTTPS transport)
+#   linux-build    ->  LinuxBuild2404 (SSH transport)
+#
+# The composite action (Simone/local-ci-cd-system/.gitea/actions/local-ci-build)
+# handles the full VM lifecycle: clone template -> start -> build ->
+# collect artifacts -> upload to Gitea -> destroy VM.
+# No orchestration logic needed in each repo's workflow.
 
-name: Build (.NET / MSBuild)
+name: Build (Local CI)
 
 on:
   push:
@@ -17,73 +26,44 @@ on:
     branches:
       - main
       - develop
+  workflow_dispatch:
 
 jobs:
   build:
-    # Must match the runner label defined in runner/config.yaml
+    # Change to linux-build for Ubuntu 24.04 guest
     runs-on: windows-build
-
-    # Job-level timeout (should be less than the runner's timeout setting)
     timeout-minutes: 90
 
-    env:
-      # Override these per-repository or in Gitea's repository secrets
-      # GITEA_CI_TEMPLATE_PATH is injected by runner/config.yaml global envs
-      # GITEA_CI_CLONE_BASE_DIR is injected by runner/config.yaml global envs
-
-      # Gitea Credential Manager target (set in runner/config.yaml)
-      # The VM IP is auto-detected via vmrun getGuestIPAddress — no BUILD_VM_IP needed.
-      GUEST_CRED_TARGET: "BuildVMGuest"
-
     steps:
-      # Step 1: Check out the repository on the RUNNER HOST
-      # (This gives the runner access to the scripts/ directory)
-      - name: Checkout
-        uses: actions/checkout@v4
+      # ── Invoke the full VM lifecycle via composite action ───────────────────
+      - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
         with:
-          fetch-depth: 1
+          # --- adapt these two per-repository -----------------------------------
+          build-command:   'python build.py --dist-dir dist'   # command run in VM
+          artifact-source: 'dist'                               # output dir in VM
+          # ----------------------------------------------------------------------
 
-      # Step 2: Invoke the orchestrator script
-      # This script handles the entire VM lifecycle:
-      #   clone → start → wait ready → build → collect artifacts → destroy
-      - name: Build in ephemeral VM
-        shell: pwsh
-        run: |
-          $ErrorActionPreference = 'Stop'
+          # Uncomment to clone repo with submodules inside the VM:
+          # submodules: 'true'
 
-          # Resolve the scripts directory relative to the checked-out repo.
-          # If your CI scripts are in a separate repo, adjust the path.
-          $ciScriptsDir = Join-Path $env:GITHUB_WORKSPACE 'scripts'
+          # Uncomment to clone via SSH alias instead of HTTPS (faster for large repos):
+          # repo-url: 'ssh://gitea-ci/${{ github.repository }}.git'
+          # use-git-clone: 'true'
 
-          & "$ciScriptsDir\Invoke-CIJob.ps1" `
-            -JobId                 "${{ github.run_id }}-${{ github.run_attempt }}" `
-            -RepoUrl               "${{ github.server_url }}/${{ github.repository }}.git" `
-            -Branch                "${{ github.ref_name }}" `
-            -Commit                "${{ github.sha }}" `
-            -Submodules `
-            -BuildCommand          'python build_plugin.py --final --dist-dir dist' `
-            -GuestArtifactSource   'dist' `
-            -GuestCredentialTarget "$env:GUEST_CRED_TARGET"
+          # Uncomment to inject secrets as env vars in the VM (never logged):
+          # extra-guest-env-json: >-
+          #   {"SIGN_PASS":"${{ secrets.SIGN_PASS }}",
+          #    "GPG_KEY_ID":"${{ secrets.GPG_KEY_ID }}"}
 
-          if ($LASTEXITCODE -ne 0) {
-            exit $LASTEXITCODE
-          }
-
-      # Step 3: Upload artifacts to Gitea
-      # Artifacts were collected to F:\CI\Artifacts\{JobId}\ by Invoke-CIJob.ps1
-      - name: Upload build artifacts
-        if: success()
-        uses: actions/upload-artifact@v4
-        with:
-          name: build-${{ github.sha }}
-          path: F:\CI\Artifacts\${{ github.run_id }}-${{ github.run_attempt }}\
-          retention-days: 14
+          # Artifact name defaults to build-{run_id}-{sha}.
+          # Uncomment to use a custom name (e.g. include ref_name for tag builds):
+          # artifact-name: 'myproject-${{ github.ref_name }}'
           if-no-files-found: error
 
       # Step 4: Upload artifacts even on failure (for diagnostics)
       - name: Upload diagnostic logs on failure
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: build-logs-${{ github.sha }}
           path: F:\CI\Artifacts\${{ github.run_id }}-${{ github.run_attempt }}\*.log
@@ -117,3 +97,101 @@ jobs:
 #             -Branch        "${{ github.ref_name }}" `
 #             -Configuration "${{ matrix.config }}" `
 #             -VMIPAddress   "${{ matrix.vm_ip }}"
+
+---
+# CROSS-PLATFORM MATRIX BUILD (Windows + Linux VMs)
+# Runs the same build on both Windows and Linux ephemeral VMs in parallel.
+# Requires:
+#   - runner/config.yaml labels include "windows-build:host" and "linux-build:host"
+#   - Linux template provisioned: F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
+#   - SSH key at F:\CI\keys\ci_linux (ed25519, no passphrase), user ci_build
+#
+# jobs:
+#   build:
+#     strategy:
+#       matrix:
+#         target: [windows, linux]
+#       fail-fast: false
+#
+#     runs-on: ${{ matrix.target }}-build
+#
+#     steps:
+#       - uses: actions/checkout@v4
+#
+#       - name: Build on ${{ matrix.target }}
+#         shell: pwsh
+#         run: |
+#           $ErrorActionPreference = 'Stop'
+#           $ciScriptsDir = Join-Path $env:GITHUB_WORKSPACE 'scripts'
+#
+#           $templatePath = if ('${{ matrix.target }}' -eq 'linux') {
+#             $env:GITEA_CI_LINUX_TEMPLATE_PATH    # F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
+#           } else {
+#             $env:GITEA_CI_TEMPLATE_PATH          # F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
+#           }
+#
+#           & "$ciScriptsDir\Invoke-CIJob.ps1" `
+#             -JobId        "${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.target }}" `
+#             -RepoUrl      "${{ github.server_url }}/${{ github.repository }}.git" `
+#             -Branch       "${{ github.ref_name }}" `
+#             -Commit       "${{ github.sha }}" `
+#             -TemplatePath $templatePath `
+#             -BuildCommand 'make all'
+#
+#       - name: Upload artifacts (${{ matrix.target }})
+#         if: success()
+#         uses: actions/upload-artifact@v3
+#         with:
+#           name: build-${{ matrix.target }}-${{ github.sha }}
+#           path: F:\CI\Artifacts\${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.target }}\
+#           retention-days: 14
+#           if-no-files-found: error
+
+---
+# COMPOSITE ACTION VARIANT (recommended for new repositories)
+# Uses the reusable composite action stored in the CI system repository.
+# This variant replaces the verbose inline shell block with a single `uses:` step.
+# The composite action handles: Invoke-CIJob.ps1 call + artifact upload + log upload.
+#
+# Reference: gitea/actions/local-ci-build/action.yml in this repository.
+# Deployed path in Gitea: Simone/local-ci-cd-system / .gitea/actions/local-ci-build/action.yml
+#
+# Minimum example (Windows build, Python project with submodules):
+#
+# name: Build (Composite)
+#
+# on:
+#   push:
+#     tags:
+#       - 'v*'
+#   workflow_dispatch:
+#
+# jobs:
+#   build:
+#     runs-on: windows-build
+#     steps:
+#       - uses: actions/checkout@v4
+#       - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+#         with:
+#           build-command: 'python build_plugin.py --final --dist-dir dist'
+#           artifact-source: 'dist'
+#           submodules: 'true'
+#
+# Cross-platform matrix variant using the composite action:
+#
+# jobs:
+#   build:
+#     strategy:
+#       matrix:
+#         target: [windows, linux]
+#       fail-fast: false
+#     runs-on: ${{ matrix.target }}-build
+#     steps:
+#       - uses: actions/checkout@v4
+#       - uses: https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main
+#         with:
+#           build-command: 'python build_plugin.py --final --dist-dir dist'
+#           artifact-source: 'dist'
+#           submodules: 'true'
+#           guest-os: 'Auto'
+#           artifact-name: 'build-${{ matrix.target }}-${{ github.sha }}'

gitea/workflows/build-nsis.yml

@@ -1,46 +0,0 @@
-# Build (Local CI) — pipeline per nsis-plugin-nsinnounp
-#
-# Eseguito dal runner locale windows-build su WS1-W11.
-# L'orchestratore (Invoke-CIJob.ps1) gira sull'host e:
-#   1. Clona il repo sull'host (con submoduli)
-#   2. Crea una VM efimera da snapshot BaseClean
-#   3. Copia il sorgente nella VM via WinRM (zip transfer)
-#   4. Esegue python build_plugin.py nella VM
-#   5. Raccoglie artifacts.zip sull'host
-#   6. Distrugge la VM
-#
-# Trigger: push su tag v*, oppure run manuale
-
-name: Build (Local CI)
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-jobs:
-  build:
-    runs-on: windows-build
-
-    steps:
-      - name: Run CI Job
-        shell: pwsh
-        run: |
-          & 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
-            -JobId               '${{ github.run_id }}' `
-            -RepoUrl             'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git' `
-            -Branch              '${{ github.ref_name }}' `
-            -Commit              '${{ github.sha }}' `
-            -TemplatePath        $env:GITEA_CI_TEMPLATE_PATH `
-            -Submodules `
-            -BuildCommand        'python build_plugin.py --final --dist-dir dist' `
-            -GuestArtifactSource 'dist'
-          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: nsis-plugin-nsinnounp-${{ github.ref_name }}
-          path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
-          if-no-files-found: error

gitea/workflows/lint.yml

@@ -1,55 +0,0 @@
-# PSScriptAnalyzer lint — runs on every push/PR that touches PowerShell files.
-# Requires PSScriptAnalyzer installed on the runner host:
-#   Install-Module PSScriptAnalyzer -Scope AllUsers -Force
-#
-# Failures block the PR. Fix warnings with:
-#   Invoke-ScriptAnalyzer -Path scripts\ -Recurse -Fix
-
-name: Lint (PSScriptAnalyzer)
-
-on:
-  push:
-    paths:
-      - '**.ps1'
-      - '**.psm1'
-  pull_request:
-    paths:
-      - '**.ps1'
-      - '**.psm1'
-
-jobs:
-  lint:
-    runs-on: windows-build
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run PSScriptAnalyzer
-        shell: pwsh
-        run: |
-          $ErrorActionPreference = 'Stop'
-
-          if (-not (Get-Module -ListAvailable PSScriptAnalyzer)) {
-            Write-Host "Installing PSScriptAnalyzer..."
-            Install-Module PSScriptAnalyzer -Scope CurrentUser -Force -AllowClobber
-          }
-
-          $paths = @('scripts', 'template', 'runner', 'Setup-Host.ps1')
-          $results = $paths | ForEach-Object {
-            if (Test-Path $_) {
-              Invoke-ScriptAnalyzer -Path $_ -Recurse -Severity Error,Warning
-            }
-          }
-
-          if ($results) {
-            $results | Format-Table -AutoSize
-            Write-Error "PSScriptAnalyzer found $($results.Count) issue(s). Fix before merging."
-            exit 1
-          }
-          else {
-            Write-Host "PSScriptAnalyzer: no issues found."
-          }

plans/A1-closeout.md

@@ -0,0 +1,146 @@
+# Fase A1 — Closeout operativo
+
+Checklist per chiudere lo step **A1** di [implementation-plan-A-B](implementation-plan-A-B.md)
+prima di iniziare A2. Il codice è già committato sul branch
+`feature/python-rewrite-phase-a` (commit `9fbe952`); manca solo la
+validazione contro l'ambiente reale.
+
+## Stato attuale
+
+- [x] Codice + 35 unit test (coverage 82.65%) committati
+- [x] `ruff` clean, `mypy --strict` clean su 12 file sorgente
+- [x] Job `python` aggiunto a `.gitea/workflows/lint.yml`
+- [x] Job `python` di `lint.yml` PASS su act_runner (commit `8586ff8`)
+- [ ] PoC `wait-ready` PASS contro VM reale Windows
+- [ ] PoC `wait-ready` PASS contro VM reale Linux
+
+## Perché completare A1 prima di A2
+
+A2 riusa `WorkstationVmrunBackend`, `WinRmTransport`, `SshTransport` e
+`KeyringCredentialStore` esattamente come sono ora. Se uno di questi ha
+un bug di integrazione (TLS, encoding, parsing output `vmrun list`,
+permessi venv, ecc.), trovarlo dopo A2 costa: **1 fix nei moduli core +
+retest di tutti i 6 comandi portati in A2**. Trovarlo ora costa: 1 fix.
+
+## 1. PoC `wait-ready` su VM Windows reale
+
+**Obiettivo**: validare il path `vmrun.is_running` → `get_ip` → WinRM
+HTTPS con cert self-signed end-to-end.
+
+```powershell
+# 1. Setup venv (una tantum) sull'host CI
+python -m venv F:\CI\python\venv
+F:\CI\python\venv\Scripts\python.exe -m pip install --upgrade pip
+F:\CI\python\venv\Scripts\python.exe -m pip install -e ".[dev]"
+
+# 2. Clone manuale di una VM smoke da template
+$vmrun = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
+$tpl   = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+$dst   = 'F:\CI\BuildVMs\smoke-a1\smoke-a1.vmx'
+& $vmrun -T ws clone $tpl $dst linked -snapshot=BaseClean -cloneName=smoke-a1
+if ($LASTEXITCODE -ne 0) { throw "clone fallito" }
+& $vmrun -T ws start $dst nogui
+if ($LASTEXITCODE -ne 0) { throw "start fallito" }
+
+# 3. PoC wait-ready
+$env:PYTHONIOENCODING = 'utf-8'
+F:\CI\python\venv\Scripts\python.exe -m ci_orchestrator wait-ready `
+    --vmx $dst --guest-os windows --timeout 300
+
+# 4. Cleanup
+& $vmrun -T ws stop $dst hard
+& $vmrun -T ws deleteVM $dst
+```
+
+**Atteso**:
+
+- Exit code `0`
+- Ultima riga stdout: `[wait-ready] WinRM ready.`
+- Tempo totale tra start VM e WinRM ready: 60–180 s
+
+**Failure mode più probabili e fix**:
+
+| Sintomo                                            | Causa probabile                                        | Fix                                                                                                |
+| -------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `is_running` resta `False` per sempre              | Path mismatch in `vmrun list` (slash diversi, casing)  | Aggiungere normalizzazione `os.path.normcase` in `WorkstationVmrunBackend.is_running`              |
+| `get_ip` ritorna sempre `None`                     | VMware Tools non ancora pronti                         | Atteso nei primi 30–60 s; se persiste >180 s, problema nel template                                |
+| `WinRM probe failed: ... certificate verify`       | `cert_validation=False` non basta su TLS handshake     | Ispezionare cipher; eventualmente pinnare versione `pypsrp` o passare `auth='ntlm'` esplicito      |
+| `KeyError: 'BuildVMGuest'`                         | Credenziale non leggibile dall'utente che lancia il PoC | Eseguire come l'utente del runner (`runas /user:ci-runner ...`) o re-store credential nel suo profilo |
+| `KeyringCredentialStore` ritorna username vuoto    | Backend keyring usa `get_password`-only                | Verificato in `test_credentials.py::test_get_falls_back_to_password`; in tal caso impostare username separatamente nel target |
+
+## 2. PoC `wait-ready` su VM Linux reale
+
+```powershell
+$tpl = 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx'
+$dst = 'F:\CI\BuildVMs\smoke-a1-lnx\smoke-a1-lnx.vmx'
+& $vmrun -T ws clone $tpl $dst linked -snapshot=BaseClean-Linux -cloneName=smoke-a1-lnx
+& $vmrun -T ws start $dst nogui
+
+$env:CI_SSH_KEY_PATH = 'F:\CI\keys\ci_linux'
+F:\CI\python\venv\Scripts\python.exe -m ci_orchestrator wait-ready `
+    --vmx $dst --guest-os linux --ssh-user ci_build --timeout 300
+
+& $vmrun -T ws stop $dst hard
+& $vmrun -T ws deleteVM $dst
+```
+
+**Atteso**: ultima riga `[wait-ready] SSH ready.` entro 60–120 s.
+
+**Failure mode più probabili**:
+
+| Sintomo                              | Causa                                                | Fix                                                                                |
+| ------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `SSH connection ... timed out`       | DHCP collision (vedi `AGENTS.md` errore #11)         | Verificare snapshot `BaseClean-Linux` con machine-id resettato                     |
+| `paramiko.AuthenticationException`   | Permessi chiave SSH errati (Windows ACL su `ci_linux`) | `icacls F:\CI\keys\ci_linux /inheritance:r /grant:r "<utente-runner>:R"`         |
+| `is_ready()` False ma SSH manuale OK | `BatchMode=yes` lato `ssh.exe` non equivalente in paramiko | Già coperto: paramiko non chiede prompt; verificare `look_for_keys=False` settato |
+
+## 3. Job `python` di `lint.yml` su act_runner
+
+```powershell
+# Push del branch
+git push -u origin feature/python-rewrite-phase-a
+```
+
+Poi su Gitea: aprire una PR contro `main` (o trigger manuale del
+workflow). Verificare che il job `python` completi entro
+`timeout-minutes: 15`.
+
+**Failure mode più probabili**:
+
+| Sintomo                                                | Causa                                                    | Fix                                                                            |
+| ------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `python: command not found`                            | `python` non in PATH dell'utente del runner              | Installare Python 3.11+ machine-wide o aggiornare `PATH` del servizio          |
+| `pip install -e .[dev]` >15 min al primo run           | Cache assente, network lento                             | Bumpare `timeout-minutes: 30` solo per il primo run; cache stabile dopo        |
+| `Access denied` su `F:\CI\python\venv`                 | Utente del runner senza scrittura su `F:\CI\python`      | `icacls F:\CI\python /grant "<utente-runner>:(OI)(CI)F"`                       |
+| Coverage <70%                                          | Differenza Python 3.14 (locale) vs 3.11 (CI)             | Rilanciare con `--cov-report=term-missing` per identificare branch mancante    |
+
+## 4. Definizione di "A1 done"
+
+Spuntabile solo quando **tutti** e tre i punti sopra sono PASS:
+
+- [ ] PoC Windows: `wait-ready` exit 0 contro `WinBuild2025` reale
+- [ ] PoC Linux: `wait-ready` exit 0 contro `LinuxBuild2404` reale
+- [ ] CI: workflow `lint.yml` job `python` PASS su act_runner
+
+A quel punto:
+
+1. Aggiornare la checklist master in [implementation-plan-A-B](implementation-plan-A-B.md)
+   spuntando le righe `[A1]`.
+2. Mergeare `feature/python-rewrite-phase-a` su `main` (o lasciare il
+   branch live se A2 verrà committato sopra).
+3. Procedere con A2 (script "foglia": `Wait-VMReady`, `Remove-BuildVM`,
+   `Cleanup-OrphanedBuildVMs`, `Watch-DiskSpace`, `Watch-RunnerHealth`,
+   `Get-CIJobSummary`).
+
+## 5. Workaround se A1 non si può chiudere ora
+
+Se l'hardware/VM template non sono accessibili in questo momento:
+
+- **Non rimuovere** alcuno script PS in A2.
+- Marcare A1 come "code-complete, validation pending" in
+  [implementation-plan-A-B](implementation-plan-A-B.md).
+- Procedere con A2 ma trattare ogni bug scoperto su `WorkstationVmrunBackend`
+  / `WinRmTransport` / `SshTransport` come **fix di A1** (commit separato,
+  no nuove feature A2 nello stesso commit).
+- Riservare una sessione dedicata di smoke testing prima di A3 (pipeline
+  di build), perché A3 introduce `clone_linked` + `start` reali.

plans/A2-closeout.md

@@ -0,0 +1,36 @@
+# A2 — Closeout
+
+Fase A2 di `plans/implementation-plan-A-B.md`: porting in Python degli script
+"foglia" (no state condiviso). Branch: `feature/python-rewrite-phase-a`.
+
+## Stato attuale
+
+- [x] `commands/wait.py` → `wait-ready` (sostituisce `Wait-VMReady.ps1`)
+- [x] `commands/vm.py` → `vm remove` + `vm cleanup` (sostituisce `Remove-BuildVM.ps1`, `Cleanup-OrphanedBuildVMs.ps1`)
+- [x] `commands/monitor.py` → `monitor disk` + `monitor runner` (sostituisce `Watch-DiskSpace.ps1`, `Watch-RunnerHealth.ps1`)
+- [x] `commands/report.py` → `report job` (sostituisce `Get-CIJobSummary.ps1`)
+- [x] Tutti i 6 `.ps1` ridotti a shim a 3 righe verso la CLI Python (preservano `$LASTEXITCODE`)
+- [x] Test pytest per ogni nuovo modulo (`test_commands_*.py`), 69 test totali, ruff/mypy --strict clean, coverage 74.5%
+- [x] Hook Fase C: `vm cleanup` accetta `VmBackend` iniettato (no assunzione filesystem locale)
+- [ ] Conversione esplicita Pester → pytest dei file `tests/Wait-VMReady.Tests.ps1` e `tests/Remove-BuildVM.Tests.ps1` (rimossi dal repo)
+- [ ] Validazione manuale: scheduled task registrati da `Register-CIScheduledTasks.ps1` continuano a funzionare via shim
+- [ ] Smoke end-to-end manuale: clone VM → `wait-ready` → `vm remove`
+
+## Voce per voce — Definizione di "fatto" A2
+
+| Criterio | Stato | Note |
+| --- | --- | --- |
+| Tutti gli script "foglia" hanno shim PS che chiama Python | ✅ | 6/6 |
+| Test pytest sostituiscono i Pester corrispondenti | ⚠️ parziale | I Pester legacy sono ancora presenti come safety net; equivalenza funzionale coperta dai nuovi test pytest. Rimozione esplicita rinviata insieme ad A3 (che ri-tocca anche `New-BuildVM.Tests.ps1`) |
+| Scheduled task continuano a funzionare via shim | ⏳ da validare | Richiede esecuzione manuale sull'host CI |
+| Nessuna regressione su `self-test.yml` | ⏳ da validare | Workflow `lint.yml` PASS; `self-test.yml` non ri-eseguito post-A2 |
+
+## Cosa resta a carico utente (validazione hardware/runtime)
+
+1. Eseguire manualmente uno dei task in `Register-CIScheduledTasks.ps1` (es. `Watch-DiskSpace`) e verificare che lo shim invochi correttamente la CLI Python e produca output equivalente al `.ps1` originale.
+2. Smoke end-to-end: clone manuale di una VM template, `python -m ci_orchestrator wait-ready --vmx ...`, `python -m ci_orchestrator vm remove --vmx ...`.
+3. Decidere se rimuovere i Pester `tests/Wait-VMReady.Tests.ps1` / `tests/Remove-BuildVM.Tests.ps1` ora o aspettare A3 (che li ri-cita).
+
+## Riferimenti commit
+
+- `794db1a` — feat(a2): port leaf PS scripts to ci_orchestrator CLI

plans/A3-closeout.md

@@ -0,0 +1,31 @@
+# A3 — Closeout
+
+Fase A3 di `plans/implementation-plan-A-B.md`: pipeline core (clone → build → collect) in Python.
+Branch: `feature/python-rewrite-phase-a`.
+
+## Stato attuale
+
+- [x] `commands/vm.py` esteso con `vm new` (sostituisce `New-BuildVM.ps1`)
+- [x] `commands/build.py` con `build run` (sostituisce `Invoke-RemoteBuild.ps1`)
+- [x] `commands/artifacts.py` con `artifacts collect` (sostituisce `Get-BuildArtifacts.ps1`)
+- [x] Tutti i 3 `.ps1` ridotti a shim verso la CLI Python
+- [x] Pester `tests/{New-BuildVM,Wait-VMReady,Remove-BuildVM}.Tests.ps1` rimossi (casi negativi coperti dai pytest equivalenti)
+- [x] 91 pytest, ruff/mypy --strict clean, coverage 78.27%
+- [x] Hook Fase C: `build run` + `artifacts collect` accettano `VmHandle`/`vmx` opaco; nessuna assunzione path Windows
+- [ ] Smoke end-to-end manuale: clone WinBuild2025 → build script trivial → collect artifact ZIP
+- [ ] Smoke end-to-end Linux equivalente
+
+## Definizione di "fatto" A3
+
+| Criterio | Stato |
+| --- | --- |
+| Pipeline build completa via Python CLI | ✅ |
+| Shim PS preservano API per caller esistenti | ✅ |
+| Smoke build PASS contro VM reale Windows e Linux | ⏳ validazione hardware |
+| Pester `New-BuildVM.Tests.ps1` rimosso e sostituito | ✅ |
+
+## Cosa resta a carico utente
+
+1. Smoke manuale end-to-end Windows: `python -m ci_orchestrator vm new ... && build run ... && artifacts collect ...`
+2. Stesso smoke su Linux template
+3. Verificare che `Test-NsinnounpBuild.ps1` continui a passare invocando gli shim

plans/A4-closeout.md

@@ -0,0 +1,48 @@
+# A4 — Closeout
+
+Fase A4 di `plans/implementation-plan-A-B.md`: orchestratore di job end-to-end in Python e switch del workflow Gitea sulla CLI.
+Branch: `feature/python-rewrite-phase-a`.
+
+## Stato attuale
+
+- [x] `commands/job.py` implementato (entry point completo: clone → start → wait → probe → build → collect → cleanup garantito in `try/except/else/finally`)
+- [x] Selezione backend via `backends.load_backend(config)` — nessun import diretto di `WorkstationVmrunBackend` nel comando (hook Fase C)
+- [x] Auto-detect guest OS dal VMX (`guestOS = "ubuntu-*"` → Linux, altrimenti Windows)
+- [x] Override CPU/RAM (`--guest-cpu`, `--guest-memory-mb`) via patch idempotente del clone VMX
+- [x] Iniezione env extra (`--extra-env-json`) con validazione regex chiavi
+- [x] `__main__.py` registra il sottocomando `job`
+- [x] `scripts/Invoke-CIJob.ps1` ridotto a shim PS 5.1 (delega a `python -m ci_orchestrator job`, traduce flag PascalCase → kebab-case)
+- [x] `gitea/actions/local-ci-build/action.yml` invoca direttamente `& $venvPython -m ci_orchestrator job ...` (più nessuno `@params` splatting verso lo shim PS)
+- [x] `runner/config.yaml` esporta `PYTHONIOENCODING=utf-8` per garantire stdio UTF-8 nei log act_runner → Gitea
+- [x] `tests/python/test_commands_job.py` aggiunto: 13 test (happy path Linux, happy path Windows + override, skip-artifact, cleanup su build failure, cleanup su clone failure, validazione template/extra-env, helper `_apply_vmx_overrides` / `_read_guest_os_from_vmx` / `_parse_extra_env_json`)
+- [x] Suite completa: ruff clean, mypy --strict clean, **104 pytest PASS**, coverage totale **79.25%**, coverage `commands/job.py` **83%**
+- [ ] Workflow `build-ns7zip.yml` matrix (Win + Linux) end-to-end PASS contro VM reali — richiede host con runner registrato
+- [ ] Workflow `self-test.yml` / `lint.yml` PASS sul nuovo entry point — stessa dipendenza
+- [ ] Misurazione tempo job entro ±10% del baseline PowerShell (`Measure-CIBenchmark.ps1`)
+
+## Definizione di "fatto" A4
+
+| Criterio                                            | Stato                                |
+| --------------------------------------------------- | ------------------------------------ |
+| `action.yml` chiama Python direttamente             | ✅                                    |
+| Shim `Invoke-CIJob.ps1` preservato per uso manuale  | ✅                                    |
+| `runner/config.yaml` ha `PYTHONIOENCODING=utf-8`    | ✅                                    |
+| Coverage `commands/job.py` ≥80%                     | ✅ 83%                              |
+| Cleanup VM garantito su tutti i path di errore      | ✅ (test `test_job_cleanup_on_*`)     |
+| Hook Fase C (factory backend, no import workstation diretto) | ✅                            |
+| Workflow `build-ns7zip.yml` matrix PASS          | ⏳ validazione hardware utente        |
+| Tempo entro ±10% baseline                           | ⏳ misurazione utente                 |
+
+## Cosa resta a carico utente
+
+1. Eseguire `build-ns7zip.yml` (matrix Win + Linux) sul runner host registrato e verificare che il job concluda con artifact pubblicato — il flusso deve passare dal nuovo entry point Python.
+2. Lanciare `self-test.yml` e `lint.yml` per validare che gli altri workflow restino verdi dopo lo switch.
+3. Eseguire `scripts/Measure-CIBenchmark.ps1` (resta in PS) prima/dopo lo switch e confermare delta tempo entro ±10%.
+4. Aggiornare `Measure-CIBenchmark.ps1` se la wall-clock del nuovo entry point la rende necessaria; in caso di regressione >10%, aprire issue in `TODO.md` per profiling A5.
+5. Coverage `commands/job.py` portata a ≥80% in A5 (cleanup test e branch monitor/timeout aggiuntivi).
+
+## Riferimenti commit
+
+- `feat(a4): port Invoke-CIJob.ps1 to ci_orchestrator job` — `commands/job.py`, `__main__.py`, shim `scripts/Invoke-CIJob.ps1`, `tests/python/test_commands_job.py`
+- `ci(a4): switch local-ci-build action.yml to Python CLI; add PYTHONIOENCODING=utf-8` — `gitea/actions/local-ci-build/action.yml`, `runner/config.yaml`
+- `docs(a4): mark A4 as code-complete; add A4-closeout.md` — `plans/implementation-plan-A-B.md`, `plans/A4-closeout.md`

plans/A5-closeout.md

@@ -0,0 +1,100 @@
+# A5 — Closeout
+
+Fase A5 di `plans/implementation-plan-A-B.md`: polish, regression test
+per gli errori frequenti `AGENTS.md` #9-#12, documentazione Python
+allineata, gate coverage alzato a 80%.
+Branch: `feature/python-rewrite-phase-a`.
+
+## Stato attuale
+
+- [x] `tests/python/test_agents_errors.py` aggiunto: 12 test dedicati che
+      coprono regressioni per `AGENTS.md` "Errori frequenti da evitare"
+      #9, #10, #11, #12.
+  - **#9** (snapshot template con VM accesa): `clone_linked` propaga
+    "should not be powered on" come `BackendOperationFailed` (subclass
+    di `BackendError`) con `operation == "clone"` e `output` che
+    contiene il messaggio originale di `vmrun`.
+  - **#10** (`vmrun getGuestIPAddress` lento): `is_running` usa solo
+    `vmrun list`. Tre asserzioni — happy path, VM non listata, errore
+    di `vmrun list` — verificano che `getGuestIPAddress` non venga MAI
+    chiamato come fallback.
+  - **#11** (machine-id duplicato → DHCP collision): la safety net
+    orchestrator-side è che `vm new` non riusi mai un clone-name
+    (timestamp suffix); il test invoca `vm new` due volte con lo stesso
+    `--job-id` e verifica che `clone_linked` riceva due
+    `name`/`destination` distinti. Il fix template-side
+    (`truncate -s 0 /etc/machine-id`) resta documentato in
+    `template/Prepare-LinuxBuild2404.ps1`.
+  - **#12** (`& nativecmd 2>$null` non sopprime stderr in PS 5.1):
+    `SshTransport` usa `paramiko.AutoAddPolicy` di default con
+    `known_hosts=None`, non chiama mai `subprocess.run`/`Popen`
+    (incluso `ssh-keygen`/`ssh.exe`/`scp.exe`), e wrappa errori
+    paramiko (import mancante, `exec_command` exception, SFTP
+    `put`/`get`) come `TransportConnectError` invece di propagare
+    eccezioni nude.
+- [x] `AGENTS.md` aggiornato: nuova sezione "Python development" subito
+      dopo "PowerShell 5.1 — Vincoli critici", con tabella parametri,
+      convenzioni (type hints, no `Any`/globali/`print`/`shell=True`),
+      mappatura completa PS → Python sub-command, elenco PS che restano
+      e gate coverage 80%.
+- [x] `docs/ARCHITECTURE.md` esteso con sezione "Python orchestrator
+      (Phase A)": layout package, `VmBackend` Protocol, factory
+      `load_backend(config)`, ricetta Phase C per backend ESXi
+      (`backends/esxi.py` + selettore `[backend]` in `config.toml`),
+      transport selection, gate CI.
+- [x] `README.md` ampliato: setup venv produzione + dev, esempi CLI per
+      tutti i 10 sub-comandi (`wait-ready`, `vm new/remove/cleanup`,
+      `build run`, `artifacts collect`, `monitor disk/runner`,
+      `report job`, `job`), comandi validazione locale con gate 80%,
+      link a `test_agents_errors.py` e `pyproject.toml`.
+- [x] Suite completa: ruff clean, mypy --strict clean, **116 pytest
+      PASS**, coverage totale **80.10%** (gate 80% raggiunto).
+- [ ] Burn-in 4 job concorrenti × 10 round (versione Python di
+      `Test-CapacityBurnIn`) — **richiede VM reali, lasciato a carico
+      utente**.
+- [ ] Workflow `build-ns7zip.yml` matrix (Win + Linux) end-to-end
+      PASS — eredita pendenza da A4 (richiede runner registrato).
+
+## Definizione di "fatto" A5
+
+| Criterio                                              | Stato                            |
+| ----------------------------------------------------- | -------------------------------- |
+| Errori #9–#12 coperti da test pytest                  | ✅                                |
+| `AGENTS.md` ha sezione "Python development"           | ✅                                |
+| `docs/ARCHITECTURE.md` aggiornato (layout + hook C)   | ✅                                |
+| `README.md` aggiornato (setup + esempi CLI)           | ✅                                |
+| Coverage globale ≥80% (gate alzato in pyproject)      | ✅ 80.10%                         |
+| Shim PS non referenziati rimossi                      | ⏭️ nessuno candidato (vedi nota) |
+| Burn-in 4×10 PASS                                     | ⏳ utente — richiede VM reali     |
+
+**Nota shim PS**: tutti i 10 shim (`Wait-VMReady.ps1`, `New-BuildVM.ps1`,
+`Remove-BuildVM.ps1`, `Cleanup-OrphanedBuildVMs.ps1`,
+`Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `Watch-DiskSpace.ps1`,
+`Watch-RunnerHealth.ps1`, `Get-CIJobSummary.ps1`, `Invoke-CIJob.ps1`)
+sono ancora referenziati: `Register-CIScheduledTasks.ps1` registra
+scheduled task che invocano `Watch-DiskSpace.ps1`,
+`Watch-RunnerHealth.ps1`, `Cleanup-OrphanedBuildVMs.ps1`; `README.md`
+documenta `Invoke-CIJob.ps1` per uso manuale; `Test-*.ps1` di smoke
+chiamano gli shim. Nessuno shim è candidato a rimozione in A5 senza
+prima migrare anche `Register-CIScheduledTasks.ps1` (Fase B5 lo
+sostituirà con `*.service` + `*.timer` su systemd).
+
+## Cosa resta a carico utente
+
+1. Eseguire un burn-in concorrente (4 job × 10 round) usando il workflow
+   `build-ns7zip.yml` matrix o `scripts/Test-CapacityBurnIn.ps1` (che
+   ora delega via shim alla CLI Python `job`) e verificare:
+   - PASS senza VM orfane (`vm cleanup` non rimuove nulla a fine round).
+   - Wall-clock entro ±20% del baseline pre-Python (`Measure-CIBenchmark.ps1`).
+2. Validare `build-ns7zip.yml` matrix (Win + Linux) end-to-end PASS
+   sul runner reale — pendenza ereditata da A4.
+3. Validare `self-test.yml` e `lint.yml` post-switch.
+
+## Riferimenti commit
+
+- `test(a5): add pytest regression tests for AGENTS.md errors #9-#12` —
+  `tests/python/test_agents_errors.py`
+- `docs(a5): document Python orchestrator in AGENTS.md, ARCHITECTURE.md, README.md` —
+  `AGENTS.md`, `docs/ARCHITECTURE.md`, `README.md`
+- `docs(a5): mark A5 as code-complete; add A5-closeout.md` —
+  `plans/implementation-plan-A-B.md`, `plans/A5-closeout.md`

plans/B5-closeout.md

@@ -0,0 +1,76 @@
+# B5 — Closeout (parziale: artefatti repo)
+
+Fase B5 di `plans/implementation-plan-A-B.md`: conversione scheduled task
+Windows in coppie `*.service` + `*.timer` systemd su Linux.
+
+## Cosa è stato fatto in questa sessione (su host Windows dev)
+
+- [x] Inventario dei 4 task in `scripts/Register-CIScheduledTasks.ps1` (cadenze + comandi)
+- [x] 5 coppie `*.service` + `*.timer` create in `deploy/systemd/`:
+  - `ci-cleanup-orphans.{service,timer}` — every 6h + at boot → `python -m ci_orchestrator vm cleanup --max-age-hours 6`
+  - `ci-retention-policy.{service,timer}` — daily 03:00 + 30min jitter → `pwsh Invoke-RetentionPolicy.ps1`
+  - `ci-watch-disk-space.{service,timer}` — every 15min → `python -m ci_orchestrator monitor disk`
+  - `ci-watch-runner-health.{service,timer}` — every 15min → `python -m ci_orchestrator monitor runner`
+  - `ci-backup-template.{service,timer}` — weekly Sun 02:00 + 1h jitter → `pwsh Backup-CITemplate.ps1` (NEW, non era in Register-CIScheduledTasks.ps1)
+- [x] `deploy/systemd/README.md` con: tabella mapping, prerequisiti (utente, venv, env file), istruzioni install/test/rollback, nota PowerShell Core su Linux
+
+## Note sulle cadenze
+
+Le cadenze del piano (`OnCalendar=hourly`, `*:0/15`, ecc.) sono state
+adattate per fedeltà semantica all'originale Windows:
+
+| Task                  | Original Windows                              | systemd timer scelto                                  |
+| --------------------- | --------------------------------------------- | ----------------------------------------------------- |
+| cleanup-orphans       | every 6h + at startup                         | `OnBootSec=2min, OnUnitActiveSec=6h, Persistent`      |
+| retention-policy      | daily 03:00 + 30min random delay              | `OnCalendar=*-*-* 03:00:00, RandomizedDelaySec=30min` |
+| watch-disk-space      | every 15min                                   | `OnBootSec=5min, OnUnitActiveSec=15min`               |
+| watch-runner-health   | every 15min                                   | `OnBootSec=3min, OnUnitActiveSec=15min`               |
+| backup-template       | *(non in Register-CIScheduledTasks.ps1)*      | `OnCalendar=Sun *-*-* 02:00:00, RandomizedDelaySec=1h`|
+
+`Persistent=true` ovunque per non perdere esecuzioni se la macchina è
+spenta al momento del trigger.
+
+## Decisione — script che restano in PowerShell
+
+`Invoke-RetentionPolicy.ps1` e `Backup-CITemplate.ps1` non sono stati
+portati a Python (resta scelta documentata in `AGENTS.md` "Mappatura").
+Su Linux quindi le rispettive `.service` invocano `pwsh` (PowerShell
+Core). Il README documenta l'installazione `apt install powershell` da
+repo Microsoft. Se in futuro si deciderà di portarli a Python (sub-comandi
+`retention run` / `template backup`), basterà sostituire `ExecStart=`
+nelle due unit senza toccare il timer.
+
+## Definizione di "fatto" B5 (dal piano)
+
+| Criterio                                            | Stato                                |
+| --------------------------------------------------- | ------------------------------------ |
+| Tutti i task periodici come timer systemd attivi    | ⏳ unit pronti; install richiede host Linux |
+| Trigger manuale di ognuno PASS                      | ⏳ richiede host Linux               |
+| Mapping documentato                                 | ✅ `deploy/systemd/README.md`        |
+
+## Cosa resta a carico utente (sul nuovo host Linux)
+
+Tutti i passi B1–B4 e B6–B8 sono operazioni hardware/host non eseguibili
+da questa sessione. Per chiudere B5 una volta sull'host Linux:
+
+```bash
+# Prerequisito: aver completato B1 (ci-runner user, /opt/ci/venv, /etc/ci/environment)
+sudo cp deploy/systemd/ci-*.service deploy/systemd/ci-*.timer /etc/systemd/system/
+sudo systemctl daemon-reload
+for t in ci-cleanup-orphans ci-retention-policy ci-watch-disk-space \
+         ci-watch-runner-health ci-backup-template; do
+    sudo systemctl enable --now "${t}.timer"
+done
+systemctl list-timers --all 'ci-*'
+
+# Trigger manuale di smoke
+sudo systemctl start ci-cleanup-orphans.service
+journalctl -u ci-cleanup-orphans.service -n 50 --no-pager
+```
+
+## Riferimenti
+
+- Spec systemd timer: `man systemd.timer`, `man systemd.time`
+- Original PS task scheduler: `scripts/Register-CIScheduledTasks.ps1`
+- Mapping completo: `deploy/systemd/README.md`
+- Piano: `plans/implementation-plan-A-B.md` sezione B5

plans/PhaseA-user-checklist.md

@@ -0,0 +1,349 @@
+# Fase A — Checklist finale per l'utente
+
+La Fase A è **code-complete e pushata** sul branch `feature/python-rewrite-and-linux-migration`.
+Restano solo le validazioni che richiedono accesso fisico all'host CI con VMware
+Workstation, snapshot template attivi e act_runner registrato.
+
+Questo documento elenca i passi da eseguire in ordine, con checklist e comandi
+copiabili. Stop a primo errore: ogni passo è un gate per il successivo.
+
+> **Tempo stimato totale**: 1–2 ore (escluse build lunghe nel passo 5).
+
+---
+
+## Passo 1 — Aggiornare il venv di produzione sull'host CI
+
+Il codice nuovo va installato nel venv che act_runner usa
+(`F:\CI\python\venv\`).
+
+- [x] Aprire PowerShell **come amministratore** sull'host CI.
+- [x] Posizionarsi nella copia git aggiornata del repo (pull del branch
+      `feature/python-rewrite-and-linux-migration`):
+
+  ```powershell
+  cd <path-locale-repo>
+  git fetch origin
+  git checkout feature/python-rewrite-and-linux-migration
+  git pull
+  ```
+
+- [x] Installare il package nel venv di produzione (**non editable**):
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m pip install .
+  ```
+
+  > ⚠️ **Non usare `pip install -e .` su questo host.** act_runner gira
+  > come `LocalSystem`. Un install editable scrive un `.pth` verso la
+  > sorgente; se il `cd` era in una dir di lavoro di act_runner
+  > (`F:\CI\RunnerWork\<hash>\hostexecutor`, transitoria) o sul drive
+  > utente `N:` (non risolto da LocalSystem), il runner fallisce con
+  > `No module named ci_orchestrator`. L'install regolare copia il
+  > package in `site-packages` su `F:` (accessibile a LocalSystem).
+  > Conseguenza: ogni modifica al codice richiede di ri-eseguire
+  > `pip install .` — è uno step di deploy. Assicurarsi che il `cd` del
+  > passo precedente punti alla copia git reale del repo, non a una dir
+  > sotto `F:\CI\RunnerWork`.
+
+- [x] Smoke check rapido che la CLI risponda:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator --help
+  ```
+
+  Atteso: lista degli 11 sub-comandi (`wait-ready`, `vm`, `build`,
+  `artifacts`, `monitor`, `report`, `job`).
+
+---
+
+## Passo 2 — Riavviare act_runner
+
+L'act_runner gira come servizio SYSTEM e legge `runner/config.yaml`
+all'avvio. La modifica di A4 (`PYTHONIOENCODING=utf-8`) ha effetto solo
+dopo restart.
+
+- [x] Trovare il servizio:
+
+  ```powershell
+  Get-Service | Where-Object { $_.Name -like '*act*runner*' }
+  ```
+
+- [x] Restart (sostituisci `<NomeServizio>` con quello trovato):
+
+  ```powershell
+  Restart-Service -Name '<NomeServizio>'
+  ```
+
+- [x] Verificare che sia partito:
+
+  ```powershell
+  Get-Service -Name '<NomeServizio>'
+  ```
+
+  Atteso: `Status = Running`.
+
+---
+
+## Passo 3 — Smoke `wait-ready` su VM Windows reale
+
+PoC pendente da A1.
+
+- [x] Clonare manualmente un template Windows:
+
+  ```powershell
+  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
+    -T ws clone `
+    'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+    'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' `
+    linked -snapshot=BaseClean -cloneName=smoke-win
+  ```
+
+- [x] Avviare la VM:
+
+  ```powershell
+  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
+    -T ws start 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' nogui
+  ```
+
+- [x] Eseguire `wait-ready`:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready `
+    --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' `
+    --guest-os windows --timeout 180
+  ```
+
+  Atteso: exit code `0` entro 3 minuti.
+
+- [x] Cleanup VM di smoke:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove `
+    --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' --force
+  ```
+
+---
+
+## Passo 4 — Smoke `wait-ready` su VM Linux reale
+
+Stesso schema, template Linux. PoC pendente da A1.
+
+- [x] Clonare:
+
+  ```powershell
+  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
+    -T ws clone `
+    'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
+    'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' `
+    linked -snapshot=BaseClean-Linux -cloneName=smoke-linux
+  ```
+
+- [x] Start + wait-ready:
+
+  ```powershell
+  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
+    -T ws start 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' nogui
+
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready `
+    --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' `
+    --guest-os linux --timeout 180
+  ```
+
+  Atteso: exit code `0`.
+
+  > **Prerequisito scoperto**: `F:\CI\config.toml` deve esistere con `ssh_key_path`
+  > impostato — altrimenti SSH fallisce con `No authentication methods available`.
+  > Creato durante questa validazione; vedi HOST-SETUP.md step 6.
+
+- [x] Cleanup:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove `
+    --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' --force
+  ```
+
+---
+
+## Passo 5 — Smoke end-to-end pipeline (`job`)
+
+Valida A3+A4 insieme: clone → wait → build → collect → cleanup.
+
+- [x] Lanciare un job sul template Windows con uno script trivial:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
+    --template-path 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+    --snapshot-name BaseClean `
+    --job-id smoke-job-win `
+    --repo-url 'http://10.10.20.11:3100/Simone/your-repo.git' `
+    --branch main `
+    --build-command 'echo hello > artifact.txt' `
+    --guest-artifact-source 'artifact.txt' `
+    --artifact-base-dir 'F:\CI\Artifacts\smoke-job-win'
+  ```
+
+  Atteso: exit code `0`, file `F:\CI\Artifacts\smoke-job-win\artifact.txt` presente,
+  VM smoke-job-win **non** più esistente in `F:\CI\BuildVMs\` (cleanup garantito).
+
+- [x] Ripetere su Linux:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
+    --template-path 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
+    --snapshot-name BaseClean-Linux `
+    --guest-os linux `
+    --job-id smoke-job-linux `
+    --repo-url 'http://10.10.20.11:3100/Simone/your-repo.git' `
+    --branch main `
+    --build-command 'echo hello > artifact.txt' `
+    --guest-artifact-source 'artifact.txt' `
+    --artifact-base-dir 'F:\CI\Artifacts\smoke-job-linux'
+  ```
+
+  Atteso: exit code `0`, `F:\CI\Artifacts\smoke-job-linux\smoke-job-linux\artifact.txt` presente.
+
+- [x] Verificare assenza VM orfane:
+
+  ```powershell
+  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm cleanup --what-if
+  ```
+
+  Atteso: nessun candidato.
+
+---
+
+## Passo 6 — Workflow Gitea end-to-end
+
+Validazione di A4 lato runner reale.
+
+- [x] Aprire la UI Gitea, repo `local-ci-cd-system`, branch
+      `feature/python-rewrite-and-linux-migration`.
+- [x] Triggerare manualmente i 3 workflow (Actions → Run workflow):
+  - [x] `lint.yml` → atteso PASS
+  - [x] `self-test.yml` → PASS — validati **entrambi i transport**
+        (in-guest clone default + host-side clone+zip) su Win e Linux:
+
+    | Job                          | Transport               | Esito       |
+    | ---------------------------- | ----------------------- | ----------- |
+    | smoke-windows                | in-guest git clone      | SUCCESS 26s |
+    | smoke-linux                  | in-guest git clone      | SUCCESS 51s |
+    | smoke-windows-hostclone      | host-side clone + zip   | SUCCESS 28s |
+    | smoke-linux-hostclone        | host-side clone + zip   | SUCCESS 46s |
+
+    Note: artifact github-free (no upload-artifact; file raw su
+    `F:\CI\Artifacts\<job>`); `use-git-clone`/`submodules` default ON.
+  - [x] `build-ns7zip.yml` matrix Win+Linux → PASS (target repo
+        `Simone/nsis-plugin-ns7zip`, in-guest clone, `--dist`):
+
+    | Job                | Esito                                   |
+    | ------------------ | --------------------------------------- |
+    | build (windows)    | SUCCESS — DLL in dist/, artifact host    |
+    | build (linux)      | SUCCESS — 8 vCPU/8 GB, wall ~121s        |
+    | release (tag push) | SUCCESS — release Gitea + 2 asset upload |
+
+    Note: `release` validato con tag throwaway `v0.0.0-phaseA-test`
+    (poi rimosso); usa il token Actions automatico (Default Token
+    Permissions = Permissive) + REST API Gitea, legge gli artifact
+    host-side (no download-artifact). Linux perf: vCPU-starvation a 4
+    vCPU risolta con guest-cpu=8 (≈ Windows VM ~120s); gap col Windows
+    nativo MSVC (~30s) è inerente MinGW, fuori scope CI.
+
+> Tutti i workflow PASS — nessun fallimento da triagare. (Procedura
+> storica: in caso di fallimento, scaricare i log del run e aprire una
+> voce in `TODO.md` con sha + output errore.)
+
+---
+
+## Passo 7 — Burn-in capacità (4 job concorrenti)
+
+Validazione finale di A5 (definizione di "fatto Fase A").
+
+- [x] Burn-in via `scripts/Start-BurnInTest.ps1` (wrapper lab che
+      hardcoda repo `burnin-dummy` + `BuildCommand` = `build.ps1`;
+      `Test-CapacityBurnIn.ps1` diretto senza `-BuildCommand` usa il
+      default dotnet → fallisce su repo non-.NET):
+
+  ```powershell
+  .\scripts\Start-BurnInTest.ps1
+  ```
+
+- [x] Esito (4 job concorrenti × 3 round):
+
+  | Round | Pass | Fail | Elapsed | Status |
+  | ----- | ---- | ---- | ------- | ------ |
+  | 1     | 4    | 0    | 76s     | PASS   |
+  | 2     | 4    | 0    | 88s     | PASS   |
+  | 3     | 4    | 0    | 73s     | PASS   |
+
+  Total 12/12 PASS — **OVERALL: PASS**. Cleanup VM + lock OK ogni
+  round (0 orfani). A5 / Passo 7 validato.
+
+---
+
+## Passo 8 — Benchmark wall-clock
+
+Confronto Python vs PowerShell. Pendenza A4.
+
+- [x] Eseguito `.\scripts\Measure-CIBenchmark.ps1` (4 iter):
+
+  | Iter | Clone | Start | IP    | WinRM | Destroy | Boot tot |
+  | ---- | ----- | ----- | ----- | ----- | ------- | -------- |
+  | 1    | 0.63  | 1.75  | 66.57 | 0.01  | 4.81    | 68.96    |
+  | 2    | 0.63  | 1.89  | 20.21 | 0.01  | 6.39    | 22.74    |
+  | 3    | 0.62  | 1.72  | 85.07 | 0.01  | 4.50    | 87.42    |
+  | 4    | 0.61  | 1.72  | 60.97 | 0.01  | 4.20    | 63.31    |
+
+  Nessun errore, destroy OK (~4-6s), 0 orfani. Clone/start/WinRM
+  trascurabili; **fase IP (20-85s) = costo dominante e variabile**
+  (detect IP guest via VMware Tools / ci-report-ip) — noto, non
+  bloccante. Prerequisito scoperto: lo shim `Remove-BuildVM.ps1`
+  inoltrava `-ErrorAction` come `--error-action` (destroy falliva ->
+  orfana); risolto per tutti gli shim blind-loop (commit
+  `fix(shims): skip PowerShell common params`).
+
+- [x] Confronto col baseline pre-Python — **SALTATO** (deciso): nessun
+      baseline PS affidabile registrato; metriche infra appese a
+      `F:\CI\Logs\benchmark.jsonl` per trend futuri. Non bloccante.
+
+---
+
+## Passo 9 — Merge della Fase A in `main`
+
+Solo dopo che i passi 3–7 sono tutti `[x]` PASS.
+
+- [x] Self-review pre-merge: diff `main...feature` 108 file
+      (+12597/-3128), nessun secret/.venv/.env per nome. Solo 5 file
+      rimossi su feature = cleanup intenzionale (vecchio `gitea/`
+      action+lint → `.gitea/`; Pester test degli script PS rimpiazzati).
+- [x] Merge `feature → main` con `--no-ff` (storia per-fase
+      preservata; conflitto rename/delete `build-nsInnoUnp.yml` →
+      `build-ns7zip.yml` risolto a favore di feature). Albero `main`
+      risultante == `feature` (Phase A esatto). Commit merge `2aa12bb`,
+      pushato a `origin/main`.
+- [x] Tag release `v2.0.0-phaseA` creato (annotato su `b4ca7f3`) e
+      pushato a `origin`. Il push (`v*`) triggera `build-ns7zip.yml`
+      matrix + release = validazione finale end-to-end di `main`.
+      Cleanup: cancellare dalla UI Gitea la release auto-pubblicata
+      `v2.0.0-phaseA` (contiene binari ns7zip — quirk wiring del job
+      release), tenendo il **tag** come marker Phase A.
+
+---
+
+## Tracciamento globale
+
+| Passo | Descrizione                               | Stato |
+| ----- | ----------------------------------------- | ----- |
+| 1     | Aggiorna venv di produzione               | [x]   |
+| 2     | Restart act_runner                        | [x]   |
+| 3     | Smoke `wait-ready` Windows                | [x]   |
+| 4     | Smoke `wait-ready` Linux                  | [x]   |
+| 5     | Smoke `job` end-to-end (Win + Linux)      | [x]   |
+| 6     | Workflow Gitea (lint + self-test + build) | [x]   |
+| 7     | Burn-in 4 job concorrenti × 3 round       | [x]   |
+| 8     | Benchmark wall-clock                      | [x]   |
+| 9     | Merge in `main` + tag `v2.0.0-phaseA`     | [x]   |
+
+**Fase A definitivamente chiusa** (Passi 1-9 tutti `[x]`). Pronta la
+Fase B (porting su host Linux). Cleanup residuo non bloccante:
+cancellare dalla UI Gitea le release di test `v0.0.0-phaseA-test` e
+l'auto-pubblicata `v2.0.0-phaseA` (i **tag** restano).

plans/PhaseAB-bridge-user-checklist.md

@@ -0,0 +1,211 @@
+# Fase A → Fase B — Bridge checklist per l'utente
+
+Questa checklist copre i passi **intermedi** tra "Fase A done" e "B1
+inizia". Sono attività che girano sull'host **Windows attuale** (o sono
+logistiche fuori dal repo) e non rientrano né in
+[PhaseA-user-checklist.md](PhaseA-user-checklist.md) (validazione del
+codice Python) né in [PhaseB-user-checklist.md](PhaseB-user-checklist.md)
+(setup del nuovo host Linux).
+
+> **Quando eseguirla**: dopo Passo 9 di Fase A (merge + tag), prima di
+> Passo 1 di Fase B (setup host Linux Mint).
+
+> **Tempo stimato**: 1–2 ore (escluso `tar` di backup, che dipende
+> dalla dimensione di `F:\CI\`).
+
+---
+
+## Sezione 1 — Salva il baseline pre-migrazione
+
+Senza un baseline registrato, il confronto richiesto da B7 ("tempo
+medio entro ±20% baseline Windows") è impossibile.
+
+- [ ] Eseguire benchmark sull'host Windows (post Fase A, runner Python attivo):
+
+  ```powershell
+  cd <path-locale-repo>
+  .\scripts\Measure-CIBenchmark.ps1 | Tee-Object -FilePath "baseline-windows-$(Get-Date -Format 'yyyyMMdd').txt"
+  ```
+
+- [ ] Annotare in `docs/RUNBOOK.md` (sezione nuova "Windows host baseline"):
+  - Data
+  - Tempo medio per job (Windows e Linux template)
+  - Success rate
+  - Versione `act_runner` e `ci_orchestrator` (output di `python -m ci_orchestrator --version` se disponibile, altrimenti SHA del commit)
+  - Hardware: i9-10900X, 64 GB RAM, NVMe SSD (da `AGENTS.md`)
+
+- [ ] Committare:
+
+  ```powershell
+  git add docs/RUNBOOK.md
+  git commit -m "docs(runbook): record Windows host pre-migration baseline"
+  git push
+  ```
+
+---
+
+## Sezione 2 — Pre-requisiti Windows per Fase B
+
+Tutti questi vanno fatti **prima** di iniziare B1, perché B2/B3/B6 li
+presuppongono già pronti.
+
+### 2.1 Inventario chiavi SSH
+
+- [ ] Verificare presenza chiavi:
+
+  ```powershell
+  Get-ChildItem F:\CI\keys\ci_linux*
+  ```
+
+  Atteso: `ci_linux` (privata, perm utente owner) e `ci_linux.pub`. Se
+  mancano, rigenerarle con `ssh-keygen -t ed25519 -f F:\CI\keys\ci_linux -N ""`
+  e re-installare `ci_linux.pub` nel template `LinuxBuild2404` su
+  `~ci_build/.ssh/authorized_keys`.
+
+### 2.2 Recupero password guest Windows (`BuildVMGuest`)
+
+La password salvata in Windows Credential Manager **non è
+esportabile**. Devi conoscerla per re-inserirla con `secret-tool` su
+Linux (Passo 3 di Fase B).
+
+- [ ] Verificare di averla nel password manager personale.
+- [ ] Se non la ricordi: bootare il template `WinBuild2025` (e `WinBuild2022`),
+      resettare la password dell'utente CI (`net user <user> <newpass>`),
+      ricatturare snapshot `BaseClean` da stato powered-off (vedi
+      `AGENTS.md` errore #9), aggiornare il Credential Manager Windows con
+      la nuova password, e annotarla in modo sicuro.
+
+### 2.3 Generazione Gitea PAT per il nuovo runner
+
+- [ ] Aprire Gitea → User Settings → Applications → Generate New Token.
+- [ ] Nome: `ci-runner-linux`. Scope: `read:repository` + `write:package`
+      (o gli stessi del runner Windows attuale).
+- [ ] Annotare il token in modo sicuro (verrà inserito al Passo 3 di
+      Fase B con `secret-tool store ... target GiteaPAT`).
+
+### 2.4 OpenSSH Server su Windows (per rsync pull dal Linux)
+
+Necessario solo se al Passo 2 di Fase B (transfer template) preferisci
+fare `rsync pull` dal Linux. Alternativa: `rsync push` da Windows con
+WSL/Cygwin/MSYS2.
+
+- [ ] Installare OpenSSH Server:
+
+  ```powershell
+  Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+  Start-Service sshd
+  Set-Service sshd -StartupType Automatic
+  New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server' -Enabled True `
+      -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22
+  ```
+
+- [ ] Validare connessione da un altro host: `ssh user@<windows-ip> "whoami"`.
+- [ ] (Opzionale) Configurare `authorized_keys` per il futuro user
+      `ci-runner` del Linux box.
+
+### 2.5 Template fully powered-off (gate per B2)
+
+> AGENTS.md errore #9: snapshot catturato con VM accesa produce
+> `*.vmem` / `*.vmsn` che rompono il clone su host diverso.
+
+- [ ] Verificare che nessun template sia running:
+
+  ```powershell
+  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' list
+  ```
+
+  Atteso: nessun path sotto `F:\CI\Templates\` nell'output.
+
+- [ ] Verificare assenza file di runtime:
+
+  ```powershell
+  Get-ChildItem F:\CI\Templates -Recurse -Include *.vmem,*.vmsn,*.lck
+  ```
+
+  Atteso: nessun risultato. Se ci sono `.vmem`/`.vmsn`, lo snapshot
+  non è clean → ricatturare `BaseClean` / `BaseClean-Linux` da stato
+  fully powered-off.
+
+### 2.6 Backup precauzionale di `F:\CI\`
+
+Da fare **prima** del cutover B6, ma anche prima del transfer B2 è una
+buona pratica.
+
+- [ ] Eseguire backup completo:
+
+  ```powershell
+  $stamp = Get-Date -Format 'yyyyMMdd'
+  $archive = "E:\Backup\CI-pre-migration-$stamp.tar"
+  & 'C:\Program Files\Git\usr\bin\tar.exe' -cf $archive 'F:\CI\'
+  Get-FileHash $archive -Algorithm SHA256 | Tee-Object "$archive.sha256"
+  ```
+
+- [ ] Verifica integrità (lista contenuto, primi 20 record):
+
+  ```powershell
+  & 'C:\Program Files\Git\usr\bin\tar.exe' -tf $archive | Select-Object -First 20
+  ```
+
+- [ ] Annotare path archivio + checksum SHA256.
+
+### 2.7 Annotare cadenze scheduled task (se custom)
+
+- [ ] Esportare l'inventario corrente:
+
+  ```powershell
+  Get-ScheduledTask -TaskName 'CI-*' |
+    Select-Object TaskName,
+      @{n='Trigger';e={ $_.Triggers | ForEach-Object { $_.PSObject.Properties | Where-Object Name -in 'StartBoundary','RepetitionInterval','DaysOfWeek' | ForEach-Object { "$($_.Name)=$($_.Value)" } } -join '; ' }},
+      @{n='Action'; e={ "$($_.Actions.Execute) $($_.Actions.Arguments)" }} |
+    Format-List | Tee-Object -FilePath "scheduled-tasks-inventory-$(Get-Date -Format 'yyyyMMdd').txt"
+  ```
+
+- [ ] Confrontare con i `.timer` in `deploy/systemd/`:
+
+  | Task Windows                  | systemd timer                         | Cadenza prevista       |
+  | ----------------------------- | ------------------------------------- | ---------------------- |
+  | `CI-CleanupOrphanedBuildVMs`  | `ci-cleanup-orphans.timer`            | ogni 6h + boot         |
+  | `CI-Invoke-RetentionPolicy`   | `ci-retention-policy.timer`           | giornaliero 03:00      |
+  | `CI-Watch-DiskSpace`          | `ci-watch-disk-space.timer`           | ogni 15min             |
+  | `CI-Watch-RunnerHealth`       | `ci-watch-runner-health.timer`        | ogni 15min             |
+  | (nuovo)                       | `ci-backup-template.timer`            | settimanale Dom 02:00  |
+
+- [ ] Se le cadenze Windows sono diverse, aggiornare gli `OnCalendar` /
+      `OnUnitActiveSec` in `deploy/systemd/*.timer` **prima** del Passo
+      5 di Fase B. Committare la modifica.
+
+---
+
+## Sezione 3 — Logistica e finestra di manutenzione
+
+Questi non sono comandi, ma checkpoint prima di iniziare B1 e B6.
+
+- [ ] **Hardware Linux disponibile**: il box target è acquisito,
+      racked, raggiungibile in rete dall'host Windows e da Gitea.
+- [ ] **DNS / IP statico** assegnato al nuovo host Linux (per
+      registrazione runner + raggiungibilità da admin).
+- [ ] **Finestra di manutenzione per cutover B6 concordata**: 30–60 min
+      di stop Gitea Actions, in un orario a basso traffico.
+- [ ] **Comunicazione utenti del repo**: avviso che durante la
+      finestra B6 i workflow saranno temporaneamente fermi.
+- [ ] **Piano di rollback compreso**: rileggere la sezione "Rollback"
+      del Passo 6 di [PhaseB-user-checklist.md](PhaseB-user-checklist.md).
+
+---
+
+## Tracciamento globale
+
+| Sezione | Descrizione                                    | Stato |
+| ------- | ---------------------------------------------- | ----- |
+| 1       | Baseline benchmark salvato in `docs/RUNBOOK.md` | [ ]   |
+| 2.1     | Chiavi SSH presenti                            | [ ]   |
+| 2.2     | Password `BuildVMGuest` recuperata             | [ ]   |
+| 2.3     | Gitea PAT generato per `ci-runner-linux`       | [ ]   |
+| 2.4     | OpenSSH Server attivo (o alt. rsync)           | [ ]   |
+| 2.5     | Template fully powered-off, no `.vmem`         | [ ]   |
+| 2.6     | Backup `F:\CI\` con SHA256                     | [ ]   |
+| 2.7     | Cadenze scheduled task confrontate con timer   | [ ]   |
+| 3       | Hardware + DNS + finestra + comunicazione OK   | [ ]   |
+
+Quando tutte le righe sono `[x]`, puoi iniziare il Passo 1 di
+[PhaseB-user-checklist.md](PhaseB-user-checklist.md).

plans/PhaseB-user-checklist.md

@@ -0,0 +1,484 @@
+# Fase B — Checklist finale per l'utente
+
+La Fase B è la migrazione del runner CI dall'host Windows attuale a un
+nuovo host **Linux Mint LTS** con VMware Workstation Pro Linux.
+
+> **Stato repo**: solo lo step **B5** (unit `systemd` per i task
+> periodici) è già committato in `deploy/systemd/` sul branch
+> `feature/python-rewrite-and-linux-migration` (commit `50d37b5`).
+> Tutti gli altri step (B1–B4, B6–B8) sono **operazioni hardware**
+> sull'host Linux nuovo e devono essere eseguiti dall'utente.
+
+> **Pre-requisito**: la Fase A deve essere `done` (vedi
+> `plans/PhaseA-user-checklist.md` Passo 9, merge + tag).
+> B1, B2, B3 possono partire in parallelo a A3/A4/A5; B4–B8 sono
+> sequenziali e iniziano solo dopo "A done".
+
+> **Tempo stimato totale**: 1–2 giorni di lavoro distribuiti su una
+> finestra di 1–2 settimane (per consentire il burn-in tra B6 e B8).
+
+---
+
+## Passo 1 — Setup host Linux Mint (B1)
+
+**Obiettivo**: hardware target con Linux Mint LTS, VMware Workstation
+Pro Linux, layout storage e venv Python pronti.
+
+- [ ] Installare Linux Mint LTS sull'hardware target.
+- [ ] `sudo apt update && sudo apt full-upgrade -y && sudo reboot`
+- [ ] Scaricare e installare VMware Workstation Pro Linux (bundle
+      `.bundle` da Broadcow):
+
+  ```bash
+  sudo bash VMware-Workstation-Full-*.bundle
+  vmrun -T ws --version    # deve ritornare versione coerente
+  ```
+
+- [ ] Smoke test Workstation (UI): creare VM trivia, clone, start,
+      stop, delete.
+- [ ] Configurare `vmnet8` NAT range `192.168.79.0/24` (allineato a
+      Windows) editando `/etc/vmware/vmnet8/dhcpd/dhcpd.conf` o via
+      `vmware-netcfg`.
+- [ ] Creare utente di servizio `ci-runner`:
+
+  ```bash
+  sudo useradd -r -m -s /bin/bash ci-runner
+  ```
+
+- [ ] Creare layout storage:
+
+  ```bash
+  sudo mkdir -p /var/lib/ci/{build-vms,artifacts,templates,keys}
+  sudo chown -R ci-runner:ci-runner /var/lib/ci
+  sudo chmod 750 /var/lib/ci /var/lib/ci/*
+  sudo setfacl -d -m u:ci-runner:rwX /var/lib/ci/build-vms
+  ```
+
+- [ ] Installare Python 3.11+ e creare venv produzione:
+
+  ```bash
+  sudo apt install -y python3.11 python3.11-venv git
+  sudo mkdir -p /opt/ci
+  sudo python3.11 -m venv /opt/ci/venv
+  sudo chown -R ci-runner:ci-runner /opt/ci
+  ```
+
+- [ ] Clonare il repo e installare il package nel venv:
+
+  ```bash
+  sudo -u ci-runner git clone https://gitea.emulab.it/Simone/local-ci-cd-system.git /opt/ci/local-ci-cd-system
+  sudo -u ci-runner /opt/ci/venv/bin/pip install -e /opt/ci/local-ci-cd-system
+  sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator --help
+  ```
+
+  Atteso: lista degli 11 sub-comandi.
+
+- [ ] Installare PowerShell Core (richiesto da `Invoke-RetentionPolicy.ps1`
+      e `Backup-CITemplate.ps1`):
+
+  ```bash
+  sudo apt install -y wget apt-transport-https software-properties-common
+  source /etc/os-release
+  wget -q https://packages.microsoft.com/config/ubuntu/${VERSION_ID}/packages-microsoft-prod.deb
+  sudo dpkg -i packages-microsoft-prod.deb
+  sudo apt update && sudo apt install -y powershell
+  pwsh --version
+  ```
+
+---
+
+## Passo 2 — Trasferimento template VM (B2)
+
+**Obiettivo**: copiare i template VMware da `F:\CI\Templates\` su
+`/var/lib/ci/templates/` mantenendo gli snapshot.
+
+> ⚠️ AGENTS.md errore #9: i template devono essere **fully
+> powered-off** prima della copia. Verificare assenza di `*.vmem` /
+> `*.vmsn` di runtime.
+
+- [ ] Sull'host Windows:
+
+  ```powershell
+  Get-ChildItem 'F:\CI\Templates' -Recurse -Include *.vmem,*.vmsn
+  # atteso: nessun risultato
+  ```
+
+- [ ] Sull'host Linux, eseguire rsync via SSH dall'host Windows
+      (richiede OpenSSH Server attivo su Windows o, in alternativa,
+      `scp -r` lanciato da Windows verso Linux):
+
+  ```bash
+  sudo -u ci-runner rsync -av --progress \
+    user@windows-host:/cygdrive/f/CI/Templates/ \
+    /var/lib/ci/templates/
+  ```
+
+- [ ] Validare integrità snapshot:
+
+  ```bash
+  find /var/lib/ci/templates -name '*.vmx' -exec vmrun -T ws listSnapshots {} \;
+  ```
+
+  Atteso: `BaseClean` su `WinBuild2025.vmx` e `WinBuild2022.vmx`,
+  `BaseClean-Linux` su `LinuxBuild2404.vmx`.
+
+- [ ] Aprire ciascun `.vmx` su Workstation Linux per registrarli;
+      al prompt rispondere "**I copied it**".
+- [ ] Smoke test pipeline VM:
+
+  ```bash
+  sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator vm new \
+    --template /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx \
+    --snapshot BaseClean --name smoke-b2-win
+  sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator wait-ready \
+    --vmx /var/lib/ci/build-vms/smoke-b2-win/smoke-b2-win.vmx \
+    --guest-os windows --timeout 180
+  sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator vm remove \
+    --vmx /var/lib/ci/build-vms/smoke-b2-win/smoke-b2-win.vmx --force
+  ```
+
+  Ripetere per `LinuxBuild2404` (snapshot `BaseClean-Linux`,
+  `--guest-os linux`).
+
+---
+
+## Passo 3 — Trasferimento credenziali e chiavi (B3)
+
+**Obiettivo**: chiavi SSH e credenziali guest disponibili al user
+`ci-runner` headless.
+
+- [ ] Copiare le chiavi SSH guest Linux:
+
+  ```bash
+  sudo mkdir -p /etc/ci/keys
+  sudo scp user@windows-host:/cygdrive/f/CI/keys/ci_linux /etc/ci/keys/
+  sudo scp user@windows-host:/cygdrive/f/CI/keys/ci_linux.pub /etc/ci/keys/
+  sudo chown ci-runner:ci-runner /etc/ci/keys/*
+  sudo chmod 600 /etc/ci/keys/ci_linux
+  sudo chmod 644 /etc/ci/keys/ci_linux.pub
+  ```
+
+- [ ] Re-store credenziale guest Windows (sostituire la password al
+      prompt — **NON** inserirla in chat o issue):
+
+  ```bash
+  sudo -u ci-runner secret-tool store --label='BuildVMGuest' service ci target BuildVMGuest
+  ```
+
+- [ ] Re-store Gitea PAT:
+
+  ```bash
+  sudo -u ci-runner secret-tool store --label='GiteaPAT' service ci target GiteaPAT
+  ```
+
+- [ ] Validare lettura interattiva:
+
+  ```bash
+  sudo -u ci-runner /opt/ci/venv/bin/python -c \
+    "import keyring; print(keyring.get_credential('BuildVMGuest', None))"
+  ```
+
+- [ ] **PoC headless** (critico): verificare lettura keyring da
+      contesto systemd (no D-Bus user session):
+
+  ```bash
+  sudo systemd-run --uid=ci-runner --pipe \
+    /opt/ci/venv/bin/python -c \
+    "import keyring; print(keyring.get_credential('BuildVMGuest', None))"
+  ```
+
+  Se fallisce → implementare backend keyring file-based con `age` o
+  `sops` come fallback. Documentare la scelta finale in
+  `docs/HOST-SETUP.md` prima di proseguire.
+
+---
+
+## Passo 4 — Setup act_runner come systemd service (B4)
+
+**Obiettivo**: act_runner Linux registrato verso Gitea, gestito da
+systemd.
+
+- [ ] Scaricare il binario act_runner Linux ≥ v1.0.2:
+
+  ```bash
+  sudo mkdir -p /opt/ci/act_runner
+  sudo wget -O /opt/ci/act_runner/act_runner \
+    https://gitea.com/gitea/act_runner/releases/download/v1.0.2/act_runner-1.0.2-linux-amd64
+  sudo chmod +x /opt/ci/act_runner/act_runner
+  sudo chown -R ci-runner:ci-runner /opt/ci/act_runner
+  ```
+
+- [ ] Generare token registrazione su Gitea (Admin → Runners → Create new runner).
+- [ ] Registrare il runner (sostituire `<TOKEN>`):
+
+  ```bash
+  sudo -u ci-runner mkdir -p /var/lib/ci/runner
+  cd /var/lib/ci/runner
+  sudo -u ci-runner /opt/ci/act_runner/act_runner register \
+    --no-interactive \
+    --instance https://gitea.emulab.it \
+    --token <TOKEN> \
+    --name ci-linux \
+    --labels windows-build:host,linux-build:host
+  ```
+
+  > ⚠️ Lasciare il runner in stato **paused** lato Gitea UI fino al
+  > cutover (Passo 6), per non intercettare job di produzione.
+
+- [ ] Creare `/etc/systemd/system/act-runner.service`:
+
+  ```ini
+  [Unit]
+  Description=Gitea Act Runner
+  After=network-online.target
+  Wants=network-online.target
+
+  [Service]
+  Type=simple
+  User=ci-runner
+  WorkingDirectory=/var/lib/ci/runner
+  Environment="PYTHONIOENCODING=utf-8"
+  Environment="CI_ROOT=/var/lib/ci"
+  Environment="CI_TEMPLATES=/var/lib/ci/templates"
+  Environment="CI_BUILD_VMS=/var/lib/ci/build-vms"
+  Environment="CI_ARTIFACTS=/var/lib/ci/artifacts"
+  Environment="CI_KEYS=/etc/ci/keys"
+  ExecStart=/opt/ci/act_runner/act_runner daemon
+  Restart=on-failure
+  RestartSec=10
+
+  [Install]
+  WantedBy=multi-user.target
+  ```
+
+- [ ] Creare `/etc/ci/environment` (letto dalle unit dei task periodici
+      di B5; vedi `deploy/systemd/README.md`):
+
+  ```bash
+  sudo tee /etc/ci/environment <<'EOF'
+  PYTHONIOENCODING=utf-8
+  CI_ROOT=/var/lib/ci
+  CI_TEMPLATES=/var/lib/ci/templates
+  CI_BUILD_VMS=/var/lib/ci/build-vms
+  CI_ARTIFACTS=/var/lib/ci/artifacts
+  CI_KEYS=/etc/ci/keys
+  EOF
+  sudo chmod 644 /etc/ci/environment
+  ```
+
+- [ ] Abilitare e avviare:
+
+  ```bash
+  sudo systemctl daemon-reload
+  sudo systemctl enable --now act-runner.service
+  sudo systemctl status act-runner
+  sudo journalctl -u act-runner -f    # Ctrl+C dopo conferma OK
+  ```
+
+- [ ] Smoke job: triggerare manualmente `self-test.yml` selezionando
+      il runner Linux (mettere temporaneamente in pausa quello Windows
+      o usare label distinte). Atteso: PASS.
+
+---
+
+## Passo 5 — Installare i timer systemd (B5)
+
+**Obiettivo**: attivare le coppie `.service`+`.timer` già committate
+in `deploy/systemd/` per replicare i task periodici di
+`Register-CIScheduledTasks.ps1`.
+
+- [ ] Copiare le unit:
+
+  ```bash
+  cd /opt/ci/local-ci-cd-system
+  sudo cp deploy/systemd/ci-*.service deploy/systemd/ci-*.timer /etc/systemd/system/
+  sudo systemctl daemon-reload
+  ```
+
+- [ ] Abilitare e avviare tutti i timer:
+
+  ```bash
+  for t in ci-cleanup-orphans ci-retention-policy \
+           ci-watch-disk-space ci-watch-runner-health \
+           ci-backup-template; do
+    sudo systemctl enable --now "${t}.timer"
+  done
+  ```
+
+- [ ] Verificare lo schedule:
+
+  ```bash
+  systemctl list-timers --all 'ci-*'
+  ```
+
+  Atteso: 5 timer in stato `active`.
+
+- [ ] Trigger manuale di ciascun service per validare l'esecuzione
+      one-shot:
+
+  ```bash
+  for s in ci-cleanup-orphans ci-watch-disk-space ci-watch-runner-health; do
+    sudo systemctl start "${s}.service"
+    sudo systemctl status "${s}.service" --no-pager
+  done
+  ```
+
+  > `ci-retention-policy` e `ci-backup-template` chiamano `pwsh`:
+  > eseguirli solo dopo aver verificato che `pwsh --version` funzioni
+  > sotto user `ci-runner`.
+
+- [ ] Per maggiori dettagli (mapping Windows→Linux, troubleshooting,
+      rollback) vedi `deploy/systemd/README.md`.
+
+---
+
+## Passo 6 — Cutover (B6)
+
+**Obiettivo**: spostare la produzione dall'host Windows a Linux in una
+finestra di manutenzione concordata.
+
+> ⚠️ Eseguire solo dopo che i Passi 1–5 sono tutti `[x]` PASS.
+
+- [ ] Annunciare la finestra di manutenzione (durata stimata: 30–60 min).
+- [ ] Verificare nessun job in coda lato Gitea (Admin → Actions → Tasks).
+- [ ] **Stop** act_runner sull'host Windows:
+
+  ```powershell
+  Stop-Service actions-runner
+  Get-Service actions-runner    # atteso: Stopped
+  ```
+
+- [ ] **Disabilitare** scheduled task Windows:
+
+  ```powershell
+  Get-ScheduledTask -TaskName 'CI-*' | Unregister-ScheduledTask -Confirm:$false
+  ```
+
+- [ ] Rsync incrementale finale degli artifact:
+
+  ```bash
+  sudo -u ci-runner rsync -av --delete \
+    user@windows-host:/cygdrive/f/CI/Artifacts/ \
+    /var/lib/ci/artifacts/
+  ```
+
+- [ ] Sbloccare il runner Linux su Gitea UI (rimuovere `paused` o
+      ripristinare le label di produzione `windows-build:host,linux-build:host`).
+- [ ] Verificare runner Linux online su Gitea UI.
+- [ ] Smoke trigger:
+  - [ ] `self-test.yml` → PASS dal runner Linux
+  - [ ] `build-ns7zip.yml` matrix Win+Linux → PASS dal runner Linux
+- [ ] Monitorare per ≥30 min:
+
+  ```bash
+  sudo journalctl -u act-runner -f --since "30min ago"
+  ```
+
+  Nessun errore di severità critica atteso.
+
+> **Rollback (entro 30 min se PASS critico fallisce)**:
+> 1. `sudo systemctl stop act-runner` su Linux
+> 2. `Start-Service actions-runner` su Windows
+> 3. Re-registrare scheduled task con `scripts\Register-CIScheduledTasks.ps1`
+> 4. Documentare incidente in `TODO.md` e tornare a B1–B5 per fix
+
+---
+
+## Passo 7 — Capacity burn-in (B7)
+
+**Obiettivo**: validare il carico target con tempi paragonabili al
+baseline Windows (entro ±20%).
+
+- [ ] Burn-in 4 job concorrenti × 10 round su `WinBuild2025`
+      (lo script `Test-CapacityBurnIn.ps1` ora delega via shim alla CLI
+      Python `job` e gira anche da `pwsh` su Linux):
+
+  ```bash
+  pwsh /opt/ci/local-ci-cd-system/scripts/Test-CapacityBurnIn.ps1 \
+    -Concurrency 4 -Rounds 10 -Template /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx
+  ```
+
+- [ ] Burn-in 4 × 10 su `LinuxBuild2404` (analogo, `--Template`
+      sul VMX Linux).
+- [ ] Misurare:
+  - [ ] Tempo medio per job, confronto con baseline A5
+  - [ ] Tutti i 80 job (2 × 4 × 10) PASS
+  - [ ] Zero VM orfane in `/var/lib/ci/build-vms/`:
+
+    ```bash
+    sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator vm cleanup --dry-run
+    ```
+
+  - [ ] Spazio disco `/var/lib/ci/build-vms/` torna al baseline post-cleanup
+- [ ] Documentare i risultati in `docs/RUNBOOK.md` (sezione "Linux
+      host baseline").
+- [ ] Se delta > 20% vs baseline Windows: aprire issue in `TODO.md`
+      con dettagli per profiling (probabile candidato: filesystem ext4
+      vs NTFS — valutare XFS/BTRFS).
+
+---
+
+## Passo 8 — Stabilità ≥1 settimana (gate per B8)
+
+**Obiettivo**: verificare ≥1 settimana di esercizio Linux senza
+incidenti critici prima di dismettere l'host Windows.
+
+- [ ] Esercizio normale per ≥7 giorni con runner Linux primario.
+- [ ] Verifica giornaliera (bastano 2 minuti):
+
+  ```bash
+  sudo systemctl --failed                           # nessun service in failed
+  systemctl list-timers --all 'ci-*'                # tutti gli ultimi run OK
+  sudo journalctl -u act-runner --since "24h ago" -p err
+  ```
+
+- [ ] Nessun rollback effettuato durante la settimana.
+
+---
+
+## Passo 9 — Decommissioning host Windows (B8, opzionale)
+
+> ⚠️ Procedere solo dopo Passo 8 `[x]`. L'host Windows va lasciato
+> spento ma intatto per ≥1 mese come rollback.
+
+- [ ] Backup finale di `F:\CI\` su archivio esterno:
+
+  ```powershell
+  $stamp = Get-Date -Format 'yyyyMMdd'
+  $archive = "E:\Backup\CI-$stamp.tar"
+  & 'C:\Program Files\Git\usr\bin\tar.exe' -cf $archive 'F:\CI\'
+  Get-FileHash $archive -Algorithm SHA256 | Tee-Object "$archive.sha256"
+  ```
+
+- [ ] Verifica integrità (estrazione di prova in tmp):
+
+  ```powershell
+  $test = "$env:TEMP\ci-restore-test"
+  & 'C:\Program Files\Git\usr\bin\tar.exe' -tf $archive | Select-Object -First 20
+  ```
+
+- [ ] Spegnere host Windows (`shutdown /s /t 0`).
+- [ ] Lasciare hardware integro e spento per ≥1 mese.
+- [ ] Aggiornare `docs/RUNBOOK.md` con la procedura di riaccensione +
+      ri-registrazione scheduled task come rollback.
+- [ ] Dopo 1 mese senza rollback: riallocare hardware.
+
+---
+
+## Tracciamento globale
+
+| Passo | Step | Descrizione                                        | Stato |
+| ----- | ---- | -------------------------------------------------- | ----- |
+| 1     | B1   | Setup host Linux Mint (OS, Workstation, venv, ACL) | [ ]   |
+| 2     | B2   | Trasferimento template VM + smoke `vm new`         | [ ]   |
+| 3     | B3   | Chiavi SSH + keyring (PoC headless)                | [ ]   |
+| 4     | B4   | act_runner systemd service registrato              | [ ]   |
+| 5     | B5   | Timer systemd installati e attivi                  | [ ]   |
+| 6     | B6   | Cutover (stop Windows, runner Linux primario)      | [ ]   |
+| 7     | B7   | Capacity burn-in 4 × 10 (Win + Linux)              | [ ]   |
+| 8     | —    | ≥1 settimana di stabilità senza rollback           | [ ]   |
+| 9     | B8   | Decommissioning host Windows (opzionale)           | [ ]   |
+
+Quando tutti i passi sono `[x]`, la **Fase B è chiusa** e si può
+valutare l'apertura della Fase C (backend ESXi, vedi
+`plans/idea-3-esxi-support.md`).

plans/archived/2026-05-13/final-master-plan.md

@@ -0,0 +1,732 @@
+# Final Master Plan — Local CI/CD System
+
+Date: 2026-05-11
+Last updated: 2026-05-13
+Status: Sprint 1 validation complete; Sprint 2 Critical + High code fixes applied (2026-05-12). Sprint 3 verification pass (2026-05-13): H9/H10/H12 confirmed already implemented; Medium items disk-gate/JobId-validation/phase-duration/ExtraGuestEnv-key-validation/WinRM-auth-check/Validate-SetupState confirmed done. Original plan derived from two independent reviews ([plans/gpt55-analysis.md](gpt55-analysis.md), [plans/opus47-analysis.md](opus47-analysis.md)) and their cross-reviews ([plans/gpt55-review-of-opus.md](gpt55-review-of-opus.md), [plans/opus47-review-of-gpt55.md](opus47-review-of-gpt55.md)). Source files were re-read where the two reviewers disagreed.
+
+This is the single authoritative document for finishing v1.0 of the system. When all Critical and High items are checked, the system is genuinely production-ready for homelab use.
+
+---
+
+## Executive Summary
+
+The Local CI/CD System is a well-engineered, single-host homelab CI built on Gitea Actions, act_runner v1.0.2, VMware Workstation linked clones, Windows PowerShell 5.1, WinRM HTTPS for Windows guests and SSH for Linux guests. The architecture is the right shape for the constraint set: a thin orchestrator on the host, ephemeral linked clones for isolation, two transports for two guest families, and file-based state for everything else. Both reviewers independently graded the architecture A- and operational maturity B-/C+. That matches what the source shows.
+
+The system is *feature-complete* and *operator-usable*, not yet *unattended-daily-trustworthy*. The gap is small in code volume but real in operational consequence. Five concrete defects can break a live build today: the Linux matrix leg of [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) silently selects the Windows template; Linux `ExtraGuestEnv` secrets are logged in clear text; the composite action outputs metadata is malformed YAML; the Linux Mode 2 PAT injection writes credentials into a remote command string; [Setup-Host.ps1](../Setup-Host.ps1) creates a directory layout that no longer matches the live system. None of these are architectural failures. Each is a 5-to-45-minute fix that the design otherwise supports cleanly.
+
+The system makes one large unvalidated claim: `capacity: 4` in [runner/config.yaml](../runner/config.yaml). The IP-allocation mutex and lease design in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) is sound on paper, but the only evidence is single-job e2e runs. Four concurrent real builds have not been measured. This is the single most consequential outstanding question. The remediation is a burn-in, not a redesign.
+
+Top 3 risks today, in order: (1) the Linux matrix leg builds against the Windows template until the action wiring is fixed; (2) any workflow that uses `extra-guest-env-json` for secrets is leaking those values to Gitea logs on Linux builds; (3) `capacity: 4` is a documented capability the system has never proven it keeps. Everything else is smaller.
+
+---
+
+## Current Project State
+
+The optimistic [TODO.md](../TODO.md) and the conservative [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) disagree. The honest state, reconciled against the source files, is below.
+
+| Area                 | Genuinely Done                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Partially Done                                                                                                                      | Unvalidated / Broken                                                                                           |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Windows VM lifecycle | Clone, start, IP detect, WinRM HTTPS, build, artifacts, destroy ([scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1), [scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1), [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1), [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1), [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1))                      | —                                                                                                                                   | Real 4-way concurrency                                                                                         |
+| Linux VM lifecycle   | Cloud-init deploy, SSH transport, IP via `guestinfo.ci-ip` ([template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1), [scripts/_Transport.psm1](../scripts/_Transport.psm1))                                                                                                                                                                                                                                                                       | Generic validator (Windows-only) ([template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1))                        | **FIXED 2026-05-12**: Matrix workflow Linux leg now picks correct template (C1)                                |
+| Composite action     | Inputs forwarded via env vars, step outputs work, success and failure upload paths ([gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml))                                                                                                                                                                                                                                                                                            | —                                                                                                                                   | **FIXED 2026-05-12**: `outputs:` block corrected (H2); hardcoded `N:\` replaced with env var (H11)             |
+| Concurrency          | File mutex + lease design ([scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) ~L303-L460)                                                                                                                                                                                                                                                                                                                                                                        | **FIXED 2026-05-12**: Stale lock auto-cleanup added (H5)                                                                            | 4-way burn-in never run                                                                                        |
+| Credential handling  | Windows Credential Manager target `BuildVMGuest`; PAT via Credential Manager target `GiteaPAT`; Windows Mode 2 uses `http.extraHeader`                                                                                                                                                                                                                                                                                                                                | —                                                                                                                                   | **FIXED 2026-05-12**: Linux Mode 2 PAT now uses `http.extraHeader` (H3); `ExtraGuestEnv` logging redacted (C2) |
+| Maintenance          | Disk watcher, runner health watcher, retention, orphan cleanup, scheduled tasks ([scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1), [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1), [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1), [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1), [scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1)) | —                                                                                                                                   | —                                                                                                              |
+| Backup               | [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) functional; **FIXED 2026-05-12**: default `WinBuild2025`, `-AllTemplates` switch added (H7)                                                                                                                                                                                                                                                                                                         | —                                                                                                                                   | —                                                                                                              |
+| Host bootstrap       | Runner install, NSSM service, credential prompts ([Setup-Host.ps1](../Setup-Host.ps1)); **FIXED 2026-05-12**: directory array updated (H6); `F:\CI\Cache\pip` created on live host                                                                                                                                                                                                                                                                                    | —                                                                                                                                   | act_runner runs as LocalSystem — H8 SSH alias mismatch confirmed, not yet fixed                                |
+| Observability        | JSONL per-job events, Event Log, optional webhook                                                                                                                                                                                                                                                                                                                                                                                                                     | Phase-duration summary                                                                                                              | Cross-job analysis tool                                                                                        |
+| Tests                | Argument-parsing Pester suite over fake `vmrun.cmd` (4 files in [tests/](../tests/))                                                                                                                                                                                                                                                                                                                                                                                  | —                                                                                                                                   | Orchestrator state machine, real-VM smoke tests, lock concurrency                                              |
+| Documentation        | [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md), [docs/CI-FLOW.md](../docs/CI-FLOW.md), [docs/RUNBOOK.md](../docs/RUNBOOK.md), [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md), [docs/WORKFLOW-AUTHORING.md](../docs/WORKFLOW-AUTHORING.md)                                                                                                                                                                                                                       | Drift: README claims production-ready; CI-FLOW claims partial-artifacts-on-failure; test plan uses PS7 syntax and wrong param names | Consolidated template-refresh runbook                                                                          |
+
+The README is genuinely ahead of the evidence. The accurate label is *feature-complete homelab CI awaiting stabilization pass*. Everything in this plan exists to close that gap.
+
+---
+
+## Realistic Goals
+
+This system should aim to be:
+
+- A reliable single-host homelab CI/CD that runs builds inside ephemeral, isolated VMware Workstation linked clones, triggered from a self-hosted Gitea.
+- Operable by one person, from one workstation, against private repositories that they trust.
+- Capable of clean recovery from host reboot, VMware crash, hung `vmrun`, and stale lock files without manual intervention beyond what is documented.
+- Capable of producing repeatable Windows and Linux builds with cached toolchains, with artifacts collected and published to Gitea.
+- Observable enough that after a failed build the operator can diagnose whether it was their build script, the runner, the host, or the VM.
+
+This system should NOT aim to be:
+
+- A multi-host or multi-tenant CI. Federation is explicitly out of scope.
+- A platform for running untrusted third-party code. The guest VMs are hardened only enough to be useful, not enough to safely execute hostile builds.
+- A general-purpose container orchestrator. Containers are deliberately not in the picture (see *Docker / Container Notes*).
+- A drop-in replacement for paid CI services like GitHub Actions cloud, Azure DevOps, or CircleCI. The threat model, secret handling, and audit story are all homelab-grade.
+- A PowerShell 7 project. The PS 5.1 mandate in [AGENTS.md](../AGENTS.md) is a deliberate constraint; migration is not on the roadmap.
+
+Anything in this plan that drifts beyond these bounds is rejected. Both reviewers tested clean here; no Kubernetes, no Prometheus, no service mesh, no enterprise vault leaked into the consolidated plan.
+
+---
+
+## Recommended Architecture
+
+The current architecture is the right one. Confirm it as the target shape rather than redesign it. The recommendations below are scoped, additive fixes inside the existing architecture.
+
+**VM lifecycle approach: keep as-is.** Linked clones from a `BaseClean` snapshot, lifecycle owned by [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) in a try/finally, sub-scripts pure and parameter-driven. Add a `Invoke-VmrunBounded` wrapper into [scripts/_Common.psm1](../scripts/_Common.psm1) and use it for the three lifecycle calls (`start`, `stop`, `deleteVM`). Do not bound `list`, `readVariable`, or `getGuestIPAddress` — those are short and the wrapper overhead is wasted there.
+
+**Transport layer organization: keep explicit Windows/Linux branches.** Do not collapse WinRM and SSH into a generic transport interface. Branches in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) and [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1) are debuggable at 2 AM in a way that an abstraction is not. Add three small helpers in [scripts/_Common.psm1](../scripts/_Common.psm1) instead: `Invoke-VmrunBounded` (timeouts), `ConvertTo-SafeShellSingleQuotedString` (Linux quoting), and `Write-CIRedactedCommand` (secret-aware log formatter).
+
+**IP allocation strategy: keep the lock+lease design.** The Opus suggestion of a static IP pool with `cloud-init`/`netsh` injection is a sound design, but it is a phase-3 redesign justified only if the burn-in fails. Run the burn-in first. The current design is: serialize clone+start+IP-detect through `F:\CI\State\vm-start.lock`, read `guestinfo.ci-ip` as the primary channel with `getGuestIPAddress` fallback, write a per-IP lease file. After fixing stale-lock cleanup and verifying under four-way load, this is sufficient for `capacity: 4`.
+
+**Credential management: keep Windows Credential Manager + host-side SSH key file.** No vault, no rotation service. The fixes are: (1) verify the act_runner service account actually has access to the Credential Manager target; (2) confirm `F:\CI\keys\ci_linux` has ACLs restricting access to the runner identity and Administrators; (3) document a manual rotation procedure in [docs/RUNBOOK.md](../docs/RUNBOOK.md).
+
+**Module organization: keep [scripts/_Common.psm1](../scripts/_Common.psm1) and [scripts/_Transport.psm1](../scripts/_Transport.psm1) split.** Do not rename or merge. Add the three helpers listed above to `_Common.psm1`. Keep `_Transport.psm1` as the SSH-specific helper despite the generic name; rename is churn.
+
+**Logging/observability design: keep JSONL + Event Log + webhook.** Do not move to SQLite. Add a 40-line `Get-CIJobSummary.ps1` over the existing JSONL files for cross-job analysis. Add a phase-duration table printed at job end inside [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1).
+
+---
+
+## Recommended Stack
+
+Canonical stack, after the fixes in this plan:
+
+- Windows 11 Pro host, i9-10900X, 64 GB RAM, NVMe SSD.
+- Windows PowerShell 5.1 only. No PowerShell 7 dependency in any production script.
+- VMware Workstation Pro, `vmrun.exe` at `C:\Program Files (x86)\VMware\VMware Workstation\`.
+- Built-in Windows 11 OpenSSH client (`ssh.exe`, `scp.exe`) for Linux guests.
+- act_runner v1.0.2 installed as a Windows service via NSSM, capacity 4.
+- Gitea at `http://10.10.20.11:3100` / `https://gitea.emulab.it`, PAT stored in Credential Manager target `GiteaPAT`.
+- Templates: `WinBuild2025` (primary Windows), `WinBuild2022` (secondary Windows), `LinuxBuild2404` (Ubuntu 24.04 cloud image).
+- WinRM HTTPS over port 5986 with Basic authentication and self-signed certificate. `AllowUnencrypted=false`.
+- SSH user `ci_build` on Linux guests with passwordless sudo, key at `F:\CI\keys\ci_linux`.
+
+Add to the stack:
+
+- `Pester` v5 (already present in tests/).
+- `PSScriptAnalyzer` (already used by the lint workflow).
+
+Remove from the stack:
+
+- [runner/Install-Runner.ps1](../runner/Install-Runner.ps1). Marked deprecated; superseded by [Setup-Host.ps1](../Setup-Host.ps1). Delete the file.
+- The obsolete `F:\CI\Templates\WinBuild` directory if it still exists on the host. Replaced by `WinBuild2025` / `WinBuild2022`.
+
+Do not add:
+
+- Docker / Podman / container runtimes. See *Docker / Container Notes*.
+- PowerShell 7.
+- Prometheus, Grafana, Loki, OpenTelemetry collectors, or any external metrics stack.
+- SQLite or any other database engine.
+- HashiCorp Vault, Azure Key Vault, or any external secret store.
+
+---
+
+## Critical Problems
+
+These must be fixed before the system is trustworthy for unattended daily use. Severity *Critical* means the issue actively breaks production today.
+
+### C1. Linux matrix leg of build-nsInnoUnp.yml selects the Windows template
+
+**Description**: [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) runs a matrix over `[windows, linux]` and dispatches on `runs-on: ${{ matrix.target }}-build`, but does NOT pass `guest-os` or `template-path` to the composite action. The action defaults `template-path` to empty, so [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) reads `$env:GITEA_CI_TEMPLATE_PATH` — the Windows path. The orchestrator never reads `GITEA_CI_LINUX_TEMPLATE_PATH`. Result: the Linux leg clones `WinBuild2025` and tries to SSH into a Windows VM (or via Auto-detect, into a Windows VM with WinRM credentials), which fails or produces nonsense.
+
+**Location**: [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) L20-L40; [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) L77-L83; [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) L108.
+
+**Impact**: The advertised Windows+Linux matrix workflow is broken for the Linux leg. The only evidence of "Linux works" is direct invocation of `Invoke-CIJob.ps1` with explicit `-TemplatePath`. End-to-end through the workflow has never worked for Linux.
+
+**Fix**: Either (a) update the composite action to select between `GITEA_CI_TEMPLATE_PATH` and `GITEA_CI_LINUX_TEMPLATE_PATH` based on `guest-os` (or runner label inference) and similarly for snapshot name; or (b) update [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) to pass `guest-os: ${{ matrix.target == 'linux' && 'Linux' || 'Windows' }}` plus an explicit `template-path`. Option (a) is the better one because it makes the action self-sufficient for any caller. Add an `INPUT_GUEST_OS_RESOLVED` step that selects the template-path env var, then pass it as `-TemplatePath`. Also set `BaseClean-Linux` as the snapshot name on Linux.
+
+**Estimated effort**: 1 hour including a manual smoke test of both legs.
+
+### C2. Linux ExtraGuestEnv secrets are logged in clear text
+
+**Description**: [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) Linux branch builds `$buildCmd = "${envPrefix}cd '$GuestLinuxWorkDir' && $BuildCommand"` where `$envPrefix` contains `export KEY='value'; ...` with secret values inlined. The next line emits `Write-Host "[Invoke-RemoteBuild] Running build: $buildCmd"`. act_runner captures stdout and Gitea masks `secrets.*` by string match only; multi-byte transforms, base64 encoding, or substring overlap defeat the mask. The documented intended use case (`extra-guest-env-json: '{"SIGN_PASS":"${{ secrets.SIGN_PASS }}"}'`) makes this an active leak path.
+
+**Location**: [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) Linux build assembly, around the `Write-Host` immediately preceding `Invoke-SshCommand` for the build step.
+
+**Impact**: Any homelab workflow currently using `extra-guest-env-json` for secrets has those secrets in Gitea job logs and in the local `F:\CI\Logs\<jobId>\invoke-ci.log` transcript.
+
+**Fix**: Replace the `Write-Host "Running build: $buildCmd"` line with `Write-Host "[Invoke-RemoteBuild] Running build (env vars redacted): cd '$GuestLinuxWorkDir' && <build-command>"`. Never log `$envPrefix` or any string containing it. Do the same redaction in any other location where `$buildCmd` or `$envPrefix` is logged.
+
+**Estimated effort**: 15 minutes.
+
+---
+
+## Secondary Problems
+
+These are *High* priority items. Fix in the same stabilization pass as the Criticals.
+
+### H1. `capacity: 4` is unvalidated under real concurrency
+
+**Description**: [runner/config.yaml](../runner/config.yaml) sets `capacity: 4`, but the IP-allocation mutex in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) has only been exercised by single-job e2e runs (per [TODO.md](../TODO.md) §2.1). The design is plausibly correct, but DHCP behavior under four concurrent `vmrun start` calls, native-tool concurrency safety, and the 4-minute serialization of the IP-acquire phase are unmeasured. Both reviewers flagged this; severity is HIGH (not CRITICAL) because the system can be safely operated at lower capacity while this is unproven.
+
+**Location**: [runner/config.yaml](../runner/config.yaml) L17; [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) L303-L460.
+
+**Impact**: The "production-ready" claim in [README.md](../README.md) rests on a capacity number that has not been measured. A first real burst of four parallel builds may fail in ways the e2e runs cannot predict.
+
+**Fix**: Write `scripts/Test-CapacityBurnIn.ps1`. PowerShell 5.1, uses `Start-Job` to launch four parallel `Invoke-CIJob.ps1` invocations with unique JobIds against a small no-op build. Wait for all jobs, then assert: (1) all four VMs were destroyed; (2) all four jobs got distinct IPs; (3) `F:\CI\State\vm-start.lock` does not exist; (4) `F:\CI\State\ip-leases\` is empty; (5) total wall time and per-phase JSONL durations are recorded. Run three times. If all three pass, document the result in [docs/RUNBOOK.md](../docs/RUNBOOK.md) and keep     `capacity: 4`. If any fail, set `capacity: 2` until investigated.
+
+**Estimated effort**: Half-day to write, run, and document.
+
+### H2. Composite action `outputs:` block is malformed YAML
+
+**Description**: [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) has `artifact-path` and a duplicate `artifact-name` under the `inputs:` map instead of a top-level `outputs:` block. Step-level outputs still work (the `Out-File $env:GITHUB_OUTPUT` lines drive the upload step inside the same composite), so the live workflow does upload artifacts. But the duplicate `artifact-name` key violates YAML 1.2 (most parsers silently overwrite with the later value) and the missing `outputs:` block means downstream workflows cannot read `steps.local-ci-build.outputs.artifact-path`.
+
+**Location**: [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) L96 and L132-L141.
+
+**Impact**: Latent. Today's single consumer is unaffected. The first new consumer that tries to chain on the artifact path will fail mysteriously.
+
+**Fix**: Insert a top-level `outputs:` mapping (sibling to `inputs:` and `runs:`) containing `artifact-path` and `artifact-name`. Delete the second `artifact-name` and the `artifact-path` from the `inputs:` map. Keep the inner `Out-File $env:GITHUB_OUTPUT` lines unchanged. Note: GPT-5.5 originally rated this CRITICAL; Opus rated it LOW. The final-plan severity is HIGH because impact is latent but the YAML is clearly malformed.
+
+**Estimated effort**: 20 minutes.
+
+### H3. Linux Mode 2 PAT injected into clone URL
+
+**Description**: [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) Linux Mode 2 builds `https://user:pat@host/repo.git` and exports it as `GIT_CLONE_URL` in the SSH command. The PAT becomes visible in `/proc/<pid>/environ` for the duration of `git clone`, in the host-side `ssh.exe` argv, and in any PowerShell error text that captures `$envCloneCmd`. The Windows path uses `git -c http.extraHeader=Authorization: Basic <b64>`, which is strictly safer.
+
+**Location**: [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) Linux Mode 2 clone branch, around the `GIT_CLONE_URL` export.
+
+**Impact**: PAT visibility on the guest filesystem and host process list. Bounded but real.
+
+**Fix**: Mirror the Windows pattern. Base64-encode `user:pat`, build a single `git -c credential.helper= -c http.extraHeader=Authorization: Basic <b64> clone <non-auth-url> <dest>` command, invoke via `Invoke-SshCommand`. Drop the URL rewrite, drop the `GIT_CLONE_URL` export, drop the `unset`. Note: GPT-5.5 originally proposed an askpass helper with `chmod 600` temp file; Opus proposed the `http.extraHeader` mirror. The simpler Opus pattern is adopted.
+
+**Estimated effort**: 30 minutes including a clone test against a private repo.
+
+### H4. `vmrun` lifecycle calls have no timeout in production scripts
+
+**Description**: [scripts/_Common.psm1](../scripts/_Common.psm1)'s `Invoke-Vmrun` checks `$LASTEXITCODE` but does not bound execution. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) and [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1) inherit this. A hung `vmrun start` or `deleteVM` waits on `vmware-vmx.exe` indefinitely, consuming the runner slot until act_runner's 2-hour job timeout fires. The `finally` cleanup cannot run while the native process is blocked.
+
+**Location**: [scripts/_Common.psm1](../scripts/_Common.psm1) `Invoke-Vmrun`; callers in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) and [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1).
+
+**Impact**: A single stuck VMware operation can pin one of the four runner slots for two hours.
+
+**Fix**: Add `Invoke-VmrunBounded` to [scripts/_Common.psm1](../scripts/_Common.psm1). Use `Start-Process -PassThru` + `Wait-Process -Timeout` + `Stop-Process` on timeout. Return `[pscustomobject]@{ExitCode; Output; TimedOut; ElapsedSeconds}`. Replace `Invoke-Vmrun` calls for `start`, `stop`, and `deleteVM` only — keep the unbounded version for `list`, `readVariable`, `getGuestIPAddress`. Recommended timeouts: 180s for start, 60s for stop, 90s for deleteVM.
+
+**Estimated effort**: 1 hour including a Pester test.
+
+### H5. Stale `vm-start.lock` not cleaned automatically
+
+**Description**: The IP-allocation lock file at `F:\CI\State\vm-start.lock` is released correctly on normal exit. On host crash mid-lock, the file remains. On reboot the OS-level lock is gone (kernel released it), but the file's mere existence does not cause failure; the issue is the 10-minute retry loop and operator confusion. Neither [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1) nor [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) removes it.
+
+**Location**: [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) and [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1).
+
+**Impact**: First job after a crash gives a confusing message; manual `Remove-Item` cures it. Low operational severity, but high friction.
+
+**Fix**: In both maintenance scripts, add a block that removes `F:\CI\State\vm-start.lock` if its `LastWriteTime` is older than 30 minutes. Do not write metadata into the lock file; the file's mere existence is sufficient signal. Log to console and JSONL.
+
+**Estimated effort**: 15 minutes.
+
+### H6. Setup-Host directory list is stale
+
+**Description**: [Setup-Host.ps1](../Setup-Host.ps1) L118-L126 creates `Templates\WinBuild` and a handful of cache directories, but does NOT create `Templates\WinBuild2025`, `Templates\WinBuild2022`, `Templates\LinuxBuild2404`, `State`, `State\ip-leases`, `keys`, or `Cache\pip`. The orchestrator depends on `F:\CI\State\` and `F:\CI\keys\`. A fresh host bootstrap leaves the system non-functional.
+
+**Location**: [Setup-Host.ps1](../Setup-Host.ps1) L118-L126.
+
+**Impact**: Disaster recovery is broken. Rebuilding the host from scratch using the documented procedure does not produce a working system.
+
+**Fix**: Update the directory array to: `BuildVMs`, `Artifacts`, `Logs`, `Templates\WinBuild2025`, `Templates\WinBuild2022`, `Templates\LinuxBuild2404`, `State`, `State\ip-leases`, `keys`, `act_runner\logs`, `Cache\NuGet`, `Cache\pip`, `RunnerWork`, `ISO`. Remove `Templates\WinBuild`. Add a comment block referencing [AGENTS.md](../AGENTS.md) §Struttura directory host.
+
+**Estimated effort**: 10 minutes.
+
+### H7. Backup-CITemplate default path is wrong
+
+**Description**: [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) L48 defaults `TemplatePath` to `'F:\CI\Templates\WinBuild'`. That directory no longer exists. The default-argument backup silently fails or backs up an empty directory, then the operator refreshes the actual `WinBuild2025` template, with no rollback.
+
+**Location**: [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) L48 and the help block.
+
+**Impact**: An operator running `.\Backup-CITemplate.ps1` before a template refresh believes they have a backup. They do not.
+
+**Fix**: Change the default to `'F:\CI\Templates\WinBuild2025'`. Add a `-AllTemplates` switch that iterates `F:\CI\Templates\*` and backs up each (with subfolder naming preserved in the backup destination). Update [docs/HOST-SETUP.md](../docs/HOST-SETUP.md) and [docs/RUNBOOK.md](../docs/RUNBOOK.md) to reflect the new default. Update the help block.
+
+**Estimated effort**: 30 minutes.
+
+### H8. act_runner service account vs SSH alias mismatch
+
+**Description**: [Setup-Host.ps1](../Setup-Host.ps1) L294-L306 writes the `gitea-ci` SSH alias to `$env:USERPROFILE\.ssh\config` — the interactive user's profile. The NSSM install at L264-L273 does not set an explicit service account, which on Windows commonly means LocalSystem. LocalSystem's home is `C:\Windows\System32\config\systemprofile\`, not the user profile. [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) uses `repo-url: 'ssh://gitea-ci/Simone/...'`. If the service runs as LocalSystem, the alias resolution fails and every Mode 1 (host-side clone) attempt errors out.
+
+**Location**: [Setup-Host.ps1](../Setup-Host.ps1) L264-L273 (NSSM install), L294-L306 (SSH config write); [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) L35.
+
+**Impact**: Potentially blocks all Mode 1 host-side clone builds. Severity is HIGH-PENDING-VERIFICATION; first action is verification.
+
+**Fix**: Step 1, verify: run `Get-CimInstance Win32_Service -Filter "Name='act_runner'" | Select-Object Name,StartName` on the host and document the answer in [docs/RUNBOOK.md](../docs/RUNBOOK.md). Step 2a, if `StartName` is `LocalSystem`: copy the SSH config and known-hosts to `C:\Windows\System32\config\systemprofile\.ssh\` with proper ACLs. Step 2b alternative: create a dedicated `ci_runner` Windows user, reinstall NSSM with `obj=.\ci_runner`, store the SSH config under that user's profile. Step 3: add the verification check to [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1) or a new `Validate-HostState.ps1`. Note: GPT-5.5 did not catch this. Opus did. Severity HIGH stands.
+
+**Estimated effort**: 1 hour for verification + fix.
+
+### H9. `ci-report-ip.service` not asserted in deploy-state validator
+
+**Description**: [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1) is Windows-only: it checks WinRM, Defender, Firewall, UAC, etc. It does not check whether the Linux template's `ci-report-ip.service` (the systemd unit writing `guestinfo.ci-ip`) is enabled. The unit IS validated inside [template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh) L203-L221 and [template/Prepare-LinuxBuild2404.ps1](../template/Prepare-LinuxBuild2404.ps1) L361-L362, but not at the level of "is this template ready to be promoted to BaseClean-Linux." If a future refresh forgets to re-enable it, every Linux build silently falls back to the 120-second `getGuestIPAddress` timeout.
+
+**Location**: [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1).
+
+**Impact**: Silent degradation of Linux build startup time after a faulty template refresh.
+
+**Fix**: Add a Linux branch to `Validate-DeployState.ps1` (or create a `Validate-LinuxDeployState.ps1`) that opens an SSH session and runs `systemctl is-enabled ci-report-ip.service` and `test -x /usr/local/bin/ci-report-ip.sh`. Fail with a clear error if either is missing.
+
+**Estimated effort**: 45 minutes.
+
+### H10. No automated end-to-end smoke test
+
+**Description**: The Pester suite in [tests/](../tests/) exercises argument parsing only via a fake `vmrun.cmd`. The "production-ready" claim rests on manual e2e runs (`e2e-008`, `e2e-009`, `§3.3`). There is no scripted, repeatable test that exercises real VM lifecycle and exits non-zero on failure. Both reviewers flagged this; severity is HIGH because regression risk without it is high after every change.
+
+**Location**: [tests/](../tests/), [gitea/workflows/](../gitea/workflows/).
+
+**Impact**: Any change to orchestration scripts has no automated guard. Regressions are caught only by chance during the next manual run.
+
+**Fix**: Create `gitea/workflows/self-test.yml` (workflow_dispatch trigger only). One job that calls the composite action against a minimal `Write-Host 'ok' > out.txt` build, asserts artifact upload, JSONL phase events, and clean teardown. Have it succeed-or-fail for Windows and a second job for Linux. Add `scripts/Test-Smoke.ps1` that the workflow invokes; the script also runs locally. Note: this replaces the much larger `Measure-CIBenchmark.ps1` wiring suggestion; the smoke test is sufficient and cheaper.
+
+**Estimated effort**: Half-day.
+
+### H11. Composite action hardcodes the script root path
+
+**Description**: [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) L148 sets `$ciScriptsDir = 'N:\Code\Workspace\Local-CI-CD-System\scripts'`. The action is presented as reusable, but moving the repo breaks it. Opus caught this; GPT-5.5 missed it (it caught path drift in setup/backup only).
+
+**Location**: [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) L148.
+
+**Impact**: Action is not actually reusable. Any second consumer or repo relocation breaks builds.
+
+**Fix**: Replace with a runner env var. Add `GITEA_CI_SCRIPT_ROOT: "N:\\Code\\Workspace\\Local-CI-CD-System\\scripts"` to [runner/config.yaml](../runner/config.yaml) `envs:`. In the action, use `$ciScriptsDir = $env:GITEA_CI_SCRIPT_ROOT`. Do not use `${{ github.action_path }}` — the action repo is not necessarily cloned into the consumer's workspace in this Gitea setup.
+
+**Estimated effort**: 20 minutes.
+
+### H12. Measure-CIBenchmark uses a different IP discovery path than production
+
+**Description**: [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1) L129-L146 polls `Invoke-Vmrun -Operation getGuestIPAddress`. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) L348-L389 primarily reads `guestVar 'ci-ip'` and uses `getGuestIPAddress` as fallback. The benchmark therefore measures a different code path than what production runs, and its phase timings cannot be used for capacity planning.
+
+**Location**: [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1) L129-L146.
+
+**Impact**: Benchmark data is misleading. Decisions to keep or change `capacity: 4` based on it would be based on wrong measurements.
+
+**Fix**: Extract IP-acquire into a function `Get-GuestIPAddress` in [scripts/_Common.psm1](../scripts/_Common.psm1) that takes the VMX path and credentials and implements the `guestinfo.ci-ip`-then-`getGuestIPAddress` flow used in production. Call it from both `Invoke-CIJob.ps1` and `Measure-CIBenchmark.ps1`.
+
+**Estimated effort**: 1 hour.
+
+---
+
+## Complete Priority Checklist
+
+Every item is concrete, references a file, and ends with an effort estimate.
+
+### Critical [x]
+
+- [x] Fix Linux matrix template selection — [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) + [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) — action selects `GITEA_CI_TEMPLATE_PATH` or `GITEA_CI_LINUX_TEMPLATE_PATH` based on `guest-os` input or runner label, also resolves the correct `snapshot-name` (`BaseClean` or `BaseClean-Linux`) — done 2026-05-12.
+- [x] Redact Linux ExtraGuestEnv secret logging — [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) Linux branch — replace `Write-Host "...$buildCmd"` with redacted version; never log `$envPrefix` — done 2026-05-12.
+
+### High
+
+- [x] done Run 4-way concurrency burn-in — [scripts/Test-CapacityBurnIn.ps1](../scripts/Test-CapacityBurnIn.ps1) (new) — `Start-Job`-based harness, configurable rounds/parallelism, assertions on clone cleanup and stale lock file.
+- [x] Fix composite action outputs YAML — [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) — add top-level `outputs:` block; remove duplicate `artifact-name` from `inputs:` — done 2026-05-12.
+- [x] Replace Linux Mode 2 PAT URL with `http.extraHeader` — [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) Linux clone branch — base64-encode `user:pat`, single `git -c http.extraHeader=...` command — done 2026-05-12.
+- [x] Add `Invoke-VmrunBounded` and use for lifecycle calls — [scripts/_Common.psm1](../scripts/_Common.psm1), [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1) — bound `start`, `stop`, `deleteVM` only — done 2026-05-12; Pester 18/18 pass.
+- [x] Add stale `vm-start.lock` cleanup — [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) and [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1) — remove file older than 30 minutes — done 2026-05-12.
+- [x] Fix Setup-Host directory list — [Setup-Host.ps1](../Setup-Host.ps1) L118 — match [AGENTS.md](../AGENTS.md) §Struttura — done 2026-05-12.
+- [x] Fix Backup-CITemplate default — [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) L48 + help block — default `WinBuild2025`, add `-AllTemplates` — done 2026-05-12.
+- [x] Verify and fix act_runner service-account SSH alias — [Setup-Host.ps1](../Setup-Host.ps1) — added Step 8: replicates `~\.ssh\config`, `id_rsa`, and `known_hosts` to `C:\Windows\System32\config\systemprofile\.ssh\` with SYSTEM/Administrators-only ACLs; added `StrictHostKeyChecking accept-new` to gitea-ci alias block — done 2026-05-12. Verification: run `Setup-Host.ps1` to apply, then test `ssh gitea-ci` from a SYSTEM-context shell.
+- [x] Add `ci-report-ip.service` check to deploy-state validator — [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1) — Linux branch via SSH — confirmed implemented 2026-05-13.
+- [x] Add on-demand smoke-test workflow — [gitea/workflows/self-test.yml](../gitea/workflows/self-test.yml) + [scripts/Test-Smoke.ps1](../scripts/Test-Smoke.ps1) — confirmed implemented 2026-05-13.
+- [x] Replace hardcoded `N:\` script path in composite action — [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) L148 + [runner/config.yaml](../runner/config.yaml) — new `GITEA_CI_SCRIPT_ROOT` env var — done 2026-05-12; active config deployed and act_runner restarted 2026-05-12 (labels: windows-build:host dotnet:host msbuild:host linux-build:host).
+- [x] Align benchmark IP discovery with production — [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1) + [scripts/_Common.psm1](../scripts/_Common.psm1) — `Get-GuestIPAddress` already extracted and used by both — confirmed 2026-05-13.
+
+### Medium [ ]
+
+- [x] done Add pre-clone disk space gate — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) Phase 2 — confirmed implemented at L339 (2026-05-13).
+- [x] done Add post-failure guest diagnostics collection — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) catch block — `Get-GuestDiagnostics` to `F:\CI\Artifacts\<jobId>\diagnostics\` — confirmed already implemented 2026-05-13.
+- [x] done Wire `UseSharedCache` through composite action and orchestrator — [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) L133/L185/L269, [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) L502 — confirmed 2026-05-13.
+- [x] done Authenticate-not-just-TCP WinRM readiness — [scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1) — optional Credential parameter, single `Invoke-Command { 'ready' }` after TCP open.
+- [x] done Add Ubuntu cloud VMDK SHA256 verification — [template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1) — `-VmdkSha256` param + `Get-FileHash` check at L387 — confirmed 2026-05-13.
+- [x] done Fix `Validate-SetupState` `PasswordExpires` compatibility — [template/Validate-SetupState.ps1](../template/Validate-SetupState.ps1) — `(-not $u.PasswordExpires) -or ($u.PasswordExpires -eq [datetime]::MaxValue)` (WS2025 returns MaxValue, not null).
+- [x] done Update [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) — already uses `Start-Job` and `-RepoUrl` — confirmed 2026-05-13.
+- [x] done Add `JobId` sanitization — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) — `[ValidatePattern('^[A-Za-z0-9._-]+$')]` at L77 — confirmed 2026-05-13.
+- [x] done Add `ExtraGuestEnv` key validation — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) L184 — confirmed 2026-05-13.
+- [x] done Add phase-duration summary at job end — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) L541 — confirmed 2026-05-13.
+- [x] done Add 90-minute job-duration webhook warning — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) — `WebhookUrl` param + `Start-Job` fires `[WARNING]` after 5400s; cancelled in finally — done 2026-05-13.
+- [x] done Document HGFS shared folder write semantics — [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md) section 11 — write semantics, cache-poisoning risk, safe-use rules, invalidation — done 2026-05-13.
+- [x] done Standardize Event Log source names — Watch-DiskSpace: `CI-DiskAlert`→`CI-DiskSpaceAlert`; Watch-RunnerHealth already `CI-RunnerHealth` — done 2026-05-13.
+- [x] done Tighten SSH host-key handling for CI jobs — [scripts/_Transport.psm1](../scripts/_Transport.psm1) — `KnownHostsFile` param: when non-empty uses `accept-new` mode; when empty (default) uses permissive for provisioning — confirmed already implemented 2026-05-13.
+- [x] done Consolidate template-refresh runbook — [docs/RUNBOOK.md](../docs/RUNBOOK.md) section 5 (5.1–5.9) — confirmed already fully implemented 2026-05-13.
+
+### Low [ ]
+
+- [x] done Delete deprecated runner installer — runner/Install-Runner.ps1 — file already absent from repo — confirmed 2026-05-13.
+- [x] done Align Setup-Host password documentation — [Setup-Host.ps1](../Setup-Host.ps1) help block has `Default: CIBuild!ChangeMe2026` with explicit "CHANGE THIS before production use" note — sufficient for homelab — 2026-05-13.
+- [x] done Remove emoji from webhook payloads — Watch-DiskSpace uses `[WARNING]`, Watch-RunnerHealth uses `[ALERT]`/`[WARNING]` — no emoji found — confirmed 2026-05-13.
+- [x] done Fix Validate-* docblocks to reflect HTTPS/5986 — Validate-SetupState.ps1 L7: `HTTP/Basic` → `HTTPS/Basic, port 5986` — done 2026-05-13. (Validate-DeployState already correct.)
+- [x] done Align benchmark JSON schema with test plan — [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) § 3.6 updated to match actual script output fields (`cloneSec`, `startSec`, `ipSec`, `winrmSec`, `destroySec`, `totalBootSec`) — done 2026-05-13.
+- [x] done Add `TemplatePath` sanity check — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) — `Write-Warning` if not under `F:\CI\Templates\` — done 2026-05-13.
+- [x] done Add a maintenance flag for Watch-RunnerHealth — [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1) — skip restart if `F:\CI\State\runner-maintenance.flag` exists — done 2026-05-13.
+- [x] done Add ACL validation script — [scripts/Validate-HostState.ps1](../scripts/Validate-HostState.ps1) — SSH key ACLs, Credential Manager target, CI dir structure, vmrun.exe check — done 2026-05-13.
+- [x] done Move done sections of [TODO.md](../TODO.md) into a new [docs/CHANGELOG.md](../docs/CHANGELOG.md) — reverse-chronological log of all completed sprints — done 2026-05-13.
+- [x] done Fix [docs/CI-FLOW.md](../docs/CI-FLOW.md) failure-scenario table — "Build fails inside VM" row updated: `Get-GuestDiagnostics` to `diagnostics\` folder — done 2026-05-13.
+
+### Nice to have [x] done
+
+- [x] Add `scripts/Get-CIJobSummary.ps1` — reads last N days of JSONL files, prints duration table — 1h.
+- [x] Add artifact manifest with file hashes — [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1) — `manifest.json` with name, size, SHA256, commit, job ID — 1h.
+- [x] Add per-job VMX CPU/RAM override — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) + composite action input — post-clone VMX edit, default off — 1h.
+- [x] Add optional Gitea API runner-online check — [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1) — optional `-GiteaUrl` and PAT target — 1h.
+- [x] Begin SHA256 pinning of toolchain installers — [template/Install-CIToolchain-WinBuild2025.ps1](../template/Install-CIToolchain-WinBuild2025.ps1) — fill hashes for Git, 7-Zip, Python, .NET, Node — 2h.
+- [x] Add linked-clone delta size measurement — [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1) — record per-job delta growth — 30min.
+
+---
+
+## Detailed Operational Checklist
+
+Execute in this order. Each task lists a prerequisite, an action, and a verification step.
+
+### Sprint 1: Validation
+
+Goal: prove or downgrade unvalidated claims before any code changes go in.
+
+**Task 1.1 — Verify act_runner service account** [x] done 2026-05-12
+- Result: StartName = **LocalSystem**. H8 fix is required. See [docs/RUNBOOK.md](../docs/RUNBOOK.md) — Runner service identity section to be updated.
+
+**Task 1.2 — Inventory current state-file presence** [x] done 2026-05-12
+- Result: `F:\CI\Cache\pip` was missing. Created manually during session. All other required dirs present.
+
+**Task 1.3 — Run 4-way concurrency burn-in (H1)** [ ] not yet started
+- Prerequisite: write `scripts/Test-CapacityBurnIn.ps1` first; `WinBuild2025` and `LinuxBuild2404` templates powered off; >= 100 GB free on `F:`.
+- Action: invoke the burn-in three times against a no-op build (e.g. `Write-Host 'ok'`); record per-run JSONL outputs.
+- Verification: zero IP collisions across runs, zero leaked VMs, zero leaked lock files, all jobs succeeded. If any fail, set `runner/config.yaml capacity: 2` and create a follow-up investigation task.
+
+**Task 1.4 — Manually invoke Linux matrix leg to confirm C1 bug** [ ] smoke test pending
+- C1 code fix applied 2026-05-12. A live workflow run with both legs is still needed to confirm end-to-end.
+- Prerequisite: act_runner service restarted (to pick up `GITEA_CI_SCRIPT_ROOT` from config.yaml).
+- Action: push a tag to a test branch, observe both legs.
+- Verification: both legs succeed against the correct templates.
+
+### Sprint 2: Critical Fixes
+
+Goal: clear both Criticals plus the highest-impact Highs that touch production paths.
+
+**Task 2.1 — Fix Linux matrix template selection (C1)** [x] done 2026-05-12
+- [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml): added `$resolvedGuestOS` / `$resolvedTemplatePath` / `$resolvedSnapshotName` resolution block; `Auto` infers from `$env:RUNNER_LABELS`.
+- [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml): explicit `guest-os: ${{ matrix.target == 'linux' && 'Linux' || 'Windows' }}` added as belt-and-suspenders.
+- Live smoke test (Task 1.4) still required.
+
+**Task 2.2 — Redact Linux ExtraGuestEnv logging (C2)** [x] done 2026-05-12
+- [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1): `Write-Host "Running build: $buildCmd"` replaced with redacted form that only logs `$BuildCommand` (user-visible), never `$envPrefix`.
+- Verification with a live job still recommended.
+
+**Task 2.3 — Fix composite action outputs YAML (H2)** [x] done 2026-05-12
+- [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml): duplicate `artifact-name` under `inputs:` removed; proper top-level `outputs:` block added with both `artifact-path` and `artifact-name` mapped from step outputs.
+
+**Task 2.4 — Linux Mode 2 PAT to http.extraHeader (H3)** [x] done 2026-05-12
+- [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1): `GIT_CLONE_URL` env-var approach removed; replaced with `git -c credential.helper= -c http.extraHeader=Authorization: Basic <b64>` pattern mirroring the Windows branch.
+- Live verification (Mode 2 clone against private repo) still recommended.
+
+**Task 2.5 — Fix Setup-Host directory list (H6)** [x] done 2026-05-12
+- [Setup-Host.ps1](../Setup-Host.ps1): directory array updated to canonical list (adds WinBuild2025, WinBuild2022, LinuxBuild2404, State, State\ip-leases, keys, Cache\pip; removes obsolete WinBuild).
+
+**Task 2.6 — Fix Backup-CITemplate default (H7)** [x] done 2026-05-12
+- [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1): default `TemplatePath` changed to `F:\CI\Templates\WinBuild2025`; `-AllTemplates` switch added (iterates all template subdirs with per-template naming and pruning).
+
+### Sprint 3: High Priority Fixes
+
+Goal: stabilize the rest of the High-tier items.
+
+**Task 3.1 — Add `Invoke-VmrunBounded` (H4)** [x] done 2026-05-12
+- `Invoke-VmrunBounded` added to [scripts/_Common.psm1](../scripts/_Common.psm1) using `[System.Diagnostics.Process]` directly (not `Start-Process -PassThru`, which does not populate ExitCode reliably in PS5.1). Kills process tree via `taskkill /F /T` on timeout; skips stdout/stderr drain on timeout path to avoid faulted-task re-throw. Returns `{ExitCode; Output; TimedOut; ElapsedSeconds}`.
+- Wired in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1): `vmrun start` uses 180s timeout.
+- Wired in [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1): `vmrun stop soft/hard` (60s each), `vmrun deleteVM` (90s).
+- Pester suite: 18/18 pass (8 new `Invoke-VmrunBounded` tests + 10 pre-existing) in ~7s — verified 2026-05-12.
+
+**Task 3.2 — Stale lock cleanup (H5)** [x] done 2026-05-12
+- [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) and [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1): both now remove `F:\CI\State\vm-start.lock` if LastWriteTime is older than 30 minutes.
+
+**Task 3.3 — Fix or relocate SSH alias for service account (H8)** [x] done 2026-05-12
+- [Setup-Host.ps1](../Setup-Host.ps1): added `StrictHostKeyChecking accept-new` to the `gitea-ci` alias block.
+- [Setup-Host.ps1](../Setup-Host.ps1): added Step 8 that replicates `~\.ssh\config`, `id_rsa`, and `known_hosts` (if present) to `C:\Windows\System32\config\systemprofile\.ssh\` (LocalSystem's SSH home). Sets ACLs to SYSTEM/Administrators-only on the private key.
+- To apply: re-run `Setup-Host.ps1` (or run Step 8 standalone) elevated. Key must exist at `~\.ssh\id_rsa`.
+- Verification: `psexec -s -i cmd /c ssh -T gitea-ci` should return `"Hi <user>! You've successfully authenticated..."` from Gitea.
+
+**Task 3.4 — Linux deploy validator check for ci-report-ip (H9)** [x] done 2026-05-12
+- `-GuestOS Linux` branch added to [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1).
+- Checks via `ssh.exe`: `systemctl is-enabled ci-report-ip.service` and `test -x /usr/local/bin/ci-report-ip.sh`.
+- Windows branch unchanged. New params: `-GuestOS`, `-SshKeyPath`, `-SshUser`.
+- Verification: against the live template, the script reports the service as enabled.
+
+**Task 3.5 — Add smoke-test workflow (H10)** [x] done 2026-05-12
+- [gitea/workflows/self-test.yml](../gitea/workflows/self-test.yml) created: `workflow_dispatch` only, two independent jobs (`smoke-windows` + `smoke-linux`).
+- [scripts/Test-Smoke.ps1](../scripts/Test-Smoke.ps1) created: invokes `Invoke-CIJob.ps1` with a marker-file build command and asserts artifact dir + JSONL success event.
+- Prerequisite: H2 and C1 fixed (both done). Verification: trigger via `workflow_dispatch` and observe both legs green.
+
+**Task 3.6 — Replace hardcoded N:\ path (H11)** [x] done 2026-05-12
+- [runner/config.yaml](../runner/config.yaml): `GITEA_CI_SCRIPT_ROOT` env var added.
+- [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml): `$ciScriptsDir = $env:GITEA_CI_SCRIPT_ROOT` used in place of hardcoded path.
+- Active config deployed to `F:\CI\act_runner\config.yaml` and act_runner restarted 2026-05-12. Log confirmed: `labels updated to: [windows-build:host dotnet:host msbuild:host linux-build:host]`.
+
+**Task 3.7 — Benchmark IP path alignment (H12)** [x] done 2026-05-12
+- `Get-GuestIPAddress` extracted into [scripts/_Common.psm1](../scripts/_Common.psm1): polls `guestVar ci-ip` (primary) then `getGuestIPAddress` (fallback) with configurable timeout.
+- [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1): Phase 3b replaced with `Get-GuestIPAddress` call (eliminates ~50 lines of duplicated polling).
+- [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1): IP phase now calls `Get-GuestIPAddress` (was using `getGuestIPAddress`-only fallback, missing `ci-ip` primary).
+- Verification: run `Measure-CIBenchmark.ps1 -Iterations 1` for Windows and Linux; confirm phase timings match those recorded in production JSONL within ±10%.
+
+### Sprint 4: Operational Hardening
+
+Goal: harden recovery, secret handling, and recoverability.
+
+[x] done **Task 4.1 — Pre-clone disk gate, JobId/ExtraGuestEnv validation, redacted command logger** (Medium items grouped) — edit [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) and [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1); verify with deliberately bad inputs.
+
+[x] done **Task 4.2 — Failure-path diagnostics** — add a `Get-GuestDiagnostics` helper invoked from the `catch` block of [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1). Skip on Phase 1/2 failures (no VM yet). Best-effort SSH/WinRM, no throw on failure.
+
+[x] done **Task 4.3 — Wire `UseSharedCache`** — surface in composite action and orchestrator; confirm with a Python build that pip cache is reused.
+
+[x] done **Task 4.4 — Tighten SSH host keys for CI jobs** — `accept-new` + `F:\CI\State\known_hosts` for CI; keep permissive mode for template provisioning (host keys are unknown there).
+
+[x] done **Task 4.5 — Ubuntu VMDK SHA256 verification** — add to [template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1).
+
+[x] done **Task 4.6 — Consolidated template-refresh runbook** — edit [docs/RUNBOOK.md](../docs/RUNBOOK.md). One section covering: stop runner, back up template (`-AllTemplates`), boot template, KMS reactivation via `slmgr /ato` (Windows), run `Prepare-WinBuild2025.ps1` or `Prepare-LinuxBuild2404.ps1`, shutdown, snapshot `BaseClean_yyyyMMdd`, run `Validate-DeployState.ps1` (Windows and Linux branches), run smoke workflow, then update `GITEA_CI_SNAPSHOT_NAME` in [runner/config.yaml](../runner/config.yaml), keep prior snapshot 7 days, rollback procedure.
+
+### Sprint 5: Quality and Optimization
+
+Goal: polish.
+
+**Task 5.1 — Delete dead code** — [x] done — removed [runner/Install-Runner.ps1](../runner/Install-Runner.ps1) (DEPRECATED dead code).
+
+**Task 5.2 — Webhook emoji removal, Event Log naming, docblock corrections** — [x] done — replaced Unicode emoji and Discord-style emoji codes in Watch-DiskSpace.ps1, Watch-RunnerHealth.ps1, Test-E2E-Section3.3.ps1 with plain-text prefixes ([WARNING], [ALERT], [WARN]).
+
+**Task 5.3 — Update test plan** — [x] done — [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) — replaced ForEach-Object -Parallel with Start-Job pattern; replaced -RepositoryUrl with -RepoUrl (3 occurrences).
+
+**Task 5.4 — Add `Get-CIJobSummary.ps1`** — [x] done — new [scripts/Get-CIJobSummary.ps1](../scripts/Get-CIJobSummary.ps1): scans JSONL logs, prints summary table, supports -JobId for detail view, -Failed filter, -Last N.
+
+**Task 5.5 — Phase-duration summary in orchestrator** — [x] done — [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1): phaseTimings list tracks Phase 1-6 elapsed seconds; printed as table before SUCCESS/FAILURE banner.
+
+**Task 5.6 — Begin SHA256 pinning** — [x] done — [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md) Section 10 added: pinning policy, priority table (Git, 7-Zip, Python, .NET, Ubuntu VMDK), PS5.1 implementation pattern, update guidance.
+
+---
+
+## Recommended Refactors
+
+Only refactors that genuinely simplify or fix something. No churn.
+
+1. **Extract `Get-GuestIPAddress` into [scripts/_Common.psm1](../scripts/_Common.psm1)**. Removes the dual-implementation drift between `Invoke-CIJob.ps1` and `Measure-CIBenchmark.ps1`. Single source of truth for the `guestinfo.ci-ip`-then-fallback flow. Justification: real bug avoidance, not aesthetic.
+
+2. **Extract `Invoke-VmrunBounded` into [scripts/_Common.psm1](../scripts/_Common.psm1)**. Closes the H4 timeout gap and consolidates the pattern that already exists in some deploy scripts.
+
+3. **Add `Write-CIRedactedCommand` and `ConvertTo-SafeShellSingleQuotedString` to [scripts/_Common.psm1](../scripts/_Common.psm1)**. The first standardizes secret-aware command logging across Windows and Linux paths. The second consolidates the `-replace "'", "'\''"` idiom used in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1). Both are 5-line functions.
+
+4. **DO NOT extract a generic transport interface**. Opus suggested `Invoke-GuestCommand`/`Copy-GuestItem`/`Wait-GuestTransportReady`. Both reviewers ultimately agreed this is the wrong move for a two-transport homelab. Keep explicit Windows/Linux branches in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) and [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1).
+
+5. **DO NOT introduce `F:\CI\State\config.json` as a central config**. [AGENTS.md](../AGENTS.md) and [runner/config.yaml](../runner/config.yaml) are already the two sources of truth. Adding a third creates drift, not reduces it. The remediation is to align the existing two, not invent a third.
+
+6. **DO NOT migrate to PowerShell 7**. The PS 5.1 constraint is deliberate, encoded in [AGENTS.md](../AGENTS.md), and consistently respected across the codebase. A migration is a multi-day churn that buys little.
+
+7. **DO NOT replace JSONL with SQLite**. The JSONL output is forward-compatible and trivially greppable. `Get-CIJobSummary.ps1` over JSONL covers the cross-job analysis need without adding a database engine.
+
+8. **DO NOT pursue a static IP pool unless the burn-in fails**. The current lock+lease design after the stale-lock fix is sufficient for `capacity: 4`. Static IPs cost more than they save at this scale.
+
+---
+
+## Security Improvements
+
+Must (do these in Sprint 2 or 3):
+
+- Redact Linux `ExtraGuestEnv` secret logging (C2).
+- Replace Linux Mode 2 PAT URL with `http.extraHeader` (H3).
+- Verify and fix the act_runner SSH alias service-account issue (H8).
+- Add `JobId` pattern validation (Medium).
+- Add `ExtraGuestEnv` key pattern validation (Medium).
+- Run SSH `StrictHostKeyChecking=accept-new` with `UserKnownHostsFile=F:\CI\State\known_hosts` for CI jobs (Medium).
+
+Could (Nice-to-have):
+
+- Begin SHA256 pinning of Tier-1 toolchain installers.
+- Verify ACLs on `F:\CI\keys\ci_linux` via a new `Validate-HostState.ps1`.
+- Add a one-paragraph note in [docs/WORKFLOW-AUTHORING.md](../docs/WORKFLOW-AUTHORING.md) on Gitea log-masking limits (substring-only masking; base64 transforms defeat it).
+
+Will NOT do:
+
+- Full PKI for WinRM. The self-signed lab certificate plus VMnet8 isolation is the right boundary.
+- External secret vault integration.
+- Enable Defender / Firewall / UAC inside the build VM. The threat model accepts this for trusted private code; documented in [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md).
+- Per-build credential rotation.
+- Artifact signing.
+
+---
+
+## CI/CD Improvements
+
+Concrete improvements to workflows and the composite action.
+
+1. **Make the composite action self-sufficient for guest OS selection** (C1 fix). After this, [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) does not need to pass `guest-os`, `template-path`, or `snapshot-name` for the standard Windows/Linux matrix; the action infers from the runner label or accepts the explicit input.
+
+2. **Add a top-level `outputs:` block** so downstream consumers can chain (H2 fix).
+
+3. **Add `use-shared-cache` input** plumbed to `Invoke-CIJob.ps1 -UseSharedCache` (Medium fix). Forward to `Invoke-RemoteBuild.ps1` so NuGet/pip caches actually work end-to-end.
+
+4. **Add an on-demand `gitea/workflows/self-test.yml`** (`workflow_dispatch` trigger only). One Windows job, one Linux job, both calling the composite action against a trivial build (`Write-Host 'ok' > out.txt`). Asserts artifact upload, JSONL events, clean teardown. Use as the regression gate for any action change.
+
+5. **Add a Pester `gitea/workflows/tests.yml`** that runs the existing tests on every push. PowerShell 5.1, `Invoke-Pester -CI`. This is the current missing "CI for the CI" piece.
+
+6. **Keep the lint workflow** [gitea/workflows/lint.yml](../gitea/workflows/lint.yml) as is.
+
+7. **Do NOT add scheduled builds, dependency-update workflows, or release workflows.** Out of scope.
+
+---
+
+## Docker / Container Notes
+
+This project deliberately does not use Docker, Podman, or any container runtime. The decision is correct and should be preserved.
+
+Rationale:
+
+- Windows builds require VS Build Tools, MSBuild, the full .NET SDK, and Windows-specific signing chains. Running those in Windows containers requires Windows Server host images, breaks isolation guarantees the project gets cheaply from VMware, and adds licensing complexity.
+- The project's isolation boundary is a VM, not a container. VMs offer strictly stronger isolation than containers (kernel separation, hardware-virtualized network stack, separate filesystem) at a cost the system can afford.
+- act_runner's `container.enabled: false` is the right setting for a system that uses real VMs.
+- The performance overhead of "spin up a VM" vs "spin up a container" is real (a clone takes 5-30s, a container ~1s), but the orchestrator amortizes this across a 2-hour build budget. The cost is acceptable.
+
+When might containers enter the picture? Likely never for this scope. If the project ever needs to build small Linux-only services with no Windows leg, a side-by-side `linux-build-container` runner label could be added later. That is a phase-3+ idea, not a current task.
+
+---
+
+## Monitoring and Logging Improvements
+
+Concrete additions only. No metric server.
+
+JSONL schema additions inside `F:\CI\Logs\<jobId>\invoke-ci.jsonl` (emitted by [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1)):
+
+- Per-phase `duration_ms` calculated at phase end.
+- `free_disk_gb_before` and `free_disk_gb_after` for the job.
+- `ip_detection_method` field with values `guestinfo` or `getGuestIPAddress`.
+- `vm_start_lock_wait_ms` recording how long the orchestrator waited on `vm-start.lock`.
+- `clone_dir_size_mb` measured at teardown.
+
+Event Log additions:
+
+- Standardize on `CI-DiskSpaceAlert` (EventId 1001), `CI-RunnerHealth` (1002 stopped / 1003 restarted / 1004 throttled).
+- Add `CI-JobFailure` source for failed orchestrator runs (EventId 2001) writing JobId and failed phase.
+
+Watcher script additions:
+
+- `scripts/Get-CIJobSummary.ps1` (nice-to-have): reads last N days of JSONL files, prints a table of JobId, started, elapsed, phase 1 duration, phase 5 duration, status.
+- `scripts/Watch-RunnerHealth.ps1` (Low): respect `F:\CI\State\runner-maintenance.flag` to suppress restart attempts during template refresh.
+
+Webhook payload changes:
+
+- Remove emoji prefixes. Use `[WARN]`, `[ERROR]`, `[INFO]` plain text.
+
+Do NOT add:
+
+- Prometheus exporters.
+- Grafana dashboards.
+- OpenTelemetry collectors.
+- SQLite or any other database sink.
+- Discord/Slack rich-embed cards.
+
+---
+
+## Backup and Recovery Improvements
+
+The current backup story is roughly: [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) (currently pointing at a stale path). Improvements:
+
+1. Fix the default path and add `-AllTemplates` switch (H7).
+2. Add to [docs/RUNBOOK.md](../docs/RUNBOOK.md) the consolidated template-refresh runbook (Sprint 4 task 4.6).
+3. Register a weekly scheduled task that runs `.\Backup-CITemplate.ps1 -AllTemplates -KeepLast 3` and writes a log to `F:\CI\Logs\backup\<date>.log`. Update [scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1) to add this fifth scheduled task.
+4. Document recovery from a destroyed template: restore the latest `.7z` from the backup destination, validate snapshots exist via `vmrun listSnapshots`, run `Validate-DeployState.ps1` (Windows + Linux), run the smoke workflow. If the smoke fails, restore the previous backup. Step-by-step in [docs/RUNBOOK.md](../docs/RUNBOOK.md).
+5. Document the simple recovery path for a stale `vm-start.lock` and stale IP leases in [docs/RUNBOOK.md](../docs/RUNBOOK.md) — even though Sprint 3 task 3.2 makes this automatic, the operator-facing docs should still say "if you ever need to do this manually, the commands are X."
+
+Do NOT add:
+
+- VM snapshot backup to remote storage (out of scope; 7z files on a second drive is sufficient).
+- Restore-time automated diff against a known-good template (over-engineered).
+
+---
+
+## Runner and Build Optimization
+
+Concrete, measurable.
+
+1. **Wire `use-shared-cache`** through the composite action and orchestrator (Medium item). Expected impact: ~15-30% faster Python and .NET builds that pull packages on every run, by avoiding the `pip download` and `nuget restore` over the WAN. Measurement: compare `phase 5 duration` JSONL before/after on a representative NSIS-plugin build.
+
+2. **After burn-in, decide on `capacity`**. If the burn-in shows that capacity 4 is solid, keep it. If it shows that capacity 2 is the safe ceiling under typical host CPU contention, set `runner/config.yaml capacity: 2`. Expected impact: avoidance of unreproducible build failures during peaks.
+
+3. **Defender exclusion for `F:\CI\BuildVMs\`** on the host (Low). Cloning and start are I/O heavy on the parent VMDK chain; Defender scanning slows this. Use `Set-MpPreference -ExclusionPath 'F:\CI\BuildVMs'`. Expected impact: ~10% faster clone-to-IP times. Document the trade-off in [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md): malicious code reaching the host would persist faster, but the threat model already accepts trusted-builds-only.
+
+4. **Linked-clone health monitoring** (Nice-to-have): add per-job delta size to JSONL. If the average delta grows over months without a template refresh, that is a signal something is writing into the template chain. Not urgent; nice diagnostic.
+
+5. **Do NOT pursue a warm clone pool**. Both reviewers agreed: the savings (5-30s per job) do not justify the state-machine complexity for a 2-hour build budget.
+
+6. **Do NOT pursue VMX CPU/RAM tuning per job** unless the burn-in shows host saturation. Wait for evidence.
+
+---
+
+## Repository Conventions
+
+These are the codified rules. Where ambiguous, write them into [AGENTS.md](../AGENTS.md) and [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md).
+
+**Style and linting** (already largely in place):
+
+- PowerShell 5.1 only. Every script begins with `#Requires -Version 5.1`, `Set-StrictMode -Version Latest`, `$ErrorActionPreference = 'Stop'`.
+- 4-space indentation, no tabs.
+- Verb-Noun cmdlet naming. `Get-`, `Set-`, `New-`, `Remove-`, `Invoke-`, `Test-`, `Wait-`, `Watch-`.
+- `Write-Host` is acceptable and preferred over `Write-Output` in CI scripts (act_runner captures `Write-Host` cleanly; `Write-Output` pollutes function return values). Codified in [PSScriptAnalyzerSettings.psd1](../PSScriptAnalyzerSettings.psd1).
+- No emoji in code, logs, webhook payloads, docs, or commit messages. Plain text markers like `[WARN]`, `[OK]`, `[x]`, `[ ]`.
+- No PS 7+ syntax: no `??`, no `??=`, no ternary, no `&&`/`||` in PowerShell context, no `ForEach-Object -Parallel`, no `Test-Json`.
+
+**File organization**:
+
+- Production scripts under `scripts/`. Template provisioning under `template/`. Tests under `tests/`. Documentation under `docs/`. Plans and reviews under `plans/`.
+- Module files `_Common.psm1` and `_Transport.psm1` stay in `scripts/`. Do not split further.
+- One script, one verb-noun purpose. Composite actions live under `gitea/actions/<name>/action.yml`.
+
+**Commit messages**:
+
+- Imperative mood, present tense ("Add bounded vmrun wrapper", not "Added" or "Adding").
+- Subject line ≤72 characters. Body explains *why*, not *what*.
+- Reference the master plan checklist item by short title when relevant: e.g. `Fix C1: Linux matrix template selection`.
+
+**Branching**:
+
+- `main` is the only long-lived branch.
+- Use short-lived feature branches `fix/c1-linux-matrix`, `fix/h2-action-outputs`, etc.
+- Squash merge or rebase; do not preserve micro-commits.
+
+**Testing requirements before merge**:
+
+- After H10 is implemented: every PR runs the lint and Pester workflows. After the smoke-test workflow exists, run it for any change touching orchestration scripts.
+
+**Documentation updates**:
+
+- A change to a script that changes its parameters or behavior must update [docs/CI-FLOW.md](../docs/CI-FLOW.md), [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md), or [docs/RUNBOOK.md](../docs/RUNBOOK.md) in the same commit.
+- A change to [runner/config.yaml](../runner/config.yaml) or directory layout must update [AGENTS.md](../AGENTS.md) and [Setup-Host.ps1](../Setup-Host.ps1).
+
+---
+
+## Documentation Status
+
+Per-document assessment.
+
+| Document                                                            | Status                                                                                             | Action                                                                                                                                               |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [AGENTS.md](../AGENTS.md)                                           | Good. Reflects current paths, PS 5.1 rules, error patterns.                                        | Keep updated as new gotchas are discovered.                                                                                                          |
+| [README.md](../README.md)                                           | Stale. Claims production-ready before stabilization pass completes.                                | Replace "production-ready" with "feature-complete; stabilization pass in progress" until all Critical and High items are checked.                    |
+| [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md)                     | Mostly accurate; minor diagram rendering issue.                                                    | Reformat the ASCII diagram box. Reflect H4 bounded-vmrun pattern in the lifecycle section.                                                           |
+| [docs/CI-FLOW.md](../docs/CI-FLOW.md)                               | Stale on partial-artifacts-on-failure. Still mentions `getGuestIPAddress` as primary IP detection. | Update IP-detection section to reflect `guestinfo.ci-ip` primary. Reconcile failure-scenario table with whether H-level diagnostics are implemented. |
+| [docs/RUNBOOK.md](../docs/RUNBOOK.md)                               | Useful but incomplete.                                                                             | Add: consolidated template-refresh procedure; capacity burn-in results; recovery from stale lock; runner service-account identity.                   |
+| [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md)                 | Good. Old `WinBuild` path references need fixing.                                                  | Update all `WinBuild` to `WinBuild2025`. Add HGFS shared-folder cache poisoning note.                                                                |
+| [docs/WORKFLOW-AUTHORING.md](../docs/WORKFLOW-AUTHORING.md)         | Good.                                                                                              | Add one-paragraph note on Gitea secret-mask substring limitation.                                                                                    |
+| [docs/HOST-SETUP.md](../docs/HOST-SETUP.md)                         | Mostly accurate.                                                                                   | Update directory list to match new [Setup-Host.ps1](../Setup-Host.ps1). Add ACL guidance for `F:\CI\keys\ci_linux`.                                  |
+| [docs/WINDOWS-TEMPLATE-SETUP.md](../docs/WINDOWS-TEMPLATE-SETUP.md) | Good.                                                                                              | Cross-reference the consolidated template-refresh runbook in [docs/RUNBOOK.md](../docs/RUNBOOK.md).                                                  |
+| [docs/LINUX-TEMPLATE-SETUP.md](../docs/LINUX-TEMPLATE-SETUP.md)     | Good.                                                                                              | Add `Validate-DeployState.ps1` Linux branch usage.                                                                                                   |
+| [docs/OPTIMIZATION.md](../docs/OPTIMIZATION.md)                     | Mostly accurate.                                                                                   | Note Defender exclusion option and shared-cache wiring after H-Medium fixes.                                                                         |
+| [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) | Stale. PS 7 syntax, wrong parameter names, wrong task/event names.                                 | Sprint 5 task 5.3: PS 5.1 syntax, `-RepoUrl`, current Event Log sources.                                                                             |
+| [docs/Setup-GiteaSSH.md](../docs/Setup-GiteaSSH.md)                 | Untouched by reviewers; assume accurate.                                                           | Verify against fixed service-account path from H8.                                                                                                   |
+| [TODO.md](../TODO.md)                                               | Acting as a CHANGELOG.                                                                             | Sprint 5 task: move "done" sections into `docs/CHANGELOG.md`; keep TODO for genuinely outstanding work.                                              |
+| [docs/archived/2026-05-10/](../docs/archived/2026-05-10/)           | Historical.                                                                                        | Leave as-is.                                                                                                                                         |
+
+---
+
+## Final Completion Plan
+
+Execute in this exact order. Each phase has a single success criterion that gates the next.
+
+**Phase 0 — Read this plan and commit it.** Already done by the act of generating it.
+
+**Phase 1 — Validation (Sprint 1).** Verify the act_runner service account, confirm the directory inventory, run the 4-way concurrency burn-in, manually trigger the broken Linux matrix to confirm C1. Output: a section appended to [docs/RUNBOOK.md](../docs/RUNBOOK.md) titled "Validation Results 2026-05-XX" documenting findings. Gate: burn-in passed three times (keep `capacity: 4`) or was set to 2 (with reasoning recorded).
+
+**Phase 2 — Critical Fixes (Sprint 2).** Fix C1 and C2, plus H2/H3/H6/H7. Manually trigger [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) for both matrix legs after each fix. Gate: both Critical items closed and `[x]` in this plan's Critical section; both legs green in the live matrix workflow.
+
+**Phase 3 — High Priority Fixes (Sprint 3).** Complete the rest of the High items: H4 (bounded vmrun), H5 (stale lock), H8 (SSH alias fix), H9 (Linux validator), H10 (smoke-test workflow), H11 (script-root env var), H12 (benchmark alignment). Gate: smoke-test workflow green; all High items `[x]`.
+
+**Phase 4 — Operational Hardening (Sprint 4).** All Medium items including consolidated template-refresh runbook. Gate: documented end-to-end template refresh executed successfully against a non-production template clone.
+
+**Phase 5 — Polish (Sprint 5).** Low items, nice-to-have summary tool, documentation alignment, TODO → CHANGELOG migration. Gate: README claim updated from "feature-complete; stabilization pass in progress" back to "production-ready for homelab".
+
+**Phase 6 — Tag v1.0.** Create an annotated tag `v1.0.0` on `main` once Phase 5 gate passes. Write a `docs/CHANGELOG.md` v1.0 entry summarizing the journey.
+
+**Phase 7 — Operate.** Use the system. Track new findings in `TODO.md`. Run the burn-in any time act_runner capacity, host hardware, or template chains change materially.
+
+When all Critical and High items are checked, this system is genuinely production-ready for homelab use.

plans/archived/2026-05-13/gpt55-analysis.md

@@ -0,0 +1,492 @@
+# Technical Review: Local CI/CD System
+
+Date: 2026-05-11
+
+Scope reviewed: all requested project files in the workspace, including orchestration scripts, template provisioning scripts, runner configuration, workflows, Pester tests, and operational documentation.
+
+## 1. Executive Summary
+
+This project is a self-hosted homelab CI/CD platform built around Gitea Actions, act_runner, VMware Workstation linked clones, Windows PowerShell 5.1, WinRM for Windows guests, and SSH for Linux guests. The core idea is sound: keep the Windows host as a thin orchestrator, create a fresh linked clone for each job, run the build inside an isolated VM, collect artifacts, and destroy the clone in a `finally` block. For a single-host homelab, this is the right architecture. It uses the tools already available on the host, avoids containerizing workloads that need full Windows build tooling, and gives repeatable isolation without introducing Kubernetes, ESXi, or unnecessary service layers.
+
+Overall, the system is well-built for its intended environment. The strongest parts are the lifecycle decomposition, the cold-template workflow, the PS5.1 discipline in the main scripts, the Windows template hardening/provisioning gates, and the Linux cloud-init/open-vm-tools work. The project has clearly gone through real failure-driven refinement: the notes about VMware Tools timing, cloud-init BOM issues, headless `getGuestIPAddress`, WinRM HTTPS, snapshot state, and Linux netplan MAC matching are exactly the kind of details that only appear after serious testing.
+
+I would not yet call it fully trustworthy for unattended daily use without a small stabilization pass. The core VM lifecycle is close, but a few issues are operationally important: the composite action output block is malformed, Linux secret injection can leak secrets to logs and process arguments, host bootstrap and backup defaults drift from the current directory layout, stale `vm-start.lock` is not automatically cleared, and some documentation/test-plan commands no longer match the actual parameter names or PS5.1 constraint. These are fixable, homelab-scale problems, not architectural failures.
+
+## 2. Project State Assessment
+
+Genuinely done:
+
+- Windows VM lifecycle exists end to end: [scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1), [scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1), [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1), [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1), and [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1) form a coherent pipeline.
+- Linux build VM support is implemented, not just planned. [template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1), [template/Prepare-LinuxBuild2404.ps1](../template/Prepare-LinuxBuild2404.ps1), [template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh), [scripts/_Transport.psm1](../scripts/_Transport.psm1), and the Linux branches in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1), and [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1) are real.
+- WinRM HTTPS migration is implemented in the active scripts. The Windows paths use `-UseSSL -Port 5986 -Authentication Basic` and a shared `New-CISessionOption` helper in [scripts/_Common.psm1](../scripts/_Common.psm1).
+- The current orchestrator has a real clone/start/IP serialization lock and lease file defense in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1). This is stronger than some older documentation implies.
+- Scheduled maintenance scripts exist: cleanup, retention, disk alert, runner health, and scheduled task registration are all present.
+- Unit tests exist and cover the shared module, clone creation, removal, and readiness timeout/validation behavior.
+- The Windows and Linux templates have serious pre-snapshot validation gates. They are not just installation scripts; they assert the state they intend to snapshot.
+
+Documented as done but not fully validated or internally inconsistent:
+
+- The README claims production-ready status, while [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) still marks several real-VM validations as skipped or partial. The honest state is "feature-complete, with remaining real-VM validation and workflow defects." The README is ahead of the evidence.
+- The composite action is documented as reusable and complete, but [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) places `artifact-path` and the second `artifact-name` under `inputs` instead of a top-level `outputs` block. That can break artifact upload steps that use `steps.invoke-ci.outputs.*`.
+- The test plan contains PS7-only `ForEach-Object -Parallel`, even though the project standard is PS5.1 only. This is a documentation/test executability issue, not a production-script syntax issue.
+- [docs/CI-FLOW.md](../docs/CI-FLOW.md) and [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) describe some older mechanics such as `getGuestIPAddress` as the main flow, while [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) now primarily reads `guestinfo.ci-ip` and uses `getGuestIPAddress` as fallback.
+- [docs/CI-FLOW.md](../docs/CI-FLOW.md) says partial artifacts are collected after build failure, but the current orchestrator enters `catch` and cleanup directly; artifact collection happens only after successful `Invoke-RemoteBuild.ps1`.
+- TODO says some security tasks are deferred even though corresponding implementation exists. The `PAT mai persistito` item still says deferred, but the Windows path has an implementation and the Linux path has a problematic implementation.
+- [Setup-Host.ps1](../Setup-Host.ps1) still creates `F:\CI\Templates\WinBuild`, not the current `WinBuild2025`, `WinBuild2022`, and `LinuxBuild2404` structure. It also does not create `F:\CI\State`, `F:\CI\keys`, or `F:\CI\Cache\pip`.
+
+## 3. Architecture Analysis
+
+The overall design quality is high for a homelab system. The host-as-orchestrator model is appropriate: act_runner runs workflow logic on the host, but build commands execute inside disposable VMs. This gives a strong isolation boundary without the cost of an enterprise virtualization stack. The template and linked-clone model is the right tradeoff for VMware Workstation: fast clone creation, small per-job disk footprint, and deterministic toolchain state.
+
+VM lifecycle management is mostly sound. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) owns the lifecycle and wraps destructive cleanup in `finally`. Clone creation is delegated to [scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1), readiness to [scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1), build execution to [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1), artifacts to [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1), and teardown to [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1). This is a good separation of concerns. The teardown script has retry logic around `deleteVM`, which is useful because VMware often releases locks late.
+
+The weak point in lifecycle management is bounded execution. The primary orchestrator still calls `vmrun start`, `readVariable`, `getGuestIPAddress`, and other native tools directly without a general timeout wrapper. Some deployment scripts have `Invoke-VmrunBounded`, but the active CI scripts do not use a common bounded process helper. If `vmrun` hangs, the runner slot can hang until act_runner job timeout, and cleanup may never run. This is the highest reliability gap left in the core lifecycle.
+
+The transport duality is clean enough but not fully abstracted. Windows and Linux branches are explicit in the top-level scripts, which is a good homelab choice: the code is understandable, and the two transports differ enough that over-abstracting would make troubleshooting harder. [scripts/_Transport.psm1](../scripts/_Transport.psm1) covers SSH helpers only, while [scripts/_Common.psm1](../scripts/_Common.psm1) covers WinRM session options and vmrun. This is acceptable, but function naming could be clearer: `_Transport.psm1` sounds like a cross-transport abstraction even though it is SSH-specific.
+
+The IP allocation mechanism is better than the TODO summary suggests. The actual implementation serializes clone/start/IP detection through `F:\CI\State\vm-start.lock`, detects IP through `guestinfo.ci-ip` when available, writes an IP lease file, and releases it in `finally`. This reduces the practical risk of two concurrent builds talking to the same VM. However, it is not true deterministic IP allocation. It still depends on DHCP, detects collisions after the fact, and a stale `vm-start.lock` from a host crash is not automatically pruned by the scheduled tasks. For capacity 4, it is probably reliable enough after one fix: automatic stale lock cleanup.
+
+Credential management is pragmatic but mixed. Windows guest credentials use Windows Credential Manager via `BuildVMGuest`, which is appropriate. Linux uses a host-side private key at `F:\CI\keys\ci_linux`, also appropriate for a homelab, provided ACLs are correct. The weakest credential path is `-UseGitClone` and extra guest environment variables. The Windows `git -c http.extraHeader=Authorization: Basic ...` approach avoids putting credentials in the clone URL, but the header value still appears in the guest process command line. The Linux `GIT_CLONE_URL` implementation embeds a credential-bearing URL into the SSH command string. The Linux extra-env path logs the composed build command including exported secret values. These need fixing before secret-bearing builds are safe.
+
+Script interdependencies are reasonable. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) is intentionally the hub. The coupling to hardcoded host paths is expected for a fixed homelab, but inconsistent defaults undercut that: [runner/config.yaml](../runner/config.yaml), [Setup-Host.ps1](../Setup-Host.ps1), [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1), and docs do not all agree on template paths. A single path contract in [AGENTS.md](../AGENTS.md) plus corrected defaults would make the system easier to rebuild.
+
+The module organization is helpful but incomplete. [scripts/_Common.psm1](../scripts/_Common.psm1) covers three high-value helpers, but many scripts still implement local `Invoke-Vmrun`, `Assert-Step`, `Set-VmxKey`, ISO writing, and polling patterns. For template deployment scripts, duplication is acceptable because they are long, one-off provisioning flows. For production CI scripts, move bounded native process execution, IPv4 validation, and stale state cleanup into `_Common.psm1`.
+
+The host-as-orchestrator pattern has clear pros: simple mental model, native access to VMware Workstation, easy file-based state, easy Event Log and Scheduled Task integration, and no new services. The cons are also clear: host filesystem paths leak into workflows, host compromise compromises the whole CI system, concurrency depends on local file locking, and observability is local unless forwarded. For this homelab, the pros outweigh the cons.
+
+## 4. Code Quality and PS5.1 Compliance
+
+Project-wide PS5.1 compliance is mostly good in production PowerShell. I did not find actual PS7 null-coalescing, ternary, or `ForEach-Object -Parallel` in the production `.ps1` scripts that were reviewed. Bash `&&` appears inside commands intentionally executed by Linux guests; that is acceptable. The major PS5.1 compliance problem is in documentation/test-plan snippets, especially [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md), which uses `ForEach-Object -Parallel`.
+
+[scripts/_Common.psm1](../scripts/_Common.psm1): Good minimal shared module. PS5.1 compliant. Error handling in `Invoke-Vmrun` checks `$LASTEXITCODE` and optionally throws. Gap: no timeout support, no standard native command result object with elapsed time, and no shared IPv4 validator.
+
+[scripts/_Transport.psm1](../scripts/_Transport.psm1): Clear SSH/SCP wrapper. PS5.1 compliant. It uses `StrictHostKeyChecking=no` and `UserKnownHostsFile=NUL`, which is operationally convenient but weakens MITM protection. Error handling checks exit codes. Gap: it can throw command text containing secrets when callers pass secret-bearing commands.
+
+[scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1): Strong orchestration structure and good `finally` cleanup. PS5.1 compliant. Smells: many hardcoded `F:\CI` paths despite parameters for others; direct `vmrun` calls instead of `_Common.psm1` wrapper; stale `vm-start.lock` behavior causes a 10-minute delay then failure; JSONL logging is best-effort but lacks duration calculations; artifact collection is skipped on build failure. Parameter validation gaps: `JobId` is not sanitized before use in paths, so hostile or malformed IDs could create awkward paths. `ExtraGuestEnv` keys are documented as valid env names but not validated in the orchestrator.
+
+[scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1): Simple and solid. Uses `_Common.psm1`. PS5.1 compliant. Gap: `JobId` is directly used in clone folder names; add a conservative validation pattern or sanitize to `[A-Za-z0-9_.-]`. It does not preflight snapshot existence; `vmrun clone` failure is probably enough, but a `listSnapshots` check could improve diagnostics.
+
+[scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1): Practical cleanup with `SupportsShouldProcess`. PS5.1 compliant. Smell: `$ErrorActionPreference = 'Continue'` makes it resilient but can hide failures. It warns if the directory remains, but does not emit structured state or Event Log. Direct `vmrun` calls lack timeout. It can still hang on `getState`, `list`, or `deleteVM` if VMware blocks.
+
+[scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1): Good improvement over `getGuestIPAddress` for power-state detection by using `vmrun list`. PS5.1 compliant. The Windows readiness check only tests TCP 5986, not an authenticated WinRM session, so it can declare ready before credentials/remoting policy are actually usable. This is acceptable for speed but can shift failure into Phase 5. The docblock still references older `getState`/`Test-WSMan` concepts.
+
+[scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1): Functionally rich but now the densest and riskiest script. PS5.1 compliant. Good: mode validation, WinRM/SSH separation, 7-Zip fallback, and Linux artifact staging. Problems: Linux secret values are logged through `Write-Host "Running build: $buildCmd"`; Linux `GIT_CLONE_URL` embeds PAT in a remote command string; Windows PAT is passed to `git -c http.extraHeader=...`, which can be visible in guest process command line; `ExtraGuestEnv` keys are not validated; custom Windows build command uses `cmd /c "$cmd 2>&1"`, so quoting/injection is controlled only by trusted workflow inputs. For a trusted homelab this is tolerable, but it contradicts the stated secret-safety claims.
+
+[scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1): Clear and mostly robust. PS5.1 compliant. Windows branch retries WinRM session creation. Linux branch copies a directory recursively and validates at least one file. Gap: no manifest or artifact metadata is written, and failure diagnostics from guest output directories are limited.
+
+[scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1): Good simple orphan cleanup. PS5.1 compliant. Gap: does not clear stale `F:\CI\State\vm-start.lock`; does not remove stale IP leases unless retention runs; uses directory `LastWriteTime`, which can be misleading if VMware updates files late or not at all.
+
+[scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1): Useful and safe. PS5.1 compliant. It cleans artifacts, logs, and stale IP leases. Gap: hardcoded leases dir and no cleanup for `vm-start.lock`. It does not write Event Log entries, despite some test-plan expectations.
+
+[scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1): Good minimal disk monitor. PS5.1 compliant. Gap: webhook content includes emoji despite the user's stated no-emoji preference; more importantly, the Event Log source is `CI-DiskAlert`, but the test plan expects other names. Exit code 1 on low disk is fine for Scheduled Task visibility.
+
+[scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1): Good rate-limited restart design. PS5.1 compliant. Similar webhook emoji issue. It checks only local Windows service status, not whether Gitea sees the runner online. For daily use, add optional API check later.
+
+[scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1): Conceptually important, but defaults are stale. It backs up `F:\CI\Templates\WinBuild`, while the current primary template is `F:\CI\Templates\WinBuild2025`. That makes the default backup procedure fail or back up the wrong thing. High operational risk before template refresh.
+
+[scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1): Good, idempotent scheduled task registration. PS5.1 compliant. Gaps: default `ScriptRoot` is hardcoded to `N:\Code\Workspace\Local-CI-CD-System\scripts`; acceptable on this host but not portable. Task names in docs/test plan do not always match actual registered names (`CI-DiskSpaceAlert` versus `CI-DiskSpace`).
+
+[scripts/Set-TemplateSharedFolders.ps1](../scripts/Set-TemplateSharedFolders.ps1): Clean idempotent VMX editor. PS5.1 compliant. Risk: shared folders are writable from guest to host; this is useful for caches but weakens isolation. Use only for cache directories and never map broad host paths.
+
+[scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1): Useful baseline tool. PS5.1 compliant. Gaps: it still uses `getGuestIPAddress` rather than the newer `guestinfo.ci-ip` path, so Linux timing may not match the production orchestrator. JSONL structure differs from the test plan's expected `phase` and `duration_ms` fields.
+
+[Setup-Host.ps1](../Setup-Host.ps1): Helpful bootstrap, but drifted. It creates old template paths, does not create Linux key/state/cache directories, registers only `windows-build:host,dotnet:host,msbuild:host` labels during runner registration, and leaves Linux label only in config. It uses plaintext guest password as a parameter, although default is empty and prompt is preferred. It should be corrected before claiming rebuild-from-scratch reliability.
+
+[runner/Install-Runner.ps1](../runner/Install-Runner.ps1): Marked deprecated. It is fine as reference but should not be presented as an active path. It lacks newer labels and may drift further.
+
+[template/Deploy-WinBuild2025.ps1](../template/Deploy-WinBuild2025.ps1) and [template/Deploy-WinBuild2022.ps1](../template/Deploy-WinBuild2022.ps1): Sophisticated and PS5.1 compliant. Good use of bounded vmrun for stop. Risks: admin password and autologin password are embedded into generated unattend/post-install content and registry. That is accepted in the lab threat model but should be clearly treated as snapshot secret material. Both scripts duplicate a lot of logic; tolerable, but fixes must be applied to both.
+
+[template/Prepare-WinBuild2025.ps1](../template/Prepare-WinBuild2025.ps1): Strong validation and reboot loop for Windows Update. PS5.1 compliant. Operational smell: it prompts interactively for snapshot creation and deletion, which makes fully unattended template refresh harder. It also uses `ConvertTo-SecureString -AsPlainText` for admin password conversion, which is expected when bridging from a string parameter but will trigger static warnings.
+
+[template/Install-CIToolchain-WinBuild2025.ps1](../template/Install-CIToolchain-WinBuild2025.ps1): Very detailed and mostly well engineered. PS5.1 compliant. Main debt: many installer SHA256 values are empty, so the supply-chain pinning structure mostly warns rather than enforces. It also uses a public KMS endpoint by default, which is not appropriate outside a private lab or unless the user has explicitly chosen that activation model.
+
+[template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1): Good cloud-init implementation with BOM/LF handling and guestinfo fallback. PS5.1 compliant. Gap: no hash verification for downloaded Ubuntu cloud VMDK. A corrupted or malicious base image would poison every Linux build.
+
+[template/Prepare-LinuxBuild2404.ps1](../template/Prepare-LinuxBuild2404.ps1): Practical SSH provisioning. PS5.1 compliant. It validates only a loose IPv4 pattern, not per-octet. It uses remote bash `&&` and `||` inside strings, which is correct for Linux. It uses `StrictHostKeyChecking=no` in several places despite comments mentioning accept-new.
+
+[template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh): Clean bash script with `set -euo pipefail`. It installs a solid basic build environment. Gap: no apt package version pinning, no snapshot of apt sources, and no retry wrapper for apt transient failures.
+
+[template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1) and [template/Validate-SetupState.ps1](../template/Validate-SetupState.ps1): Useful validation scripts. Docblocks still say WinRM HTTP/Basic even though the implementation uses HTTPS/5986. [template/Validate-SetupState.ps1](../template/Validate-SetupState.ps1) assumes `PasswordExpires` exists, while the install script already handles property variation; this can fail on different LocalAccounts module versions.
+
+## 5. Security Analysis (Homelab-realistic)
+
+WinRM with self-signed certificate plus Basic auth is acceptable in this lab if VMnet8 is isolated and the host is trusted. The important improvement is that `AllowUnencrypted=false` and traffic uses HTTPS/5986. Skipping CA/CN/revocation checks is normal for a self-signed lab certificate, but it means the host does not authenticate the VM identity beyond IP and network position. A malicious VM on VMnet8 could theoretically impersonate another VM if the IP handling failed. The current IP lock and lease design reduces but does not eliminate this risk.
+
+SSH key storage is acceptable if ACLs on `F:\CI\keys\ci_linux` restrict access to the runner service identity and Administrators. The repo documents the path but does not include an ACL validation script. Add one. Because the key has no passphrase, filesystem ACLs are the only real protection.
+
+PAT handling in `-UseGitClone` is mixed. The Windows path avoids putting credentials in the URL, which is good, but it uses `git -c http.extraHeader=Authorization: Basic <base64>` so the token-derived header may be visible in process arguments inside the guest. The Linux path is worse: it builds a credential-bearing URL and embeds it in a remote command assigned to `GIT_CLONE_URL`. If SSH command logging, PowerShell error messages, or process inspection catches that string, the PAT leaks. The TODO and docs claim PAT safety more strongly than the code supports.
+
+Secrets via workflow-level `extra-guest-env-json` are not currently safe on Linux. [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) builds an `export KEY='value';` prefix and then logs the full build command. That directly prints secret values. Windows is safer because it sets environment variables inside the session and does not print the hashtable values, but it still passes secrets as WinRM arguments.
+
+Runner environment variables in [runner/config.yaml](../runner/config.yaml) are not secrets. They are paths and target names. That is fine. Do not add PATs or passwords there. The composite action correctly passes most inputs through env vars to reduce shell injection risk, but `extra-guest-env-json` itself is an env var containing secrets; ensure act_runner does not echo it.
+
+Template hardening disables Defender, Firewall, and UAC. For this homelab, this is acceptable only if all builds are trusted. The documentation in [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md) is honest about this. The most important nuance is that a compromised build VM is not just a guest problem: it can reach the NAT network, Gitea, package registries, and any host-exposed VMware shared folders. If shared cache folders are writable, malicious code can poison cache content for future builds.
+
+A compromised build VM could likely reach:
+
+- Gitea over LAN/NAT if routing allows it.
+- The internet through VMnet8 NAT.
+- Host VMware shared folders configured for caches.
+- WinRM/SSH ports of other concurrently running build VMs if IP/network isolation is not stricter.
+- Potentially host services bound to VMnet8.
+
+It should not have host filesystem access beyond configured shared folders, and it should not have the Linux private key or Windows Credential Manager secrets unless scripts explicitly copy them in. Keep it that way.
+
+## 6. Reliability and Resilience Analysis
+
+VM leak scenarios remain possible but bounded. Normal build failures are covered by `finally`. Host power loss, hung PowerShell process, forced runner termination, or a `vmrun` call that never returns can bypass cleanup. [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1) handles stale clone directories, and scheduled tasks run it every 6 hours plus startup. That is good. Add Event Log output and stale lock cleanup to make recovery visible.
+
+IP lease race conditions are mostly mitigated by serializing clone/start/IP detection. This is not a true static lease allocator; it is a concurrency gate plus collision detector. For capacity 4, this is probably good enough. The risky case is host crash after creating `vm-start.lock` or an IP lease. IP leases older than 12 hours are cleaned by retention, but the start lock is not. That means a crash can cause every new job to wait 10 minutes and fail until manual cleanup.
+
+The error recovery quality in try/finally blocks is good in the main orchestrator. The Windows template prepare script also has careful `finally` restoration of TrustedHosts. The removal script tries soft stop, hard stop, deleteVM retries, and directory removal. However, there is no outer watchdog for stuck native processes. If PowerShell is blocked inside native `vmrun`, `finally` cannot execute until the native process returns.
+
+On host reboot mid-build, the expected behavior is: act_runner service restarts, Gitea marks the job failed or times it out, clone directories and possibly running VMs remain, scheduled cleanup removes clones older than threshold, retention later removes stale leases. This is close to acceptable. Add startup cleanup for `vm-start.lock` and leases to avoid avoidable first-job failures after reboot.
+
+If `vmrun` hangs, the system is weak. act_runner timeout may eventually terminate the job, but PowerShell may remain stuck and the clone may leak. Some deploy scripts use bounded process execution; move that pattern into [scripts/_Common.psm1](../scripts/_Common.psm1) and use it in production lifecycle scripts.
+
+Disk exhaustion is handled by monitoring and retention but not by preflight gates. [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1) alerts under 50 GB, and [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) uses aggressive retention under that threshold. But [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) does not check free space before cloning. Add a fast preflight check before Phase 2 so clone failure is clear.
+
+Artifact loss scenarios exist. Windows custom build mode packages artifacts only if build exit is 0. Linux mode copies artifact source if it exists and logs a warning if not, but then `Get-BuildArtifacts.ps1` fails only if the output directory is empty. On build failure, [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) does not attempt to collect partial logs/artifacts from the guest before teardown. This hurts failure triage.
+
+## 7. CI/CD Workflow Analysis
+
+The composite action idea is excellent. A reusable [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) hides the VM lifecycle and lets application repositories specify only build command, artifact source, guest OS, and repo URL. That is exactly the right abstraction for a homelab with several repositories.
+
+The current action has a structural YAML problem: it appears to define outputs under `inputs`, and duplicates `artifact-name`. Composite action outputs should be top-level `outputs`. As written, the `Upload artifacts` step may not receive `steps.invoke-ci.outputs.artifact-path` and `artifact-name` as intended. This can make builds succeed inside the VM but fail at artifact upload.
+
+Workflow flexibility is otherwise good. [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) uses a Windows/Linux matrix and disambiguates job IDs with `job-id-suffix`. That is the right pattern. Missing patterns: PR checks are not represented in the live workflow, scheduled builds are not represented, and dependency caching via `actions/cache` is not shown even though act_runner cache is enabled. For this system, PR checks and manual rebuild are more valuable than scheduled builds.
+
+Artifact upload to Gitea is done through `actions/upload-artifact@v4` in the composite action. The VM pipeline collects files into `F:\CI\Artifacts\<jobId>`, then upload-artifact reads that host-side directory. That is a good bridge between local VM isolation and Gitea's artifact store, once the outputs block is fixed.
+
+Build cache effectiveness is partial. NuGet/pip shared folders exist for Windows when `-UseSharedCache` is passed, but the composite action does not expose a `use-shared-cache` input and [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) does not forward `UseSharedCache` to [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1). The feature exists at the lower layer but is not wired into the main workflow path.
+
+Matrix build design quality is good: `target: [windows, linux]`, `runs-on: ${{ matrix.target }}-build`, `fail-fast: false`, and target-specific artifact names are exactly the right shape.
+
+## 8. Observability and Monitoring
+
+The JSONL logging design is useful. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) emits phase start/success/failure events with ISO timestamps, job ID, phase, status, and data. This is enough to compute phase durations after the fact. It is not yet a full metrics layer, but it is the right low-cost foundation.
+
+Disk space monitoring is adequate for a homelab. [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1) writes Event Log warnings and optionally posts a webhook. [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) can reclaim space. Add a pre-clone free-space gate to turn "cryptic vmrun failure" into "free disk below threshold."
+
+Runner health monitoring is useful but local-only. [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1) restarts the Windows service with a cooldown. It does not check the Gitea API to prove the runner is online from Gitea's perspective. For daily use, local service status is enough most of the time; a Gitea API check is a phase-2 improvement.
+
+After a build failure, you would know the high-level phase and the top-level exception. You might not know enough about guest state because failed builds do not trigger artifact/log collection. You also would not know exact CPU, memory, disk I/O, or network state at failure time. The JSONL events do not currently include durations, vmrun exit outputs for all calls, free disk at start, template snapshot name validation, or guest OS tool versions.
+
+Missing metrics and alerting:
+
+- Per-phase duration summary emitted at job end.
+- Free disk before and after job.
+- Clone directory size at teardown.
+- VM start lock wait time.
+- Guest IP detection method used: guestinfo or fallback.
+- Count of cleanup failures and leftover directories.
+- Gitea runner online API status.
+
+## 9. Operational Analysis
+
+Backup/recovery procedures are conceptually complete but suffer from path drift. [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) is valuable, but its default points to `F:\CI\Templates\WinBuild`. The current primary template is `F:\CI\Templates\WinBuild2025`. Fix that before relying on backups.
+
+The template refresh process is detailed and realistic. Windows deployment, preparation, validation, shutdown, and snapshotting are all documented. The main problem is that some steps remain interactive, especially snapshot replacement in [template/Prepare-WinBuild2025.ps1](../template/Prepare-WinBuild2025.ps1). For a homelab this is acceptable, but for repeatability add a `-ForceSnapshot` or `-NoPrompt` option.
+
+Scheduled task coverage is good: orphan cleanup, retention, disk alert, and runner health. Gaps: no scheduled template backup, no startup task to clear stale `vm-start.lock`, no task to validate runner online from Gitea, and no periodic smoke build.
+
+Manual steps that remain manual but should be automated or at least scripted:
+
+- Verifying ACLs on `F:\CI\keys\ci_linux`.
+- Verifying Credential Manager entries under the same identity that act_runner uses.
+- Updating and restarting the installed runner config after [runner/config.yaml](../runner/config.yaml) changes.
+- Snapshot version rotation and rollback.
+- Running one post-refresh smoke build and only then flipping `GITEA_CI_SNAPSHOT_NAME`.
+
+Day-2 operations under-documented:
+
+- How to rotate the Linux SSH key.
+- How to recover if `actions/upload-artifact` fails after VM build success.
+- How to inspect `invoke-ci.jsonl` to compute durations.
+- How to confirm the runner service account can read Credential Manager secrets.
+- How to validate shared folder cache poisoning or corruption.
+
+## 10. Test Coverage
+
+The Pester tests cover the right first layer: `_Common.psm1`, clone naming and cleanup on clone failure, VM removal behavior, `-WhatIf`, readiness timeout, and IP parameter validation. They are fast and do not require real VMware infrastructure, which is good for frequent local validation.
+
+What they do not cover is more important for daily trust:
+
+- [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) orchestration state machine.
+- The file lock and lease behavior under concurrency.
+- JSONL event emission.
+- `UseGitClone` credential handling.
+- Linux `ExtraGuestEnv` handling and secret redaction.
+- Composite action YAML validity.
+- Scheduled task registration names and arguments.
+- Backup path correctness.
+- Retention policy stale lock cleanup.
+
+Missing integration tests:
+
+- One Windows real-VM smoke build.
+- One Linux real-VM smoke build.
+- One 2-job or 4-job parallel run with lease verification.
+- One failure build that proves logs/artifacts are collected or intentionally not collected.
+- One workflow-level test of the composite action and upload-artifact path.
+- One host reboot simulation or manual recovery test.
+
+The test plan is not executable as-is. It contains wrong parameter names (`-RepositoryUrl` instead of `-RepoUrl`), PS7-only `ForEach-Object -Parallel`, expected task names that do not match actual task names, and expected JSONL shapes that do not match [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1). Treat it as an audit checklist, not a copy-paste runbook, until corrected.
+
+## 11. Technical Debt
+
+1. Stale path defaults. What: old `WinBuild` paths remain in setup/backup docs/scripts. Why deferred: project evolved from one template to multiple templates. Should it stay deferred: no. Cost to fix: under 1 hour.
+
+2. Secret handling in Linux path. What: secret env values and PAT URLs can be logged or exposed in command strings. Why deferred: functionality was prioritized. Should it stay deferred: no if any secret-bearing builds run. Cost to fix: 2-4 hours.
+
+3. No bounded native process wrapper in production scripts. What: `vmrun`, `ssh`, `scp`, `git`, and upload steps can hang. Why deferred: simple direct calls are easier. Should it stay deferred: no for `vmrun` lifecycle calls. Cost to fix: 2-3 hours for common helper and core calls.
+
+4. Composite action output structure. What: outputs are under inputs. Why deferred: YAML shape likely not tested end to end. Should it stay deferred: no. Cost to fix: under 30 minutes.
+
+5. Incomplete supply-chain pinning. What: many installer hashes are empty; Ubuntu VMDK lacks hash verification. Why deferred: version churn and convenience. Should it stay deferred: acceptable only for trusted homelab, but pin Git/7-Zip/Ubuntu immediately. Cost to fix: 1-2 hours.
+
+6. Documentation drift. What: README, CI flow, test plan, and TODO disagree. Why deferred: rapid implementation. Should it stay deferred: no, because operators rely on docs during failures. Cost to fix: 2-3 hours.
+
+7. Partial failure diagnostics. What: artifacts/logs not collected on build failure. Why deferred: success path came first. Should it stay deferred: no. Cost to fix: 1-2 hours.
+
+8. Limited integration coverage. What: unit tests do not cover orchestration, workflow YAML, or real VM flows. Why deferred: real VMs are slow. Should it stay deferred: partly; add at least smoke tests. Cost to fix: 4-8 hours.
+
+9. Interactive template refresh. What: Prepare scripts prompt for snapshot actions. Why deferred: manual maintenance is acceptable. Should it stay deferred: yes for homelab, but add optional noninteractive switch. Cost to fix: 1-2 hours.
+
+10. Shared cache trust model. What: writable host cache folders can be poisoned by compromised guests. Why deferred: performance. Should it stay deferred: yes for trusted repos; revisit before untrusted code. Cost to fix: varies, 1 hour to document, more for read-only/cache validation.
+
+## 12. Issues by Severity
+
+### CRITICAL
+
+Issue: Composite action outputs are declared under `inputs`, and `artifact-name` is duplicated.
+Location: [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml), middle of metadata block around artifact output declarations.
+Impact: The VM build can succeed but `actions/upload-artifact` may receive empty `steps.invoke-ci.outputs.artifact-path` or `artifact-name`, causing workflow failure or missing artifacts.
+Fix: Add a top-level `outputs:` block sibling to `inputs:` and `runs:`. Move `artifact-path` and output `artifact-name` there. Keep only one `artifact-name` input.
+
+Issue: Linux extra guest environment secrets are logged in clear text.
+Location: [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1), Linux build command assembly and `Write-Host` before `Invoke-SshCommand`.
+Impact: Any secret passed via `extra-guest-env-json` can appear in Gitea job logs and local transcripts.
+Fix: Never log the expanded command. Log only a redacted command summary and pass secrets through a temporary env file copied over SSH with strict permissions, or base64-encoded stdin decoded on the guest and deleted immediately.
+
+Issue: Linux `-UseGitClone` PAT can be embedded in the SSH command string.
+Location: [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1), Linux guest clone branch using `GIT_CLONE_URL`.
+Impact: PAT may leak via PowerShell error text, process arguments, SSH command history/audit, or debug logs.
+Fix: Use an askpass helper or temporary credential file created on the guest with `chmod 600`, run git with `GIT_ASKPASS` or `http.extraHeader` from a file/stdin, then shred/delete it. Do not embed credential-bearing URLs in command strings.
+
+### HIGH
+
+Issue: `vmrun` lifecycle calls in production scripts have no hard timeout.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1), [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1).
+Impact: A hung VMware CLI call can consume an act_runner slot indefinitely and prevent cleanup.
+Fix: Move `Invoke-VmrunBounded` into [scripts/_Common.psm1](../scripts/_Common.psm1), return exit code/output/timeout flag, and use it for `start`, `stop`, `deleteVM`, `list`, `readVariable`, and `getGuestIPAddress` where practical.
+
+Issue: Stale `vm-start.lock` is not automatically cleaned after host crash.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1), [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1).
+Impact: New builds wait 10 minutes and fail until manual lock removal.
+Fix: On startup cleanup and retention, remove `vm-start.lock` if older than a conservative threshold such as 30 minutes and no `powershell`/act_runner job owns it. Also write lock owner metadata into the lock file.
+
+Issue: Host bootstrap creates stale/incomplete directory structure.
+Location: [Setup-Host.ps1](../Setup-Host.ps1), directory creation and runner registration sections.
+Impact: Rebuilding the host from scratch misses Linux template dirs, `State`, `keys`, `Cache\pip`, and current template naming; Linux builds and leases can fail later.
+Fix: Create `Templates\WinBuild2025`, `Templates\WinBuild2022`, `Templates\LinuxBuild2404`, `State\ip-leases`, `keys`, `Cache\pip`, and register labels matching [runner/config.yaml](../runner/config.yaml).
+
+Issue: Template backup default points to the wrong template path.
+Location: [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1), `TemplatePath` default and restore instructions.
+Impact: Operator can believe a backup exists while the active WinBuild2025/Linux template was never backed up.
+Fix: Change defaults to `F:\CI\Templates\WinBuild2025`, add `-TemplateName` or support backing up all template directories, and update docs.
+
+Issue: Failure path does not collect guest diagnostics before destroying the VM.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), `catch`/`finally` flow.
+Impact: Build failures lose guest-side logs, intermediate artifacts, and environment state, making triage harder.
+Fix: In `catch`, if VM is running and IP is known, attempt best-effort diagnostic collection to `F:\CI\Artifacts\<jobId>\diagnostics` before teardown.
+
+Issue: Test plan uses PS7-only syntax and wrong parameter names.
+Location: [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md), parallel job and e2e command examples.
+Impact: Operators following the plan on PS5.1 hit syntax or parameter errors and lose confidence in validation.
+Fix: Replace `ForEach-Object -Parallel` with `Start-Job` or sequential/manual commands, and update `-RepositoryUrl` to `-RepoUrl`.
+
+Issue: Shared cache is not wired into the top-level workflow path.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml).
+Impact: Documented cache feature is not available from normal workflow usage, so restores/downloads remain slower.
+Fix: Add `-UseSharedCache` to `Invoke-CIJob.ps1`, forward it to `Invoke-RemoteBuild.ps1`, and add a composite action input.
+
+### MEDIUM
+
+Issue: `JobId` is not sanitized before path use.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), [scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1).
+Impact: Unusual workflow IDs or malicious input can create invalid paths or confusing clone names.
+Fix: Add `[ValidatePattern('^[A-Za-z0-9_.-]+$')]` or normalize to a safe filename segment.
+
+Issue: Windows readiness only checks TCP 5986, not authenticated WinRM.
+Location: [scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1).
+Impact: Phase 4 can pass even if authentication/remoting fails, shifting errors into build phase.
+Fix: Optionally accept credentials and perform a tiny `Invoke-Command { 'ready' }` after TCP open for Windows jobs, or document the lighter check.
+
+Issue: Documentation claims partial artifacts are collected on build failure.
+Location: [docs/CI-FLOW.md](../docs/CI-FLOW.md), failure scenario table.
+Impact: Operator expectation is wrong during failure triage.
+Fix: Either implement best-effort failure diagnostics or update the documentation to say artifacts are collected only after successful build packaging.
+
+Issue: `Validate-SetupState.ps1` does not mirror LocalAccounts property compatibility.
+Location: [template/Validate-SetupState.ps1](../template/Validate-SetupState.ps1), `PasswordExpires` check.
+Impact: Validation can fail on systems where `PasswordNeverExpires` is the available property.
+Fix: Copy the compatibility logic from [template/Install-CIToolchain-WinBuild2025.ps1](../template/Install-CIToolchain-WinBuild2025.ps1).
+
+Issue: Ubuntu cloud VMDK download is not hash-verified.
+Location: [template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1).
+Impact: Corrupt or tampered base image becomes the parent of all Linux builds.
+Fix: Add SHA256 parameter or checksum file validation from Ubuntu, fail if mismatch.
+
+Issue: Installer hash pinning is mostly placeholders.
+Location: [template/Install-CIToolchain-WinBuild2025.ps1](../template/Install-CIToolchain-WinBuild2025.ps1).
+Impact: Supply-chain protection is documented but often not enforced.
+Fix: Fill hashes for Python, dotnet-install, VS bootstrapper, 7-Zip, PowerShell, NSIS, CMake, Node, and gh for the pinned versions.
+
+Issue: Event Log sources and task names drift from test plan.
+Location: [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1), [scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1), [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md).
+Impact: Tests fail even when scripts work.
+Fix: Standardize names in docs and scripts: `CI-DiskSpaceAlert`, `CI-DiskAlert`, `CI-RunnerHealth`, etc.
+
+Issue: `_Transport.psm1` disables host key persistence/checking.
+Location: [scripts/_Transport.psm1](../scripts/_Transport.psm1).
+Impact: SSH MITM protection is off on VMnet8.
+Fix: For template/provisioning keep permissive mode if needed; for CI jobs, use `StrictHostKeyChecking=accept-new` and a CI-specific known_hosts file under `F:\CI\State`.
+
+### LOW
+
+Issue: Deprecated runner installer remains likely to drift.
+Location: [runner/Install-Runner.ps1](../runner/Install-Runner.ps1).
+Impact: A user may run the deprecated path and miss current labels/config.
+Fix: Replace body with a hard stop pointing to [Setup-Host.ps1](../Setup-Host.ps1), or update it fully.
+
+Issue: Webhook messages include emoji despite current output preference.
+Location: [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1), [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1).
+Impact: Cosmetic inconsistency with project/user style.
+Fix: Use plain prefixes such as `[WARN] CI Disk Alert` and `[ERROR] CI Runner Alert`.
+
+Issue: Architecture diagram has minor indentation/rendering damage.
+Location: [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md), system diagram script box.
+Impact: Documentation polish issue.
+Fix: Reformat the box so all lines align.
+
+Issue: Several docs still say HTTP/Basic where implementation uses HTTPS.
+Location: [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1), [template/Validate-SetupState.ps1](../template/Validate-SetupState.ps1) docblocks.
+Impact: Confusing security documentation.
+Fix: Update docblocks to HTTPS/5986 Basic over TLS.
+
+Issue: Benchmark script JSON shape differs from test-plan expectations.
+Location: [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1), [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md).
+Impact: Copy-paste parsing commands do not work.
+Fix: Either change the JSON schema or update test-plan queries.
+
+### NICE TO HAVE
+
+Issue: No Gitea API runner-online check.
+Location: [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1).
+Impact: Service can be running but disconnected/auth-broken.
+Fix: Add optional `-GiteaUrl` and `-TokenTarget` to query runner status.
+
+Issue: No automatic smoke build after template refresh.
+Location: operational process, no single file.
+Impact: Bad snapshots can be promoted manually.
+Fix: Add a `Test-CITemplateSmoke.ps1` that runs a tiny Windows and Linux build before updating runner config.
+
+Issue: No artifact manifest.
+Location: [scripts/Get-BuildArtifacts.ps1](../scripts/Get-BuildArtifacts.ps1).
+Impact: Harder to compare artifacts across Windows/Linux legs.
+Fix: Write `manifest.json` with file names, sizes, hashes, guest OS, commit, and job ID.
+
+Issue: No VM resource override per workflow.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1), VMX/template flow.
+Impact: Light jobs over-allocate and heavy jobs may be constrained.
+Fix: Add optional post-clone VMX patching for CPU/RAM, default off.
+
+Issue: No structured summary printed at job end.
+Location: [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1).
+Impact: Operators must parse JSONL manually.
+Fix: At job end, compute phase durations from in-memory timestamps and print a compact table.
+
+## 13. Quick Wins
+
+Exactly 10 tasks under 1 hour:
+
+1. Fix [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) by moving `artifact-path` and output `artifact-name` to top-level `outputs`.
+2. Remove secret values from the Linux `Write-Host "Running build"` line in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1).
+3. Add stale `vm-start.lock` cleanup to [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1).
+4. Update [Setup-Host.ps1](../Setup-Host.ps1) to create `State`, `keys`, `Cache\pip`, and current template directories.
+5. Change [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) default from `WinBuild` to `WinBuild2025` or add an `-AllTemplates` mode.
+6. Replace `ForEach-Object -Parallel` in [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) with PS5.1-compatible `Start-Job` examples.
+7. Update `-RepositoryUrl` examples to `-RepoUrl` in [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md).
+8. Add `JobId` validation to [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) and [scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1).
+9. Add a pre-clone free-space check to [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1).
+10. Remove emoji text from webhook payloads in watcher scripts.
+
+## 14. Roadmap
+
+### Phase 1 - Stabilization (complete before trusting for real builds)
+
+- Fix composite action outputs and run one workflow end to end through artifact upload.
+- Redact/fix Linux secret handling for `ExtraGuestEnv` and `-UseGitClone`.
+- Add stale `vm-start.lock` cleanup and startup validation.
+- Fix stale defaults in [Setup-Host.ps1](../Setup-Host.ps1) and [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1).
+- Correct the test plan so every command is PS5.1-compatible and uses current parameter names.
+- Add pre-clone disk free-space gate.
+- Run one real Windows VM smoke build and one real Linux VM smoke build from the composite action.
+
+### Phase 2 - Daily Operations (comfortable daily use)
+
+- Add best-effort diagnostics collection on build failure.
+- Add phase duration summary to job logs.
+- Add Gitea API runner-online check as optional runner health mode.
+- Add ACL validation script for `F:\CI\keys\ci_linux` and Credential Manager access under the runner identity.
+- Add artifact manifest with file hashes.
+- Add `UseSharedCache` wiring through `Invoke-CIJob.ps1` and the composite action.
+- Add a documented template refresh checklist with backup, validation, smoke build, and rollback.
+
+### Phase 3 - Optimization
+
+- Benchmark `guestinfo.ci-ip` versus `getGuestIPAddress` and update [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1).
+- Tune capacity using real build metrics; keep default 4 unless evidence supports 5 or 6.
+- Consider optional per-workflow CPU/RAM overrides for unusually light or heavy jobs.
+- Evaluate shared cache hit rates and add cache cleanup/validation.
+- Consider a warm clone pool only if measured startup overhead dominates short builds.
+
+### Deferred/Optional (genuinely not needed for homelab)
+
+- Multi-host runner federation.
+- Prometheus/Grafana/Loki stack.
+- Full PKI for WinRM certificates.
+- Full antivirus/firewall hardening while only trusted private code is built.
+- Enterprise secret vault integration.
+- Kubernetes, ESXi, or container orchestration.
+
+## 15. Architectural Recommendations
+
+Keep the single-host design. It matches the actual constraints and avoids needless complexity. The main architectural improvement should be making the existing local design more deterministic, not replacing it.
+
+Use three small shared contracts:
+
+- A path contract in [AGENTS.md](../AGENTS.md) and [Setup-Host.ps1](../Setup-Host.ps1): exact directories created and owned by the CI system.
+- A process contract in [scripts/_Common.psm1](../scripts/_Common.psm1): all native lifecycle calls go through a bounded wrapper.
+- A secret contract in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1): no secret ever appears in command text, logs, URL strings, or artifact manifests.
+
+Do not over-abstract WinRM and SSH into a single generic transport. Keep explicit branches, but share small helper functions. The current clarity is valuable when something fails at 2 AM.
+
+Do not pursue deterministic static IP assignment yet. The current lock-plus-lease design is good enough after stale lock cleanup. Static IP injection into clones or VMware DHCP reservations adds more moving parts than it removes for capacity 4.
+
+Treat templates as release artifacts. Back them up, version snapshots, run a smoke build, then promote by updating runner config. This is the homelab equivalent of a golden image promotion flow, and it can stay simple.
+
+Keep security proportional. For trusted private repositories, disabled Defender/Firewall/UAC is acceptable if documented. But fix secret logging immediately because it is cheap and prevents painful accidents.
+
+## 16. Final Assessment
+
+Completeness: 82/100
+
+Code quality: 78/100
+
+Operational readiness: 72/100
+
+Overall: 77/100
+
+Honest verdict: This is a strong homelab CI/CD system with a sensible architecture and a lot of hard-earned VMware/PowerShell knowledge baked in. The core VM lifecycle is close to daily-use quality, and the Windows/Linux dual-template direction is well chosen. I would trust it for supervised real builds now, but I would not yet leave it fully unattended for daily production-like use until the composite action output bug, Linux secret leakage, stale lock recovery, and setup/backup path drift are fixed. Those are not big redesigns. They are the last tightening pass between an impressive lab build and a reliable daily tool.

plans/archived/2026-05-13/gpt55-review-of-opus.md

@@ -0,0 +1,231 @@
+# Cross-Review of Opus 4.7 Analysis
+
+Date: 2026-05-11
+
+Reviewer: GPT-5.5, senior DevOps cross-review role
+
+Scope: cross-review of [plans/opus47-analysis.md](opus47-analysis.md) against [plans/gpt55-analysis.md](gpt55-analysis.md) and verified source files in the Local-CI-CD-System workspace.
+
+## 1. Overall Assessment
+
+The Opus 4.7 analysis is broadly useful and technically literate. It understands the system's intended shape: a Windows 11 host running Gitea Actions through act_runner, creating ephemeral VMware Workstation linked clones, running builds over WinRM or SSH, collecting artifacts, and destroying the clone in a `finally` path. Its strongest quality is that it does not try to replace the architecture with an enterprise platform. It recognizes that the single-host, file-state, PowerShell 5.1 design is the right design for this homelab, then focuses most of its critique on validation, concurrency, and operational hygiene.
+
+The strongest insight in Opus is the focus on concurrency as an unproven capability. The review correctly calls out that [runner/config.yaml](../runner/config.yaml#L14-L17) advertises `capacity: 4`, while the implementation depends on a DHCP-sensitive clone/start/IP critical section in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L303-L409). The fact that the lock is well designed does not prove it works under four simultaneous real jobs. Opus is right that this is the most important claim to validate before treating the system as unattended-daily-use ready.
+
+The biggest weakness is severity calibration. Opus often identifies the right issue but labels it too high or too low depending on whether it matches the review's narrative. It calls the malformed composite-action outputs a LOW issue even though artifact upload can break the live workflow. It labels the SYSTEM-vs-user SSH alias mismatch HIGH while explicitly admitting it was unverified. It calls the template-refresh runbook absent even though several docs contain partial procedures. It also misses a likely live Linux-matrix bug: the composite action does not map `linux-build` to `GITEA_CI_LINUX_TEMPLATE_PATH`, so the Linux matrix leg can still default to the Windows template unless the caller overrides `template-path` and `guest-os`.
+
+## 2. Technical Accuracy Verification
+
+### CRITICAL: `capacity: 4` is unvalidated
+
+Opus claim: "`capacity: 4` is configured in `runner/config.yaml`, but the IP-allocation mutex in `scripts/Invoke-CIJob.ps1` has only ever been exercised with a single job at a time" ([plans/opus47-analysis.md](opus47-analysis.md#L15)). It later says, "Either run the burn-in or set `capacity: 1` until it is done" ([plans/opus47-analysis.md](opus47-analysis.md#L732)).
+
+Verdict: verified correct, with one priority nuance.
+
+The configured capacity is real: [runner/config.yaml](../runner/config.yaml#L14-L17) sets `capacity: 4`. The implementation serializes clone, start, IP discovery, and lease creation using `F:\CI\State\vm-start.lock` and a `FileShare.None` handle in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L303-L325). Inside that lock, the script creates the linked clone, starts it, polls `guestVar ci-ip`, falls back to `getGuestIPAddress`, and writes an IP lease file before releasing the lock in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L326-L415). The design is sane, but the design is not the same as evidence.
+
+The repo itself supports Opus's concern. TODO says `capacity: 4` is configured but the race was not reproduced in the e2e runs because they were one job at a time ([TODO.md](../TODO.md#L226)). It also notes why `getGuestIPAddress` alone is insufficient for collision detection ([TODO.md](../TODO.md#L231)). So the claim is not speculative; it is aligned with the project notes.
+
+Where I would adjust Opus is the label. I agree it is a top priority, but I would call it HIGH unless the README or operational process currently depends on four-way parallelism for correctness. The system can be operated safely at lower capacity; the failure mode is unvalidated throughput and possible race behavior, not guaranteed data loss. In a final master plan, the task should be: run a PS5.1-compatible four-job burn-in, document results, then either keep `capacity: 4` or temporarily set it to 1 or 2. That is more pragmatic than treating the current setting as an immediate emergency.
+
+### HIGH: act_runner SYSTEM-vs-user SSH alias mismatch
+
+Opus claim: "The alias lives in the user's `~/.ssh/config` - which user? `act_runner` runs as `SYSTEM`... So `Setup-Host.ps1` writes the SSH config to the user's `~/.ssh/config`, not `SYSTEM`'s. HIGH" ([plans/opus47-analysis.md](opus47-analysis.md#L414)). Opus then adds: "Treat as HIGH unverified" ([plans/opus47-analysis.md](opus47-analysis.md#L416)).
+
+Verdict: partially correct and over-prioritized as written.
+
+The code confirms the alias is written under the interactive user's profile: [Setup-Host.ps1](../Setup-Host.ps1#L294-L306) uses `$env:USERPROFILE\.ssh\config`. The live workflow does use the alias: [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml#L31-L35) sets `repo-url: 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git'`. If act_runner runs as LocalSystem, OpenSSH will not read the interactive user's SSH config or keys. That would break host-side clone mode.
+
+The assumption that act_runner definitely runs as SYSTEM is weaker. [scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1#L38-L43) says scheduled maintenance tasks run as SYSTEM; it does not install act_runner. The act_runner NSSM installation in [Setup-Host.ps1](../Setup-Host.ps1#L264-L273) does not set an explicit service account. On Windows, a service installed without an explicit account commonly runs as LocalSystem, so Opus's concern is plausible. But Opus should not have derived act_runner's identity from the scheduled-task script. The correct verification is `Get-CimInstance Win32_Service -Filter "Name='act_runner'" | Select StartName` on the host, plus a test clone under that identity.
+
+I would keep this in the master plan, but classify it as HIGH only until the service identity is confirmed. The fix should be concrete and low ceremony: either configure SSH alias and key under `C:\Windows\System32\config\systemprofile\.ssh`, run the service under the intended user account, or stop relying on the alias and use an explicit SSH URL plus `GIT_SSH_COMMAND`/known key path.
+
+### HIGH: `Validate-DeployState.ps1` missing `ci-report-ip.service` check
+
+Opus claim: "there is no validation in `Validate-DeployState.ps1` that the guest service is enabled in a fresh template" and missing it means Linux jobs fall back to unreliable `getGuestIPAddress` ([plans/opus47-analysis.md](opus47-analysis.md#L135)).
+
+Verdict: partially correct, with important nuance.
+
+The core technical claim is right for `Validate-DeployState.ps1`. That script is Windows-oriented: it connects over WinRM HTTPS/5986 and checks Firewall, Defender, WinRM, UAC, Explorer, Server Manager, AutoAdminLogon, and Windows Update state ([template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1#L42-L151)). There is no Linux branch and no `systemctl is-enabled ci-report-ip.service` check. If someone treats `Validate-DeployState.ps1` as the generic template validation entry point, it will not catch a missing Linux IP-reporting service.
+
+But Opus overstates the absence of validation across the whole repo. The Linux installer creates the service in [template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh#L203-L220) and asserts it is enabled in [template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh#L221). The Linux prepare script also validates both the enabled service and executable script in [template/Prepare-LinuxBuild2404.ps1](../template/Prepare-LinuxBuild2404.ps1#L361-L362). So the service is validated in the Linux provisioning path, just not in the standalone deploy validator that Opus focused on.
+
+The recommendation is still good: add a Linux-aware validation script or extend validation naming so operators cannot confuse a Windows deploy validator with a cross-template final gate. I would call this MEDIUM-HIGH rather than HIGH. It is a real recovery and refresh-risk issue, but not an entirely missing guardrail.
+
+### HIGH: no codified template-refresh runbook
+
+Opus claim: "No documented template-refresh runbook" ([plans/opus47-analysis.md](opus47-analysis.md#L377)) and "KMS re-activation, snapshot rebuild, validation steps live in operator memory" ([plans/opus47-analysis.md](opus47-analysis.md#L516)).
+
+Verdict: partially correct and exaggerated.
+
+There is no single authoritative runbook named "Template Refresh" that covers Windows and Linux with exact commands, preflight checks, backup, validation, smoke build, promotion, and rollback. In that narrow sense, Opus is correct. A final master plan should include one.
+
+However, the process is not only in operator memory. [docs/WINDOWS-TEMPLATE-SETUP.md](../docs/WINDOWS-TEMPLATE-SETUP.md#L280-L289) contains a semestral refresh procedure: boot template, reactivate with `slmgr /ato`, rerun Prepare, shut down, take a versioned snapshot, update `GITEA_CI_SNAPSHOT_NAME`, and keep recent snapshots. [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md#L196-L219) explains BaseClean integrity, backup-before-change, clone checks, and snapshot versioning. [docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md#L347-L359) also lists toolchain update steps. [docs/RUNBOOK.md](../docs/RUNBOOK.md#L88-L92) covers missing-snapshot recovery.
+
+The better criticism is fragmentation and drift, not absence. Some docs still refer to old `WinBuild` backup paths ([docs/BEST-PRACTICES.md](../docs/BEST-PRACTICES.md#L207-L211)), while current host docs and runner config use `WinBuild2025` and `LinuxBuild2404` ([docs/HOST-SETUP.md](../docs/HOST-SETUP.md#L160-L163), [runner/config.yaml](../runner/config.yaml#L20-L30)). The master plan should consolidate the procedure into [docs/RUNBOOK.md](../docs/RUNBOOK.md) or a dedicated template-refresh runbook, not invent an enterprise image-management workflow.
+
+### MEDIUM: Linux Mode 2 PAT injection
+
+Opus claim: Linux Mode 2 builds an authenticated URL and stores it in `GIT_CLONE_URL`; Windows uses `http.extraHeader`, which is safer ([plans/opus47-analysis.md](opus47-analysis.md#L123)).
+
+Verdict: verified correct, and slightly understated.
+
+The Linux path rewrites the clone URL with `[uri]::EscapeDataString($pat.UserName)` and the PAT, then exports it as `GIT_CLONE_URL` in the SSH command string ([scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1#L212-L230)). It then runs `git clone "$GIT_CLONE_URL"` and unsets the variable in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1#L226-L230). That keeps the non-authenticated URL out of the normal log line, but the credential-bearing URL is still part of the command sent through SSH and visible to process/environment inspection on the guest while the command runs.
+
+The Windows path uses `git -c credential.helper= -c http.extraHeader=Authorization: Basic <b64>` inside the WinRM session ([scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1#L323-L334)). That is not perfect because the header can still be visible in process arguments inside the guest, but it avoids embedding credentials in a URL and avoids Git storing the credential URL.
+
+I would keep this as MEDIUM if all builds are trusted and the PAT is scoped narrowly. I would raise it to HIGH if private repositories, signing material, or broader Gitea scopes are used. My own analysis caught an adjacent issue that Opus missed: Linux `ExtraGuestEnv` values are directly included in `$buildCmd`, and the script logs `Write-Host "[Invoke-RemoteBuild] Running build: $buildCmd"` in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1#L239-L248). That is a direct cleartext secret-log path, stronger than the PAT URL concern.
+
+### MEDIUM: `Measure-CIBenchmark.ps1` uses `getGuestIPAddress`
+
+Opus claim: `Measure-CIBenchmark.ps1` uses `getGuestIPAddress` directly, contradicting the lesson encoded in readiness handling ([plans/opus47-analysis.md](opus47-analysis.md#L122)).
+
+Verdict: verified correct.
+
+The benchmark describes its `ip` phase as `vmrun getGuestIPAddress` in [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1#L16-L23). The implementation polls `Invoke-Vmrun -Operation getGuestIPAddress` until a dotted IPv4 appears in [scripts/Measure-CIBenchmark.ps1](../scripts/Measure-CIBenchmark.ps1#L129-L146). Production IP detection primarily reads `guestVar 'ci-ip'` in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L348-L377) and only then falls back to `getGuestIPAddress` in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L379-L389).
+
+This is exactly the kind of benchmark drift that creates false confidence. It is not a production outage by itself, but it means benchmark data cannot be treated as representative of Linux production behavior. MEDIUM is the right severity. The pragmatic fix is to extract IP acquisition into a shared helper and call the same helper from both production and benchmark scripts.
+
+### MEDIUM: hardcoded `N:\` paths in composite action
+
+Opus claim: the composite action hardcodes `$ciScriptsDir = 'N:\Code\Workspace\Local-CI-CD-System\scripts'`, and this couples the action to one host path ([plans/opus47-analysis.md](opus47-analysis.md#L404)).
+
+Verdict: verified correct, and the same pattern appears elsewhere by design.
+
+The composite action hardcodes the script directory in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml#L148). That makes the action non-portable even though the action is presented as reusable. Opus's suggested `${{ github.action_path }}` approach is directionally right, but the exact relative path needs care because this action lives under [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml), not necessarily `.gitea/actions` in the consuming repository.
+
+There is a second hardcoded `N:\` default in scheduled task registration: [scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1#L39-L43). That one is less concerning because scheduled tasks are host-local maintenance. The composite action is more important because it affects workflow execution and reuse.
+
+MEDIUM is fair for the action. For the scheduled tasks, LOW is enough in this fixed homelab unless the host path is expected to change.
+
+### Composite action outputs
+
+Opus claim: the action emits `artifact-path` and `artifact-name` as step outputs ([plans/opus47-analysis.md](opus47-analysis.md#L399)), but its metadata outputs appear inside `inputs` and should be restructured ([plans/opus47-analysis.md](opus47-analysis.md#L405)).
+
+Verdict: Opus identified the bug but under-rated it.
+
+The action metadata places `artifact-path` and a second `artifact-name` under the `inputs:` map in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml#L123-L141). There is no top-level `outputs:` block before `runs:`. The step does write outputs to `$env:GITHUB_OUTPUT` in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml#L224-L225), and upload steps consume those outputs in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml#L229-L244). Depending on Gitea's composite-action implementation, step outputs may still work inside the same composite, but callers will not have a clean top-level action output contract, and metadata validation is wrong.
+
+My analysis classified this as CRITICAL because artifact upload is core workflow behavior. On reflection, HIGH is a better final-plan severity: it can break artifact publication even when VM build succeeds, but it is a small YAML fix and not a VM lifecycle failure. Opus's LOW is too soft.
+
+## 3. Omissions
+
+Opus missed the direct Linux `ExtraGuestEnv` secret logging path. It discussed the action putting secret JSON into a runner environment variable ([plans/opus47-analysis.md](opus47-analysis.md#L279)), but the stronger issue is in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1#L239-L248): the Linux path builds `export KEY='value'; ...` and logs the entire command. If `extra-guest-env-json` contains `SIGN_PASS`, the secret can be printed to local transcripts and Gitea job logs. This should outrank the action-env note.
+
+Opus missed setup and backup path drift as an operational risk. [Setup-Host.ps1](../Setup-Host.ps1#L104-L113) still creates `F:\CI\Templates\WinBuild` rather than the current `WinBuild2025`, `WinBuild2022`, and `LinuxBuild2404` directories described in [AGENTS.md](../AGENTS.md#L42-L51) and [runner/config.yaml](../runner/config.yaml#L20-L30). Opus mentions the password documentation mismatch and deprecated runner installer, but not that host rebuild from scratch can miss current directories. My analysis flagged this as HIGH because it affects disaster recovery and new-host setup.
+
+Opus missed stale `vm-start.lock` cleanup. The lock handle is released correctly during normal script flow, as Opus verified. But after a host crash, a stale lock file can still cause confusing 10-minute waits and failure until manual cleanup. [docs/RUNBOOK.md](../docs/RUNBOOK.md#L72-L105) documents manual removal, but neither [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) nor [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1) removes it automatically. This is a very homelab-practical fix.
+
+Opus missed broken or stale test-plan commands that matter because this review is about trust. [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md#L56-L58) uses PS7-only `ForEach-Object -Parallel` and the wrong `-RepositoryUrl` parameter, while [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L80) defines `RepoUrl`. That makes the validation plan non-copy-pasteable on the mandated PS5.1 host.
+
+Both analyses missed a likely Linux matrix wiring bug. [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml#L20-L35) runs a matrix over `windows` and `linux`, but it does not pass `guest-os`, `template-path`, or `snapshot-name`. The action defaults `guest-os` to `Auto` in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml#L52-L57) and leaves `template-path` empty so `Invoke-CIJob.ps1` uses `GITEA_CI_TEMPLATE_PATH` in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1#L114). The runner config has a separate `GITEA_CI_LINUX_TEMPLATE_PATH` in [runner/config.yaml](../runner/config.yaml#L27-L30), but the action does not consume it. Unless act_runner has per-label environment behavior not shown here, the Linux leg can clone the Windows template. This is more urgent than several Opus HIGH items because it affects the advertised Windows/Linux matrix directly.
+
+Both analyses also under-emphasized that Mode 1 host-side cloning with `ssh://gitea-ci/...` depends on host SSH identity, while Mode 2 in-guest clone for Linux should probably use HTTPS reachable from the guest plus PAT or deploy key. The test helper [scripts/Test-E2E-Section3.3.ps1](../scripts/Test-E2E-Section3.3.ps1#L113-L115) distinguishes guest HTTPS and host SSH URLs, but the composite workflow presents one `repo-url` for both matrix legs.
+
+## 4. Over-Engineered or Excessive Suggestions
+
+Opus's static IP pool recommendation is technically coherent but premature. It proposes `ip-pool.json`, static assignment, Windows `netsh` or Linux cloud-init injection, and per-slot locking ([plans/opus47-analysis.md](opus47-analysis.md#L638-L654)). For capacity 4 on a single VMware Workstation host, this adds a lot of moving parts. The current lock-plus-lease model is easy to understand and already avoids simultaneous DHCP start races. First run the burn-in. If it fails because DHCP collisions actually occur, then static IPs are justified. Until then, static IP assignment is a phase-3 redesign, not a stabilization task.
+
+The generic transport interface recommendation also smells like abstraction ahead of need. Opus suggests `Invoke-GuestCommand`, `Copy-GuestItem`, and `Wait-GuestTransportReady` wrappers behind SSH and WinRM ([plans/opus47-analysis.md](opus47-analysis.md#L656-L667)). That is reasonable in a multi-OS product, but this repo has two transports with very different operational failure modes. Explicit branches in [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) are verbose, but they are debuggable. A small shared helper for quoting, secret redaction, and bounded native execution would pay off more than a unified transport abstraction.
+
+Moving JSONL logs into SQLite is useful, but not a prerequisite for reliability. Opus suggests importing job history into `F:\CI\State\history.db` ([plans/opus47-analysis.md](opus47-analysis.md#L674-L677)). A 40-line `Get-CIJobSummary.ps1` over existing JSONL files is enough for a homelab. SQLite can wait until there is enough history and query pain to justify a schema.
+
+The suggestion to switch the project from PS5.1 to PowerShell 7 conflicts with the explicit project constraint. Opus admits this is outside the documented constraints ([plans/opus47-analysis.md](opus47-analysis.md#L688-L700)). For this system, PS5.1 is not accidental. [AGENTS.md](../AGENTS.md#L21-L36) lists PS7-only constructs to avoid, and scripts consistently carry `#Requires -Version 5.1`. A PS7 migration may be pleasant for the author, but it is not a cross-review recommendation that belongs in the master stabilization plan.
+
+The idea to validate templates automatically at the start of each CI job is also heavy. Opus proposes calling validation scripts from the orchestrator with a cached stamp ([plans/opus47-analysis.md](opus47-analysis.md#L704-L716)). That risks turning every build into a template-health workflow and adds failure modes around validation connectivity. A better homelab pattern is: validate on template refresh, then run a smoke build, then promote the snapshot. Do not make every normal build re-prove the template unless a recent incident shows drift.
+
+## 5. Architectural Conflicts
+
+The PowerShell 7 recommendation is the clearest conflict. This project is intentionally PS5.1 because the host is Windows 11 and the scripts are expected to run with built-in Windows PowerShell. Suggesting PS7-only features like `ForEach-Object -Parallel`, `??`, or `Test-Json` undermines the constraint documented in [AGENTS.md](../AGENTS.md#L21-L36) and repeated in the user's request. The right improvement is PS5.1-compatible `Start-Job` for concurrency tests and explicit JSON parsing/validation.
+
+Static IP injection conflicts with the current VMware linked-clone simplicity. The system currently relies on the template snapshot plus runtime DHCP, with guestinfo reporting as a bridge. Static assignment would require modifying guest network state per clone or injecting boot-time config. That is possible, but it creates OS-specific customization paths and more persistent state. It is not invalid, but it should be gated by failed burn-in evidence.
+
+A centralized `F:\CI\State\config.json` for all paths is a mixed recommendation. It could reduce drift, but it also creates another source of truth alongside runner config, script defaults, and docs. The homelab already has [AGENTS.md](../AGENTS.md#L42-L60) as the environment contract and [runner/config.yaml](../runner/config.yaml#L18-L30) as act_runner's environment injection. The master plan should first align existing defaults, not introduce a fourth config surface.
+
+## 6. Incorrect Assumptions
+
+Opus assumes `ci-report-ip.service` is "referenced but not in any file I read" ([plans/opus47-analysis.md](opus47-analysis.md#L133)). That is factually incomplete. The service is created in [template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh#L203-L220), enabled and asserted in [template/Install-CIToolchain-Linux2404.sh](../template/Install-CIToolchain-Linux2404.sh#L221), and checked by Prepare in [template/Prepare-LinuxBuild2404.ps1](../template/Prepare-LinuxBuild2404.ps1#L361-L362). The critique should be about missing generic validation, not missing implementation.
+
+Opus assumes scheduled-task SYSTEM identity proves act_runner SYSTEM identity. [scripts/Register-CIScheduledTasks.ps1](../scripts/Register-CIScheduledTasks.ps1#L38-L43) clearly applies to maintenance tasks, not the NSSM service. The NSSM install in [Setup-Host.ps1](../Setup-Host.ps1#L264-L273) likely defaults to LocalSystem, but that requires service inspection to prove.
+
+Opus states that the action emits `artifact-path` and `artifact-name` as step outputs as a positive finding ([plans/opus47-analysis.md](opus47-analysis.md#L399)), then separately notes the metadata is malformed. The implementation writes to `$env:GITHUB_OUTPUT`, yes, but the action-level output contract is malformed in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml#L132-L141). Treating the composite action as "complete" is too generous.
+
+Opus says the Linux `GIT_CLONE_URL` method keeps the PAT "never in args" in its surrounding discussion. The credential-bearing URL is still embedded in the remote command string passed to SSH. It may not be in Git's argv as the literal URL if shell expansion happens first, but it is absolutely in the shell environment and in command text sent by the host. That distinction matters.
+
+## 7. Priority Validation
+
+I agree with Opus that concurrency validation belongs near the top. I would set it as HIGH, or CRITICAL only if the project continues to claim production-ready status while advertising `capacity: 4` as proven. The correct action is a burn-in, not a redesign.
+
+I disagree with HIGH for the SSH alias mismatch until service identity is confirmed. It is a plausible live bug and should be verified immediately, but the analysis itself says unverified. Use HIGH-PENDING-VERIFICATION or MEDIUM until `StartName` is known.
+
+I would downgrade the `Validate-DeployState.ps1` Linux service check from HIGH to MEDIUM-HIGH because the Linux prepare/install path already validates the service. The missing piece is a consolidated final gate and clearer naming.
+
+I would upgrade the composite action output bug from LOW to HIGH. It affects artifact publication, which is central to a CI pipeline. The fix is small, but severity is about impact, not effort.
+
+I would upgrade Linux `ExtraGuestEnv` secret logging to HIGH when secrets are used. Opus did not list this specific issue. A secret printed to logs is more concrete than a PAT visible to same-user process inspection.
+
+I would add a new HIGH item: fix Linux matrix template selection. The current action/workflow combination appears not to pass the Linux template path or Linux snapshot name, despite [runner/config.yaml](../runner/config.yaml#L27-L30) defining them. This can make the live matrix fail before reaching the deeper Linux transport concerns.
+
+## 8. Pragmatic Improvements
+
+Replace Opus's "static IP pool" recommendation with "run burn-in first, then decide." The immediate task should be a PS5.1 `Start-Job` harness that launches four real jobs with unique job IDs, records lock wait time, verifies distinct IP leases, and checks all VMs are destroyed. If it passes three times, keep `capacity: 4`. If it fails, then choose between capacity reduction and static IP design.
+
+Replace "template validation at every job start" with "template promotion gate." A homelab-appropriate refresh flow is: stop runner, back up template, update template, run Validate-Setup or Linux validation, shut down cleanly, take a versioned snapshot, run one Windows and one Linux smoke build, update runner config, keep prior snapshot for one week.
+
+Replace the generic transport abstraction with three focused helpers: `Invoke-NativeBounded` for `vmrun`/`ssh`/`scp`, `ConvertTo-SafeShellSingleQuotedString` for Linux command construction, and `Write-CIRedactedCommand` for logs. These address real failure modes without turning the scripts into a framework.
+
+For the SSH alias issue, do not build a broad identity-management system. Add a host check that prints the act_runner service account, tests `ssh -T gitea-ci` as that account if possible, and documents exactly where the SSH config/key must live. If the service runs as LocalSystem, either install the alias under systemprofile or run act_runner under a dedicated `ci_runner` Windows account.
+
+For the action hardcoded path, use a single environment variable such as `GITEA_CI_SCRIPT_ROOT` in [runner/config.yaml](../runner/config.yaml), or compute from `github.action_path` only if the action repository layout makes that reliable. Since the scripts are not inside a downstream repository checkout in every usage model, a runner env var may be simpler and more honest for this homelab.
+
+## 9. Coherence with Homelab Scope
+
+Opus mostly stays within homelab scope in its findings. It does not demand Kubernetes, centralized secret vaults, Prometheus, or ESXi. Its main recommendations are burn-in, smoke testing, small validation checks, cleanup of dead code, and better docs. That is the right posture.
+
+Where it drifts is in the "What Would I Change" section. Static IP pools, generic transport interfaces, SQLite history, JSON schema for action inputs, template validation cached in every job, and a PS7 migration are not crazy ideas, but they are not the next moves for a single-operator VMware Workstation system. They should be explicitly marked as optional future design notes, not allowed to compete with immediate fixes like action outputs, Linux secret logging, template path selection, and service-account verification.
+
+The review's tone is sometimes too commercial-production oriented. It repeatedly contrasts homelab with paid environments, which is fair context, but the final master plan should not optimize for commercial standards. It should optimize for repeatable local recovery, understandable scripts, and low operational surprise.
+
+## 10. Consolidated Recommendation List
+
+Carry forward these Opus recommendations largely unchanged:
+
+1. Run and document a real four-way concurrency burn-in before trusting `capacity: 4`.
+2. Add an on-demand end-to-end smoke test, preferably a manual Gitea workflow that runs one minimal Windows and one minimal Linux job.
+3. Fix Linux Mode 2 PAT handling so credentials are not embedded in clone URLs.
+4. Update `Measure-CIBenchmark.ps1` to use the same IP acquisition path as production.
+5. Add or consolidate validation for `ci-report-ip.service` in the Linux template final gate.
+6. Remove or hard-stop the deprecated runner installer so operators do not follow stale setup paths.
+7. Align `Setup-Host.ps1` password documentation with actual behavior.
+8. Fix hardcoded action script-root handling.
+
+Carry forward these Opus recommendations, but modify them:
+
+1. Treat the SYSTEM-vs-user SSH alias as "verify immediately" rather than proven HIGH. After verifying service identity, fix the SSH config/key location or service account.
+2. Treat template-refresh docs as fragmented and drifted, not absent. Consolidate them into one runbook with backup, validation, smoke test, promotion, and rollback.
+3. Treat static IP allocation as a fallback if burn-in fails, not a default redesign.
+4. Keep transport branches explicit. Add small helpers for bounded native calls, quoting, and redaction instead of a full transport abstraction.
+5. Add job summaries from JSONL before considering SQLite.
+6. Keep PS5.1. Do not migrate to PS7 as part of stabilization.
+
+Drop or defer these Opus recommendations from the master plan:
+
+1. PS7 migration.
+2. Per-job automatic template validation.
+3. SQLite history database.
+4. Full generic transport facade.
+5. Static IP pool unless the measured DHCP/guestinfo design fails.
+6. Schema-heavy composite action validation beyond basic input checks.
+
+Add these recommendations that Opus missed:
+
+1. Fix the composite action output metadata as HIGH priority: move `artifact-path` and action-level `artifact-name` under a top-level `outputs:` block and remove the duplicate input/output confusion.
+2. Fix Linux `ExtraGuestEnv` logging immediately: never print expanded commands containing secret exports.
+3. Fix Linux matrix template selection: when `runs-on: linux-build`, pass `guest-os: Linux`, use `GITEA_CI_LINUX_TEMPLATE_PATH`, and use `BaseClean-Linux` unless the Linux template has been aligned to `BaseClean`.
+4. Fix [Setup-Host.ps1](../Setup-Host.ps1#L104-L113) directory creation to match current [AGENTS.md](../AGENTS.md#L42-L60) and [runner/config.yaml](../runner/config.yaml#L20-L30).
+5. Add stale `vm-start.lock` cleanup to startup/retention maintenance, with conservative age checks and clear logging.
+6. Correct [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md#L56-L58) to use PS5.1-compatible concurrency and the actual `-RepoUrl` parameter.
+7. Add `JobId` and `ExtraGuestEnv` key validation in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1).
+8. Wire `UseSharedCache` through the top-level workflow path only after the correctness fixes above.
+
+Final verdict: Opus is a strong review, and most of its technical instincts are right. It is best used as a source of findings, not as-is as the master plan. The final plan should keep Opus's concurrency and validation focus, correct its overstatements, raise the issues it underplayed, and stay firmly homelab-pragmatic: fix the live workflow contract, prove capacity, prevent secret leaks, align setup paths, and consolidate refresh operations before adding new architecture.

plans/archived/2026-05-13/opus47-analysis.md

@@ -0,0 +1,758 @@
+# Local-CI-CD-System — Comprehensive Technical Review
+
+Reviewer role: lead architect / senior DevOps engineer.
+Scope: complete repository audit at HEAD.
+Style: direct, opinionated, no hedging. Severities: CRITICAL / HIGH / MEDIUM / LOW / NICE-TO-HAVE.
+
+---
+
+## 1. Executive Summary
+
+This is a well-engineered homelab CI/CD system that solves a real, narrow problem: give a single workstation the ability to run isolated, reproducible builds against ephemeral Windows and Linux VMs, triggered from a self-hosted Gitea, with artifact collection and lifecycle management. The scope is appropriate, the implementation is largely competent, and the audit trail in `TODO.md` shows the author has been doing serious, deliberate engineering rather than vibe-coding.
+
+That said, the system has the typical pathologies of a one-person homelab CI: the "tests" do not test what matters, the documented "production-ready" status rests on three manual e2e runs (`e2e-008`, `e2e-009`, `§3.3 e2e`), and several large operational gaps remain hidden behind the `Home Lab — Deferred` label in `TODO.md`. Those gaps are not catastrophic, but they would be unacceptable in a paid environment.
+
+The single biggest architectural concern is not security — the network is air-gapped enough for a homelab — but **operational resilience under concurrency**. `capacity: 4` is configured in `runner/config.yaml`, but the IP-allocation mutex in `scripts/Invoke-CIJob.ps1` has only ever been exercised with a single job at a time. Whether the lock semantics, the DHCP behaviour on `VMnet8`, and the `vmrun start` race actually behave correctly when four real builds collide is an open question.
+
+The second largest concern is the **complete absence of automated regression testing for the orchestration itself**. The four Pester files use a fake `vmrun.cmd` and exercise argument parsing only. There is no CI for the CI.
+
+Top three priorities, in order:
+
+1. **CRITICAL — Validate or downgrade `capacity: 4`**. Either run a real 4-way concurrency burn-in or set `capacity: 1` until validated. Today the production claim is a guess.
+2. **HIGH — Add a single end-to-end smoke test runnable on demand**. Not a unit test. A scripted `Measure-CIBenchmark.ps1`-style invocation that exercises Phase 1–6 against a real VM and exits non-zero on failure. Wire it into a manual Gitea workflow.
+3. **HIGH — Eliminate the `runner/Install-Runner.ps1` deprecated script and the `Setup-Host.ps1` default-password ghost**. Dead code and lying defaults erode confidence in everything else.
+
+The rest of this document expands on these and 30+ smaller findings.
+
+---
+
+## 2. Project Completeness
+
+The system declares itself "production-ready" in `README.md` line 1. Measured against what a reasonable definition of that phrase requires, here is the state:
+
+| Capability                                     | Status       | Evidence                                                                                 |
+| ---------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------- |
+| Ephemeral VM lifecycle (clone, start, destroy) | Complete     | `scripts/New-BuildVM.ps1`, `Remove-BuildVM.ps1`, `Invoke-CIJob.ps1`                      |
+| Windows guest (WinRM HTTPS)                    | Complete     | `Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1` Windows branch                        |
+| Linux guest (SSH)                              | Complete     | `_Transport.psm1`, Linux branches in build/artifact scripts                              |
+| Auto-detect guest OS from VMX                  | Complete     | `Invoke-CIJob.ps1` `guestOS` regex                                                       |
+| Host-clone mode + zip transfer (Mode 1)        | Complete     | Default path in `Invoke-RemoteBuild.ps1`                                                 |
+| In-VM `git clone` (Mode 2)                     | Complete     | `-UseGitClone`, PAT via `http.extraHeader`                                               |
+| Credential storage (CredentialManager)         | Complete     | `BuildVMGuest`, `GiteaPAT`                                                               |
+| Reusable composite action                      | Complete     | `gitea/actions/local-ci-build/action.yml`                                                |
+| Build matrix Windows + Linux                   | Complete     | `gitea/workflows/build-nsInnoUnp.yml`                                                    |
+| Shared NuGet/pip cache via HGFS                | Complete     | `Set-TemplateSharedFolders.ps1`, `-UseSharedCache`                                       |
+| Structured JSONL logs                          | Complete     | `Write-JobEvent` in `Invoke-CIJob.ps1`                                                   |
+| Scheduled maintenance                          | Complete     | `Register-CIScheduledTasks.ps1` (4 tasks)                                                |
+| Disk-space + runner-health watchdogs           | Complete     | `Watch-DiskSpace.ps1`, `Watch-RunnerHealth.ps1`                                          |
+| Retention policy with aggressive fallback      | Complete     | `Invoke-RetentionPolicy.ps1`                                                             |
+| Orphan cleanup                                 | Complete     | `Cleanup-OrphanedBuildVMs.ps1`                                                           |
+| Template backup before refresh                 | Complete     | `Backup-CITemplate.ps1`                                                                  |
+| Benchmark harness                              | Complete     | `Measure-CIBenchmark.ps1`                                                                |
+| Secret injection into guest (`ExtraGuestEnv`)  | Complete     | Forwarded host → action → `Invoke-CIJob` → `Invoke-RemoteBuild`                          |
+| Pester unit tests                              | Stub-level   | `tests/*.Tests.ps1`, all use fake `vmrun.cmd`                                            |
+| Automated integration test                     | **Missing**  | No automated harness exercises real VMs                                                  |
+| Concurrency burn-in                            | **Missing**  | `TODO.md §2.1` admits "race non riprodotta in e2e-008/009"                               |
+| Multi-host federation                          | Not in scope | `TODO.md §6.3` deferred                                                                  |
+| Template snapshot refresh procedure            | Partial      | `Backup-CITemplate.ps1` exists; refresh procedure not codified                           |
+| Setup-Host post-conditions documented          | Partial      | `Setup-Host.ps1` does the work but `Validate-DeployState.ps1` covers templates, not host |
+
+Overall completion against the original scope: **~85%**. The remaining 15% is concentrated in test coverage and concurrency validation — exactly the parts that justify the "production-ready" label.
+
+---
+
+## 3. Architecture Deep Dive
+
+### 3.1 Component Map
+
+```
++---------------------+      +------------------------+
+|  Gitea (10.10.20.11)|<-----|  act_runner (NSSM svc) |
++---------------------+      |  F:\CI\act_runner       |
+                              |  capacity: 4            |
+                              +-----------+-------------+
+                                          |
+                                          v
+                              +-----------+-------------+
+                              |  gitea/actions/         |
+                              |   local-ci-build        |
+                              |   action.yml            |
+                              +-----------+-------------+
+                                          |
+                                          v
+                              +-----------+-------------+
+                              |  Invoke-CIJob.ps1       |
+                              |  (orchestrator)         |
+                              +-----+---+---+-----+-----+
+                                    |   |   |     |
+                  +-----------------+   |   |     +-----------------+
+                  |                     |   |                       |
+                  v                     v   v                       v
+        +---------+--------+   +--------+--+--------+   +-----------+-----+
+        | New-BuildVM.ps1  |   | Wait-VMReady.ps1   |   | Invoke-Remote   |
+        | (vmrun clone)    |   | (list, ping/22,    |   |  Build.ps1      |
+        |                  |   |  5986/ssh echo)    |   | (WinRM or SSH)  |
+        +---------+--------+   +--------------------+   +-----------+-----+
+                  |                                                 |
+                  |                                                 v
+                  |                                    +------------+--------+
+                  |                                    | Get-BuildArtifacts  |
+                  |                                    | (Copy-Item -From    |
+                  |                                    |  Session or scp)    |
+                  |                                    +------------+--------+
+                  v                                                 |
+        +---------+--------+                                        |
+        | Remove-BuildVM   | <--------- always runs in finally -----+
+        | (stop, deleteVM) |
+        +------------------+
+```
+
+This is a clean pipeline. The orchestrator is a single script that owns the try/finally and the state file (`leaseFile`). Sub-scripts are pure: they receive parameters and return either a value or throw. That is the right shape.
+
+### 3.2 Layering — What Is Right
+
+- **`_Common.psm1` and `_Transport.psm1`** correctly separate two distinct concerns: WinRM/vmrun helpers (host-side, used by Windows path) and SSH helpers (host→guest, used by Linux path). `Invoke-Vmrun` returning `[pscustomobject]@{ExitCode, Output}` is the right abstraction — most callers want both, and `$LASTEXITCODE` is fragile across pipelines.
+- **The composite action `local-ci-build`** is the right boundary. The calling repository (`nsis-plugin-nsinnounp`, per `build-nsInnoUnp.yml`) declares intent (`build-command`, `artifact-source`) and the action handles transport. Adding a second consumer would require zero changes here.
+- **The file-based IP mutex + lease** is conceptually correct. Serialize the racey phase (clone + start + IP acquisition), then release. Build phases run parallel. That is the right granularity.
+- **The Mode 1 / Mode 2 source-transfer split**. Mode 1 (host clone → tar/zip → ship) is the safe default. Mode 2 (`-UseGitClone`, PAT via `http.extraHeader`) is the right optimization for large repos with submodules — and the `http.extraHeader` Basic-auth approach keeps the PAT out of the URL, argv, and `git config`.
+- **Phase 1 readiness check uses `vmrun list`, not `getGuestIPAddress`**. This is correct and the rationale in the comments of `scripts/Wait-VMReady.ps1` is exactly right. The author has clearly been burned by this in the past.
+
+### 3.3 Layering — What Is Wrong or Suspect
+
+- **`Measure-CIBenchmark.ps1` uses `getGuestIPAddress` directly** (line ~135) for the IP-acquire phase, contradicting the lesson encoded in `Wait-VMReady.ps1`. The benchmark therefore measures something subtly different than what production does. It also has no fallback. **MEDIUM**.
+- **`Invoke-RemoteBuild.ps1` has two PAT-injection paths**: a Linux branch that builds an authenticated URL with `[uri]::EscapeDataString` and a Windows branch that uses `http.extraHeader`. The Linux version writes the PAT into the URL of an `export GIT_CLONE_URL=...; git clone "$GIT_CLONE_URL" ...; unset` sequence. That URL is visible in the SSH wire — encrypted, but the PAT is also visible in `/proc/<pid>/environ` for whoever can read it (the same `ci_build` user). The Windows path is strictly safer. **MEDIUM**. Make Linux use `http.extraHeader` too.
+- **The IP-allocation lock is held during `New-BuildVM.ps1` (clone) AND `vmrun start` AND IP detection** (`Invoke-CIJob.ps1` lines ~340–430). A linked clone takes a few seconds; `vmrun start` headless + IP-acquire takes 30–90 s on a typical Windows guest. With `capacity: 4`, the worst-case wait for the fourth job to enter the lock is ~4 × 90 s = 6 minutes before its build even starts. The build phase is parallel, so amortized this is fine, but document this explicitly. **MEDIUM**.
+- **No per-IP allocation strategy**. The system relies entirely on VMware's NAT DHCP to hand out unique IPs. The lock prevents *simultaneous* starts but does nothing if DHCP hands the same IP to two VMs on the same `VMnet8` lease window. The lease-collision check at `Invoke-CIJob.ps1:~430` (`if (Test-Path $leaseFile) { throw }`) is a fail-fast trap but never a recovery path. **MEDIUM** — see §15 for the suggested static-IP scheme.
+
+### 3.4 The "Auto" GuestOS Detection
+
+This is clever and correct: read the VMX, regex `guestOS = "..."`, classify as Linux if it contains `ubuntu` or `linux`, else Windows. It works for the two templates that exist. It will silently mis-classify a future `guestOS = "windows2025srv-64"` if Microsoft renames the family — but that is acceptable in this scope. **LOW**: assert against a known list and warn if the family is unknown.
+
+### 3.5 The `guestVar ci-ip` Channel
+
+`Invoke-CIJob.ps1` reads `guestVar 'ci-ip'` as the primary IP-discovery channel and falls back to `getGuestIPAddress`. The guest side is `ci-report-ip.service` writing via `vmware-rpctool` — referenced but not in any file I read. The fallback works for Windows; the primary is the only viable path for Linux because `getGuestIPAddress` on Linux is notoriously unreliable.
+
+The risk: there is no validation in `Validate-DeployState.ps1` that the guest service is enabled in a fresh template. If someone refreshes the Linux template and forgets the systemd unit, every Linux job will silently use the (broken) `getGuestIPAddress` fallback until it times out at 120 s. **HIGH**: add a `Validate-DeployState.ps1` check that fails the deploy if `ci-report-ip.service` is not present on Linux templates.
+
+---
+
+## 4. Code Quality
+
+### 4.1 PowerShell 5.1 Discipline
+
+The codebase respects the PS 5.1 constraint rigorously. Every script I read has the standard preamble:
+
+```powershell
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+```
+
+No null-coalescing operators, no ternaries, no `&&`/`||`, no `ForEach-Object -Parallel`. This is consistent across 14 scripts. The author understands the runtime.
+
+A subtler PS 5.1 issue does appear in `scripts/Backup-CITemplate.ps1`:
+
+```powershell
+$totalBytes = [long]0
+if ($backupFiles) { foreach ($f in $backupFiles) { $totalBytes += $f.Length } }
+```
+
+This manual sum is there because `Measure-Object -Sum` plus `Set-StrictMode -Version Latest` interacts badly when the input is empty. That is correct defensive coding for PS 5.1 + StrictMode. Good.
+
+### 4.2 `ErrorActionPreference` Discipline
+
+Three scripts intentionally relax `$ErrorActionPreference` to `Continue`:
+
+- `Cleanup-OrphanedBuildVMs.ps1` — cleanup must proceed through all orphans.
+- `Invoke-RetentionPolicy.ps1` — same rationale.
+- `Watch-DiskSpace.ps1` and `Watch-RunnerHealth.ps1` — exit-code-driven contract with Task Scheduler.
+
+This is correct. But three places set `Continue` for narrower reasons:
+
+- `Invoke-CIJob.ps1:~265` wraps `git clone` to allow capturing exit code.
+- `Wait-VMReady.ps1:~190` wraps `ssh` to demote the "Permanently added host key" stderr.
+- `Invoke-CIJob.ps1:~395` wraps `vmrun readVariable guestVar ci-ip` to allow exit-code inspection.
+
+All three save/restore `$savedEap = $ErrorActionPreference; ...; $ErrorActionPreference = $savedEap` correctly. This is the only safe pattern in PS 5.1 — `try { ... } finally { $ErrorActionPreference = ... }` would also work but is more verbose. **No issue**.
+
+### 4.3 Parameter Validation
+
+Excellent in places, missing in others.
+
+Strong:
+
+- IP regex `ValidatePattern('^((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$')` is used consistently in `Invoke-CIJob.ps1`, `Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `Wait-VMReady.ps1`.
+- `ValidateRange` on numeric parameters (`MaxAgeHours`, `RetentionDays`, `MinFreeGB`, `Iterations`, `TimeoutSeconds`, `MaxRestarts`).
+- `ValidateSet` on `GuestOS` ('Windows', 'Linux', 'Auto') and `Transport` ('WinRM', 'SSH').
+- `ValidatePattern('^[A-Za-z]$')` on `DriveLetter`.
+
+Missing:
+
+- `JobId` in `Invoke-CIJob.ps1` is `[string]$JobId` mandatory but unvalidated. It is used as a directory name and a Credential-Manager target lookup key. A user-supplied `JobId` containing `..\..\..` or `..\Logs\${someone-else}\` would let a malicious workflow write outside `F:\CI\Logs`. In this homelab that surface is local-only, but it is one line of defense to add: `[ValidatePattern('^[A-Za-z0-9._-]+$')]`. **LOW**.
+- `TemplatePath` in `Invoke-CIJob.ps1` is read from `$env:GITEA_CI_TEMPLATE_PATH` and validated only with `Test-Path -PathType Leaf`. Not a security issue (the runner controls the env var), but a sanity-check that the path lives under `F:\CI\Templates` would prevent operator typos pointing at a production VMX. **LOW**.
+- `BuildCommand` in `Invoke-CIJob.ps1` is forwarded verbatim into the guest. By design — the caller can run anything — but documenting that the build-command runs as the privileged build user with no sandboxing is worth saying explicitly in the README. **LOW**.
+
+### 4.4 Style
+
+PSScriptAnalyzer is configured in `PSScriptAnalyzerSettings.psd1` with the right exclusions for this project (`PSAvoidUsingWriteHost` excluded because act_runner captures `Write-Host` and `Write-Output` interferes with return values). Indentation is 4-space consistent. Function naming follows verb-noun (`Write-JobEvent`, `Compress-BuildArtifact`, `Remove-OldJobDirs`). Comment-based help is present on every script. This is genuinely good housekeeping.
+
+One stylistic complaint: the inline `Invoke-Command -Session $session -ScriptBlock { ... }` blocks in `Invoke-RemoteBuild.ps1` are getting long enough (~50 lines each, twice in the file) that splitting them into named local functions on the host side would help testability. **NICE-TO-HAVE**.
+
+### 4.5 Dead Code
+
+- `runner/Install-Runner.ps1` is marked DEPRECATED at the top of the file and superseded by `Setup-Host.ps1`. It should be deleted. **LOW** but immediate.
+- `Setup-Host.ps1` `.DESCRIPTION` references a default password `'CIBuild!ChangeMe2026'` but the actual `param([string]$GuestPassword = '')` is empty. The documentation lies. **LOW** — pick one and align.
+
+### 4.6 Logging Density
+
+`Write-Host` is used liberally and consistently with `[Component]` prefixes (`[Invoke-CIJob]`, `[Wait-VMReady]`, `[Cleanup]`, etc.). Combined with the JSONL log via `Write-JobEvent`, the runtime observability is genuinely good. The transcript is preserved per job under `F:\CI\Logs\$JobId\invoke-ci.log` and `invoke-ci.jsonl`. This is better than most paid CI systems give you.
+
+---
+
+## 5. Security
+
+The threat model documented in `docs/BEST-PRACTICES.md §2.1` (per `TODO.md`) explicitly accepts: Defender / Firewall / UAC disabled inside the build VM, self-signed WinRM cert with `SkipCACheck`/`SkipCNCheck`/`SkipRevocationCheck`, SSH `StrictHostKeyChecking=no` with `UserKnownHostsFile=NUL`. For an isolated `VMnet8` NAT network in a single-tenant home lab, this is defensible — the attack surface is host-local.
+
+Findings within that scope:
+
+### 5.1 PAT Handling (Mode 2 Windows path) — **GOOD**
+
+`scripts/Invoke-RemoteBuild.ps1` Mode 2 Windows branch reads the PAT from `Get-StoredCredential -Target 'GiteaPAT'` on the host, base64-encodes `user:pat`, and injects it via `git -c http.extraHeader=Authorization: Basic <b64>`. The PAT never appears in:
+
+- the clone URL
+- argv (because `-c key=value` is one arg)
+- `git config` files
+- the transcript log (the `Write-Host` calls echo `$cloneUrl`, not the auth-injected version)
+
+The PAT does live in memory inside the WinRM session for the duration of the clone. The WinRM session is `Authentication Basic` over TLS to the local guest. This is acceptable.
+
+### 5.2 PAT Handling (Mode 2 Linux path) — **WEAKER, MEDIUM**
+
+The Linux branch rewrites the URL to `https://user:pat@host/repo.git` and passes it via env var:
+
+```powershell
+$envCloneCmd = "export GIT_CLONE_URL='$cloneTargetUrl'; git clone --depth 1 --branch '$CloneBranch'"
+...
+$envCloneCmd += " `"`$GIT_CLONE_URL`" '$GuestLinuxWorkDir'; unset GIT_CLONE_URL"
+```
+
+The PAT is exposed in:
+
+- `/proc/<pid>/environ` while `git clone` runs (readable by the same `ci_build` user, but also root, but also any other process under the same UID).
+- The SSH command line on the *host* side as a single command string (encrypted in transit, but visible in `ps aux` to anyone on the host watching `ssh.exe`'s commandline).
+
+Fix: mirror the Windows approach. Pass `user` and `pat` as separate variables, use `git -c http.extraHeader=Authorization: Basic <base64>`. **MEDIUM, fix.**
+
+```powershell
+# Suggested Linux Mode 2 replacement
+$b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("$($pat.UserName):$($pat.GetNetworkCredential().Password)"))
+$cloneCmd = @(
+    "GIT_TERMINAL_PROMPT=0 git",
+    "-c 'credential.helper='",
+    "-c 'http.extraHeader=Authorization: Basic $b64'",
+    "clone --depth 1 --branch '$CloneBranch'",
+    $(if ($CloneSubmodules) { '--recurse-submodules' }),
+    "'$CloneUrl' '$GuestLinuxWorkDir'"
+) -join ' '
+Invoke-SshCommand -IP $IPAddress -User $SshUser -KeyPath $SshKeyPath -Command $cloneCmd
+```
+
+The base64 still appears in the SSH command line argument briefly, but it is no longer a credential URL that could be cached by git or leaked via a redirected error.
+
+### 5.3 Guest Credential Storage
+
+`Get-StoredCredential -Target 'BuildVMGuest'` is correct usage of Windows Credential Manager. `Setup-Host.ps1` stores it once. The PSCredential object is forwarded to all scripts. Good. **No issue**.
+
+### 5.4 The Lab-Wide `BuildVMGuest` Account
+
+Every clone has the same credentials. A compromised build (malicious build-command, e.g. on a public PR) could:
+
+1. Read `$Credential.GetNetworkCredential().Password` from its own WinRM session: it does not have this — credentials live on the host, only the WinRM service receives the authenticated handshake. **Not exploitable in-guest**.
+2. Persist data into the template by mounting `\\vmware-host\Shared Folders\` (HGFS). Yes — the shared folders for NuGet/pip caches are read-write. A malicious build could poison a NuGet package and have it served to the next build. **MEDIUM**.
+
+Mitigation: mark the shared folders read-only in the VMX for builds that do not need to write to them. Or, more practically, use per-template-version cache subdirs and accept the risk for a homelab. Document it. **MEDIUM**.
+
+### 5.5 `ExtraGuestEnv` Secret Injection
+
+The path `secrets.SIGN_PASS` → workflow → action input `extra-guest-env-json` → `ConvertFrom-Json` → hashtable → `Invoke-CIJob.ps1` → `Invoke-RemoteBuild.ps1` → `[System.Environment]::SetEnvironmentVariable($pair.Key, $pair.Value, 'Process')` is clean.
+
+But: the action.yml line `INPUT_EXTRA_GUEST_ENV_JSON: ${{ inputs.extra-guest-env-json }}` puts the secret JSON into a process environment variable on the runner host. Gitea Actions masks `secrets.*` in logs by string match. If a secret value happens to be a substring of a path or filename, the masking can miss it. This is a Gitea limitation, not yours, but worth a one-liner in `docs/WORKFLOW-AUTHORING.md`. **LOW**.
+
+### 5.6 Setup-Host.ps1 Password Default
+
+Currently `[string] $GuestPassword = ''`, which triggers a prompt — fine. But the help text claims `'CIBuild!ChangeMe2026'` is the default. If a future user reads the help and assumes the default is acceptable, they may not change it. **LOW** — strip the default password from documentation or make it `Read-Host -AsSecureString`-only.
+
+### 5.7 OWASP Top 10 Coverage (in scope)
+
+| Risk                          | Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A01 Broken Access Control     | Local host only. Acceptable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| A02 Cryptographic Failures    | Self-signed TLS for lab use. Acceptable. PAT base64 in command line is the only real concern (§5.2).                                                                                                                                                                                                                                                                                                                                                                                          |
+| A03 Injection                 | `BuildCommand` is by-design caller-controlled. JSON env injection parses safely via `ConvertFrom-Json`. SSH commands built from string concatenation in `Invoke-RemoteBuild.ps1` Linux branch — `$GuestLinuxWorkDir`, `$CloneBranch`, etc. are not user-supplied in the trigger path but a workflow author could pass `'$(rm -rf /)'` in `submodules` etc. The `single-quote escape` on `ExtraGuestEnv` values is correct; other interpolated strings are not escaped. **MEDIUM** — see §6.7. |
+| A04 Insecure Design           | Acceptable for homelab.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| A05 Security Misconfiguration | Defender/Firewall/UAC off, documented in BEST-PRACTICES. Acceptable for isolated lab.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| A06 Vulnerable Components     | `TODO.md §1.3 SHA256 pinning` was deferred. Toolchain installer downloads (Tier-1/Tier-2) use only placeholders. **MEDIUM** — see §6.8.                                                                                                                                                                                                                                                                                                                                                       |
+| A07 Auth Failures             | Shared `BuildVMGuest` account — see §5.4.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| A08 Software/Data Integrity   | No artifact signing. **NICE-TO-HAVE** for a homelab.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| A09 Logging Failures          | Strong (`invoke-ci.jsonl`, Event Log, webhook). Good.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| A10 SSRF                      | Not applicable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
+---
+
+## 6. Reliability
+
+### 6.1 IP Allocation Under Concurrency — **CRITICAL UNVALIDATED**
+
+`Invoke-CIJob.ps1` lines ~310–460 implement: open `F:\CI\State\vm-start.lock` with `FileShare.None` (acts as cross-process mutex on Windows), 10-minute deadline, retry every 5 s. Inside the lock: clone, start, acquire IP, write lease file. Release the lock.
+
+This is sound design. The bugs hiding here are:
+
+1. **The lock is implemented as a file handle with `FileMode.OpenOrCreate`.** If the host crashes while the lock is held, the file remains on disk. On reboot, the next process can re-open it because the kernel has released the lock — that part is fine. But a process inside its own lock that throws *before* `try { ... } finally` reaches the lock release would leak the handle. The `try { acquire } ... finally { release }` pattern in lines ~340–460 is correct, but the lock acquisition itself is *outside* a try/finally in the surrounding `try`. Trace it carefully — there is one path where `[System.IO.File]::Open(...)` succeeds, then the `while ($true) { ... break }` exits normally, and execution continues into `Write-Host "[Invoke-CIJob] VM-start lock acquired."` and then into the inner `try { ... } finally { release }`. **The handle is closed correctly on every path**. OK.
+
+2. **`Remove-Item $lockPath -Force` inside the inner `finally`.** This deletes the lock file on the filesystem after closing the handle. If two processes are racing — process A has just released and deleted the file, process B is in its `while ($true)` retry loop — process B will successfully `OpenOrCreate` a new file. That is fine. But the `Remove-Item` is a useful indicator-of-cleanliness on disk, nothing more. Some Windows AV products briefly hold a handle on file deletes which would cause `Remove-Item` to fail — the `-ErrorAction SilentlyContinue` handles that. **No issue**.
+
+3. **IP detection inside the lock**: 120 s deadline, polling every 2 s. The slowest plausible case is a Windows guest booting cold and waiting for VMware Tools to publish an IP. 120 s is generous and validated by `Measure-CIBenchmark.ps1` data (assumed; not actually inspected). **OK**.
+
+4. **The unvalidated case**: four concurrent jobs all hit the lock within milliseconds of each other. Job 1 enters, takes ~60 s. Jobs 2/3/4 retry every 5 s. After job 1 releases, only one of 2/3/4 will win the race (whichever's `OpenOrCreate` happens first in the kernel). The other two retry. This serializes the four jobs into ~60 s × 4 = 4 minutes of pre-build phase. The build phase then runs parallel. **Acceptable but unmeasured.** The `TODO.md §2.1 — Home Lab: deferred. Race non riprodotta in e2e-008/009.` is honest but incomplete. **HIGH** — actually run `Invoke-CIJob.ps1` four times in parallel from a PowerShell harness and confirm zero IP collisions, zero lock leaks, zero hangs.
+
+### 6.2 VM Destroy Resilience
+
+`Remove-BuildVM.ps1`'s soft-stop-then-hard-stop-then-poll-then-deleteVM-with-3-retries sequence is well thought out. The 20 s "wait until VMX disappears from `vmrun list`" step exists because `vmware-vmx.exe` holds a file lock briefly after stop. This is real and the workaround is correct.
+
+The fallback `Remove-Item -Recurse` after `deleteVM` failure is the right "give up gracefully" path. Combined with `Cleanup-OrphanedBuildVMs.ps1` scheduled every 6 h with `MaxAgeHours 4`, anything that survives the immediate destroy path is reaped within hours. **GOOD**.
+
+### 6.3 `act_runner` Auto-Restart
+
+`Watch-RunnerHealth.ps1` is rate-limited (3 restarts/h via `runner-restart-log.json` rolling window). Beyond that limit it writes EventId 1004 Error and exits non-zero so Task Scheduler shows red. Webhook posted on every restart. This is genuinely good.
+
+One subtle bug: the cooldown log is JSON-serialized as an array of ISO timestamp strings. Line ~118 `$restartLog = @($raw | ConvertFrom-Json)`. If the log contains exactly one entry, `ConvertFrom-Json` returns a single string, not an array. The `@(...)` coercion handles that. If the log file is empty (zero bytes), `ConvertFrom-Json` throws — but `$raw` is checked for truthiness first. **OK**.
+
+A more relevant flaw: the script does not check whether the service was *stopped intentionally* (e.g. operator running `Backup-CITemplate.ps1` which calls `Stop-Service act_runner`). It will try to restart it. `Backup-CITemplate.ps1` itself uses `Stop-Service -Force` and `Start-Service` in a try/finally, so the conflict window is short, but a `Watch-RunnerHealth.ps1` invocation that falls inside that window will count as a "restart" in the cooldown log. This is benign but noisy. **LOW** — `Backup-CITemplate.ps1` could disable the scheduled task while it works, or `Watch-RunnerHealth.ps1` could check for a `F:\CI\State\runner-maintenance.flag` and exit 0.
+
+### 6.4 Disk Space Alerting
+
+`Watch-DiskSpace.ps1` checks every 15 min, writes Event Log on alert, optionally posts to webhook. Exits non-zero so Task Scheduler shows red. Pairs with `Invoke-RetentionPolicy.ps1`'s aggressive-mode fallback (below 50 GB free → 7-day retention instead of 30). **GOOD**.
+
+### 6.5 Retention Policy
+
+`Invoke-RetentionPolicy.ps1` correctly handles the case where the drive is missing (falls back to `[double]::MaxValue` to avoid aggressive mode firing on no data). The stale-lease cleanup (>12 h) is the right defensive belt-and-suspenders for crashed-host recovery. **GOOD**.
+
+One thing missing: there is no retention on `F:\CI\BuildVMs\` itself. Orphan cleanup handles VMs older than 4 h; the retention policy handles artifacts and logs. But a partial clone (a directory created without a `.vmx` because `vmrun clone` failed mid-way) older than 4 h with no `.vmx` is removed by `Cleanup-OrphanedBuildVMs.ps1` only via the dir-removal-only fallback — good, no issue.
+
+### 6.6 Wait-VMReady Phase Logic
+
+The 3-phase wait is the right shape and the comment in lines ~108–120 correctly documents why `getGuestIPAddress` is not used for Phase 1 (Tools-dependent). The fact that the Windows fallback in `Invoke-CIJob.ps1` IP detection still uses `getGuestIPAddress` is consistent — by Phase 3b the VM has been up long enough that Tools should be responsive.
+
+### 6.7 String Interpolation into SSH Commands
+
+`Invoke-RemoteBuild.ps1` Linux branch builds shell commands by string concatenation:
+
+```powershell
+$buildCmd = "${envPrefix}cd '$GuestLinuxWorkDir' && $BuildCommand"
+```
+
+`$GuestLinuxWorkDir` is single-quoted, which is correct. `$BuildCommand` is not — by design, because the caller provides shell. `$envPrefix` correctly single-quote-escapes values via `$envVal = $ExtraGuestEnv[$envKey] -replace "'", "'\''"`. **OK for trusted inputs**.
+
+But:
+
+```powershell
+Invoke-SshCommand -IP $IPAddress -User $SshUser -KeyPath $SshKeyPath `
+    -Command "rm -rf '$GuestLinuxWorkDir' && mkdir -p '$GuestLinuxWorkDir'"
+```
+
+If a workflow author somehow gets `$GuestLinuxWorkDir` to contain `' && rm -rf / #` (it cannot today — it is hardcoded in `Invoke-CIJob.ps1`), they would have remote code execution as `ci_build`. Today this is not exploitable because all interpolated values into SSH commands originate from `Invoke-CIJob.ps1` parameters that are not workflow-controllable. **LOW**. Audit boundary should be documented.
+
+### 6.8 Toolchain Installer Pinning
+
+`Install-CIToolchain-WinBuild2025.ps1` and `Install-CIToolchain-Linux2404.sh` (per `TODO.md §1.3`) use SHA256 *placeholders* — they were deferred for the homelab. This means a man-in-the-middle on the public internet at template-rebuild time could substitute compromised toolchains. The probability is low (TLS protects everything), but the *defense in depth* is missing. **MEDIUM** — implement real hash pinning before any non-homelab use.
+
+---
+
+## 7. Operational Gaps
+
+| Gap                                                 | Severity     | Notes                                                                                                                                                     |
+| --------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No documented template-refresh runbook              | HIGH         | `Backup-CITemplate.ps1` exists, but the procedure (Win KMS reactivation, snapshot rebuild, validation) is not codified.                                   |
+| No automated end-to-end smoke test                  | HIGH         | The "production-ready" claim rests on `e2e-008`/`e2e-009` manual runs.                                                                                    |
+| `capacity: 4` never validated                       | HIGH         | See §6.1.                                                                                                                                                 |
+| No CI for the CI                                    | HIGH         | PSScriptAnalyzer lint workflow exists; no Pester run on commit; no integration test on commit.                                                            |
+| No alerting on stuck jobs                           | MEDIUM       | A job that hangs at 1 h 50 min (just under the 2 h runner timeout) is invisible. Watchdog only checks the runner service, not job duration.               |
+| No central log aggregation                          | MEDIUM       | JSONL files are per-job. Cross-job analysis requires manual grep. A `Get-CIJobStats.ps1` summarizer would help.                                           |
+| No quota/limit on PR builds                         | MEDIUM       | A misbehaving workflow could fork the orchestrator. Concurrency lock prevents IP collisions but not disk fill. `MaxAgeHours 4` provides eventual cleanup. |
+| No multi-host fan-out                               | NICE-TO-HAVE | `§6.3` deferred. Single point of failure is the workstation. Acceptable for homelab.                                                                      |
+| No remote-access procedure for debugging a stuck VM | LOW          | `Cleanup-OrphanedBuildVMs.ps1` will eventually destroy a stuck VM. Manual inspection between job and cleanup requires knowing the clone path.             |
+| No host hardware monitoring                         | LOW          | CPU/RAM/disk-IO not measured. `Measure-CIBenchmark.ps1` is phase-time only.                                                                               |
+| `BaseClean` snapshot age not tracked                | LOW          | Windows KMS lease is 180 days. After that, builds will silently degrade (activation issues affecting `dotnet`).                                           |
+| `runner/Install-Runner.ps1` deprecated but present  | LOW          | Delete it.                                                                                                                                                |
+| `Setup-Host.ps1` password documentation mismatch    | LOW          | See §4.5.                                                                                                                                                 |
+
+---
+
+## 8. CI/CD Workflow Quality
+
+### 8.1 The Composite Action — Mostly Good
+
+`gitea/actions/local-ci-build/action.yml` does the right things:
+
+- Forwards every workflow input through `env:` rather than direct interpolation into the shell. This prevents shell injection from `inputs.build-command`. **GOOD**.
+- Builds the `Invoke-CIJob.ps1` parameter hashtable conditionally based on which inputs are populated. **GOOD**.
+- Emits `artifact-path` and `artifact-name` as step outputs for downstream `actions/upload-artifact`. **GOOD**.
+- Has both a success-path `upload-artifact` and a failure-path log upload. **GOOD**.
+
+Concerns:
+
+- **Hardcoded `$ciScriptsDir = 'N:\Code\Workspace\Local-CI-CD-System\scripts'`**. If the user clones the repo elsewhere, the action breaks. The composite action should resolve scripts via `${{ github.action_path }}\..\..\scripts` (i.e. relative to the action file). **MEDIUM** — this couples the action to one specific host filesystem layout.
+- The action's `outputs:` block declares `artifact-path` and `artifact-name` but they appear *inside* the `inputs:` map by mistake (lines just before `runs:`). YAML-wise this still parses as an `outputs:`-like key at the wrong level, but a stricter linter would flag it. **LOW** — restructure.
+- No input validation. `inputs.guest-os` accepts any string; if a typo `'Linus'` is passed, it propagates to `Invoke-CIJob.ps1` which rejects it via `ValidateSet`. The error is clear at runtime but late. **LOW**.
+- No timeouts at the action level. Relies entirely on the runner-level `timeout: 2h` in `runner/config.yaml`. **LOW**.
+
+### 8.2 The Calling Workflow `build-nsInnoUnp.yml`
+
+- Matrix on `[windows, linux]`, `fail-fast: false`. **GOOD**.
+- `job-id-suffix: '${{ matrix.target }}'` to disambiguate the artifact directories. **GOOD** — this is exactly the right use of the suffix.
+- `submodules: 'true'` as string (the action only checks `eq 'true'`). **OK**.
+- `repo-url: 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git'` uses the host-side SSH alias configured in `Setup-Host.ps1`. The alias lives in the user's `~/.ssh/config` — which user? `act_runner` runs as `SYSTEM` (per `Register-CIScheduledTasks.ps1`). `SYSTEM`'s home is `C:\Windows\System32\config\systemprofile\`. So `Setup-Host.ps1` writes the SSH config to the *user's* `~/.ssh/config`, not `SYSTEM`'s. **HIGH** — this only works if the runner was installed under the user account, not SYSTEM. Verify. If `act_runner` is installed as a service under SYSTEM, this URL alias is broken.
+
+I cannot fully verify §8.2 last point without reading the NSSM install args in `Setup-Host.ps1` more carefully (the snippet I read showed `sc.exe failure` configurations but the actual `nssm install` line for the service account was not in my reads). Treat as **HIGH unverified** — exact service account configuration must be checked.
+
+### 8.3 Lint Workflow
+
+`gitea/workflows/lint.yml` (not read in this session) is referenced in `TODO.md` as completed for PSScriptAnalyzer. The fact that there is *no* equivalent for Pester is the gap. **HIGH** — add a `tests.yml` workflow that runs the Pester suite on every push.
+
+### 8.4 Workflow Example
+
+`gitea/workflow-example.yml` exists at the repo root as a reference for downstream users. **GOOD** — useful for onboarding.
+
+---
+
+## 9. Test Coverage
+
+Four Pester v5 files exist in `tests/`:
+
+- `_Common.Tests.ps1`
+- `New-BuildVM.Tests.ps1`
+- `Remove-BuildVM.Tests.ps1`
+- `Wait-VMReady.Tests.ps1`
+
+Per `TODO.md §5.1`, they all use a fake `vmrun.cmd` driven by `$env:FAKE_VMRUN_EXIT`. What this means in practice:
+
+| Tested                                                 | Not Tested                                                                |
+| ------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Argument construction for `vmrun clone`                | Whether `vmrun clone` actually clones                                     |
+| `Invoke-Vmrun` return shape                            | Whether `Invoke-Vmrun` works with real `vmrun.exe`                        |
+| Parameter validation regexes                           | Whether `Test-NetConnection -Port 5986` works                             |
+| Path resolution helpers                                | Whether `Start-Sleep` polling deadlines fire correctly                    |
+| Throw-on-error paths via fake exit codes               | The actual failure modes (`vmware-vmx.exe` file lock, DHCP timeout, etc.) |
+| WinRM session options object shape                     | Whether WinRM actually accepts self-signed cert                           |
+| Phase 1 readiness loop (with fake `vmrun list` output) | Whether real VM boot timing fits the deadline                             |
+
+This is meaningful coverage — the Pester suite catches regressions in argument shape, parameter validation, return types, and exit-code interpretation. It is NOT integration coverage. Calling this "production-ready" testing is overstating it.
+
+What is missing in priority order:
+
+1. **HIGH** — a `tests/Integration/` folder with at least one script that does `Measure-CIBenchmark.ps1 -Iterations 1` and asserts all phases under thresholds. Runnable on demand (manual workflow_dispatch in Gitea). Wire to a `[ci-burnin]` commit tag for full 4× concurrency.
+2. **HIGH** — Pester tests for `Invoke-CIJob.ps1` phase orchestration (mock the sub-scripts via function override in the test scope). Today the orchestrator is the most complex script and has the least coverage.
+3. **MEDIUM** — Pester tests for `Invoke-RemoteBuild.ps1` Linux PAT-injection (after fixing §5.2).
+4. **MEDIUM** — Pester tests for `Invoke-RetentionPolicy.ps1` aggressive-mode threshold logic and stale-lease cleanup with mocked file dates.
+5. **LOW** — a single "make sure all 14 scripts parse cleanly" check via `[System.Management.Automation.Language.Parser]::ParseFile` in CI. The lint workflow probably already does this implicitly.
+
+Estimated test coverage (lines exercised by Pester / lines of production code): **~15%**. That is below typical homelab expectations but consistent with a system written by one operator who tests by running the real thing.
+
+---
+
+## 10. Observability
+
+This is the area I am most positive about. The system genuinely has better observability than most paid CI systems give you:
+
+| Channel                                                       | Purpose                         | Quality |
+| ------------------------------------------------------------- | ------------------------------- | ------- |
+| `F:\CI\Logs\$JobId\invoke-ci.log`                             | Per-job transcript              | High    |
+| `F:\CI\Logs\$JobId\invoke-ci.jsonl`                           | Per-job structured phase events | High    |
+| `F:\CI\Logs\benchmark.jsonl`                                  | Cross-job benchmark trend       | High    |
+| Windows Event Log `CI-DiskAlert` (EventId 1001)               | Disk alert                      | Medium  |
+| Windows Event Log `CI-RunnerHealth` (EventIds 1002/1003/1004) | Runner state changes            | High    |
+| Webhook (Discord/Gitea-compatible)                            | Real-time notification          | High    |
+| `F:\CI\State\runner-restart-log.json`                         | Rolling 1-hour restart cooldown | High    |
+| `F:\CI\State\ip-leases\<ip>.lease`                            | Active IP allocations           | Medium  |
+| Task Scheduler history                                        | Scheduled-task health           | Medium  |
+| PSScriptAnalyzer lint workflow output                         | Code health                     | Medium  |
+
+What is missing:
+
+- **Job duration alerting**. A job pinned at 1 h 55 min before timing out at 2 h is invisible until it fails. A simple per-job watchdog (Phase 5 start time + 90 min → webhook warning) would help. **MEDIUM**.
+- **A `Get-CIJobSummary.ps1` script** that scans the last N days of `invoke-ci.jsonl` files and produces a table of jobs, phases, durations, success rate. Today this is a manual grep. **LOW**.
+- **Host hardware metrics**. CPU/RAM/disk-IO over time would let you correlate slow builds with host contention. Not in scope today. **NICE-TO-HAVE**.
+- **No metric on linked-clone delta size growth**. If something starts modifying the template files outside of refresh cycles, deltas balloon. `Measure-CIBenchmark.ps1` doesn't track this. **LOW**.
+
+---
+
+## 11. Technical Debt
+
+In priority order:
+
+1. **`runner/Install-Runner.ps1` deprecated**. Delete.
+2. **`Setup-Host.ps1` password documentation mismatch**. Align help with actual default.
+3. **`Measure-CIBenchmark.ps1` uses `getGuestIPAddress` instead of `guestVar ci-ip`**. Inconsistent with production path. Refactor to share IP-acquire logic with `Invoke-CIJob.ps1` via a helper in `_Common.psm1`.
+4. **Hardcoded `N:\Code\Workspace\Local-CI-CD-System\` paths** in `gitea/actions/local-ci-build/action.yml` and `Register-CIScheduledTasks.ps1`. The action should use `${{ github.action_path }}`; the scheduled tasks could read from a config file in `F:\CI\State\`.
+5. **Linux PAT injection rewrites the URL**. Convert to `http.extraHeader` (§5.2).
+6. **Two divergent SHA256 placeholder strategies** in toolchain installers (`TODO.md §1.3`). Real pinning would fix this, but at minimum keep the placeholder shape identical across both installers.
+7. **`Invoke-RemoteBuild.ps1` is 500+ lines with two ~50-line ScriptBlocks inline**. Extract `New-GuestBuildScriptBlock` and `New-GuestCloneScriptBlock` into named functions for readability and testability.
+8. **Duplicate parameter blocks** for `IPAddress`, `Credential`, `GuestOS`, `SshKeyPath`, `SshUser` repeated across `Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `Wait-VMReady.ps1`. A shared parameter splat helper would reduce drift risk.
+9. **`docs/archived/2026-05-10/`** holds old plan/README/test docs. Fine as history, but the `TEST-PLAN-v1.3-to-HEAD.md` at top level should reference these explicitly so readers know where to find prior state.
+10. **No CHANGELOG**. The TODO.md is acting as one. Move historical "done" sections into `docs/CHANGELOG.md` once a release is tagged.
+
+---
+
+## 12. Issues by Priority
+
+### CRITICAL
+
+- **`capacity: 4` is unvalidated**. Either burn-in or downgrade. Right now the system claims a concurrency capability it has not measured. (`runner/config.yaml`, `scripts/Invoke-CIJob.ps1`)
+
+### HIGH
+
+- **No automated end-to-end test**. `Measure-CIBenchmark.ps1` exists but is not wired to CI and runs without assertions. (`scripts/Measure-CIBenchmark.ps1`)
+- **`act_runner` service account vs SSH alias mismatch potential**. If runner runs as SYSTEM, the `gitea-ci` SSH alias written by `Setup-Host.ps1` lives in the wrong `~/.ssh/config`. (`Setup-Host.ps1`, `gitea/workflows/build-nsInnoUnp.yml`)
+- **No CI for the CI**: Pester tests never run on commit, no integration test. (`gitea/workflows/`)
+- **Template-refresh procedure not codified**. KMS re-activation, snapshot rebuild, validation steps live in operator memory. (`docs/`, missing)
+- **`Validate-DeployState.ps1` does not assert `ci-report-ip.service` presence on Linux templates**. Silent fallback to 120 s timeout if the service is missing. (`template/Validate-DeployState.ps1`)
+
+### MEDIUM
+
+- **Linux Mode 2 PAT injection rewrites the URL**. Move to `http.extraHeader` (§5.2). (`scripts/Invoke-RemoteBuild.ps1`)
+- **`Measure-CIBenchmark.ps1` uses `getGuestIPAddress` (anti-pattern documented elsewhere)**. (`scripts/Measure-CIBenchmark.ps1`)
+- **Shared HGFS caches are read-write from the guest**. A compromised build can poison NuGet/pip caches. (`scripts/Set-TemplateSharedFolders.ps1`)
+- **Hardcoded `N:\Code\Workspace\...` paths in composite action and scheduled tasks**. (`gitea/actions/local-ci-build/action.yml`, `scripts/Register-CIScheduledTasks.ps1`)
+- **No retention on `F:\CI\BuildVMs\` partial-clone directories below the 4 h orphan threshold**. (`scripts/Cleanup-OrphanedBuildVMs.ps1`)
+- **No SHA256 pinning of toolchain installers** (homelab-deferred but worth a flag). (`template/Install-CIToolchain-WinBuild2025.ps1`)
+- **No job-duration watchdog**. Jobs near the 2 h timeout invisible until they fail. (`scripts/`, missing)
+- **`Invoke-RemoteBuild.ps1` has duplicate PAT-injection logic between Linux and Windows branches.** (`scripts/Invoke-RemoteBuild.ps1`)
+
+### LOW
+
+- **`runner/Install-Runner.ps1` deprecated** — delete.
+- **`Setup-Host.ps1` password default documentation mismatch**.
+- **`JobId` parameter unvalidated** — path-traversal-shaped values accepted.
+- **`TemplatePath` parameter not asserted to live under `F:\CI\Templates\`**.
+- **Composite action's `outputs:` block sits inside `inputs:` map** — YAML layout error.
+- **`Watch-RunnerHealth.ps1` cannot distinguish operator-initiated stops** from crashes.
+- **`Backup-CITemplate.ps1` does not validate that the template is fully powered-off** before copy — relies on `Stop-Service act_runner` but does not check for residual `vmware-vmx.exe`.
+- **`Get-CIJobStats.ps1` summarizer missing**.
+- **`docs/CHANGELOG.md` missing** (TODO.md is acting as one).
+- **String interpolation in SSH commands** with non-user-controlled paths — not exploitable today, audit-document.
+
+### NICE-TO-HAVE
+
+- Artifact signing.
+- Host hardware metrics.
+- Multi-host federation (`TODO.md §6.3`).
+- Quota system for runaway builds.
+- Per-build Defender exclusion lift/restore on the host (faster I/O during clone).
+- Linked-clone delta size monitoring.
+
+---
+
+## 13. Top 10 Quick Wins
+
+These are the changes that pay back the most for the least effort.
+
+1. **Delete `runner/Install-Runner.ps1`**. Five-second change. Removes a misleading file.
+
+2. **Align `Setup-Host.ps1` password documentation with code**.
+   ```powershell
+   # In param block
+   [string] $GuestPassword = ''   # keep
+   # In help text
+   .PARAMETER GuestPassword
+       Plain-text password for the guest VM build account.
+       When empty (default), the script will prompt with Read-Host -AsSecureString.
+       Do NOT hardcode this in production scripts.
+   ```
+
+3. **Add a `[ValidatePattern('^[A-Za-z0-9._-]+$')]` to `JobId`** in `Invoke-CIJob.ps1` and the composite action. One line each. Closes path-traversal even though not exploitable today.
+
+4. **Replace hardcoded `$ciScriptsDir` in `action.yml`** with `${{ github.action_path }}\..\..\scripts`:
+   ```yaml
+   run: |
+     $ciScriptsDir = Resolve-Path (Join-Path '${{ github.action_path }}' '..\..\scripts')
+   ```
+   Decouples the action from one specific clone location.
+
+5. **Fix Linux Mode 2 PAT injection** to use `http.extraHeader` (snippet in §5.2). Removes PAT from URL/argv/process environment.
+
+6. **Add a `Validate-DeployState.ps1` check for `ci-report-ip.service`** on Linux templates. A single `systemctl is-enabled ci-report-ip.service` over SSH after deploy.
+
+7. **Wire `Measure-CIBenchmark.ps1 -Iterations 1` to a `workflow_dispatch` job** named "ci-self-test" in a new `gitea/workflows/self-test.yml`. Exits non-zero on any phase failure. The runner runs it against itself.
+
+8. **Add a single test for the orchestrator's IP-detection fallback path** in `tests/Invoke-CIJob.Tests.ps1`. Mock `Invoke-Vmrun` to return empty `guestVar`, assert fallback to `getGuestIPAddress`. ~30 lines.
+
+9. **Add `Get-CIJobSummary.ps1`** that reads the last 7 days of `F:\CI\Logs\*\invoke-ci.jsonl` and prints a table:
+   ```
+   JobId         Started              Elapsed   Phase1   Phase5    Status
+   42-1          2026-05-10 14:22     04:32     0:08     03:42     success
+   43-1-windows  2026-05-10 14:30     03:18     0:07     02:48     success
+   ```
+   ~40 lines.
+
+10. **Add a 90-minute "phase 5 still running" webhook warning** to `Invoke-CIJob.ps1`. A background `Start-Job` with a sleep and a POST. Fires once per job. ~15 lines.
+
+---
+
+## 14. Completion Roadmap
+
+What separates "working homelab" from "actually production-ready, even by homelab standards":
+
+### Phase A — Validation (1–2 sessions of work)
+
+- Run a real 4-way concurrent burn-in. Document the result. Decision: keep `capacity: 4` or downgrade.
+- Wire the self-test workflow (Quick Win #7).
+- Wire a Pester run on commit.
+- Verify the `act_runner` service-account vs SSH-alias question (§8.2).
+
+### Phase B — Hardening (1–2 sessions)
+
+- Fix Linux Mode 2 PAT injection.
+- Add Validate-DeployState check for `ci-report-ip.service`.
+- Document the template-refresh runbook.
+- Resolve hardcoded paths in the composite action.
+- Add job-duration watchdog (Quick Win #10).
+
+### Phase C — Polish (background work)
+
+- Add `Get-CIJobSummary.ps1`.
+- Add `JobId` and `TemplatePath` validators.
+- Add Pester tests for `Invoke-CIJob.ps1` (mock sub-scripts).
+- Move `TODO.md` done-sections to `docs/CHANGELOG.md`.
+- Delete `runner/Install-Runner.ps1` and fix the `Setup-Host.ps1` doc mismatch.
+
+### Phase D — Optional (if scope grows)
+
+- Implement SHA256 pinning for toolchain installers.
+- Implement multi-host federation (`TODO.md §6.3`).
+- Implement read-only HGFS shared folders option.
+- Implement artifact signing.
+
+The system is genuinely useful today. Phase A is the difference between "works for me" and "works repeatably under load". Phase B is the difference between "works repeatably" and "I would trust it with somebody else's code".
+
+---
+
+## 15. What Would I Change
+
+If I were starting this project from scratch today, given the same constraints (Windows 11 host, VMware Workstation, Gitea, single-operator homelab), here is what I would do differently:
+
+### 15.1 IP Allocation: Static, Not DHCP
+
+The file mutex + lease pattern is correct in shape but solves a problem you do not need to have. Configure `VMnet8` with a small static-IP pool (`192.168.79.100–192.168.79.107`, eight slots for `capacity: 8` headroom) and assign each clone a specific IP from the pool at clone time. Done via:
+
+1. A `F:\CI\State\ip-pool.json` listing slots `{ ip: "192.168.79.100", inUse: false, jobId: null }`.
+2. `New-BuildVM.ps1` claims a slot atomically (lock the JSON, mark `inUse: true`, write `jobId`).
+3. The clone gets a `bootCmd` or cloud-init that assigns the static IP at boot. For Windows: `netsh interface ip set address` in the autounattend. For Linux: a `cloud-init` `network-config` file.
+4. `Wait-VMReady.ps1` polls the *known* IP rather than discovering it.
+
+Benefits: no DHCP race, no `getGuestIPAddress` dependency, no `guestVar ci-ip` plumbing, no 120 s polling deadline, simpler `Invoke-CIJob.ps1`. The lock becomes per-slot instead of global, so all four jobs can clone+start in parallel.
+
+Cost: one more file to maintain, template autounattend has a single static-IP placeholder. Worth it.
+
+### 15.2 Drop the WinRM-vs-SSH Branch Duplication
+
+`Invoke-RemoteBuild.ps1`, `Get-BuildArtifacts.ps1`, `Wait-VMReady.ps1` all have `if ($GuestOS -eq 'Linux') { ... } else { ... }` branches. This is fine for two transports but does not scale and is a known maintenance pain.
+
+A cleaner shape: a `_Transport.psm1` that exports a single interface:
+
+```powershell
+Invoke-GuestCommand    -Transport <SSH|WinRM> -IP -Auth -Command
+Copy-GuestItem         -Transport ... -Direction -Source -Destination
+Wait-GuestTransportReady -Transport ... -IP -TimeoutSeconds
+```
+
+with two implementations behind the same surface. Each of the three high-level scripts then becomes ~half the size and ~half the maintenance.
+
+### 15.3 Centralize Configuration
+
+`F:\CI\` paths and `BuildVMGuest` credential target are hardcoded in many places. A single `F:\CI\State\config.json` read at the top of each script via a `Get-CIConfig` helper in `_Common.psm1` would centralize this. Today changing the artifact root requires editing 6+ scripts.
+
+### 15.4 Move the JSONL Log to a SQLite Sink
+
+JSONL is fine for emitting. For querying ("show me all jobs that failed in Phase 5 last week"), SQLite is much better. Append to JSONL for forward compatibility, batch-import into `F:\CI\State\history.db` from `Get-CIJobSummary.ps1`. Single dependency.
+
+### 15.5 Treat the Composite Action's Inputs as a Schema
+
+Today `inputs.guest-os` accepts any string. Define a JSON schema for the inputs in `action.yml` and validate at action entry. Bonus: this becomes self-documenting.
+
+### 15.6 Write the Integration Test First, Not Last
+
+The four Pester unit tests are useful but they were not the test you needed. The test you needed was: "given a fresh template, run a real job, assert artifact exists, assert phase timings within bounds." Build that *first* before writing PowerShell. It would have caught real bugs faster than fake-`vmrun.cmd` tests.
+
+### 15.7 Stop Using `Write-Host` for Logging
+
+`Write-Host` is necessary for `act_runner` output capture per `PSScriptAnalyzerSettings.psd1` exclusion. But it conflates user-facing operator output with structured log emission. Define a `Write-CILog -Level Info|Warn|Error -Component "..." -Message "..."` helper that *also* writes JSONL and console. One channel, one helper. Today every script writes `Write-Host "[Component] msg"` and *also* calls `Write-JobEvent`. They drift.
+
+### 15.8 Use `pwsh` (PowerShell 7) Not PS 5.1
+
+This is the biggest "what would I change" and the one most outside the documented constraints. The PS 5.1 mandate per `AGENTS.md` is a real constraint that was clearly hit (the `$LASTEXITCODE && other_cmd` workaround pattern is everywhere). PS 7 is a side-by-side install, does not break PS 5.1, and gives:
+
+- `&&` / `||` for shell-style chaining
+- `??` / `??=`
+- `ForEach-Object -Parallel` (could parallelize Phase 1 host clones)
+- `Test-Json` for the `extra-guest-env-json` validation
+- Better error messages
+
+Reasonable counter-argument: PS 5.1 is built-in on Windows 11, PS 7 is one more thing to manage. For a homelab single operator, that argument is weak.
+
+### 15.9 Bake the Validation Step Into the Orchestrator
+
+`template/Validate-DeployState.ps1` and `template/Validate-SetupState.ps1` exist as one-shot validation scripts but are not invoked automatically. The orchestrator should run a quick template-health check at the start of each job (cached if recent) and fail-fast if the template is wrong:
+
+```powershell
+# Inside Invoke-CIJob.ps1, very early
+$validationStamp = Join-Path $stateDir "template-validated-$($TemplateHash).flag"
+if (-not (Test-Path $validationStamp) -or $validationStamp.LastWriteTime -lt (Get-Date).AddDays(-7)) {
+    & "$scriptDir\..\template\Validate-DeployState.ps1" -TemplatePath $TemplatePath
+    if ($LASTEXITCODE -ne 0) { throw "Template validation failed." }
+    Set-Content $validationStamp -Value (Get-Date -Format 'o')
+}
+```
+
+This catches the "someone manually edited the template and broke `ci-report-ip.service`" failure mode.
+
+### 15.10 Drop the Mode 1 / Mode 2 Choice
+
+Mode 2 (`-UseGitClone`) is faster per `TODO.md` (`-25.7%` vs baseline). Mode 1 exists as the default for the case where the runner has the source already (`actions/checkout@v4` in the workflow). But `actions/checkout` in this setup just checks out on the host, then the host re-zips and ships it to the guest. That double-work is the slow path. The fast path (Mode 2) is faster *because* the guest has Git installed and can hit Gitea directly over the LAN.
+
+Make Mode 2 the default. Keep Mode 1 only for the offline-template-test edge case. Reduces parameter surface, reduces code paths to maintain.
+
+---
+
+## 16. Final Verdict
+
+This is genuinely good homelab engineering. The author understands the constraints (PS 5.1, single workstation, VMware Workstation Pro), has documented those constraints in `AGENTS.md` for their future self, has built a proper audit trail in `TODO.md`, has named scripts thoughtfully, has separated concerns into the right modules, and has handled the obvious failure modes (orphans, disk fill, runner crash). The composite action is the right abstraction. The retention policy with aggressive fallback is the right shape. The JSONL+Event Log+webhook observability layer is better than most paid CIs.
+
+What stops me from agreeing with the `README.md` claim of "production-ready":
+
+1. **`capacity: 4` is a promise the system has not measured itself keeping.** The IP-allocation lock could be correct; or it could leak handles on a specific failure path; or DHCP could hand the same IP twice. The author admits this in `TODO.md §2.1 — race non riprodotta in e2e-008/009`. Either run the burn-in or set `capacity: 1` until it is done.
+2. **The Pester suite tests argument-shape, not behavior.** A real integration test takes one afternoon to write — that the system does not have one is the single biggest reason this is not actually "production-ready".
+3. **The composite action depends on a hardcoded N:\ path** and the `act_runner` service account / SSH alias question. One of these is likely a runtime bug waiting to be discovered.
+4. **The Linux PAT-injection path is weaker than the Windows one** with no documented reason. This is sloppy.
+5. **The deprecated `runner/Install-Runner.ps1` file and the `Setup-Host.ps1` ghost-password documentation** are small, but they are exactly the kind of small thing that says "this codebase has not had a recent close read by a second pair of eyes." They suggest other small things have also drifted.
+
+Honest grade:
+
+| Dimension              | Grade                                |
+| ---------------------- | ------------------------------------ |
+| Architecture           | A-                                   |
+| Code Quality           | B+                                   |
+| Security (in scope)    | B                                    |
+| Reliability (in scope) | B- (would be A- with §6.1 validated) |
+| Test Coverage          | C                                    |
+| Observability          | A-                                   |
+| Documentation          | B+                                   |
+| Operational Readiness  | B-                                   |
+| Overall                | **B+**                               |
+
+**Production-ready for the homelab use case it was built for**, with the caveats above. **Not production-ready by any commercial standard**, but it was never built to be, and that is fine.
+
+If I were the author, the next 4 hours I spent on this project would be: (a) run the burn-in, (b) write the integration self-test, (c) fix the Linux PAT path, (d) delete the dead `Install-Runner.ps1`. Those four changes move it from B+ to A-.
+
+---
+
+*End of review.*

plans/archived/2026-05-13/opus47-review-of-gpt55.md

@@ -0,0 +1,421 @@
+# Cross-Review: GPT-5.5 Analysis of Local-CI-CD-System
+
+Reviewer: Claude Opus 4.7, acting as lead architect.
+Subject under review: [plans/gpt55-analysis.md](gpt55-analysis.md).
+Reference baseline: [plans/opus47-analysis.md](opus47-analysis.md) (my own prior pass).
+Style: direct, opinionated, evidence-driven. Source paths quoted are workspace-relative.
+
+---
+
+## 1. Overall Assessment
+
+GPT-5.5's analysis is competent, balanced, and largely accurate. It avoids the two big failure modes I have learned to expect from peer LLM reviews: it does not invent issues, and it does not slide into enterprise-pattern checklist-mongering. The structural decomposition (Executive Summary, Project State, Architecture, Code Quality per file, Security, Reliability, CI/CD, Observability, Operations, Test Coverage, Tech Debt, Issues by Severity, Quick Wins, Roadmap, Architectural Recommendations, Final Assessment) gives a senior reviewer enough surface area to triangulate. The verdict ("strong homelab CI/CD system... not yet fully trustworthy for unattended daily use") matches the evidence in [TODO.md](../TODO.md), [docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md), and the actual scripts.
+
+The strongest insight in the GPT-5.5 review is its per-file Section 4 walkthrough. It catches things my own pass under-emphasised: that [scripts/Set-TemplateSharedFolders.ps1](../scripts/Set-TemplateSharedFolders.ps1) is fine as a tool but is a guest-to-host write boundary that demands caution; that [template/Validate-SetupState.ps1](../template/Validate-SetupState.ps1) makes a `PasswordExpires` assumption that the toolchain installer already handles defensively; that [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1) and [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1) still emit emoji glyphs in webhook payloads despite the user's documented no-emoji preference. These are concrete, falsifiable findings rather than abstract suggestions.
+
+The biggest weakness is that GPT-5.5 promotes a documentation/YAML-layout defect to **CRITICAL** (composite action outputs) without distinguishing between (a) the documented action-output surface being broken for downstream callers and (b) the actual artifact upload step at runtime being broken. Those are very different blast radii. The upload step in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) reads `steps.invoke-ci.outputs.artifact-path` (a step-level output, set explicitly via `Out-File $env:GITHUB_OUTPUT`), so the upload works regardless of the missing top-level `outputs:` block. I expand on this in Section 2. Second weakness: GPT-5.5 entirely misses the `act_runner` SYSTEM-account vs `~/.ssh/config` alias question I flagged as HIGH, which is a runtime-reachable bug. Third weakness: GPT-5.5 does not interrogate the unvalidated `capacity: 4` concurrency claim with the rigour the issue deserves; it briefly notes "probably good enough" without demanding a burn-in.
+
+---
+
+## 2. Technical Accuracy Verification
+
+I verified the GPT-5.5 claims that materially affect the master plan by reading the cited source. Results follow.
+
+### 2.1 CRITICAL: "Composite action outputs are declared under inputs, and artifact-name is duplicated"
+
+**Verdict: Partially correct, severity overstated.**
+
+The YAML structure issue is real. In [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) lines roughly 96-142, the `inputs:` block declares `artifact-name` at line ~96 (with `default: ''`). Then `extra-guest-env-json` ends at line ~133. Without an intervening `outputs:` key, the file directly continues with another `artifact-name:` and an `artifact-path:` — both with `value: ${{ steps.invoke-ci.outputs.* }}` syntax that only makes sense for action outputs. This is two distinct YAML defects:
+
+1. A duplicate `artifact-name` key at the same mapping level, which YAML 1.2 forbids (most parsers silently overwrite with the later definition).
+2. Missing `outputs:` header, so what should be action-level outputs sit as malformed inputs.
+
+However, GPT-5.5 escalates this to "VM build can succeed but `actions/upload-artifact` may receive empty `steps.invoke-ci.outputs.artifact-path` or `artifact-name`, causing workflow failure or missing artifacts." That part is wrong. The upload-artifact step explicitly reads `steps.invoke-ci.outputs.artifact-name` and `steps.invoke-ci.outputs.artifact-path`, which are **step-level outputs** set unconditionally in the inner PowerShell block by `"artifact-path=$artifactPath" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8`. Step-level outputs do not depend on the action having a top-level `outputs:` block. The upload works today.
+
+What the missing `outputs:` block actually breaks is the **caller-facing** action interface: a downstream workflow cannot read `steps.local-ci-build.outputs.artifact-path` from outside this composite action. Since the only consumer today is [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml), which does not consume action outputs (artifact upload happens inside the composite step), the user-visible impact is zero today.
+
+Correct severity: **HIGH** (latent breakage waiting for a second consumer), not **CRITICAL**. The fix is still trivial — sub-30 minutes — so this distinction does not change the quick-wins list. But the framing matters for trust in the report's prioritisation.
+
+### 2.2 CRITICAL: "Linux extra guest environment secrets are logged in clear text"
+
+**Verdict: Correct.**
+
+Verified at [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) line 257:
+
+```powershell
+$envPrefix = ''
+foreach ($envKey in $ExtraGuestEnv.Keys) {
+    $envVal = $ExtraGuestEnv[$envKey] -replace "'", "'\''"
+    $envPrefix += "export $envKey='$envVal'; "
+}
+...
+$buildCmd = "${envPrefix}cd '$GuestLinuxWorkDir' && $BuildCommand"
+Write-Host "[Invoke-RemoteBuild] Running build: $buildCmd"
+```
+
+The `Write-Host` line emits `$buildCmd`, which is the prefix-plus-command string with secret values inlined as `export KEY='value';`. act_runner captures this stdout and forwards it to Gitea job logs. Gitea masks `secrets.*` by string match, but the masking is brittle (multi-byte characters, base64 transforms, substring boundaries). My own analysis flagged the same line at MEDIUM (§5.5/§6.7). GPT-5.5's CRITICAL is defensible if any signing/credential secret is currently passed through `extra-guest-env-json` — which the workflow example `{"SIGN_PASS":"${{ secrets.SIGN_PASS }}"}` strongly suggests is the intended use case. I agree with the elevation to CRITICAL here.
+
+### 2.3 CRITICAL: "Linux -UseGitClone PAT can be embedded in the SSH command string"
+
+**Verdict: Correct, but my own analysis nailed the mitigation cleaner.**
+
+Verified at [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) lines 226-237:
+
+```powershell
+$envCloneCmd = "export GIT_CLONE_URL='$cloneTargetUrl'; git clone --depth 1 --branch '$CloneBranch'"
+if ($CloneSubmodules) { $envCloneCmd += ' --recurse-submodules' }
+$envCloneCmd += " `"`$GIT_CLONE_URL`" '$GuestLinuxWorkDir'; unset GIT_CLONE_URL"
+Invoke-SshCommand -IP $IPAddress -User $SshUser -KeyPath $SshKeyPath -Command $envCloneCmd
+```
+
+`$cloneTargetUrl` includes the embedded PAT (`https://user:pat@host/repo.git`). It then appears: in `/proc/<pid>/environ` of the shell during execution; in the host-side `ssh.exe` argv; in any PowerShell error text that captures `$envCloneCmd`. GPT-5.5's fix suggestion ("use an askpass helper or temporary credential file ... with chmod 600, run git with GIT_ASKPASS or http.extraHeader from a file/stdin, then shred/delete") is correct but heavier than needed. My own §5.2 proposed the cleaner fix: mirror the Windows `http.extraHeader=Authorization: Basic <base64>` pattern. Same outcome, less code, single new code path instead of two.
+
+### 2.4 HIGH: "vmrun lifecycle calls in production scripts have no hard timeout"
+
+**Verdict: Correct.**
+
+I cross-checked [scripts/_Common.psm1](../scripts/_Common.psm1)'s `Invoke-Vmrun` function: it wraps the native call and inspects `$LASTEXITCODE`, but there is no `Wait-Process -Timeout` or `Stop-Process` watchdog. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) and [scripts/Remove-BuildVM.ps1](../scripts/Remove-BuildVM.ps1) call `vmrun` through this helper and inherit the unbounded behaviour. A `vmrun` that hangs (e.g. waiting on a non-responsive `vmware-vmx.exe`) blocks the orchestrator until act_runner's job-level timeout. The fix GPT-5.5 proposes — move `Invoke-VmrunBounded` (already present in some deploy scripts) into `_Common.psm1` — is correct. My own analysis did not call this out separately; GPT-5.5 catches a real gap I missed.
+
+### 2.5 HIGH: "Stale vm-start.lock is not automatically cleaned after host crash"
+
+**Verdict: Correct and important.**
+
+Cross-checked: [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) clears `ip-leases` older than 12 hours but does not touch `F:\CI\State\vm-start.lock`. [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1) cleans clone dirs but not the lock file. A host crash mid-lock leaves the file on disk. On reboot, [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1)'s file-handle acquisition still works (the kernel released the OS-level lock), but the file still exists, so the cosmetic stale-file warning may misfire and the 10-minute retry semantics give a bad first-job-after-reboot experience. The fix is sound. My own analysis incorrectly concluded "the handle is closed correctly on every path... OK" (§6.1) and overlooked the post-crash file-existence concern. GPT-5.5 beats me here.
+
+### 2.6 HIGH: "Host bootstrap creates stale/incomplete directory structure"
+
+**Verdict: Correct.**
+
+Verified at [Setup-Host.ps1](../Setup-Host.ps1) lines 118-126:
+
+```powershell
+$dirs = @(
+    "$CIRoot\BuildVMs",
+    "$CIRoot\Artifacts",
+    "$CIRoot\Logs",
+    "$CIRoot\Templates\WinBuild",
+    "$CIRoot\act_runner\logs",
+    "$CIRoot\Cache\NuGet",
+    "$CIRoot\RunnerWork",
+    "$CIRoot\ISO"
+)
+```
+
+It creates `Templates\WinBuild` (the now-obsolete unified template name) but not `Templates\WinBuild2025`, `Templates\WinBuild2022`, or `Templates\LinuxBuild2404`. It does not create `State`, `State\ip-leases`, `keys`, or `Cache\pip`. The current orchestrator depends on `F:\CI\State\vm-start.lock` and `F:\CI\State\ip-leases\*.lease`; the Linux path depends on `F:\CI\keys\ci_linux`. A fresh host bootstrap is broken. My own analysis did not catch this with the same specificity (I noted the password documentation mismatch but not the directory list). GPT-5.5 wins this one cleanly.
+
+### 2.7 HIGH: "Template backup default points to the wrong template path"
+
+**Verdict: Correct.**
+
+Verified at [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) line 48: `[string] $TemplatePath = 'F:\CI\Templates\WinBuild'`. With three template families now in production (WinBuild2025, WinBuild2022, LinuxBuild2404), the default points at a directory that either does not exist or is the wrong one. An operator running the default-parameter backup before a template refresh will silently back up nothing useful, then refresh the real template, then have no rollback. This is an operational time bomb. GPT-5.5 ranks it HIGH; I concur. My own analysis flagged the script's existence as Complete in Section 2 without auditing the default — I missed the path drift.
+
+### 2.8 HIGH: "Failure path does not collect guest diagnostics before destroying the VM"
+
+**Verdict: Correct in fact, debatable in priority.**
+
+[scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) enters its `catch`/`finally` and proceeds directly to `Remove-BuildVM.ps1` without attempting partial log/artifact collection from the running guest. This contradicts the failure-scenario table in [docs/CI-FLOW.md](../docs/CI-FLOW.md). However, GPT-5.5 ranks this HIGH, equal with the secret-leak issues. I would put it MEDIUM at most. For a single-operator homelab, when a build fails and the VM is destroyed, the JSONL phase events + the `Write-Host` transcript in `F:\CI\Logs\$JobId\invoke-ci.log` already capture more failure context than most commercial CI systems retain. The missing "best-effort guest log dump" is a quality-of-life improvement, not a HIGH operational issue.
+
+### 2.9 HIGH: "Test plan uses PS7-only syntax and wrong parameter names"
+
+**Verdict: Correct but already-known.**
+
+[docs/TEST-PLAN-v1.3-to-HEAD.md](../docs/TEST-PLAN-v1.3-to-HEAD.md) does contain `ForEach-Object -Parallel` and `-RepositoryUrl` (the real param is `-RepoUrl`). This is documentation-only drift, not production breakage. GPT-5.5 ranks HIGH; I would put MEDIUM. The bar for HIGH should be "actively breaks production or compromises trust at runtime". A wrong-parameter-name in a test plan breaks the operator's afternoon, not the system. Quick-wins #6 and #7 in the GPT-5.5 list correctly call out the fix; the severity rating is the only quibble.
+
+### 2.10 HIGH: "Shared cache is not wired into the top-level workflow path"
+
+**Verdict: Correct.**
+
+[gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml) does not expose `use-shared-cache`. [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) does not forward a `UseSharedCache` parameter to `Invoke-RemoteBuild.ps1`. The HGFS shared-folder mechanism exists at the lower layer (per [scripts/Set-TemplateSharedFolders.ps1](../scripts/Set-TemplateSharedFolders.ps1)), so the feature can be wired in by adding one input and one parameter pass-through. My own analysis listed shared HGFS caches as a security concern (§5.4 cache poisoning) but did not call out the wiring gap. GPT-5.5 has the operational insight I missed.
+
+### 2.11 MEDIUM: "Windows readiness only checks TCP 5986, not authenticated WinRM"
+
+**Verdict: Correct.**
+
+[scripts/Wait-VMReady.ps1](../scripts/Wait-VMReady.ps1) confirms ready when `Test-NetConnection -Port 5986` returns true. WinRM listener can be bound and accepting TCP before HTTPS handshake / Basic auth is fully operational, particularly on a cold Windows guest where `WinRM service` starts before TrustedHosts and certificate bindings finalise. The fix (optional `Invoke-Command { 'ready' }` post-TCP-open) is correct. I did not catch this in my own analysis, which is a clear miss on my side.
+
+### 2.12 MEDIUM: "Watch-DiskSpace.ps1 webhook payload includes emoji"
+
+**Verdict: Correct.**
+
+Verified at [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1) line ~95: `$body = @{ content = ":warning: **CI Disk Alert** — $msg" }`. The Discord `:warning:` shortcode renders as the warning glyph in the Discord client. The user's documented preference (in memory) is no emoji. GPT-5.5 catches it; my own analysis did not.
+
+### 2.13 MEDIUM: "Ubuntu cloud VMDK download is not hash-verified"
+
+**Verdict: Correct.**
+
+[template/Deploy-LinuxBuild2404.ps1](../template/Deploy-LinuxBuild2404.ps1) downloads the Ubuntu cloud image without SHA256 verification. A man-in-the-middle at template-build time (or a compromised mirror) substitutes a malicious base, and every Linux build VM inherits that compromise. My own analysis covered SHA256 pinning for **toolchain** installers (§5.7/§6.8) but did not call out the **base image** as a separate supply-chain channel. GPT-5.5 makes the correct distinction.
+
+### 2.14 LOW: "Deprecated runner installer remains likely to drift"
+
+**Verdict: Correct, both analyses concur.**
+
+[runner/Install-Runner.ps1](../runner/Install-Runner.ps1) is marked deprecated but present. Both reviewers flag it. Action: delete.
+
+### 2.15 Summary of verification
+
+Out of 18 verifiable factual claims I cross-checked, 16 are correct, 1 is partially correct with overstated severity (composite action outputs), and 1 is overstated in priority (failure-path diagnostics). That is a high accuracy rate. GPT-5.5 is a credible technical reviewer for this codebase.
+
+---
+
+## 3. Omissions
+
+What GPT-5.5 missed that my own analysis caught:
+
+1. **`act_runner` service-account vs SSH alias mismatch** (my §8.2 HIGH). If [Setup-Host.ps1](../Setup-Host.ps1) installs `act_runner` as a Windows service running under `SYSTEM`, the `~/.ssh/config` alias `gitea-ci` referenced in [gitea/workflows/build-nsInnoUnp.yml](../gitea/workflows/build-nsInnoUnp.yml) (`repo-url: 'ssh://gitea-ci/Simone/...'`) lives in the *interactive user's* `~/.ssh/config`, not `SYSTEM`'s. This is a runtime-reachable bug: every Linux Mode 2 clone fails with "unknown host gitea-ci" until the alias is reinstalled in `C:\Windows\System32\config\systemprofile\.ssh\config`. GPT-5.5 never mentions this. It is potentially HIGH-severity and definitely worth a verification step.
+
+2. **`Measure-CIBenchmark.ps1` uses `getGuestIPAddress` instead of `guestVar ci-ip`** (my §3.3, §11.3). GPT-5.5 mentions this almost as a footnote ("It still uses `getGuestIPAddress` rather than the newer `guestinfo.ci-ip` path"), but does not connect it to the larger issue: the benchmark measures a different IP-discovery path than production, so benchmark results do not represent real timing. This makes capacity-planning data unreliable.
+
+3. **`Validate-DeployState.ps1` does not assert `ci-report-ip.service` presence on Linux templates** (my §3.5, §6 issue list HIGH). The systemd unit writing `guestinfo.ci-ip` is the primary IP-discovery channel for Linux. If a template refresh forgets the unit, every Linux job silently falls back to the 120-second `getGuestIPAddress` timeout. GPT-5.5 does not mention this dependency at all.
+
+4. **`capacity: 4` is unvalidated** as a first-class CRITICAL issue (my §1 top priority, §6.1). GPT-5.5 mentions "For capacity 4, this is probably reliable enough after one fix: automatic stale lock cleanup," which is too easy. Whether four parallel `Invoke-CIJob.ps1` invocations actually behave correctly — under DHCP lease contention, under simultaneous `vmrun start`, under the cumulative ~6-minute pre-build serialization — has not been measured. The honest engineering position is: either run the burn-in or set `capacity: 1` until validated. GPT-5.5 lets this slide.
+
+5. **Hardcoded `N:\Code\Workspace\Local-CI-CD-System\scripts` in [gitea/actions/local-ci-build/action.yml](../gitea/actions/local-ci-build/action.yml)** (my §11.4, §13 quick win #4). GPT-5.5 notes path drift in setup/backup but misses that the composite action itself contains a hardcoded clone path. Move the host repo and the action breaks.
+
+6. **PS 7 strategic question** (my §15.8). My analysis raises this and explicitly counter-argues that the PS 5.1 mandate is the right homelab choice today. GPT-5.5 takes PS 5.1 as a fixed constraint and never considers whether the constraint deserves revisiting. This is a stylistic difference, not a defect, but the "what would I change" section in my own analysis is a strategic-thinking layer GPT-5.5 omits entirely.
+
+7. **The 4-minute pre-build serialization under capacity: 4** (my §3.3). At ~60-90 seconds per IP-acquire phase, four concurrent jobs serialize ~6 minutes of pre-build wait for the last one. The build phase is parallel after that. GPT-5.5 does not work this math.
+
+What both of us missed:
+
+1. **VMware shared-folder write semantics in detail**. Both analyses flag HGFS cache poisoning at MEDIUM. Neither verifies which specific shared folders are configured in the template VMX and whether the NuGet/pip cache directories are writable from the guest by default. The actual remediation depends on those specifics.
+
+2. **Gitea Actions secret masking under base64/hex transforms**. Neither analysis quantifies the masking limitation. If a workflow author base64-encodes a secret before passing it through `extra-guest-env-json`, Gitea's string-match masking misses the encoded value in logs. Worth a one-liner in security docs.
+
+3. **`vmrun` invocation under simultaneous PowerShell processes**. Both of us trust that `vmrun.exe` is process-safe. I have not seen a documented assertion of this, and the VMware Workstation product is historically single-user single-instance. Under capacity 4, four PowerShell processes each invoke `vmrun start` simultaneously. The IP lock serializes the user-visible flow, but native-tool concurrency safety is an unstated assumption.
+
+4. **Network namespace / VMnet8 saturation under load**. With four concurrent Windows builds each downloading NuGet packages and four concurrent Linux builds each running `apt update`, the NAT outbound bandwidth is a single shared resource. No analysis mentions this.
+
+5. **`act_runner` log rotation**. Both of us treat act_runner's own log file as a fire-and-forget concern. On a multi-month homelab, that file grows. Neither analysis mentions rotation.
+
+---
+
+## 4. Over-Engineered or Excessive Suggestions
+
+The GPT-5.5 list is generally restrained. The suggestions that drift toward over-engineering:
+
+1. **"Use an askpass helper or temporary credential file created on the guest with chmod 600, run git with GIT_ASKPASS or http.extraHeader from a file/stdin, then shred/delete it"** (CRITICAL #3 Linux PAT fix). This is a four-moving-parts mitigation when a one-line `http.extraHeader=Authorization: Basic <base64>` (mirroring the existing Windows path) gives equivalent or better security. Smell: enterprise-pattern over-think. The simpler fix has fewer failure modes.
+
+2. **"Add lock owner metadata into the lock file"** (HIGH stale vm-start.lock fix). The orchestrator is single-instance per host. The lock file's existence is sufficient signal; adding JSON metadata (PID, hostname, started-at) is a small but real complication that pays back only if the system grows multi-host. For homelab scope, just delete the file if older than 30 minutes. The PID-based liveness check is enterprise-runtime territory.
+
+3. **"Per-phase duration summary, free disk before and after job, clone directory size at teardown, VM start lock wait time, guest IP detection method, cleanup-failure count, Gitea runner online API status"** (Section 8 missing metrics). This is the full nine yards of observability. For a homelab, the existing JSONL + Event Log + webhook is already more than most commercial CI has. The summary table at job-end (Quick Win in my analysis, also in GPT-5.5's NICE-TO-HAVE) is the highest-value subset. The rest is metrics-for-metrics'-sake.
+
+4. **"Standardize names in docs and scripts: CI-DiskSpaceAlert, CI-DiskAlert, CI-RunnerHealth"** (MEDIUM Event Log sources). GPT-5.5 lists three target names that are themselves inconsistent (`CI-DiskSpaceAlert` and `CI-DiskAlert` in the same sentence). The right fix is to pick one and propagate; the request shape is correct, the example list contradicts itself.
+
+5. **"Add optional `-GiteaUrl` and `-TokenTarget` to query runner status"** (NICE-TO-HAVE Gitea API check). The PAT used for API queries needs to be stored in Credential Manager, the API endpoint can change between Gitea versions, and the value-add over local service status is incremental. This is a reasonable second-phase improvement; calling it out at all in a "homelab" review is borderline.
+
+6. **"Treat templates as release artifacts. Back them up, version snapshots, run a smoke build, then promote by updating runner config"** (Section 15 architectural recommendation). The shape is correct but the language drifts toward release-engineering vocabulary that does not match homelab scope. The practical translation — `Backup-CITemplate.ps1` → refresh → `Test-CITemplateSmoke.ps1` → update `runner/config.yaml` — is fine, but does not need the "release artifacts" framing.
+
+7. **"Pin Git/7-Zip/Ubuntu immediately"** (MEDIUM hash pinning). For a private homelab consuming only the original vendor URLs over TLS, the probability of a successful supply-chain substitution is genuinely low. Time-to-pin is non-trivial (correct SHA256 must be tracked per installer version, which then becomes an upgrade-blocker). For a homelab, accepting unverified TLS-fetched installers from `python.org`, `7-zip.org`, `microsoft.com` is defensible. The "immediately" elevates urgency beyond what threat-modelling supports.
+
+None of these are catastrophically over-engineered. GPT-5.5 stays mostly in scope. But the cumulative drift is real: a master plan that adopts every GPT-5.5 suggestion uncritically will accumulate enterprise-shaped barnacles.
+
+---
+
+## 5. Architectural Conflicts
+
+GPT-5.5's recommendations are mostly consistent with system constraints. Two minor conflicts:
+
+1. **"Move bounded native process execution, IPv4 validation, and stale state cleanup into `_Common.psm1`"** (§3 architecture). The directive is sound, but `Invoke-VmrunBounded` as it exists in some deploy scripts uses `Wait-Process -Timeout` plus `Stop-Process`. On PS 5.1 / Windows PowerShell, `Wait-Process -Timeout` is reliable, but the `Stop-Process` afterwards does not guarantee `vmrun.exe`'s child `vmware-vmx.exe` process is cleaned up. The architectural fix is correct in spirit but glosses over the cleanup semantics of native VMware processes. A complete implementation would also locate the child PID and force-terminate. GPT-5.5 does not flag this nuance.
+
+2. **"Use `StrictHostKeyChecking=accept-new` and a CI-specific known_hosts file under `F:\CI\State`"** (MEDIUM SSH host-key handling). The directive is correct for CI jobs. But `accept-new` requires OpenSSH 7.6+; the Windows 11 built-in OpenSSH client is OpenSSH for Windows 8.x+, which supports it. PS 5.1 itself does not constrain this. On VMnet8 with template-controlled host keys, this is fine. No real conflict, but worth noting that the alternative `UserKnownHostsFile=F:\CI\State\known_hosts` with `StrictHostKeyChecking=yes` plus a known-hosts seed step at template-prepare time is the stricter option.
+
+The other GPT-5.5 recommendations respect PS 5.1, VMware Workstation single-host topology, and the headless-host model.
+
+---
+
+## 6. Incorrect Assumptions
+
+1. **"The current orchestrator now primarily reads `guestinfo.ci-ip` and uses `getGuestIPAddress` as fallback"** (Section 2). This is technically correct, but GPT-5.5 does not verify the guest-side dependency: a `ci-report-ip.service` (or equivalent on Windows) must exist in the template to publish `guestinfo.ci-ip`. Section 6 of my own analysis flags this; GPT-5.5 takes the channel for granted.
+
+2. **"Cleanup happens after `Invoke-RemoteBuild.ps1` success only"** (Section 2 inconsistency note about docs vs implementation). GPT-5.5 conflates "artifact collection happens only after successful build" with "cleanup happens only after success." The cleanup (Remove-BuildVM) runs in `finally`, so it runs whether build succeeded or failed. The doc/reality drift is only about artifact collection, not cleanup. Minor.
+
+3. **"For capacity 4, [the IP lock is] probably reliable enough after one fix: automatic stale lock cleanup"** (Section 3). The assertion "probably reliable enough" is unsupported. Whether DHCP collisions occur under four-way contention, whether `vmrun start` is concurrency-safe, whether the 120-second IP-acquire deadline holds when host CPU is contended — none of this has been measured. The correct stance is "unknown until burn-in."
+
+4. **"`scripts/_Transport.psm1` covers SSH helpers only, while `scripts/_Common.psm1` covers WinRM session options and vmrun. This is acceptable..."** (Section 3). This naming is slightly misleading. `_Transport.psm1` reads as a generic transport abstraction but contains only SSH helpers. The name is asymmetric with `_Common.psm1`'s WinRM helpers. GPT-5.5 calls this out but then accepts it. I find the asymmetry more bothersome — the symmetric option would be either `_SshTransport.psm1` + `_WinrmTransport.psm1` or a single `_Transport.psm1` covering both. Style preference, not a defect.
+
+5. **"VS Build Tools 2026 (MSBuild 18.5 / v145), .NET SDK 10"** (cited in [AGENTS.md](../AGENTS.md) and implicitly in GPT-5.5's Windows toolchain section). These version numbers correspond to future/unreleased Microsoft products as of the workspace's stated date. GPT-5.5 takes them at face value without questioning whether the project's stated environment dates and the actual installer URLs in [template/Install-CIToolchain-WinBuild2025.ps1](../template/Install-CIToolchain-WinBuild2025.ps1) are consistent. Probably out of scope, but a careful reviewer should at least note this.
+
+6. **"Composite action correctly passes most inputs through env vars to reduce shell injection risk"** (Section 5). Correct. But GPT-5.5 then says "`extra-guest-env-json` itself is an env var containing secrets; ensure act_runner does not echo it." act_runner does not echo env vars by default. The risk is the downstream usage inside [scripts/Invoke-RemoteBuild.ps1](../scripts/Invoke-RemoteBuild.ps1) (already flagged), not act_runner itself. Minor framing slip.
+
+---
+
+## 7. Priority Validation
+
+| GPT-5.5 Severity | Item                                 | My Verdict                  | Rationale                                                                                                      |
+| ---------------- | ------------------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| CRITICAL         | Composite action outputs structure   | Should be HIGH              | Step-level outputs work today; only caller-facing action interface is broken. Latent, not active.              |
+| CRITICAL         | Linux extra guest env secret logging | CRITICAL (concur)           | Active leak path.                                                                                              |
+| CRITICAL         | Linux Mode 2 PAT in SSH command      | HIGH-CRITICAL boundary      | PAT visibility limited to host argv + guest /proc. Real but bounded. I would put HIGH; CRITICAL is defensible. |
+| HIGH             | vmrun unbounded calls                | HIGH (concur)               |                                                                                                                |
+| HIGH             | Stale vm-start.lock                  | HIGH (concur)               |                                                                                                                |
+| HIGH             | Setup-Host stale dirs                | HIGH (concur)               |                                                                                                                |
+| HIGH             | Backup default path                  | HIGH (concur)               |                                                                                                                |
+| HIGH             | Failure-path diagnostics             | Should be MEDIUM            | Quality-of-life, not operational-trust.                                                                        |
+| HIGH             | Test plan PS7 / wrong params         | Should be MEDIUM            | Documentation-only.                                                                                            |
+| HIGH             | Shared cache not wired               | Should be MEDIUM            | Documented feature missing, performance impact only.                                                           |
+| MEDIUM           | JobId not sanitized                  | Should be LOW               | Local-only attack surface in single-tenant homelab.                                                            |
+| MEDIUM           | Wait-VMReady TCP-only check          | MEDIUM (concur)             |                                                                                                                |
+| MEDIUM           | CI-FLOW doc claims partial artifacts | Should be LOW               | Pure docs.                                                                                                     |
+| MEDIUM           | Validate-SetupState PasswordExpires  | MEDIUM (concur)             | Validation failure mode.                                                                                       |
+| MEDIUM           | Ubuntu VMDK no hash                  | MEDIUM (concur)             |                                                                                                                |
+| MEDIUM           | Installer hash placeholders          | MEDIUM (concur for homelab) |                                                                                                                |
+| MEDIUM           | Event Log / task name drift          | Should be LOW               | Tests fail not scripts.                                                                                        |
+| MEDIUM           | _Transport.psm1 host-key handling    | MEDIUM (concur)             |                                                                                                                |
+
+Items I would add at HIGH that GPT-5.5 missed: `act_runner` SYSTEM-vs-user SSH alias mismatch (verifiable, runtime-reachable), `ci-report-ip.service` missing from `Validate-DeployState.ps1` (silent 120 s timeout), `capacity: 4` burn-in not run (concurrency claim unmeasured).
+
+Items I would demote from CRITICAL: composite action outputs (real but contained to caller interface only).
+
+---
+
+## 8. Pragmatic Improvements
+
+GPT-5.5's recommendations, recast for homelab-pragmatic adoption:
+
+1. **Composite action outputs**: Move both `artifact-path` and `artifact-name` to a top-level `outputs:` block and remove the duplicate `artifact-name` declaration. Keep the inner `Out-File $env:GITHUB_OUTPUT` lines; they continue to drive step-level outputs that the upload step depends on. 20 minutes.
+
+2. **Linux secret redaction**: Replace `Write-Host "[Invoke-RemoteBuild] Running build: $buildCmd"` with `Write-Host "[Invoke-RemoteBuild] Running build (env vars redacted): cd '$GuestLinuxWorkDir' && <build-command>"`. Do NOT log the env prefix at all. Move from CRITICAL fix to one-line change. 5 minutes.
+
+3. **Linux PAT injection**: Mirror Windows `http.extraHeader=Authorization: Basic <base64>` via `git -c http.extraHeader=...`. Do not pursue askpass helper. 30 minutes including a test.
+
+4. **vmrun bounded wrapper**: Move `Invoke-VmrunBounded` into `_Common.psm1`, use for `start`, `stop`, `deleteVM`. Skip `list`, `readVariable`, `getGuestIPAddress` — those are short-running calls and the wrapper adds overhead. Bounded scope. 45 minutes.
+
+5. **Stale lock cleanup**: Add a 5-line block to [scripts/Invoke-RetentionPolicy.ps1](../scripts/Invoke-RetentionPolicy.ps1) and to a startup step in [scripts/Cleanup-OrphanedBuildVMs.ps1](../scripts/Cleanup-OrphanedBuildVMs.ps1) that removes `F:\CI\State\vm-start.lock` if older than 30 minutes. No metadata inside the lock file. 15 minutes.
+
+6. **Setup-Host directory list**: Update [Setup-Host.ps1](../Setup-Host.ps1) line 118 directory array to include `Templates\WinBuild2025`, `Templates\WinBuild2022`, `Templates\LinuxBuild2404`, `State`, `State\ip-leases`, `keys`, `Cache\pip`. Remove `Templates\WinBuild`. 5 minutes.
+
+7. **Backup default**: Change [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) default to `'F:\CI\Templates\WinBuild2025'`. Add a `-AllTemplates` switch that iterates all `Templates\*` directories. 20 minutes.
+
+8. **Test plan**: Replace `ForEach-Object -Parallel` with `1..4 | ForEach-Object { Start-Job -ScriptBlock { ... } } | Wait-Job | Receive-Job`. Replace `-RepositoryUrl` with `-RepoUrl`. Pure text edit. 15 minutes.
+
+9. **JobId validation**: Add `[ValidatePattern('^[A-Za-z0-9._-]+$')]` to JobId parameter in [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1) and [scripts/New-BuildVM.ps1](../scripts/New-BuildVM.ps1). 5 minutes.
+
+10. **Pre-clone disk check**: Add to Phase 2 of [scripts/Invoke-CIJob.ps1](../scripts/Invoke-CIJob.ps1): `if ((Get-PSDrive F).Free / 1GB -lt 20) { throw "Insufficient disk space" }`. 5 minutes.
+
+11. **Webhook emoji removal**: Replace `:warning:` and similar in [scripts/Watch-DiskSpace.ps1](../scripts/Watch-DiskSpace.ps1) and [scripts/Watch-RunnerHealth.ps1](../scripts/Watch-RunnerHealth.ps1) with `[WARN]` and `[ERROR]`. 5 minutes.
+
+What GPT-5.5 proposes that I would defer or drop:
+
+- Lock-owner metadata in lock file (over-engineered for single-host).
+- Gitea API runner online check (acceptable as deferred).
+- Per-build VMX CPU/RAM override (defer; no demand signal yet).
+- Artifact manifest with hashes (NICE-TO-HAVE for homelab).
+
+---
+
+## 9. Coherence with Homelab Scope
+
+GPT-5.5 generally stays in homelab scope. The phrasing in a few places drifts toward enterprise language ("release artifacts," "golden image promotion flow," "path contract / process contract / secret contract"), but the concrete actions remain proportional. The "Deferred/Optional" list correctly excludes multi-host runner federation, Prometheus/Grafana/Loki, full PKI, enterprise secret vaults, and Kubernetes/ESXi. That is the right scope discipline.
+
+Where GPT-5.5 over-extends:
+
+- The Section 5 enumeration of "what a compromised build VM could reach" reads as enterprise threat-modelling for a single-tenant lab. The threat model is "the operator runs only their own private code." Listing five attack vectors is exhaustive but past the point of useful for the operator's actual risk picture.
+- The Section 8 "missing metrics and alerting" list of seven specific metrics implies a metrics-stack mindset. For homelab, "phase duration printed at job end" subsumes 80% of the value of that list.
+- The Section 15 trio of "path contract / process contract / secret contract" reads as architecture-document framing. For a single-operator homelab, the same content fits in three sentences in [AGENTS.md](../AGENTS.md).
+
+Where GPT-5.5 stays correctly proportional:
+
+- "Keep the single-host design." Correct.
+- "Do not pursue deterministic static IP assignment yet." Correct, and notably more conservative than my own §15.1 which proposes a static-IP pool. GPT-5.5 is right here: the existing lock + lease design after stale-lock cleanup is good enough at this capacity.
+- "Keep security proportional." Correct.
+- "Do not over-abstract WinRM and SSH into a single generic transport." Correct. My own §15.2 proposes generic transport abstraction; GPT-5.5 explicitly counter-argues that "the current clarity is valuable when something fails at 2 AM." GPT-5.5 wins this debate.
+
+---
+
+## 10. Consolidated Recommendation List
+
+After this review, the following GPT-5.5 recommendations should make it into the master plan unchanged:
+
+**Phase 1 — Stabilization (adopt as-is):**
+- Fix composite action outputs (with corrected severity, HIGH not CRITICAL).
+- Redact Linux secret logging (concur CRITICAL).
+- Fix Linux Mode 2 PAT to use `http.extraHeader` (cleaner than GPT-5.5's askpass proposal).
+- Add stale `vm-start.lock` cleanup (concur HIGH).
+- Fix [Setup-Host.ps1](../Setup-Host.ps1) directory list (concur HIGH).
+- Fix [scripts/Backup-CITemplate.ps1](../scripts/Backup-CITemplate.ps1) default path (concur HIGH).
+- Pre-clone disk space gate (concur).
+- Test plan PS5.1 + parameter name corrections (demoted to MEDIUM).
+- Real Windows + Linux VM smoke build via composite action (concur).
+
+**Phase 2 — Adopt with modification:**
+- vmrun bounded wrapper: scope to `start`/`stop`/`deleteVM`, not all native calls.
+- Failure-path diagnostics: implement as a single `Get-GuestDiagnostics` helper, MEDIUM not HIGH.
+- Shared cache wiring through composite action: concur, add as Phase 2.
+- Event Log / task name standardization: pick one canonical set, propagate.
+- Phase duration summary at job end: concur (lighter than full metrics layer).
+
+**Adopt at LOW priority:**
+- Webhook emoji removal.
+- Delete deprecated [runner/Install-Runner.ps1](../runner/Install-Runner.ps1).
+- Docblock HTTPS/5986 corrections in Validate-* scripts.
+- Benchmark JSON shape vs test plan.
+
+**Drop or defer indefinitely:**
+- Lock-owner metadata inside lock file.
+- Gitea API runner online check.
+- Per-build VMX CPU/RAM override.
+- Artifact manifest with hashes.
+- Full SHA256 pinning for installers (acceptable as deferred for homelab).
+- Smoke build automation as a separate `Test-CITemplateSmoke.ps1` (combine with capacity burn-in instead).
+
+**Add from my own analysis (GPT-5.5 missed these):**
+- `act_runner` service-account vs SSH alias mismatch verification (HIGH).
+- `ci-report-ip.service` presence check in [template/Validate-DeployState.ps1](../template/Validate-DeployState.ps1) (HIGH).
+- `capacity: 4` burn-in or downgrade (CRITICAL).
+- Hardcoded `N:\Code\Workspace\...` in composite action (MEDIUM).
+- `Measure-CIBenchmark.ps1` use of `getGuestIPAddress` aligned with production path (MEDIUM).
+
+---
+
+## 11. Comparison with My Own Analysis
+
+Where GPT-5.5 outperforms my analysis:
+
+1. **Per-file scrutiny in Section 4**. GPT-5.5 walks 20+ files explicitly and catches small defects (PasswordExpires assumption in `Validate-SetupState.ps1`, `Measure-CIBenchmark.ps1` JSON schema vs test plan, emoji in webhook payloads, `Watch-DiskSpace.ps1` Event Log source name drift). My analysis is structured around themes; I missed those concrete file-level facts.
+2. **Stale vm-start.lock impact on first-job-after-reboot UX**. My §6.1 verified the lock-handle path is correct on graceful exit but missed the file-existence-after-crash concern. GPT-5.5 makes this explicit.
+3. **Setup-Host directory list audit**. I caught the password documentation drift; I missed the directory-list drift. GPT-5.5 enumerates exactly which directories are missing.
+4. **Backup-CITemplate default path audit**. I listed the script as Complete without checking the default. GPT-5.5 actually opened the file and read line 48.
+5. **Shared cache wiring gap**. I treated shared cache as a security concern; GPT-5.5 treats it as a wiring/operability concern. Both are valid; GPT-5.5's framing is more actionable.
+6. **CI-FLOW doc vs reality drift on partial-artifact-on-failure**. I did not audit `CI-FLOW.md` against the orchestrator's actual `catch` flow. GPT-5.5 did.
+7. **Wait-VMReady TCP-only check**. Concrete defect I missed. GPT-5.5 caught.
+8. **Ubuntu VMDK hash absence as separate channel from toolchain hash placeholders**. I lumped these; GPT-5.5 separates them, which is correct.
+9. **Linux extra-env redaction at CRITICAL severity**. I had this at MEDIUM. GPT-5.5's CRITICAL is more defensible if any production workflow currently injects a secret via `extra-guest-env-json`.
+
+Where my analysis outperforms GPT-5.5:
+
+1. **`act_runner` SYSTEM-account vs `~/.ssh/config` alias**. My §8.2 HIGH. GPT-5.5 misses entirely. This is a verifiable runtime-reachable bug.
+2. **`capacity: 4` burn-in or downgrade as CRITICAL**. My §1 top priority. GPT-5.5 minimizes this to "probably reliable enough after one fix."
+3. **`ci-report-ip.service` presence check in template validation**. My §3.5. GPT-5.5 omits this dependency chain entirely.
+4. **`Measure-CIBenchmark.ps1` measures a different IP path than production**. My §3.3. GPT-5.5 mentions in passing but does not connect to capacity-planning credibility.
+5. **Hardcoded `N:\Code\Workspace\...` in composite action**. My §8.1. GPT-5.5 catches path drift in setup/backup but not in the action itself.
+6. **The 4-minute pre-build serialization math**. My §3.3 works the arithmetic. GPT-5.5 does not.
+7. **Section 15 strategic-thinking layer ("What I Would Change")**. My analysis includes a counterfactual section (static IP allocation, transport abstraction, configuration centralization, JSONL→SQLite sink, schema validation, integration-test-first, structured logging helper, PS 7 reconsideration, validation in orchestrator, drop Mode 1). GPT-5.5 has architectural recommendations but does not run a true counterfactual.
+8. **OWASP Top 10 mapped explicitly**. My §5.7 walks A01-A10 explicitly. GPT-5.5 covers security thematically without the framework. Either is fine for homelab; the framework view makes audit conversations easier.
+9. **Honest grade with per-dimension breakdown**. My Final Verdict gives A-/B+/B/B-/C grades per dimension. GPT-5.5 gives single-number scores (82/78/72/77) without showing the dimensions. My breakdown is more diagnostically useful.
+
+Complementarity:
+
+GPT-5.5 is the better **per-file auditor**. Its strength is reading scripts one at a time and surfacing small concrete defects. The Section 4 enumeration is exactly what a careful code reviewer produces.
+
+My analysis is the better **systems-level interrogator**. It questions claims (capacity: 4 unvalidated), traces cross-file dependencies (SSH alias vs service account, `ci-report-ip.service` vs orchestrator IP discovery), and works the strategic counterfactual.
+
+Combined, the two reviews cover the codebase better than either alone. The master plan should:
+
+- Adopt GPT-5.5's Section 4 per-file findings nearly verbatim as the action item list.
+- Adopt my §6.1 (capacity validation), §8.2 (service account verification), §3.5 (ci-report-ip.service check) as the missing critical items.
+- Use my Section 15 as the long-horizon strategic background that informs but does not block Phase 1.
+- Use GPT-5.5's Phase 1/2/3/Deferred phasing as the roadmap skeleton.
+
+---
+
+## 12. Closing
+
+The GPT-5.5 analysis is a credible, accurate, well-organised technical review with a small number of severity miscalibrations and one notable omission set (the service-account / ssh-alias / ci-report-ip.service / capacity-burn-in cluster). It would be perfectly defensible to adopt the GPT-5.5 report as the primary working document for the next stabilization pass, provided the missing items above are appended.
+
+The honest verdict on GPT-5.5's verdict ("strong homelab CI/CD system... last tightening pass between an impressive lab build and a reliable daily tool") is: correct, fair, and consistent with the evidence. I would sign that conclusion.
+
+The honest verdict on my own analysis vs GPT-5.5: comparable overall, complementary in coverage. Neither replaces the other. The combination is stronger than either alone, which is exactly the value proposition of running two independent reviews.
+
+---
+
+*End of cross-review. Word count: approximately 5,400.*

plans/idea-1-python-rewrite.md

@@ -0,0 +1,208 @@
+# Fase A — Rewrite in Python
+
+> **Stato**: piano esecutivo (parte committed della roadmap).
+> Prerequisito di [Fase B](idea-2-linux-host.md). Vedi [overview](ideas-overview.md).
+> Baseline: ~13.000 righe PowerShell 5.1 (41 file `.ps1` + 2 `.psm1`), 2 script
+> bash, 5 workflow Gitea Actions.
+
+---
+
+## 1. Obiettivo
+
+Riscrivere host orchestrator + script di gestione VM in **Python 3.11+**,
+**con design cross-platform fin dall'inizio** (la Fase B trasferirà l'host
+su Linux Mint senza riscrivere il core).
+
+Vincoli mantenuti:
+
+- runtime act_runner + Gitea (consuma comandi via shell, agnostico al linguaggio)
+- template VM (Windows con WinRM, Linux con SSH)
+- VMware Workstation Pro come hypervisor (`vmrun` invariato)
+- formato artifact e layout di storage
+- workflow YAML esistenti (`gitea/workflows/*.yml`) — cambia solo la `shell:`
+  e il comando invocato
+
+Il punto di ingresso `Invoke-CIJob.ps1` viene sostituito da
+`python -m ci_orchestrator job ...`, invocato da
+`gitea/actions/local-ci-build/action.yml`.
+
+---
+
+## 2. Decisioni di design forzate dal target Linux futuro
+
+Per evitare un doppio porting in Fase B, il codice Python deve rispettare
+da subito queste regole:
+
+| Regola                                                | Implementazione                                                                                          |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Nessun path hardcoded                                 | Tutti i path via `pathlib.Path` + variabili ambiente (`CI_ROOT`, `CI_TEMPLATES`, `CI_BUILD_VMS`, `CI_ARTIFACTS`, `CI_KEYS`) con default in un file `config.toml`. |
+| Path-binari astratti                                  | `vmrun`, `ssh`, `scp` cercati via `shutil.which()` con fallback a env var (`VMRUN_PATH`); default `vmrun.exe` su Windows, `vmrun` su Linux. |
+| Nessuna API Windows-only nel core                     | `keyring` (cross-platform), `paramiko` (no openssh client esterno), `pypsrp` (no `New-PSSession`).      |
+| Astrazione hypervisor                                  | Interfaccia `VmBackend` (Protocol) con metodi `clone_linked`, `start`, `stop`, `delete`, `get_ip`. Implementazione iniziale `WorkstationVmrunBackend`. Hook per `EsxiBackend` futuro (Fase C). |
+| Astrazione credential store                           | Interfaccia `CredentialStore` con backend `KeyringCredentialStore` (default) — funziona uguale su Win Credential Manager e Linux Secret Service. |
+| Logging                                               | `logging` con formatter strutturato; nessun colore ANSI obbligatorio (alcuni runner cattura non li gestiscono). |
+| Path separator nei workflow YAML                      | Lasciare i workflow esistenti per ora; in Fase B si aggiorneranno i path (variabili env già pronte ad assorbire la modifica). |
+
+---
+
+## 3. Mappa di traduzione
+
+| Componente PowerShell                                                | Equivalente Python                                                              |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `Invoke-Vmrun` (wrapper `vmrun.exe` su Win / `vmrun` su Linux)       | `subprocess.run([vmrun, '-T', 'ws', op, *args], check=False, capture_output=True)` |
+| `New-PSSession` + `Invoke-Command` (WinRM)                           | `pypsrp.client.Client(host, username, password, ssl=True, cert_validation=False)` |
+| `Copy-Item -ToSession / -FromSession`                                | `pypsrp.client.Client.copy()` / `fetch()`                                       |
+| `_Transport.psm1` (`ssh.exe` / `scp.exe`)                            | `paramiko.SSHClient` / `paramiko.SFTPClient`                                    |
+| Credential Manager (`BuildVMGuest`, `GiteaPAT`)                      | `keyring.get_credential('BuildVMGuest', None)`                                  |
+| Pester                                                                | `pytest` + `pytest-mock`                                                        |
+| PSScriptAnalyzer                                                     | `ruff` + `mypy --strict`                                                        |
+| `Write-Host`                                                         | `logging.getLogger(__name__).info(...)`                                         |
+| `ConvertTo-Json` per stato job                                       | `json.dumps()` su dataclass                                                     |
+| Workflow YAML                                                        | invariati in Fase A                                                             |
+| Script `.sh` in `gitea/burnin-dummy/`                                | invariati (girano nel guest Linux)                                              |
+
+---
+
+## 4. Cosa NON viene portato in Python
+
+Gli script `template/` (`Prepare-*.ps1`, `Deploy-*.ps1`,
+`Install-CIToolchain-*.ps1`) restano in PowerShell:
+
+- girano una tantum (ricostruzione template)
+- sono fortemente legati a Windows (autounattend.xml, registry, sysprep, WinRM enable)
+- gli script `Install-CIToolchain-WinBuild*.ps1` girano **dentro** il guest
+  Windows e PS è il linguaggio nativo lì
+
+In Fase B questi script restano richiamabili da host Linux con `pwsh` 7
+quando serve ricostruire un template Windows (operazione rara, anche manuale).
+
+---
+
+## 5. Strategia di migrazione: strangler fig in 4 step
+
+Sequenza obbligata. Ad ogni step, gli script PS non ancora portati continuano
+a funzionare; la coesistenza è garantita dalla stessa CLI `python -m ci_orchestrator`
+chiamata internamente dagli script `.ps1` man mano che vengono "scavati".
+
+### Step A1 — Bootstrap progetto + moduli core (`_Common`, `_Transport`)
+
+Output:
+- `pyproject.toml`, package `src/ci_orchestrator/`
+- `venv` in `F:\CI\python\venv\`
+- moduli: `config.py` (env + TOML), `vmrun.py` (wrapper), `winrm.py` (pypsrp),
+  `ssh.py` (paramiko), `credentials.py` (keyring), `backends/workstation.py`
+- protocollo `VmBackend` definito
+- test pytest per ognuno (mock `subprocess`, `paramiko`, `pypsrp`)
+
+Validazione: `lint.yml` e `self-test.yml` continuano a passare; nuovi job
+pytest aggiunti al workflow `lint.yml`.
+
+### Step A2 — Script "foglia" (no state condiviso con orchestratore)
+
+Portare in Python (CLI subcommands `python -m ci_orchestrator <cmd>`):
+
+- `Wait-VMReady` → `wait-ready`
+- `Remove-BuildVM` → `vm remove`
+- `Cleanup-OrphanedBuildVMs` → `vm cleanup`
+- `Watch-DiskSpace` → `monitor disk`
+- `Watch-RunnerHealth` → `monitor runner`
+- `Get-CIJobSummary` → `report job`
+
+Per ognuno: il file `.ps1` viene sostituito da uno **shim** di 3 righe che
+chiama `python -m ci_orchestrator <cmd> ...`, così i call site esterni
+(scheduled tasks, ecc.) non si rompono.
+
+### Step A3 — Pipeline di build
+
+Portare in Python:
+
+- `New-BuildVM` → `vm new`
+- `Invoke-RemoteBuild` → `build run`
+- `Get-BuildArtifacts` → `artifacts collect`
+
+Stessa strategia shim per i `.ps1` esistenti.
+
+### Step A4 — Orchestratore + switch workflow
+
+Portare `Invoke-CIJob.ps1` → `python -m ci_orchestrator job`.
+Aggiornare `gitea/actions/local-ci-build/action.yml` per chiamare Python
+direttamente (non più via shim, per ridurre overhead startup).
+
+A questo punto i `.ps1` shim restano come fallback; eliminarli al primo
+ciclo di pulizia successivo.
+
+### Step trasversale A5 — Test e documentazione
+
+Parallelo agli step A1-A4:
+- ogni feature portata ha test pytest che coprono almeno gli scenari
+  documentati negli "errori frequenti" di `AGENTS.md` (#9, #10, #11, #12)
+- `AGENTS.md` aggiornato con sezione "Python development" (venv, stile,
+  pytest, ruff)
+- `docs/ARCHITECTURE.md` aggiornato con il nuovo layout package
+- `README.md` aggiornato con setup Python
+
+---
+
+## 6. Layout repository post-Fase A
+
+```
+src/ci_orchestrator/
+    __init__.py
+    __main__.py            # entry point CLI (click)
+    config.py              # env vars + config.toml loader
+    credentials.py         # CredentialStore protocol + KeyringStore
+    backends/
+        __init__.py
+        protocol.py        # VmBackend Protocol
+        workstation.py     # WorkstationVmrunBackend
+    transport/
+        __init__.py
+        winrm.py           # pypsrp client wrapper
+        ssh.py             # paramiko client wrapper
+    commands/
+        job.py             # ex Invoke-CIJob
+        vm.py              # new / remove / cleanup
+        build.py           # build run
+        artifacts.py       # collect
+        wait.py            # wait-ready
+        monitor.py         # disk / runner
+        report.py          # job summary
+tests/
+    test_backends_workstation.py
+    test_transport_winrm.py
+    test_transport_ssh.py
+    test_commands_job.py
+    ...
+pyproject.toml
+config.example.toml
+scripts/                   # PS legacy (shim sottili durante migrazione)
+template/                  # PS invariati (provisioning template)
+gitea/                     # workflow + actions invariati
+```
+
+---
+
+## 7. Rischi e mitigazioni
+
+| Rischio                                                                                  | Severità | Mitigazione                                                                                            |
+| ---------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `pypsrp` ha edge case con WinRM HTTPS self-signed                                        | Media    | PoC su `wait-ready` come primo deliverable di Step A1 prima di committare al resto.                    |
+| `keyring` sotto SYSTEM account (act_runner service) può non vedere credenziali utente    | Alta     | Già un problema oggi con Credential Manager; documentare l'uso di credenziali a livello machine (DPAPI machine scope su Win, file vault con `age` su Linux). |
+| Perdita di know-how degli "errori frequenti" `AGENTS.md` durante refactor                | Media    | Convertire ognuno (#9, #10, #11, #12) in un test pytest **prima** di rimuovere il `.ps1` corrispondente. |
+| Doppio mantenimento durante la migrazione                                                | Alta     | Strategia shim minimizza la finestra; `lint.yml` deve passare per **entrambi** i mondi (PSSA + ruff).  |
+| Astrazione `VmBackend` over-engineered se Fase C non parte mai                           | Bassa    | Una sola implementazione concreta + Protocol = ~50 righe extra; costo trascurabile.                    |
+| act_runner cattura male l'output Python (encoding UTF-8 vs cp1252 su Win)                | Media    | Forzare `PYTHONIOENCODING=utf-8` in `runner/config.yaml` env.                                          |
+
+---
+
+## 8. Definizione di "fatto" (Fase A)
+
+- [ ] Tutti gli script in `scripts/` portati a Python o ridotti a shim
+- [ ] `Invoke-CIJob.ps1` non più presente nei workflow YAML
+- [ ] `pytest` verde con coverage minima 70% su `src/ci_orchestrator/`
+- [ ] `ruff check` + `mypy --strict` puliti su tutto `src/`
+- [ ] `lint.yml` aggiornato: PSSA per file PS legacy + ruff/mypy per Python
+- [ ] Workflow `build-ns7zip.yml` PASS su matrice Windows + Linux
+- [ ] Smoke test (`Test-Smoke.ps1` o equivalente Python) PASS
+- [ ] Capacity burn-in 4 job concorrenti PASS
+- [ ] `README.md`, `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/HOST-SETUP.md` aggiornati

plans/idea-2-linux-host.md

@@ -0,0 +1,214 @@
+# Fase B — Migrazione host su Linux Mint
+
+> **Stato**: piano esecutivo (parte committed della roadmap).
+> Prerequisito: [Fase A](idea-1-python-rewrite.md) completata.
+> Vedi [overview](ideas-overview.md).
+> Hypervisor scelto: **VMware Workstation Pro Linux** (zero conversione template).
+
+---
+
+## 1. Obiettivo
+
+Spostare l'host CI/CD da Windows 11 + Workstation Pro a **Linux Mint** +
+**Workstation Pro Linux**, mantenendo:
+
+- act_runner / Gitea (binario Linux ufficiale)
+- workflow YAML invariati (path generalizzati via env vars introdotte in Fase A)
+- template VM Windows e Linux **identici** (stessi `.vmx`, `.vmdk`, snapshot)
+- artifact layout (cambia solo la radice: `F:\CI\` → `/var/lib/ci/`)
+- transport WinRM/SSH ai guest (pypsrp + paramiko già cross-platform da Fase A)
+
+Cambia: OS host, service manager, credential store, percorsi, ownership filesystem.
+
+---
+
+## 2. Decisione hypervisor: perché Workstation Pro Linux
+
+Confronto sintetico (decisione presa, non più aperta):
+
+| Opzione                            | Verdetto                                                             |
+| ---------------------------------- | -------------------------------------------------------------------- |
+| **VMware Workstation Pro Linux**   | **SCELTA.** `vmrun` identico, VMX template riutilizzabili 1:1, free per uso personale e commerciale dal 2024. Plumbing-only port. |
+| KVM + libvirt                      | Rimandato. Richiederebbe conversione VMDK→qcow2, virtio injection nei guest Windows, rewrite backend hypervisor. Resta come piano B se Broadcom dismette Workstation. |
+| VirtualBox                         | Scartato. Performance/snapshot inferiori.                            |
+
+---
+
+## 3. Mappa di adattamento
+
+| Componente attuale                                  | Equivalente Linux + Workstation Pro                          |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `vmrun.exe` (`C:\Program Files (x86)\...`)          | `/usr/bin/vmrun` (binario senza `.exe`, installato dal package Workstation) |
+| File `.vmx` / `.vmdk`                               | **identici, copiati così come sono**                         |
+| Snapshot `BaseClean` / `BaseClean-Linux`            | preservati nella copia                                        |
+| `F:\CI\BuildVMs\`                                   | `/var/lib/ci/build-vms/`                                     |
+| `F:\CI\Artifacts\`                                  | `/var/lib/ci/artifacts/`                                     |
+| `F:\CI\Templates\`                                  | `/var/lib/ci/templates/`                                     |
+| `F:\CI\keys\ci_linux`                               | `/etc/ci/keys/ci_linux` (perms `600`, owner `ci-runner`)     |
+| Credential Manager (`BuildVMGuest`, `GiteaPAT`)     | `secret-tool` / GNOME Keyring / KWallet (backend `keyring`)  |
+| WinRM HTTPS verso guest Windows                     | identico (pypsrp parla con WinRM da Linux senza modifiche)   |
+| SSH verso guest Linux                               | identico (paramiko)                                          |
+| act_runner come Windows Service                     | systemd unit `act-runner.service`                            |
+| Task Scheduler (`Register-CIScheduledTasks.ps1`)    | systemd `*.timer` + `*.service` units                        |
+| PowerShell 5.1                                      | `pwsh` 7 (solo per ricostruire template, raro)               |
+| `vmnet8` NAT (`192.168.79.0/24`)                    | `vmnet8` NAT su Workstation Pro Linux (stesso concetto, IP range configurabile) |
+
+---
+
+## 4. Strategia di migrazione
+
+### Step B1 — Setup host Linux Mint in parallelo (no impatto produzione)
+
+- Installazione Linux Mint LTS + aggiornamenti
+- Installazione VMware Workstation Pro per Linux (bundle ufficiale Broadcom)
+- Verifica `vmrun` con una VM di test (clone, start, stop)
+- Configurazione `vmnet8` NAT range coerente o equivalente
+- Creazione utente di servizio `ci-runner` (uid dedicato)
+- Creazione storage layout `/var/lib/ci/{build-vms,artifacts,templates,keys}`
+  con ownership `ci-runner:ci-runner` (mode 750)
+- Installazione Python 3.11+ + venv in `/opt/ci/venv/` con `pip install -e .`
+  del package `ci_orchestrator` portato in Fase A
+
+Validazione: `python -m ci_orchestrator --help` funziona da utente `ci-runner`.
+
+### Step B2 — Trasferimento template VM
+
+- Spegnere i template Workstation sull'host Windows (devono essere
+  fully powered-off — vedi `AGENTS.md` errore #9)
+- Copia bit-by-bit di `F:\CI\Templates\` → `/var/lib/ci/templates/`
+  (`scp -r` o `rsync`)
+- Aprire i `.vmx` su Workstation Linux per registrarli (`vmrun start ... nogui`
+  con stop immediato, oppure `vmrun -T ws snapshot list`) — risolverà
+  eventuali path interni se Workstation li chiede
+- Verifica snapshot presenti: `vmrun listSnapshots <vmx>` deve mostrare
+  `BaseClean` / `BaseClean-Linux`
+- Smoke test manuale: clone linked + start + WinRM/SSH dal host Linux
+
+### Step B3 — Trasferimento credenziali e chiavi
+
+- Copia chiave SSH guest Linux: `F:\CI\keys\ci_linux*` → `/etc/ci/keys/`
+  (mode 600, owner `ci-runner`)
+- Re-store delle credenziali guest Windows nel keyring Linux:
+  `secret-tool store --label='BuildVMGuest' service ci target BuildVMGuest`
+- Re-store Gitea PAT: `secret-tool store --label='GiteaPAT' service ci target GiteaPAT`
+- Verifica via Python: `keyring.get_credential('BuildVMGuest', None)` non None
+
+### Step B4 — Setup act_runner come systemd service
+
+- Download act_runner Linux binary (versione allineata a v1.0.2 o successiva)
+- Registrazione runner verso Gitea con label `windows-build:host` e
+  `linux-build:host` (stesse label di oggi → workflow non cambiano)
+- File unit `/etc/systemd/system/act-runner.service`:
+  - `User=ci-runner`
+  - `WorkingDirectory=/var/lib/ci/runner`
+  - `Environment=PYTHONIOENCODING=utf-8`
+  - env vars `CI_*` per il config Python
+- `systemctl enable --now act-runner.service`
+- Validazione: `journalctl -u act-runner -f` mostra connessione a Gitea OK
+
+### Step B5 — Conversione scheduled tasks → systemd timers
+
+`Register-CIScheduledTasks.ps1` definisce N task periodici. Per ognuno
+creare:
+- `/etc/systemd/system/ci-<task>.service` (oneshot, chiama
+  `python -m ci_orchestrator <cmd>`)
+- `/etc/systemd/system/ci-<task>.timer` (`OnCalendar=...` equivalente)
+- `systemctl enable --now ci-<task>.timer`
+
+Task tipici da convertire:
+- `cleanup-orphaned-vms` (ogni ora)
+- `retention-policy` (giornaliero)
+- `watch-disk-space` (ogni 15 min)
+- `watch-runner-health` (ogni 5 min)
+- `backup-template` (settimanale)
+
+### Step B6 — Cutover
+
+Finestra di manutenzione concordata:
+
+1. Stop act_runner sull'host Windows (`Stop-Service actions-runner`)
+2. Rsync incrementale finale degli artifact recenti:
+   `F:\CI\Artifacts\` → `/var/lib/ci/artifacts/`
+3. Verificare nessun job in coda lato Gitea
+4. Avviare act_runner Linux (`systemctl start act-runner`)
+5. Trigger manuale di un workflow di smoke test
+6. Trigger del workflow matrix `build-ns7zip.yml` (Win + Linux build)
+
+Se PASS → cutover confermato. Se FAIL → rollback (riavvio runner Windows,
+nessun dato è stato distrutto).
+
+### Step B7 — Capacity burn-in sul nuovo host
+
+Eseguire `Test-CapacityBurnIn` (versione Python) con N=4 concorrenti × R=10
+round, sia per template Windows che Linux. Confronto tempi vs baseline
+Windows host pre-migrazione (aspettativa: paragonabili, eventuali differenze
+vanno indagate ma non sono blocker se entro ±20%).
+
+### Step B8 — Decommissioning host Windows (opzionale)
+
+Dopo 1-2 settimane di stabilità sul nuovo host:
+- Backup finale di `F:\CI\` su archivio
+- Spegnimento runner Windows (lasciato installato per un mese come
+  rollback option)
+- Riallocazione hardware
+
+---
+
+## 5. Adattamenti al codice Python (residui dopo Fase A)
+
+Se Fase A ha rispettato le regole di §2 di [idea-1-python-rewrite.md](idea-1-python-rewrite.md),
+il codice **non cambia**. Modifiche residue attese:
+
+- `config.example.toml`: aggiungere sezione `[paths.linux]` con default
+  `/var/lib/ci/...` (la sezione `[paths.windows]` resta per chi ricostruisce
+  template da Win)
+- `runner/config.yaml`: path env vars aggiornati a POSIX
+- Eventuali test pytest che assumevano `Path('F:\\CI')` → usare fixture
+  parametrizzata
+- Workflow `lint.yml`: rimuovere o relegare a job opzionale la parte PSSA
+  (utile solo se si tocca ancora codice PS dei template)
+
+---
+
+## 6. Rischi specifici Fase B
+
+| Rischio                                                                                | Severità | Mitigazione                                                                                  |
+| -------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `vmrun` su Workstation Linux ha differenze sottili nel parsing output `list` / `getGuestIPAddress` | Media    | Test del modulo `vmrun.py` su Linux durante Step B1; eventuali fix dietro feature flag.      |
+| Performance I/O linked clone su filesystem ext4 vs NTFS                                | Bassa    | Misurare con burn-in (Step B7). Eventualmente XFS o BTRFS con CoW per il dataset template.   |
+| `vmnet8` NAT range configurato diversamente su Linux: IP collision con altri host LAN  | Media    | Allineare il range a quello attuale Windows (`192.168.79.0/24`) in `vmware-vmnet.conf`.     |
+| WinRM HTTPS self-signed: pypsrp da Linux può negoziare TLS 1.2 con cipher non supportati dal Windows guest | Media    | Già testato in Fase A (lo stesso codice gira anche da Windows host). Validare con smoke test prima del cutover. |
+| Permessi su `/var/lib/ci/build-vms/`: vmrun gira come `ci-runner` ma deve scrivere VMDK CoW | Media    | ACL POSIX: `setfacl -d -m u:ci-runner:rwX` sulla directory. Test in Step B1.                |
+| `secret-tool` headless: act_runner come systemd service non ha sessione D-Bus per accedere al keyring | Alta     | Usare backend `keyring` file-based + `age`/`sops` (vault file) oppure `keyring.backends.SecretService` con D-Bus user@.service. Decidere in Step B3 con PoC. |
+| Errore #11 `AGENTS.md` (machine-id Linux clone)                                        | Bassa    | Identico comportamento, fix identico (reset machine-id pre-snapshot). Già documentato.       |
+| Errore #12 `AGENTS.md` (stderr nativa + `'Stop'`)                                      | N/A      | Sparisce: il codice non è più PowerShell.                                                    |
+
+---
+
+## 7. Path alternativo "dual-host" (se la Fase B si blocca)
+
+Se durante la migrazione si scopre un blocker grave (es. WinRM da Linux
+non funzionante affidabilmente verso il template Windows specifico), si
+può ripiegare su:
+
+- mantenere host Windows per i job `windows-build:host`
+- usare host Linux Mint solo per `linux-build:host` (label dedicata)
+- runner doppio registrato verso Gitea
+
+Costo: codebase divisa in due ambienti, maggiore overhead operativo.
+**Soluzione di emergenza, non target finale.**
+
+---
+
+## 8. Definizione di "fatto" (Fase B)
+
+- [ ] act_runner gira come systemd service `act-runner.service` su Linux Mint
+- [ ] Tutti i template VM (`WinBuild2025`, `WinBuild2022`, `LinuxBuild2404`)
+      operativi dal nuovo host con snapshot integri
+- [ ] Workflow `build-ns7zip.yml` (matrix Win+Linux) PASS dal nuovo host
+- [ ] Burn-in capacity 4 job concorrenti PASS, tempi entro ±20% del baseline
+- [ ] Storage migrato a `/var/lib/ci/`, host Windows in stand-by come rollback
+- [ ] Tutti i timer systemd attivi e schedulati
+- [ ] Credenziali guest accessibili da `ci-runner` headless
+- [ ] `README.md`, `AGENTS.md`, `docs/HOST-SETUP.md` aggiornati per host Linux
+- [ ] Almeno 1 settimana di esercizio in produzione senza incidenti

plans/idea-3-esxi-support.md

@@ -0,0 +1,179 @@
+# Fase C — Supporto ESXi per le Build VM (futuro)
+
+> **Stato**: **piano differito**, da rivalutare dopo che Fase A
+> ([rewrite Python](idea-1-python-rewrite.md)) e Fase B
+> ([host Linux](idea-2-linux-host.md)) sono stabili in produzione.
+> Vedi [overview](ideas-overview.md).
+>
+> Questo documento esiste per:
+> 1. Garantire che il design di Fase A abbia gli hook corretti
+>    (astrazione `VmBackend`).
+> 2. Avere un piano pronto se/quando si decide di scalare oltre i limiti
+>    dell'host singolo Workstation Pro.
+
+---
+
+## 1. Quando attivare Fase C
+
+Fase C ha senso **solo se** si verifica almeno uno di:
+
+- Saturazione della concorrenza locale (>4 job paralleli regolarmente)
+- Necessità di disaccoppiare hardware CI control plane (ufficio) dal hardware
+  build (rack/datacenter)
+- Disponibilità di hardware ESXi + licenza vSphere Essentials o superiore
+- Richiesta di QoS / resource pool per i job CI vs altri carichi
+
+Se nessuno è vero a 6-12 mesi dal completamento Fase B, **non aprire Fase C**:
+Workstation Pro su Linux copre il caso d'uso e l'overhead operativo di un
+secondo backend non è giustificato.
+
+---
+
+## 2. Architettura prevista
+
+```
+   ┌──────────────┐    ┌─────────────────────────────┐
+   │  Gitea       │    │  ESXi host(s)               │
+   │  act_runner  │    │   ├─ Template Windows (snap BaseClean)        │
+   │ (Linux Mint) │    │   ├─ Template Linux   (snap BaseClean-Linux)  │
+   │              │    │   └─ Datastore: ci-builds  │
+   └──────┬───────┘    └──────────▲──────────────────┘
+          │                       │  vSphere API (443)
+          ▼                       │
+   ┌──────────────────┐           │
+   │ ci_orchestrator  │───────────┘
+   │ (Python, Linux)  │
+   │  ↳ EsxiBackend   │
+   └─────┬────────────┘
+         │ WinRM/SSH
+         ▼
+    Build VM efimera su ESXi
+```
+
+L'host CI Linux (Fase B) continua a esistere come control plane.
+Le build VM girano su ESXi remoto. Il transport WinRM/SSH al guest non
+cambia.
+
+---
+
+## 3. Implementazione: nuovo backend pyVmomi
+
+Sfruttando l'astrazione `VmBackend` introdotta in Fase A:
+
+```python
+# src/ci_orchestrator/backends/esxi.py
+class EsxiBackend(VmBackend):
+    def __init__(self, host: str, user: str, password: str, datastore: str, folder: str): ...
+    def clone_linked(self, template: str, snapshot: str, name: str) -> VmHandle: ...
+    def start(self, vm: VmHandle) -> None: ...
+    def stop(self, vm: VmHandle, hard: bool = True) -> None: ...
+    def delete(self, vm: VmHandle) -> None: ...
+    def get_ip(self, vm: VmHandle, timeout: float) -> str: ...
+```
+
+Selezione backend via env / config:
+
+```toml
+[backend]
+type = "esxi"  # oppure "workstation"
+
+[backend.esxi]
+host = "esxi.lab.local"
+user = "ci-runner@vsphere.local"
+datastore = "ci-builds"
+folder = "ci"
+```
+
+---
+
+## 4. Mappa operazioni Workstation → ESXi
+
+| Operazione                    | Workstation (oggi)                            | ESXi (Fase C, pyVmomi)                                                  |
+| ----------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
+| Linked clone                  | `vmrun clone ... linked -snapshot=BaseClean`  | `vim.VirtualMachineCloneSpec(linkedClone=True, snapshot=ref)`           |
+| Start VM                      | `vmrun start <vmx>`                           | `VirtualMachine.PowerOn()` (Task)                                       |
+| Stop VM                       | `vmrun stop <vmx> hard`                       | `VirtualMachine.PowerOff()` (Task)                                      |
+| Delete VM                     | `vmrun deleteVM <vmx>`                        | `VirtualMachine.Destroy_Task()`                                         |
+| List snapshots                | `vmrun listSnapshots`                         | `VirtualMachine.snapshot.rootSnapshotList`                              |
+| Get guest IP                  | `vmrun getGuestIPAddress`                     | `VirtualMachine.guest.ipAddress` (richiede VMware Tools nei guest)      |
+| Test running                  | `vmrun list`                                  | `VirtualMachine.runtime.powerState == 'poweredOn'`                      |
+
+---
+
+## 5. Setup ESXi richiesto (Step C0)
+
+Prerequisiti hardware/licenza da verificare PRIMA di pianificare:
+
+- **Licenza**: ESXi free **non basta** (le API write sono bloccate dal 2020).
+  Serve almeno **vSphere Essentials** o licenza valutativa rinnovabile.
+- **Hardware**: server con CPU che supporti la versione ESXi target,
+  RAM ≥64 GB, NVMe locale per datastore.
+- **Network**: portgroup dedicato per le build VM, DHCP raggiungibile.
+- **Account**: user dedicato con ruolo custom (datastore, folder, snapshot,
+  power, network — minimo set richiesto da `clone_linked`/`destroy`).
+
+---
+
+## 6. Sequenza implementativa
+
+### C1 — Validazione ambiente
+- Setup hardware ESXi + licenza
+- Account vSphere dedicato
+- Test manuale clone+start+stop via UI vSphere
+- Misurazione tempi di clone (baseline)
+
+### C2 — Implementazione `EsxiBackend`
+- `pip install pyvmomi` aggiunto al `pyproject.toml`
+- `src/ci_orchestrator/backends/esxi.py` implementato
+- Test pytest con `pyvmomi` mock + un test di integrazione
+  opzionale che gira solo se env `CI_TEST_ESXI_HOST` è settata
+
+### C3 — Migrazione template
+- Export OVF dei template Workstation: `ovftool ... template.vmx template.ovf`
+- Import su datastore ESXi: `ovftool template.ovf vi://...`
+- Verifica WinRM/SSH raggiungibili dal control plane verso le VM ESXi
+- Snapshot `BaseClean` / `BaseClean-Linux` ricreati lato ESXi
+
+### C4 — Canary deploy
+- Workflow di test dedicato con label `windows-build:esxi` o
+  config override `backend=esxi`
+- Eseguito quotidianamente per ≥1 settimana
+- Confronto metriche (tempo totale, success rate) vs Workstation backend
+
+### C5 — Rollout selettivo
+- Workflow di produzione spostati uno a uno su backend ESXi
+- Monitoring tempi via `Measure-CIBenchmark` equivalente Python
+- Workstation backend resta disponibile come fallback (basta cambiare config)
+
+### C6 — Adattamenti tooling secondari
+- `Cleanup-OrphanedBuildVMs` esteso per query ESXi folder-scoped
+- `Watch-DiskSpace` esteso a query datastore via API
+- `Backup-CITemplate` sostituito da snapshot ESXi nativi o `ovftool` schedulato
+
+---
+
+## 7. Rischi specifici Fase C
+
+| Rischio                                                                                | Severità | Mitigazione                                                                       |
+| -------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
+| Licenza ESXi free blocca API write (`CloneVM_Task` non autorizzata)                    | **Critica** | Verificare licenza in C1 prima di qualsiasi sviluppo. Procurare vSphere Essentials. |
+| Linked clone su ESXi standalone (no vCenter) ha gap funzionali                         | Alta     | PoC manuale in C1; se gap rilevante, valutare full clone vs linked.               |
+| Tempo clone+poweron+IP > Workstation locale per latenza rete + overhead vSphere        | Media    | Misurare in C1; possibile mitigazione: pool di VM "warm" pre-clonate.             |
+| VMware Tools nel guest non sempre rapide a riportare IP via API                        | Bassa    | Stesso problema oggi (`AGENTS.md` errore #10). Fallback: parse DHCP lease su ESXi via API. |
+| Concorrenza: race condition su naming VM o folder                                      | Media    | Lock per JobId lato orchestrator; suffisso UUID nel nome VM.                      |
+| Cleanup VM orfane più costoso (API call per ogni VM in folder)                         | Bassa    | Riscrivere cleanup come query folder-scoped, non scan globale.                    |
+| Single point of failure: ESXi giù = tutta la CI giù                                    | Media    | Documentare procedura fallback su backend Workstation locale (basta cambio config). |
+| Errore #11 `AGENTS.md` (machine-id identico clone Linux) si ripropone                  | Bassa    | Stessa fix lato template, già documentata.                                        |
+
+---
+
+## 8. Definizione di "fatto" (Fase C)
+
+- [ ] Hardware ESXi + licenza Essentials operativi
+- [ ] `EsxiBackend` implementato, testato (unit + integration test)
+- [ ] Template Windows e Linux importati e funzionanti su ESXi con snapshot
+- [ ] Almeno 1 workflow di produzione in canary su backend ESXi per ≥1 settimana
+      senza regressioni
+- [ ] Documentazione (`docs/HOST-SETUP.md`, `docs/ARCHITECTURE.md`,
+      `AGENTS.md`) aggiornata con istruzioni multi-backend
+- [ ] Procedura di rollback su backend Workstation testata e documentata

plans/ideas-overview.md

@@ -0,0 +1,79 @@
+# Roadmap evolutiva — overview
+
+Decisione presa: implementare **prima Idea 1 (Python) + Idea 2 (host Linux)**
+in sequenza, e **solo dopo** valutare Idea 3 (ESXi).
+
+| Fase | Cosa                                                                               | File di dettaglio                                    |
+| ---- | ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| A    | Rewrite in Python sull'host Windows attuale (codebase cross-platform-ready)        | [idea-1-python-rewrite.md](idea-1-python-rewrite.md) |
+| B    | Migrazione host: Windows 11 + Workstation Pro → Linux Mint + Workstation Pro Linux | [idea-2-linux-host.md](idea-2-linux-host.md)         |
+| C    | (Futuro, condizionato a A+B stabili) Aggiunta backend ESXi                         | [idea-3-esxi-support.md](idea-3-esxi-support.md)     |
+
+---
+
+## 1. Razionale dell'ordine
+
+1. **Idea 1 prima di Idea 2**: scrivere Python *sapendo già* che girerà anche
+   su Linux evita un doppio porting. Tutto il codice nuovo nasce
+   cross-platform (no path hardcoded `F:\`, no `Get-StoredCredential`,
+   no `New-PSSession` come unica via). Idea 2 diventa un'operazione di
+   "swap della base OS" con codice già pronto.
+2. **Workstation Pro su entrambi gli OS**: scegliendo Workstation Pro anche
+   su Linux (binario `/usr/bin/vmrun`, senza `.exe`) si mantiene **lo stesso
+   comando `vmrun` e gli stessi VMX template** — zero conversione VMDK→qcow2,
+   zero rewrite del backend hypervisor. Idea 2 diventa un porting di
+   plumbing (path, service manager, credential store) e non di logica.
+3. **ESXi dopo**: una volta stabilizzato Python + Linux, l'introduzione di
+   ESXi è un nuovo backend dietro un'astrazione `VmBackend` (introdotta
+   già in fase A come hook di design); il core non cambia.
+
+---
+
+## 2. Sinergie sfruttate
+
+- Python (Idea 1) abilita `pypsrp` (WinRM cross-platform), `paramiko` (SSH
+  cross-platform), `keyring` (Credential Manager su Win, Secret Service su
+  Linux): un unico tooling che funziona su entrambi gli host.
+- Tenere VMware Workstation Pro su Linux (Idea 2) elimina la necessità di
+  imparare libvirt/KVM ora; resta come opzione futura se Broadcom dismette
+  Workstation Pro.
+- L'astrazione `VmBackend` introdotta come "design hook" già in Idea 1
+  riduce a costo marginale l'aggiunta del backend ESXi (Idea 3) tramite
+  `pyVmomi`.
+
+---
+
+## 3. Riepilogo prerequisiti per fase
+
+| Fase | Prerequisiti host                                                                                  | Prerequisiti competenze                                 |
+| ---- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| A    | Python 3.11+ su Windows; ambiente venv in `F:\CI\python\venv\`                                     | Python, pytest, pypsrp/paramiko                         |
+| B    | Hardware Linux Mint operativo; VMware Workstation Pro Linux installata; storage analogo a `F:\CI\` | systemd, bash, secret-tool, gestione utente di servizio |
+| C    | Hardware ESXi + licenza Essentials o superiore; account vSphere dedicato                           | pyVmomi, datastore/portgroup management                 |
+
+---
+
+## 4. Criteri di "fase completata"
+
+- **A done**: `Invoke-CIJob.ps1` retired; tutti i job CI passano via
+  `python -m ci_orchestrator job ...`; test pytest verdi; capacity burn-in
+  4 job concorrenti PASS sull'host Windows attuale.
+- **B done**: act_runner gira come systemd service su Linux Mint; tutti i
+  workflow esistenti (Windows + Linux build) PASS dal nuovo host; storage
+  migrato a `/var/lib/ci/`; capacity burn-in PASS.
+- **C done** (se attivata): label `windows-build:esxi` operativa con backend
+  pyVmomi; canary su almeno 1 workflow di produzione per ≥1 settimana
+  senza regressioni.
+
+---
+
+## 5. Cosa fare se A o B falliscono / si bloccano
+
+- **Stop in A**: il sistema PowerShell attuale resta in produzione (rollback
+  banale, niente è stato distrutto). La parte Python già scritta resta come
+  modulo "side-by-side" non utilizzato.
+- **Stop in B**: l'host Windows resta primario; eventuale runner Linux
+  secondario può comunque essere utile per workload sperimentali (path
+  "dual-host" descritto in [idea-2-linux-host.md](idea-2-linux-host.md) §7).
+- **Stop pianificato in C**: nessun impatto — C è opzionale per definizione,
+  Workstation Pro su Linux copre già il caso d'uso primario.

plans/prompt-implementation-plan-A-B.md

@@ -0,0 +1,176 @@
+# Prompt — Generazione piano di implementazione unificato Fase A + Fase B
+
+> Copia-incolla il blocco sotto come messaggio iniziale all'IA che dovrà
+> produrre il piano. L'IA deve avere accesso in lettura al repository
+> `local-ci-cd-system` (in particolare ai file citati nei riferimenti).
+
+---
+
+## Prompt da fornire all'IA
+
+Sei un senior platform/DevOps engineer assegnato al progetto
+**local-ci-cd-system** (CI/CD on-prem basato su Gitea Actions + act_runner +
+VMware Workstation Pro + VM ephemere Win/Linux). Il tuo compito è produrre
+**un singolo documento di piano implementativo dettagliato** che fonde
+**Fase A** (rewrite Python dell'orchestratore) e **Fase B** (migrazione
+host da Windows 11 a Linux Mint) in un'unica roadmap eseguibile, mantenendo
+**hook architetturali compatibili con Fase C** (backend ESXi futuro) senza
+implementarla.
+
+### Contesto obbligatorio da leggere PRIMA di scrivere
+
+Prima di produrre output, leggi e tieni come riferimento:
+
+1. [AGENTS.md](../AGENTS.md) — vincoli host, PowerShell 5.1, errori frequenti
+   (#1–#12). Tutti i punti devono restare validi o essere esplicitamente
+   superati dal piano.
+2. [plans/ideas-overview.md](ideas-overview.md) — razionale, ordine, criteri
+   di "fase completata", strategia di rollback.
+3. [plans/idea-1-python-rewrite.md](idea-1-python-rewrite.md) — Fase A
+   (decisioni di design, mappa di traduzione, step A1–A5, layout repo,
+   rischi, definizione di fatto).
+4. [plans/idea-2-linux-host.md](idea-2-linux-host.md) — Fase B (decisione
+   hypervisor, mappa di adattamento, step B1–B8, rischi, fatto).
+5. [plans/idea-3-esxi-support.md](idea-3-esxi-support.md) — Fase C: leggi
+   solo §2 (architettura) e §3 (backend pyVmomi) per sapere quali hook
+   lasciare aperti nel design.
+6. [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md), [docs/CI-FLOW.md](../docs/CI-FLOW.md),
+   [docs/HOST-SETUP.md](../docs/HOST-SETUP.md), [docs/RUNBOOK.md](../docs/RUNBOOK.md)
+   per capire layout e operatività attuali.
+7. La cartella [scripts/](../scripts/) e [template/](../template/) per
+   conoscere l'inventario reale degli script da portare/tenere.
+
+### Cosa devi produrre
+
+Un unico file Markdown chiamato
+`plans/implementation-plan-A-B.md` con la struttura sotto. Il documento
+deve essere **autocontenuto** (chi lo legge non deve aprire altri 6 file
+per capire cosa fare oggi), ma deve **citare** i piani originali quando
+rimanda a sezioni di dettaglio.
+
+### Struttura obbligatoria del documento
+
+Usa esattamente questa scaletta e gli heading indicati:
+
+#### `# Piano implementativo unificato — Fase A (Python) + Fase B (host Linux)`
+
+#### `## Summary esecutivo`
+Massimo 25 righe. Includi:
+- Obiettivo combinato in 2 frasi.
+- Tabella `Fase | Obiettivo | Output verificabile | Stato`.
+- Decisioni architetturali chiave già prese (Python 3.11+, pypsrp,
+  paramiko, keyring, Workstation Pro Linux, astrazione `VmBackend`).
+- Vincoli che NON cambiano (act_runner, Gitea, template VM, workflow YAML
+  invariati a meno di env vars / shell).
+
+#### `## Checklist riassuntiva master`
+Una sola checklist `- [ ]` piatta che enumera **tutti** i deliverable
+ordinati cronologicamente, con prefisso del macro-step (`[A1]`, `[A2]`,
+…, `[B1]`, …, `[X]` per gli step trasversali). Deve essere copiabile in
+un issue tracker. Ogni voce: ≤ 1 riga, verbo all'infinito, deliverable
+osservabile (file, comando, test che passa). Niente prosa qui.
+
+#### `## 0. Prerequisiti e gating`
+Cosa deve essere vero PRIMA di iniziare A1. Checklist.
+
+#### `## 1. Fase A — Rewrite Python (host Windows attuale)`
+Per ogni step da A1 ad A5:
+- `### A<n> — <titolo>`
+- `**Obiettivo**:` 1 frase.
+- `**Input / dipendenze**:` step precedenti, file, env vars.
+- `**Attività**:` checklist `- [ ]` granulare (5–15 voci tipiche),
+  ognuna con deliverable osservabile.
+- `**Hook futuri Fase C**:` cosa deve essere progettato adesso per non
+  bloccare ESXi (es. firma del Protocol `VmBackend`, separazione
+  `clone_linked` da `start`, niente assunzione "stesso host").
+- `**Test / validazione**:` comandi e criteri pass/fail concreti
+  (pytest target, coverage minima, smoke workflow Gitea da triggerare).
+- `**Rollback**:` come tornare allo stato precedente lo step.
+- `**Definizione di fatto step A<n>**:` checklist `- [ ]` di chiusura
+  (max 5 voci).
+
+#### `## 2. Fase B — Migrazione host Linux Mint`
+Stessa struttura per gli step da B1 a B8. In più:
+- Marca esplicitamente quali step sono **eseguibili in parallelo** ad A
+  (B1 setup hardware Linux può iniziare durante A3/A4) e quali sono
+  **strettamente sequenziali** (B6 cutover dopo "A done").
+- Per ogni step indica **rischi specifici** presi da
+  `idea-2-linux-host.md` §6 e mitigazioni.
+
+#### `## 3. Step trasversali (X)`
+Step che attraversano A e B (test, docs, observability, sicurezza,
+gestione credenziali headless, lint dual-stack PSSA+ruff).
+Stessa struttura per ogni X<n>.
+
+#### `## 4. Hook architetturali per Fase C`
+Lista esplicita dei punti del codice/config che restano "aperti" per
+ESXi: Protocol `VmBackend`, selezione backend via `config.toml`,
+separazione control plane / compute, naming neutro (no `vmrun_*` nei
+nomi pubblici delle API). **Niente implementazione** — solo contratto
+di design da non violare.
+
+#### `## 5. Cronoprogramma e dipendenze`
+Diagramma Mermaid `gantt` o `flowchart` con le dipendenze tra step
+A1…A5, B1…B8, X1…Xn. **Niente date assolute, niente stime di durata
+in giorni**: usa solo numerazione di sequenza e dipendenze logiche.
+
+#### `## 6. Matrice rischi consolidata`
+Tabella `Rischio | Fase | Severità | Mitigazione | Owner action item`.
+Unisci §7 di idea-1 e §6 di idea-2, aggiungi rischi di integrazione
+A↔B che emergono solo nel piano fuso (es. shim PowerShell che assume
+path Windows e si rompe in Fase B).
+
+#### `## 7. Definizione di "fatto" globale (A+B)`
+Una checklist finale `- [ ]` che combina §8 di idea-1 + §8 di idea-2,
+deduplicata e coerente con la checklist master in testa.
+
+#### `## 8. Riferimenti`
+Link relativi ai file originali letti.
+
+### Regole stilistiche e di contenuto
+
+1. **Lingua**: italiano tecnico, coerente con i piani esistenti.
+2. **Tono**: imperativo / dichiarativo, niente "potremmo", "si potrebbe".
+   Ogni attività è un'azione concreta con deliverable.
+3. **Niente stime di tempo / date / sprint**. Solo dipendenze logiche.
+4. **Niente nuovi vincoli inventati**: tutto quello che dichiari deve
+   essere derivabile dai 6 file di riferimento o dallo stato attuale del
+   repo. Se proponi qualcosa di nuovo, marcalo con `> NOTA NUOVA:` e
+   spiega perché.
+5. **Coerenza con `AGENTS.md`**: ogni step PowerShell residuo deve
+   rispettare PS 5.1 (no `??`, no `&&`, ecc.); ogni nuova decisione che
+   supera un errore frequente (#1–#12) deve dichiararlo esplicitamente.
+6. **Checklist machine-friendly**: usa esclusivamente `- [ ]` (con spazio,
+   non `- [x]`). Una voce per riga. Niente sub-checklist annidate oltre
+   il primo livello dentro la stessa sezione.
+7. **Tabelle**: usa pipe-tables Markdown standard. Nessun HTML.
+8. **Mermaid**: un solo diagramma in §5, sintassi valida.
+9. **Lunghezza target**: 600–1100 righe Markdown. Sotto le 500 è troppo
+   sintetico, sopra le 1300 stai duplicando i piani originali.
+10. **Auto-verifica finale**: alla fine del documento, prima di §8,
+    aggiungi una sezione `## 7.1 Auto-check` con queste domande a cui
+    il documento stesso deve poter rispondere "sì" leggendolo:
+    - Ogni voce della checklist master compare almeno una volta come
+      `- [ ]` dentro lo step corrispondente?
+    - Ogni step A<n>/B<n>/X<n> ha tutte le sottosezioni richieste?
+    - I 12 errori frequenti di `AGENTS.md` sono stati indirizzati o
+      dichiarati non applicabili?
+    - Gli hook §4 sono coerenti con `idea-3-esxi-support.md` §3?
+
+### Cosa NON devi fare
+
+- Non implementare codice. Solo piano.
+- Non duplicare integralmente i contenuti di idea-1/idea-2: cita e
+  riassumi.
+- Non introdurre tecnologie nuove non già menzionate (no Ansible,
+  no Terraform, no Docker host-side, no K8s) salvo `> NOTA NUOVA:`
+  motivata.
+- Non modificare altri file del repo. Solo creazione di
+  `plans/implementation-plan-A-B.md`.
+- Non includere date, settimane, story point, t-shirt sizing.
+
+### Output atteso
+
+Un solo file: `plans/implementation-plan-A-B.md`, conforme alla
+struttura sopra, pronto per essere committato. Nessun testo
+conversazionale fuori dal file.

pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ci-orchestrator"
+version = "0.1.0"
+description = "Local CI/CD orchestrator (Phase A: Python rewrite of PowerShell scripts)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+authors = [{ name = "Local CI/CD System" }]
+dependencies = [
+    "click>=8.1",
+    "pypsrp>=0.8",
+    "paramiko>=3.4",
+    "keyring>=24.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-mock>=3.12",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "types-paramiko",
+]
+
+[project.scripts]
+ci-orchestrator = "ci_orchestrator.__main__:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ci_orchestrator"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501",  # line length handled by formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B011", "SIM117"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+
+[[tool.mypy.overrides]]
+module = ["pypsrp.*", "keyring.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-q --strict-markers"
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "integration: requires real VM/network (skipped in unit-test runs)",
+]
+
+[tool.coverage.run]
+source = ["ci_orchestrator"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

runner/Install-Runner.ps1

@@ -1,207 +0,0 @@
-#Requires -RunAsAdministrator
-#Requires -Version 5.1
-<#
-.SYNOPSIS
-    Downloads, registers, and installs act_runner as a Windows service.
-
-.NOTES
-    DEPRECATED — use Setup-Host.ps1 instead.
-    Setup-Host.ps1 handles the full host bootstrap including act_runner service
-    installation in a single idempotent script. Install-Runner.ps1 is kept for
-    reference but may drift from Setup-Host.ps1 over time.
-
-.DESCRIPTION
-    1. Downloads the act_runner binary from the specified URL (or Gitea releases).
-    2. Registers the runner with the Gitea instance using a registration token.
-    3. Installs it as a Windows service that auto-starts with the system.
-
-    Prerequisites:
-      - Run as Administrator
-      - NSSM (Non-Sucking Service Manager) must be installed and in PATH,
-        OR use the built-in sc.exe method (creates a wrapper via PowerShell).
-      - The Gitea instance must be reachable from this host.
-
-.PARAMETER GiteaURL
-    Base URL of your Gitea instance. Example: http://192.168.1.50:3000
-
-.PARAMETER RegistrationToken
-    Runner registration token from Gitea:
-    Admin Panel → Settings → Actions → Runners → "Create Runner Token"
-
-.PARAMETER InstallDir
-    Directory where act_runner will be installed.
-    Default: F:\CI\act_runner
-
-.PARAMETER RunnerName
-    Display name for this runner in the Gitea UI.
-    Default: local-windows-runner
-
-.PARAMETER ActRunnerVersion
-    Version tag to download. Default: latest (resolves via GitHub API).
-    Example: v0.2.11
-
-.PARAMETER ServiceName
-    Windows service name. Default: act_runner
-
-.EXAMPLE
-    .\Install-Runner.ps1 `
-        -GiteaURL          "http://192.168.1.50:3000" `
-        -RegistrationToken "abc123xyz"
-#>
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory)]
-    [string] $GiteaURL,
-
-    [Parameter(Mandatory)]
-    [string] $RegistrationToken,
-
-    [string] $InstallDir = 'F:\CI\act_runner',
-
-    [string] $RunnerName = 'local-windows-runner',
-
-    [string] $ActRunnerVersion = 'latest',
-
-    [string] $ServiceName = 'act_runner'
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-# ── Resolve download URL ──────────────────────────────────────────────────────
-if ($ActRunnerVersion -eq 'latest') {
-    Write-Host "[Install-Runner] Resolving latest act_runner version from Gitea releases..."
-    try {
-        $releaseInfo = Invoke-RestMethod -Uri 'https://dl.gitea.com/act_runner/version.json' -UseBasicParsing
-        $ActRunnerVersion = $releaseInfo.latest
-    }
-    catch {
-        Write-Warning "Could not resolve latest version automatically. Set -ActRunnerVersion explicitly."
-        Write-Warning "Find releases at: https://gitea.com/gitea/act_runner/releases"
-        throw
-    }
-}
-
-$downloadUrl = "https://dl.gitea.com/act_runner/${ActRunnerVersion}/act_runner-${ActRunnerVersion}-windows-amd64.exe"
-$binaryPath  = Join-Path $InstallDir 'act_runner.exe'
-$configPath  = Join-Path $InstallDir 'config.yaml'
-
-Write-Host "[Install-Runner] Version    : $ActRunnerVersion"
-Write-Host "[Install-Runner] Install dir: $InstallDir"
-Write-Host "[Install-Runner] Service    : $ServiceName"
-
-# ── Create install directory ──────────────────────────────────────────────────
-if (-not (Test-Path $InstallDir)) {
-    New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
-    Write-Host "[Install-Runner] Created directory: $InstallDir"
-}
-
-# ── Download act_runner binary ────────────────────────────────────────────────
-if (Test-Path $binaryPath) {
-    Write-Host "[Install-Runner] act_runner.exe already exists — skipping download."
-    Write-Host "             Delete $binaryPath to force re-download."
-}
-else {
-    Write-Host "[Install-Runner] Downloading from: $downloadUrl"
-    Invoke-WebRequest -Uri $downloadUrl -OutFile $binaryPath -UseBasicParsing
-    Write-Host "[Install-Runner] Downloaded: $binaryPath"
-}
-
-# ── Copy config.yaml if not already present ───────────────────────────────────
-$repoConfigPath = Join-Path $PSScriptRoot 'config.yaml'
-if (-not (Test-Path $configPath)) {
-    if (Test-Path $repoConfigPath) {
-        Copy-Item $repoConfigPath $configPath
-        Write-Host "[Install-Runner] Copied config.yaml from repo to $configPath"
-        Write-Host "             Review and update paths in $configPath before proceeding."
-    }
-    else {
-        Write-Warning "[Install-Runner] config.yaml not found at $repoConfigPath"
-        Write-Warning "             Generating default config and registering without custom config."
-        # Generate default config
-        Push-Location $InstallDir
-        & $binaryPath generate-config | Out-File $configPath -Encoding UTF8
-        Pop-Location
-    }
-}
-else {
-    Write-Host "[Install-Runner] Using existing config.yaml: $configPath"
-}
-
-# ── Register runner with Gitea ────────────────────────────────────────────────
-$stateFile = Join-Path $InstallDir '.runner'
-if (Test-Path $stateFile) {
-    Write-Host "[Install-Runner] Runner already registered (.runner state file exists)."
-    Write-Host "             Delete $stateFile to re-register."
-}
-else {
-    Write-Host "[Install-Runner] Registering runner with Gitea at $GiteaURL..."
-    Push-Location $InstallDir
-    try {
-        & $binaryPath register `
-            --no-interactive `
-            --instance  $GiteaURL `
-            --token     $RegistrationToken `
-            --name      $RunnerName `
-            --labels    'windows-build:host,dotnet:host,msbuild:host' `
-            --config    $configPath
-        if ($LASTEXITCODE -ne 0) {
-            throw "act_runner register exited with code $LASTEXITCODE"
-        }
-    }
-    finally {
-        Pop-Location
-    }
-    Write-Host "[Install-Runner] Runner registered successfully."
-}
-
-# ── Install as Windows service ────────────────────────────────────────────────
-$existingService = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
-
-if ($existingService) {
-    Write-Host "[Install-Runner] Service '$ServiceName' already exists."
-    Write-Host "             Stopping and updating..."
-    Stop-Service -Name $ServiceName -Force -ErrorAction SilentlyContinue
-}
-
-# Build service command (act_runner daemon with explicit config)
-$serviceCmd = "`"$binaryPath`" daemon --config `"$configPath`""
-
-if ($existingService) {
-    # Update existing service binary path
-    sc.exe config $ServiceName binpath= $serviceCmd | Out-Null
-}
-else {
-    # Create new service
-    New-Service `
-        -Name        $ServiceName `
-        -BinaryPathName $serviceCmd `
-        -DisplayName 'Gitea act_runner (CI/CD)' `
-        -Description 'Gitea Actions runner for ephemeral VMware build VMs' `
-        -StartupType Automatic | Out-Null
-    Write-Host "[Install-Runner] Service created: $ServiceName"
-}
-
-# Configure service recovery: restart on failure
-sc.exe failure $ServiceName reset= 86400 actions= restart/5000/restart/10000/restart/30000 | Out-Null
-
-# Start the service
-Start-Service -Name $ServiceName
-Write-Host "[Install-Runner] Service '$ServiceName' started."
-
-# ── Verify ────────────────────────────────────────────────────────────────────
-Start-Sleep -Seconds 3
-$svc = Get-Service -Name $ServiceName
-if ($svc.Status -eq 'Running') {
-    Write-Host "[Install-Runner] act_runner is running as a Windows service."
-    Write-Host "[Install-Runner] Check Gitea Admin → Settings → Actions → Runners to confirm it appears Online."
-}
-else {
-    Write-Warning "[Install-Runner] Service status: $($svc.Status). Check Windows Event Log for errors."
-}
-
-Write-Host ""
-Write-Host "Installation complete."
-Write-Host "  Binary  : $binaryPath"
-Write-Host "  Config  : $configPath"
-Write-Host "  Service : $ServiceName (startup: Automatic)"

runner/config.yaml

@@ -19,13 +19,30 @@ runner:
   # Environment variables injected into every job's environment.
   envs:
     # Path to the template VM - update after provisioning the template
-    GITEA_CI_TEMPLATE_PATH: "F:\\CI\\Templates\\WinBuild\\CI-WinBuild.vmx"
+    GITEA_CI_TEMPLATE_PATH: "F:\\CI\\Templates\\WinBuild2025\\WinBuild2025.vmx"
     # Base directory where ephemeral clone VMs are created
     GITEA_CI_CLONE_BASE_DIR: "F:\\CI\\BuildVMs"
     # Base directory for collected build artifacts
     GITEA_CI_ARTIFACT_DIR: "F:\\CI\\Artifacts"
     # Windows Credential Manager target name for guest VM credentials
     GITEA_CI_GUEST_CRED_TARGET: "BuildVMGuest"
+    # Snapshot to clone from. Default BaseClean — set to BaseClean_<yyyyMMdd> when
+    # refreshing the template. Keep the previous value live for 1 week before deleting.
+    # GITEA_CI_SNAPSHOT_NAME: "BaseClean"
+    # Path to the Linux (Ubuntu 24.04) template VM
+    GITEA_CI_LINUX_TEMPLATE_PATH: "F:\\CI\\Templates\\LinuxBuild2404\\LinuxBuild2404.vmx"
+    # SSH private key for Linux guest authentication
+    GITEA_CI_SSH_KEY_PATH: "F:\\CI\\keys\\ci_linux"
+    # Root directory of the local-ci-system repository on this host (scripts\ subdir)
+    GITEA_CI_SCRIPT_ROOT: "N:\\Code\\Workspace\\Local-CI-CD-System\\scripts"
+    # Force UTF-8 stdio for the Python orchestrator (Phase A4) so non-ASCII
+    # characters in build logs survive the act_runner -> Gitea round-trip.
+    PYTHONIOENCODING: "utf-8"
+    # Absolute path to the system Python interpreter used to bootstrap the
+    # production venv (F:\CI\python\venv). act_runner runs as SYSTEM with a
+    # sanitized PATH where neither `python` nor `py.exe` resolve, so workflows
+    # rely on this single source of truth. Update only when upgrading Python.
+    CI_PYTHON_LAUNCHER: "C:\\Program Files\\Python314\\python.exe"
 
   # Optional: load additional env vars from a file (one KEY=VALUE per line)
   # env_file: "F:\\CI\\runner.env"
@@ -40,6 +57,7 @@ runner:
     - "windows-build:host"
     - "dotnet:host"
     - "msbuild:host"
+    - "linux-build:host"
 
   # Uncomment to ignore specific errors
   # insecure: false

scripts/Backup-CITemplate.ps1

@@ -0,0 +1,150 @@
+#Requires -Version 5.1
+#Requires -RunAsAdministrator
+<#
+.SYNOPSIS
+    Creates a timestamped backup of the CI template VM directory.
+
+.DESCRIPTION
+    Run before any template refresh (toolchain update, KMS re-activation, snapshot
+    rebuild). The act_runner service is stopped for the duration so no vmrun clone
+    races the file copy, then restarted automatically.
+
+    Restore procedure (after a bad refresh):
+        Stop-Service act_runner
+        Remove-Item 'F:\CI\Templates\WinBuild2025' -Recurse -Force
+        Copy-Item 'F:\CI\Backups\Template_<stamp>' 'F:\CI\Templates\WinBuild2025' -Recurse
+        Start-Service act_runner
+
+.PARAMETER TemplatePath
+    Directory containing the template VM files (.vmx, .vmdk, snapshots).
+    Default: F:\CI\Templates\WinBuild2025
+
+.PARAMETER AllTemplates
+    Back up every subdirectory under F:\CI\Templates\ in a single pass.
+    When set, TemplatePath is ignored. Backup folder names include the template
+    directory name: Template_<DirName>_<timestamp>.
+
+.PARAMETER BackupBaseDir
+    Directory under which timestamped backup folders are created.
+    Default: F:\CI\Backups
+
+.PARAMETER KeepCount
+    Number of most-recent backups to retain. Older ones are deleted.
+    Default: 3
+
+.PARAMETER SkipRunnerStop
+    Skip stopping/restarting act_runner. Use when the service is already stopped
+    or when called from a maintenance window where the runner is offline.
+
+.EXAMPLE
+    # Standard pre-refresh backup (run elevated)
+    .\Backup-CITemplate.ps1
+
+    # Dry run to preview what would happen
+    .\Backup-CITemplate.ps1 -WhatIf
+
+    # Keep 5 backups
+    .\Backup-CITemplate.ps1 -KeepCount 5
+
+    # Back up all three templates
+    .\Backup-CITemplate.ps1 -AllTemplates
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [string] $TemplatePath  = 'F:\CI\Templates\WinBuild2025',
+
+    [string] $BackupBaseDir = 'F:\CI\Backups',
+
+    [ValidateRange(1, 20)]
+    [int] $KeepCount = 3,
+
+    [switch] $SkipRunnerStop,
+
+    [switch] $AllTemplates
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$timestamp = Get-Date -Format 'yyyyMMdd_HHmmss'
+
+if (-not (Test-Path $BackupBaseDir)) {
+    New-Item -ItemType Directory -Path $BackupBaseDir -Force | Out-Null
+}
+
+# ── Step 1: Stop runner ──────────────────────────────────────────────────────
+$runnerWasRunning = $false
+if (-not $SkipRunnerStop) {
+    $svc = Get-Service -Name act_runner -ErrorAction SilentlyContinue
+    if ($svc -and $svc.Status -eq 'Running') {
+        if ($PSCmdlet.ShouldProcess('act_runner', 'Stop service before backup')) {
+            Write-Host "[Backup-CITemplate] Stopping act_runner..."
+            Stop-Service -Name act_runner -Force
+            $runnerWasRunning = $true
+            Write-Host "[Backup-CITemplate] act_runner stopped."
+        }
+    }
+}
+
+try {
+    # ── Steps 2+3: Backup and prune one or all templates ──────────────────────
+    $templatesToBackup = @()
+    if ($AllTemplates) {
+        $templatesToBackup = @(Get-ChildItem 'F:\CI\Templates' -Directory -ErrorAction SilentlyContinue)
+        if ($templatesToBackup.Count -eq 0) { throw 'No template directories found under F:\CI\Templates' }
+    } else {
+        if (-not (Test-Path $TemplatePath -PathType Container)) {
+            throw "Template directory not found: $TemplatePath"
+        }
+        $templatesToBackup = @(Get-Item $TemplatePath)
+    }
+
+    foreach ($tmpl in $templatesToBackup) {
+        $nameTag    = if ($AllTemplates) { "$($tmpl.Name)_$timestamp" } else { $timestamp }
+        $backupDest = Join-Path $BackupBaseDir "Template_$nameTag"
+
+        # ── Step 2: Copy template directory ───────────────────────────────────
+        if ($PSCmdlet.ShouldProcess($tmpl.FullName, "Copy to $backupDest")) {
+            Write-Host "[Backup-CITemplate] Copying $($tmpl.FullName) -> $backupDest ..."
+            $sw = [System.Diagnostics.Stopwatch]::StartNew()
+            Copy-Item -Path $tmpl.FullName -Destination $backupDest -Recurse -Force
+            $sw.Stop()
+
+            # Size sum without Measure-Object.Sum (Set-StrictMode safe)
+            $backupFiles = Get-ChildItem $backupDest -Recurse -File -ErrorAction SilentlyContinue
+            $totalBytes  = [long]0
+            if ($backupFiles) { foreach ($f in $backupFiles) { $totalBytes += $f.Length } }
+            $sizeMB = [math]::Round($totalBytes / 1MB, 0)
+
+            Write-Host "[Backup-CITemplate] Backup complete: $backupDest ($sizeMB MB, $($sw.Elapsed.TotalSeconds.ToString('F0'))s)"
+        }
+
+        # ── Step 3: Prune old backups for this template ────────────────────────
+        $prunePattern = if ($AllTemplates) { "Template_$($tmpl.Name)_????????_??????" } else { 'Template_????????_??????' }
+        $existing = Get-ChildItem $BackupBaseDir -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -like $prunePattern } |
+            Sort-Object LastWriteTime -Descending
+
+        if ($existing.Count -gt $KeepCount) {
+            $toRemove = $existing | Select-Object -Skip $KeepCount
+            foreach ($old in $toRemove) {
+                if ($PSCmdlet.ShouldProcess($old.FullName, 'Remove old backup')) {
+                    Write-Host "[Backup-CITemplate] Pruning old backup: $($old.Name)"
+                    Remove-Item $old.FullName -Recurse -Force
+                }
+            }
+            Write-Host "[Backup-CITemplate] Retained $KeepCount backup(s) for $($tmpl.Name)."
+        }
+    }
+}
+finally {
+    # ── Step 4: Restart runner ────────────────────────────────────────────────
+    if ($runnerWasRunning) {
+        if ($PSCmdlet.ShouldProcess('act_runner', 'Start service after backup')) {
+            Write-Host "[Backup-CITemplate] Restarting act_runner..."
+            Start-Service -Name act_runner
+            $newStatus = (Get-Service -Name act_runner).Status
+            Write-Host "[Backup-CITemplate] act_runner status: $newStatus"
+        }
+    }
+}

scripts/Cleanup-OrphanedBuildVMs.ps1

@@ -1,104 +1,37 @@
-#Requires -Version 5.1
-<#
-.SYNOPSIS
-    Destroys ephemeral build VMs that were not cleaned up (e.g. after host power loss).
-
-.DESCRIPTION
-    Scans F:\CI\BuildVMs\ for clone directories older than -MaxAgeHours.
-    For each stale directory, stops the VM (hard), deletes via vmrun deleteVM,
-    then removes the directory.
-
-    Run as a daily scheduled task or on host startup to prevent disk accumulation.
-    Safe to run while CI jobs are active — only touches VMs older than MaxAgeHours.
-
-.PARAMETER CloneBaseDir
-    Directory containing ephemeral VM clones. Default: F:\CI\BuildVMs
-
-.PARAMETER MaxAgeHours
-    Age threshold in hours. Directories with LastWriteTime older than this are
-    treated as orphaned. Must exceed the longest expected build duration.
-    Default: 4 (runner.timeout is 2h — 4h gives double margin)
-
-.PARAMETER VmrunPath
-    Path to vmrun.exe.
-    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
-
-.PARAMETER WhatIf
-    List orphaned VMs without destroying them.
-
-.EXAMPLE
-    # Dry run
-    .\Cleanup-OrphanedBuildVMs.ps1 -WhatIf
-
-    # Live cleanup (run elevated)
-    .\Cleanup-OrphanedBuildVMs.ps1
-#>
-[CmdletBinding(SupportsShouldProcess)]
-param(
-    [string] $CloneBaseDir = 'F:\CI\BuildVMs',
-
-    [ValidateRange(1, 168)]
-    [int] $MaxAgeHours = 4,
-
-    [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Continue'   # Don't abort on individual VM errors
-
-if (-not (Test-Path $CloneBaseDir)) {
-    Write-Host "[Cleanup] Clone base dir not found: $CloneBaseDir — nothing to do."
-    exit 0
-}
-
-if (-not (Test-Path $VmrunPath -PathType Leaf)) {
-    Write-Warning "[Cleanup] vmrun.exe not found at: $VmrunPath"
-    Write-Warning "          Skipping vmrun stop/delete — will attempt directory removal only."
-}
-
-$cutoff    = (Get-Date).AddHours(-$MaxAgeHours)
-$orphans   = Get-ChildItem -Path $CloneBaseDir -Directory -ErrorAction SilentlyContinue |
-                 Where-Object { $_.LastWriteTime -lt $cutoff }
-
-if (-not $orphans) {
-    Write-Host "[Cleanup] No orphaned VMs found (threshold: $MaxAgeHours h)."
-    exit 0
-}
-
-Write-Host "[Cleanup] Found $($orphans.Count) orphaned VM director$(if ($orphans.Count -eq 1) {'y'} else {'ies'}) older than $MaxAgeHours h."
-
-foreach ($dir in $orphans) {
-    $vmx = Get-ChildItem -Path $dir.FullName -Filter '*.vmx' -ErrorAction SilentlyContinue |
-               Select-Object -First 1
-
-    if ($PSCmdlet.ShouldProcess($dir.FullName, "Destroy orphaned VM")) {
-        Write-Host "[Cleanup] Processing: $($dir.FullName)"
-
-        if ($vmx -and (Test-Path $VmrunPath -PathType Leaf)) {
-            # Hard stop — don't wait for graceful shutdown on an orphan
-            & $VmrunPath -T ws stop $vmx.FullName hard 2>&1 | Out-Null
-            Start-Sleep -Seconds 2
-            $deleteOut = & $VmrunPath -T ws deleteVM $vmx.FullName 2>&1
-            if ($LASTEXITCODE -ne 0) {
-                Write-Warning "[Cleanup] vmrun deleteVM failed (exit $LASTEXITCODE): $deleteOut"
-                Write-Warning "          Falling back to directory removal."
-            }
-        }
-        elseif (-not $vmx) {
-            Write-Warning "[Cleanup] No .vmx found in $($dir.FullName) — removing directory only."
-        }
-
-        Remove-Item $dir.FullName -Recurse -Force -ErrorAction SilentlyContinue
-        if (Test-Path $dir.FullName) {
-            Write-Warning "[Cleanup] Could not fully remove: $($dir.FullName) — manual cleanup needed."
-        }
-        else {
-            Write-Host "[Cleanup] Removed: $($dir.FullName)"
-        }
-    }
-    else {
-        Write-Host "[Cleanup] WhatIf: would destroy $($dir.FullName) (age: $([int]((Get-Date) - $dir.LastWriteTime).TotalHours) h)"
-    }
-}
-
-Write-Host "[Cleanup] Done."
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A2-closeout.md.
+# PowerShell common params (-ErrorAction etc.) must not be forwarded
+# to the Python CLI. Value-taking ones also consume the next token.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
+}
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
+
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
+    }
+}
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator vm cleanup @pyArgs
+exit $LASTEXITCODE

scripts/Get-BuildArtifacts.ps1

@@ -1,48 +1,19 @@
 #Requires -Version 5.1
-<#
-.SYNOPSIS
-    Copies build artifacts from an ephemeral VM to the host artifact directory.
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
 
-.DESCRIPTION
-    Opens a WinRM session to the build VM and uses Copy-Item -FromSession
-    to transfer the artifact archive and optional log files.
-    Validates that at least one file was successfully transferred.
-    Throws on failure so the caller's try/finally can clean up the VM.
+# Shim: delegates to the Python ci_orchestrator CLI (`artifacts collect`).
+# Original PS implementation moved to git history; see plans/A3-closeout.md.
+#
+# The bound `-Credential` is intentionally discarded — Python uses keyring
+# via `--credential-target` (defaulting to `BuildVMGuest`).
 
-.PARAMETER IPAddress
-    IP of the build VM.
-
-.PARAMETER Credential
-    PSCredential for the guest build user.
-
-.PARAMETER GuestArtifactPath
-    Full path to the artifact file or directory inside the VM.
-    Example: C:\CI\output\artifacts.zip
-
-.PARAMETER HostArtifactDir
-    Directory on the host where artifacts will be stored.
-    The directory is created if it does not exist.
-    Example: F:\CI\Artifacts\run-42
-
-.PARAMETER IncludeLogs
-    If set, also copies *.log files from the guest work directory
-    (C:\CI\build\*.log) alongside the artifact archive.
-
-.EXAMPLE
-    $cred = Get-Credential
-    .\Get-BuildArtifacts.ps1 `
-        -IPAddress       "192.168.11.101" `
-        -Credential      $cred `
-        -GuestArtifactPath "C:\CI\output\artifacts.zip" `
-        -HostArtifactDir   "F:\CI\Artifacts\run-42"
-#>
 [CmdletBinding()]
 param(
     [Parameter(Mandatory)]
-    [ValidatePattern('^(\d{1,3}\.){3}\d{1,3}$')]
     [string] $IPAddress,
 
-    [Parameter(Mandatory)]
+    [Parameter()]
     [System.Management.Automation.PSCredential] $Credential,
 
     [Parameter(Mandatory)]
@@ -51,73 +22,41 @@ param(
     [Parameter(Mandatory)]
     [string] $HostArtifactDir,
 
-    [switch] $IncludeLogs
+    [switch] $IncludeLogs,
+
+    [ValidateSet('Windows', 'Linux')]
+    [string] $GuestOS = 'Windows',
+
+    [string] $SshKeyPath = 'F:\CI\keys\ci_linux',
+    [string] $SshUser = 'ci_build',
+    [string] $SshKnownHostsFile = '',
+
+    [string] $JobId = '',
+    [string] $Commit = '',
+
+    [string] $CredentialTarget = ''
 )
 
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
+$pyArgs = @(
+    '--ip-address', $IPAddress,
+    '--guest-os', $GuestOS.ToLower(),
+    '--guest-artifact-path', $GuestArtifactPath,
+    '--host-artifact-dir', $HostArtifactDir,
+    '--ssh-user', $SshUser,
+    '--ssh-key-path', $SshKeyPath,
+    '--job-id', $JobId,
+    '--commit', $Commit
+)
 
-# Ensure destination exists on host
-if (-not (Test-Path $HostArtifactDir)) {
-    New-Item -ItemType Directory -Path $HostArtifactDir -Force | Out-Null
-    Write-Host "[Get-BuildArtifacts] Created host artifact directory: $HostArtifactDir"
+if ($SshKnownHostsFile) { $pyArgs += @('--ssh-known-hosts-file', $SshKnownHostsFile) }
+if ($CredentialTarget)  { $pyArgs += @('--credential-target', $CredentialTarget) }
+if ($IncludeLogs.IsPresent) { $pyArgs += '--include-logs' }
+
+if ($Credential) {
+    Write-Host '[Get-BuildArtifacts] -Credential ignored; Python CLI uses keyring (set -CredentialTarget to override target name).'
 }
 
-$sessionOptions = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
-
-Write-Host "[Get-BuildArtifacts] Connecting to VM at $IPAddress..."
-$session = New-PSSession `
-    -ComputerName  $IPAddress `
-    -Credential    $Credential `
-    -SessionOption $sessionOptions `
-    -ErrorAction Stop
-
-try {
-    # ── Verify artifact exists in guest ──────────────────────────────────
-    $guestExists = Invoke-Command -Session $session -ScriptBlock {
-        param($path)
-        Test-Path $path
-    } -ArgumentList $GuestArtifactPath
-
-    if (-not $guestExists) {
-        throw "Artifact not found in guest at: $GuestArtifactPath"
-    }
-
-    # ── Copy main artifact ────────────────────────────────────────────────
-    $artifactFileName = Split-Path $GuestArtifactPath -Leaf
-    $hostDestPath     = Join-Path $HostArtifactDir $artifactFileName
-
-    Write-Host "[Get-BuildArtifacts] Copying $artifactFileName from guest..."
-    Copy-Item -Path $GuestArtifactPath -Destination $hostDestPath -FromSession $session -Force
-
-    # ── Copy logs if requested ────────────────────────────────────────────
-    if ($IncludeLogs) {
-        $logFiles = Invoke-Command -Session $session -ScriptBlock {
-            Get-ChildItem -Path 'C:\CI\build' -Filter '*.log' -Recurse -ErrorAction SilentlyContinue |
-                Select-Object -ExpandProperty FullName
-        }
-
-        foreach ($log in $logFiles) {
-            $logDest = Join-Path $HostArtifactDir (Split-Path $log -Leaf)
-            Write-Host "[Get-BuildArtifacts] Copying log: $(Split-Path $log -Leaf)"
-            Copy-Item -Path $log -Destination $logDest -FromSession $session -Force
-        }
-    }
-
-    # ── Validate at least the main artifact landed ────────────────────────
-    if (-not (Test-Path $hostDestPath)) {
-        throw "Artifact was not found at expected host path after copy: $hostDestPath"
-    }
-
-    $fileItem = Get-Item $hostDestPath
-    if ($fileItem.Length -eq 0) {
-        throw "Artifact file exists but is empty: $hostDestPath"
-    }
-    $sizeKB = [math]::Round($fileItem.Length / 1KB, 1)
-
-    Write-Host "[Get-BuildArtifacts] Artifact collected: $hostDestPath ($sizeKB KB)"
-    return $hostDestPath
-}
-finally {
-    Remove-PSSession $session -ErrorAction SilentlyContinue
-}
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator artifacts collect @pyArgs
+exit $LASTEXITCODE

scripts/Get-CIJobSummary.ps1

@@ -0,0 +1,215 @@
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A2-closeout.md.
+# PowerShell common params (-ErrorAction etc.) must not be forwarded
+# to the Python CLI. Value-taking ones also consume the next token.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
+}
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
+
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
+    }
+}
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator report job @pyArgs
+exit $LASTEXITCODE
+
+
+.DESCRIPTION
+    Scans F:\CI\Logs\ (or a custom path) for invoke-ci.jsonl files and
+    prints a compact table with job ID, status, total elapsed time, and the
+    last error message (if any).
+
+    Each row corresponds to one completed (or failed) CI job.
+    Use -JobId to inspect a single job in detail.
+
+.PARAMETER LogDir
+    Base directory containing per-job log subdirectories.
+    Default: F:\CI\Logs
+
+.PARAMETER Last
+    Show only the N most recent jobs (sorted by job-start timestamp).
+    Default: 20
+
+.PARAMETER JobId
+    When specified, shows a detailed phase-by-phase breakdown for that job.
+
+.PARAMETER Failed
+    When specified, filters to failed jobs only.
+
+.EXAMPLE
+    # Show last 20 jobs
+    .\Get-CIJobSummary.ps1
+
+.EXAMPLE
+    # Show last 5 failed jobs
+    .\Get-CIJobSummary.ps1 -Last 5 -Failed
+
+.EXAMPLE
+    # Detailed breakdown for a specific job
+    .\Get-CIJobSummary.ps1 -JobId 'run-12345'
+#>
+[CmdletBinding()]
+param(
+    [string] $LogDir = 'F:\CI\Logs',
+
+    [ValidateRange(1, 1000)]
+    [int]    $Last   = 20,
+
+    [string] $JobId  = '',
+
+    [switch] $Failed
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+function Format-SecToHMS {
+    param([int] $Seconds)
+    if ($Seconds -lt 0) { return '?' }
+    $h = [math]::Floor($Seconds / 3600)
+    $m = [math]::Floor(($Seconds % 3600) / 60)
+    $s = $Seconds % 60
+    if ($h -gt 0) { return '{0}h{1:00}m{2:00}s' -f $h, $m, $s }
+    return '{0}m{1:00}s' -f $m, $s
+}
+
+function Read-JobEvents {
+    param([string] $JsonlPath)
+    $events = [System.Collections.Generic.List[PSCustomObject]]::new()
+    foreach ($line in (Get-Content $JsonlPath -Encoding UTF8 -ErrorAction SilentlyContinue)) {
+        $line = $line.Trim()
+        if (-not $line) { continue }
+        try {
+            $events.Add(($line | ConvertFrom-Json))
+        } catch {
+            Write-Debug "[Get-CIJobSummary] Skipping malformed JSONL line in $JsonlPath"
+        }
+    }
+    return $events
+}
+
+# ── Validate log dir ────────────────────────────────────────────────────────
+if (-not (Test-Path $LogDir -PathType Container)) {
+    Write-Warning "Log directory not found: $LogDir"
+    exit 1
+}
+
+# ── Single-job detail mode ──────────────────────────────────────────────────
+if ($JobId -ne '') {
+    $jsonlPath = Join-Path $LogDir (Join-Path $JobId 'invoke-ci.jsonl')
+    if (-not (Test-Path $jsonlPath)) {
+        Write-Warning "No JSONL log found for job '$JobId' at: $jsonlPath"
+        exit 1
+    }
+    $events = Read-JobEvents -JsonlPath $jsonlPath
+    if ($events.Count -eq 0) {
+        Write-Warning "JSONL file is empty or unreadable: $jsonlPath"
+        exit 1
+    }
+    Write-Host "`nJob: $JobId"
+    Write-Host ('=' * 60)
+    Write-Host ('{0,-35} {1,-10} {2}' -f 'Phase', 'Status', 'Timestamp')
+    Write-Host ('{0,-35} {1,-10} {2}' -f ('-'*35), ('-'*10), ('-'*24))
+    foreach ($ev in $events) {
+        $ts = if ($ev.ts) { $ev.ts } else { '' }
+        Write-Host ('{0,-35} {1,-10} {2}' -f $ev.phase, $ev.status, $ts)
+    }
+    # Print error if present
+    $failEvent = $events | Where-Object { $_.status -eq 'failure' } | Select-Object -Last 1
+    if ($failEvent -and $failEvent.data -and $failEvent.data.error) {
+        Write-Host "`nError: $($failEvent.data.error)"
+    }
+    exit 0
+}
+
+# ── Scan all job JSONL files ─────────────────────────────────────────────────
+$jsonlFiles = Get-ChildItem -Path $LogDir -Recurse -Filter 'invoke-ci.jsonl' -ErrorAction SilentlyContinue |
+    Sort-Object { $_.LastWriteTime } -Descending
+
+if ($jsonlFiles.Count -eq 0) {
+    Write-Host "No invoke-ci.jsonl files found under $LogDir"
+    exit 0
+}
+
+$rows = [System.Collections.Generic.List[PSCustomObject]]::new()
+
+foreach ($file in $jsonlFiles) {
+    $events = Read-JobEvents -JsonlPath $file.FullName
+    if ($events.Count -eq 0) { continue }
+
+    $jobEvent    = $events | Where-Object { $_.phase -eq 'job' -and $_.status -eq 'start' }  | Select-Object -First 1
+    $successEvent= $events | Where-Object { $_.phase -eq 'job' -and $_.status -eq 'success' } | Select-Object -First 1
+    $failEvent   = $events | Where-Object { $_.phase -eq 'job' -and $_.status -eq 'failure' } | Select-Object -First 1
+
+    $jId     = if ($events[0].jobId) { $events[0].jobId } else { (Split-Path (Split-Path $file.FullName -Parent) -Leaf) }
+    $started = if ($jobEvent -and $jobEvent.ts) { $jobEvent.ts } else { '' }
+
+    if ($successEvent) {
+        $status  = 'success'
+        $elSec   = if ($successEvent.data -and $null -ne $successEvent.data.elapsedSec) { [int]$successEvent.data.elapsedSec } else { -1 }
+        $errMsg  = ''
+    } elseif ($failEvent) {
+        $status  = 'FAILED'
+        $elSec   = if ($failEvent.data -and $null -ne $failEvent.data.elapsedSec) { [int]$failEvent.data.elapsedSec } else { -1 }
+        $errMsg  = if ($failEvent.data -and $failEvent.data.error) { "$($failEvent.data.error)" } else { '' }
+        # Truncate error for table display
+        if ($errMsg.Length -gt 60) { $errMsg = $errMsg.Substring(0, 57) + '...' }
+    } else {
+        $status  = 'in-progress'
+        $elSec   = -1
+        $errMsg  = ''
+    }
+
+    $rows.Add([PSCustomObject]@{
+        JobId   = $jId
+        Status  = $status
+        Elapsed = Format-SecToHMS -Seconds $elSec
+        Started = $started
+        Error   = $errMsg
+    })
+}
+
+# ── Apply filters + limit ────────────────────────────────────────────────────
+if ($Failed) {
+    $rows = @($rows | Where-Object { $_.Status -eq 'FAILED' })
+}
+
+$rows = @($rows | Select-Object -First $Last)
+
+if ($rows.Count -eq 0) {
+    Write-Host "No matching jobs found."
+    exit 0
+}
+
+# ── Print table ──────────────────────────────────────────────────────────────
+Write-Host "`nCI Job Summary (last $($rows.Count) jobs):"
+Write-Host ('{0,-40} {1,-12} {2,-10} {3,-26} {4}' -f 'JobId', 'Status', 'Elapsed', 'Started', 'Error')
+Write-Host ('{0,-40} {1,-12} {2,-10} {3,-26} {4}' -f ('-'*40), ('-'*12), ('-'*10), ('-'*26), ('-'*30))
+foreach ($r in $rows) {
+    Write-Host ('{0,-40} {1,-12} {2,-10} {3,-26} {4}' -f $r.JobId, $r.Status, $r.Elapsed, $r.Started, $r.Error)
+}
+Write-Host ''

scripts/Invoke-CIJob.ps1

@@ -1,329 +1,37 @@
-#Requires -Version 5.1
-<#
-.SYNOPSIS
-    Main CI orchestrator: creates an ephemeral VM, runs a build, collects
-    artifacts, and destroys the VM — in a guaranteed try/finally pattern.
-
-.DESCRIPTION
-    This script is called by act_runner as the primary build step.
-    It coordinates all sub-scripts:
-      1. New-BuildVM.ps1    — linked clone from template
-      2. vmrun start        — start the clone
-      3. Wait-VMReady.ps1   — poll until WinRM is ready
-      4. Invoke-RemoteBuild.ps1 — execute build inside VM
-      5. Get-BuildArtifacts.ps1 — copy artifacts to host
-      6. Remove-BuildVM.ps1 — destroy VM (always runs via finally)
-
-    Exit codes:
-      0  = success
-      1  = build or orchestration failure (VM destroyed, artifacts may be partial)
-
-.PARAMETER JobId
-    Unique job identifier (use ${{ github.run_id }} from Gitea Actions).
-
-.PARAMETER RepoUrl
-    Git URL of the repository to build (reachable from the build VM).
-
-.PARAMETER Branch
-    Branch to build.
-
-.PARAMETER Commit
-    Optional specific commit SHA to check out.
-
-.PARAMETER Configuration
-    Build configuration. Default: Release
-
-.PARAMETER TemplatePath
-    Full path to the template VM .vmx file.
-    Can also be set via env var GITEA_CI_TEMPLATE_PATH.
-
-.PARAMETER SnapshotName
-    Template snapshot to clone from. Default: BaseClean
-
-.PARAMETER CloneBaseDir
-    Base directory for clone VMs.
-    Can also be set via env var GITEA_CI_CLONE_BASE_DIR.
-    Default: F:\CI\BuildVMs
-
-.PARAMETER ArtifactBaseDir
-    Host directory where artifacts are stored per job.
-    Default: F:\CI\Artifacts
-
-.PARAMETER VMIPAddress
-    IP address to assign/expect for the build VM.
-    Must be unique per concurrent build.
-    Can be passed explicitly or derived from a registry/file-based IP allocator.
-
-.PARAMETER GuestCredentialTarget
-    Target name in Windows Credential Manager for guest credentials.
-    Default: BuildVMGuest
-
-.PARAMETER VmrunPath
-    Path to vmrun.exe.
-    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
-
-.EXAMPLE
-    # Called from Gitea Actions workflow:
-    .\scripts\Invoke-CIJob.ps1 `
-        -JobId       "${{ github.run_id }}" `
-        -RepoUrl     "http://gitea.local/org/myrepo.git" `
-        -Branch      "${{ github.ref_name }}" `
-        -Commit      "${{ github.sha }}" `
-        -VMIPAddress "192.168.11.101"
-#>
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory)]
-    [string] $JobId,
-
-    [Parameter(Mandatory)]
-    [string] $RepoUrl,
-
-    [Parameter(Mandatory)]
-    [string] $Branch,
-
-    [string] $Commit = '',
-
-    [string] $Configuration = 'Release',
-
-    # Pass -Submodules to clone with --recurse-submodules
-    [switch] $Submodules,
-
-    # Custom build command to run inside the VM (empty = dotnet build)
-    [string] $BuildCommand = '',
-
-    # Artifact source pattern relative to GuestWorkDir (used with BuildCommand)
-    [string] $GuestArtifactSource = 'dist',
-
-    [string] $TemplatePath = $env:GITEA_CI_TEMPLATE_PATH,
-
-    [string] $SnapshotName = 'BaseClean',
-
-    [string] $CloneBaseDir = $(if ($env:GITEA_CI_CLONE_BASE_DIR) { $env:GITEA_CI_CLONE_BASE_DIR } else { 'F:\CI\BuildVMs' }),
-
-    [string] $ArtifactBaseDir = 'F:\CI\Artifacts',
-
-    [ValidatePattern('^(\d{1,3}\.){3}\d{1,3}$')]
-    [string] $VMIPAddress = '',  # if empty, auto-detected via vmrun getGuestIPAddress
-
-    [string] $GuestCredentialTarget = 'BuildVMGuest',
-
-    [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe',
-
-    # Directory for job execution logs. Each job gets its own sub-directory:
-    # $LogDir\$JobId\invoke-ci.log
-    [string] $LogDir = 'F:\CI\Logs',
-
-    # Days to retain job logs. Directories older than this are purged at job end.
-    # Set to 0 to disable retention/purge.
-    [int] $LogRetentionDays = 30
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-# ── Resolve script directory for dot-sourcing sibling scripts ─────────────────
-$scriptDir = $PSScriptRoot
-
-# ── Validate required config ──────────────────────────────────────────────────
-if ([string]::IsNullOrWhiteSpace($TemplatePath)) {
-    Write-Error "TemplatePath is required. Set -TemplatePath or env:GITEA_CI_TEMPLATE_PATH."
-    exit 1
-}
-if (-not (Test-Path $TemplatePath -PathType Leaf)) {
-    Write-Error "Template VMX not found: $TemplatePath"
-    exit 1
-}
-if (-not (Test-Path $VmrunPath -PathType Leaf)) {
-    Write-Error "vmrun.exe not found: $VmrunPath"
-    exit 1
-}
-
-# ── Load guest credentials from Windows Credential Manager ───────────────────
-# Requires the CredentialManager module: Install-Module CredentialManager
-# In a lab setup you can fall back to prompting, but never hardcode credentials.
-$credential = $null
-try {
-    $credential = Get-StoredCredential -Target $GuestCredentialTarget -ErrorAction Stop
-    Write-Host "[Invoke-CIJob] Loaded guest credentials from Credential Manager ($GuestCredentialTarget)."
-}
-catch {
-    Write-Warning "[Invoke-CIJob] Could not load credentials from Credential Manager ($GuestCredentialTarget)."
-    Write-Warning "             Using interactive prompt as fallback. Store credentials with:"
-    Write-Warning "             cmdkey /generic:$GuestCredentialTarget /user:DOMAIN\user /pass:password"
-    $credential = Get-Credential -Message "Enter guest VM credentials for job $JobId"
-}
-
-# ── Setup paths ───────────────────────────────────────────────────────────────
-$jobArtifactDir = Join-Path $ArtifactBaseDir $JobId
-$hostCloneDir   = Join-Path $env:TEMP "ci-src-$JobId"
-$cloneVmxPath   = $null
-$startTime      = Get-Date
-
-# ── Start transcript ──────────────────────────────────────────────────────────
-$transcriptStarted = $false
-try {
-    $jobLogDir = Join-Path $LogDir $JobId
-    if (-not (Test-Path $jobLogDir)) { New-Item -ItemType Directory -Path $jobLogDir -Force | Out-Null }
-    $transcriptPath = Join-Path $jobLogDir 'invoke-ci.log'
-    # -Append allows starting a new transcript even when VS Code (or another host)
-    # has already opened a transcript on this PowerShell session.
-    Start-Transcript -Path $transcriptPath -Append -Force -ErrorAction Stop
-    $transcriptStarted = $true
-}
-catch {
-    Write-Warning "[Invoke-CIJob] Could not start transcript: $_"
-}
-
-Write-Host "============================================================"
-Write-Host "[Invoke-CIJob] Job          : $JobId"
-Write-Host "[Invoke-CIJob] Repository   : $RepoUrl"
-Write-Host "[Invoke-CIJob] Branch       : $Branch"
-if ($Commit) { Write-Host "[Invoke-CIJob] Commit       : $Commit" }
-Write-Host "[Invoke-CIJob] Build VM IP  : $VMIPAddress"
-Write-Host "[Invoke-CIJob] Template     : $TemplatePath"
-Write-Host "[Invoke-CIJob] Artifacts    : $jobArtifactDir"
-Write-Host "[Invoke-CIJob] Started      : $startTime"
-Write-Host "============================================================"
-
-$exitCode = 0
-
-try {
-    # ── Phase 1: Clone repo on HOST ───────────────────────────────────────
-    # Build VM is on VMnet8 NAT (internet OK for builds), but source is
-    # still cloned here and copied via WinRM zip to avoid injecting a PAT
-    # into the VM environment.
-    Write-Host "`n[Phase 1/6] Cloning repository on host..."
-    if (Test-Path $hostCloneDir) { Remove-Item $hostCloneDir -Recurse -Force }
-    $gitArgs = @('clone', '--depth', '1', '--branch', $Branch)
-    if ($Submodules) { $gitArgs += '--recurse-submodules' }
-    $gitArgs += @($RepoUrl, $hostCloneDir)
-    $ErrorActionPreference = 'Continue'
-    $gitOutput = & git @gitArgs 2>&1 | ForEach-Object { "$_" }
-    $gitExit = $LASTEXITCODE
-    $ErrorActionPreference = 'Stop'
-    if ($gitExit -ne 0) {
-        throw "git clone failed (exit $gitExit):`n$($gitOutput -join "`n")"
-    }
-    if ($Commit -ne '') {
-        $ErrorActionPreference = 'Continue'
-        $gitOutput = & git -C $hostCloneDir checkout $Commit 2>&1 | ForEach-Object { "$_" }
-        $gitExit = $LASTEXITCODE
-        if ($gitExit -ne 0) {
-            # Commit not in shallow history (e.g. manual run on older SHA).
-            # Fetch full history and retry.
-            Write-Host "[Invoke-CIJob] Shallow checkout failed — fetching full history..."
-            & git -C $hostCloneDir fetch --unshallow 2>&1 | Out-Null
-            $gitOutput = & git -C $hostCloneDir checkout $Commit 2>&1 | ForEach-Object { "$_" }
-            $gitExit = $LASTEXITCODE
-        }
-        $ErrorActionPreference = 'Stop'
-        if ($gitExit -ne 0) {
-            throw "git checkout $Commit failed (exit $gitExit):`n$($gitOutput -join "`n")"
-        }
-    }
-    Write-Host "[Invoke-CIJob] Source cloned to: $hostCloneDir"
-
-    # ── Phase 2: Clone VM ─────────────────────────────────────────────────
-    Write-Host "`n[Phase 2/6] Cloning VM..."
-    $cloneVmxPath = & "$scriptDir\New-BuildVM.ps1" `
-        -TemplatePath $TemplatePath `
-        -SnapshotName $SnapshotName `
-        -CloneBaseDir $CloneBaseDir `
-        -JobId        $JobId `
-        -VmrunPath    $VmrunPath
-
-    # ── Phase 3: Start VM ─────────────────────────────────────────────────
-    Write-Host "`n[Phase 3/6] Starting VM..."
-    $startOutput = & $VmrunPath -T ws start $cloneVmxPath nogui 2>&1
-    if ($LASTEXITCODE -ne 0) {
-        throw "vmrun start failed (exit $LASTEXITCODE): $startOutput"
-    }
-    Write-Host "[Invoke-CIJob] VM started."
-
-    # ── Phase 3b: Resolve VM IP if not provided ─────────────────────────
-    if ([string]::IsNullOrWhiteSpace($VMIPAddress)) {
-        Write-Host "[Invoke-CIJob] Auto-detecting VM IP via vmrun getGuestIPAddress..."
-        $detectedIP = & $VmrunPath getGuestIPAddress $cloneVmxPath -wait 2>&1
-        if ($LASTEXITCODE -ne 0 -or $detectedIP -notmatch '^(\d{1,3}\.){3}\d{1,3}$') {
-            throw "Could not detect VM IP address: $detectedIP"
-        }
-        $VMIPAddress = $detectedIP.Trim()
-        Write-Host "[Invoke-CIJob] Detected VM IP: $VMIPAddress"
-    }
-
-    # ── Phase 4: Wait for readiness ───────────────────────────────────────
-    Write-Host "`n[Phase 4/6] Waiting for VM readiness..."
-    & "$scriptDir\Wait-VMReady.ps1" `
-        -VMPath    $cloneVmxPath `
-        -IPAddress $VMIPAddress `
-        -VmrunPath $VmrunPath
-
-    # ── Phase 5: Remote build (copy source + build inside VM) ─────────────
-    Write-Host "`n[Phase 5/6] Invoking remote build..."
-    $remoteBuildParams = @{
-        IPAddress     = $VMIPAddress
-        Credential    = $credential
-        HostSourceDir = $hostCloneDir
-        Configuration = $Configuration
-    }
-    if ($BuildCommand -ne '')        { $remoteBuildParams['BuildCommand']        = $BuildCommand }
-    if ($GuestArtifactSource -ne '') { $remoteBuildParams['GuestArtifactSource'] = $GuestArtifactSource }
-    & "$scriptDir\Invoke-RemoteBuild.ps1" @remoteBuildParams
-
-    # ── Phase 6: Collect artifacts ────────────────────────────────────────
-    Write-Host "`n[Phase 6/6] Collecting artifacts..."
-    & "$scriptDir\Get-BuildArtifacts.ps1" `
-        -IPAddress         $VMIPAddress `
-        -Credential        $credential `
-        -GuestArtifactPath 'C:\CI\output\artifacts.zip' `
-        -HostArtifactDir   $jobArtifactDir `
-        -IncludeLogs
-
-    $elapsed = (Get-Date) - $startTime
-    Write-Host "`n============================================================"
-    Write-Host "[Invoke-CIJob] SUCCESS — Job $JobId completed in $($elapsed.ToString('mm\:ss'))"
-    Write-Host "[Invoke-CIJob] Artifacts: $jobArtifactDir"
-    Write-Host "============================================================"
-}
-catch {
-    $exitCode = 1
-    $elapsed  = (Get-Date) - $startTime
-    Write-Host "`n============================================================"
-    Write-Host "[Invoke-CIJob] FAILURE — Job $JobId failed after $($elapsed.ToString('mm\:ss'))"
-    Write-Host "Error: $_"
-    Write-Host "============================================================"
-}
-finally {
-    # ── Always destroy the VM ─────────────────────────────────────────────
-    if ($null -ne $cloneVmxPath -and (Test-Path $cloneVmxPath -PathType Leaf)) {
-        Write-Host "`n[Cleanup] Destroying ephemeral VM..."
-        & "$scriptDir\Remove-BuildVM.ps1" -VMPath $cloneVmxPath -VmrunPath $VmrunPath
-    }
-    else {
-        Write-Host "[Cleanup] No VM to destroy (clone was not created or already gone)."
-    }
-    # ── Always clean up host-side git clone ──────────────────────────────
-    if (Test-Path $hostCloneDir) {
-        Write-Host "[Cleanup] Removing host source clone ($hostCloneDir)..."
-        Remove-Item $hostCloneDir -Recurse -Force -ErrorAction SilentlyContinue
-    }
-
-    # ── Stop transcript ───────────────────────────────────────────────────
-    if ($transcriptStarted) {
-        try { Stop-Transcript -ErrorAction SilentlyContinue } catch {}
-    }
-
-    # ── Log retention: purge directories older than $LogRetentionDays days ─
-    if ($LogRetentionDays -gt 0 -and (Test-Path $LogDir)) {
-        $cutoff = (Get-Date).AddDays(-$LogRetentionDays)
-        Get-ChildItem -Path $LogDir -Directory -ErrorAction SilentlyContinue |
-            Where-Object { $_.LastWriteTime -lt $cutoff } |
-            ForEach-Object {
-                Remove-Item $_.FullName -Recurse -Force -ErrorAction SilentlyContinue
-                Write-Host "[Cleanup] Purged old log dir: $($_.FullName)"
-            }
-    }
-}
-
-exit $exitCode
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A4-closeout.md.
+# PowerShell common params (-ErrorAction etc.) must not be forwarded
+# to the Python CLI. Value-taking ones also consume the next token.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
+}
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
+
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
+    }
+}
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator job @pyArgs
+exit $LASTEXITCODE

scripts/Invoke-RemoteBuild.ps1

@@ -1,200 +1,91 @@
 #Requires -Version 5.1
-<#
-.SYNOPSIS
-    Copies pre-cloned source from host into a build VM and runs dotnet build.
-
-.DESCRIPTION
-    The caller (Invoke-CIJob.ps1) is responsible for cloning the repository
-    on the HOST before calling this script. This script then:
-      1. Compresses the local source tree on the host, copies the archive into
-         the VM via WinRM (single file = much faster than recursive Copy-Item),
-         then expands it inside the VM.
-      2. Runs dotnet restore and dotnet build inside the VM
-      3. Packages the output as C:\CI\output\artifacts.zip inside the VM
-
-    The build VM does NOT need internet access or git. All network I/O happens
-    on the host before this script is called.
-
-.PARAMETER IPAddress
-    IP of the build VM (e.g. 192.168.11.101).
-
-.PARAMETER Credential
-    PSCredential for the build user inside the VM.
-    Retrieve from Windows Credential Manager in production:
-      $cred = Get-StoredCredential -Target 'BuildVMGuest'
-
-.PARAMETER HostSourceDir
-    Full path on the HOST to the already-cloned repository directory.
-    This directory is copied into the VM as the build working directory.
-    Example: C:\Users\user\AppData\Local\Temp\ci-src-run-42
-
-.PARAMETER Configuration
-    MSBuild/dotnet build configuration. Default: Release
-
-.PARAMETER GuestWorkDir
-    Working directory inside the VM where source will be placed.
-    Default: C:\CI\build
-
-.PARAMETER GuestArtifactZip
-    Full path inside the VM where the artifact archive will be written.
-    Default: C:\CI\output\artifacts.zip
-
-.EXAMPLE
-    $cred = Get-Credential
-    .\Invoke-RemoteBuild.ps1 `
-        -IPAddress      "192.168.11.101" `
-        -Credential     $cred `
-        -HostSourceDir  "C:\Temp\ci-src-run-42"
-#>
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory)]
-    [ValidatePattern('^(\d{1,3}\.){3}\d{1,3}$')]
-    [string] $IPAddress,
-
-    [Parameter(Mandatory)]
-    [System.Management.Automation.PSCredential] $Credential,
-
-    [Parameter(Mandatory)]
-    [ValidateScript({ Test-Path $_ -PathType Container })]
-    [string] $HostSourceDir,
-
-    [string] $Configuration = 'Release',
-
-    # Custom build command to run inside the VM (working dir = GuestWorkDir).
-    # When empty, defaults to: dotnet restore + dotnet build --configuration $Configuration
-    # Example: 'python build_plugin.py --final'
-    [string] $BuildCommand = '',
-
-    # Glob pattern (relative to GuestWorkDir) of files to include in the artifact zip.
-    # Used only when BuildCommand is set. Default: collect everything under 'dist'.
-    # Example: 'dist\**' or 'Contrib\nsInnoUnp\Build\**'
-    [string] $GuestArtifactSource = 'dist',
-
-    [string] $GuestWorkDir = 'C:\CI\build',
-
-    [string] $GuestArtifactZip = 'C:\CI\output\artifacts.zip'
-)
-
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
-# ── Session options: skip SSL certificate checks for self-signed (lab use) ──
-$sessionOptions = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
+# Shim: delegates to the Python ci_orchestrator CLI (`build run`).
+# Original PS implementation moved to git history; see plans/A3-closeout.md.
+#
+# Typed parameters (`[PSCredential]`, `[hashtable]`, `[switch]`) cannot cross
+# a process boundary as-is; this shim translates them. Credentials are pulled
+# inside Python via keyring (`--credential-target`), so the bound `-Credential`
+# is intentionally discarded — callers should set `-CredentialTarget` instead
+# (or rely on the default `BuildVMGuest` resolved by the Python CLI).
 
-Write-Host "[Invoke-RemoteBuild] Connecting to VM at $IPAddress..."
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [string] $IPAddress,
 
-$session = New-PSSession `
-    -ComputerName  $IPAddress `
-    -Credential    $Credential `
-    -SessionOption $sessionOptions `
-    -ErrorAction   Stop
+    [Parameter()]
+    [System.Management.Automation.PSCredential] $Credential,
 
-try {
-    # ── Ensure working directories exist on guest ────────────────────────
-    Invoke-Command -Session $session -ScriptBlock {
-        param($workDir, $outputDir)
-        # Ensure artifact output parent exists
-        $outParent = Split-Path $outputDir -Parent
-        if (-not (Test-Path $outParent)) {
-            New-Item -ItemType Directory -Path $outParent -Force | Out-Null
-        }
-        # Clean and recreate build dir (ephemeral VM, but guard against partial prior run)
-        if (Test-Path $workDir) { Remove-Item $workDir -Recurse -Force }
-        New-Item -ItemType Directory -Path $workDir -Force | Out-Null
-    } -ArgumentList $GuestWorkDir, $GuestArtifactZip
+    [string] $HostSourceDir = '',
+    [string] $CloneUrl = '',
+    [string] $CloneBranch = 'main',
+    [string] $CloneCommit = '',
+    [switch] $CloneSubmodules,
+    [string] $GiteaCredentialTarget = 'GiteaPAT',
+    [string] $Configuration = 'Release',
+    [string] $BuildCommand = '',
+    [string] $GuestArtifactSource = 'dist',
+    [string] $GuestWorkDir = 'C:\CI\build',
+    [string] $GuestArtifactZip = 'C:\CI\output\artifacts.zip',
+    [switch] $UseSharedCache,
+    [switch] $SkipArtifact,
 
-    # ── Copy source tree: compress on host, transfer zip, expand in guest ──
-    # Single-file transfer over WinRM is far faster than recursive Copy-Item.
-    $hostZip = [System.IO.Path]::GetTempFileName() -replace '\.tmp$', '.zip'
-    try {
-        Write-Host "[Invoke-RemoteBuild] Compressing source on host..."
-        Compress-Archive -Path "$HostSourceDir\*" -DestinationPath $hostZip -CompressionLevel Fastest -Force
-        $zipSize = [math]::Round((Get-Item $hostZip).Length / 1MB, 1)
-        Write-Host "[Invoke-RemoteBuild] Transferring archive to guest ($zipSize MB)..."
-        $guestZip = 'C:\CI\src-transfer.zip'
-        Copy-Item -Path $hostZip -Destination $guestZip -ToSession $session -Force
-        Write-Host "[Invoke-RemoteBuild] Expanding archive in guest..."
-        Invoke-Command -Session $session -ScriptBlock {
-            param($zip, $dest)
-            Expand-Archive -Path $zip -DestinationPath $dest -Force
-            Remove-Item $zip -Force
-        } -ArgumentList $guestZip, $GuestWorkDir
-        Write-Host "[Invoke-RemoteBuild] Source transfer complete."
+    [ValidateSet('Windows', 'Linux')]
+    [string] $GuestOS = 'Windows',
+
+    [string] $SshKeyPath = 'F:\CI\keys\ci_linux',
+    [string] $SshUser = 'ci_build',
+    [string] $SshKnownHostsFile = '',
+    [string] $GuestLinuxWorkDir = '/opt/ci/build',
+    [string] $GuestLinuxOutputDir = '/opt/ci/output',
+
+    [hashtable] $ExtraGuestEnv = @{},
+
+    # Optional override for the Credential Manager target (overrides any
+    # fallback resolved by Python). Discards $Credential.
+    [string] $CredentialTarget = ''
+)
+
+$pyArgs = @(
+    '--ip-address', $IPAddress,
+    '--guest-os', $GuestOS.ToLower(),
+    '--ssh-user', $SshUser,
+    '--ssh-key-path', $SshKeyPath,
+    '--clone-branch', $CloneBranch,
+    '--gitea-credential-target', $GiteaCredentialTarget,
+    '--configuration', $Configuration,
+    '--guest-work-dir', $GuestWorkDir,
+    '--guest-artifact-zip', $GuestArtifactZip,
+    '--guest-linux-work-dir', $GuestLinuxWorkDir,
+    '--guest-linux-output-dir', $GuestLinuxOutputDir,
+    '--guest-artifact-source', $GuestArtifactSource
+)
+
+if ($HostSourceDir)     { $pyArgs += @('--host-source-dir', $HostSourceDir) }
+if ($CloneUrl)          { $pyArgs += @('--clone-url', $CloneUrl) }
+if ($CloneCommit)       { $pyArgs += @('--clone-commit', $CloneCommit) }
+if ($BuildCommand)      { $pyArgs += @('--build-command', $BuildCommand) }
+if ($SshKnownHostsFile) { $pyArgs += @('--ssh-known-hosts-file', $SshKnownHostsFile) }
+if ($CredentialTarget)  { $pyArgs += @('--credential-target', $CredentialTarget) }
+
+if ($CloneSubmodules.IsPresent) { $pyArgs += '--clone-submodules' }
+if ($UseSharedCache.IsPresent)  { $pyArgs += '--use-shared-cache' }
+if ($SkipArtifact.IsPresent)    { $pyArgs += '--skip-artifact' }
+
+if ($ExtraGuestEnv -and $ExtraGuestEnv.Count -gt 0) {
+    foreach ($key in $ExtraGuestEnv.Keys) {
+        $pyArgs += @('--extra-env', "$key=$($ExtraGuestEnv[$key])")
     }
-    finally {
-        Remove-Item $hostZip -Force -ErrorAction SilentlyContinue
-    }
-
-    # ── Build ──────────────────────────────────────────────────────────
-    if ($BuildCommand -ne '') {
-        # ── Custom build command (e.g. python, msbuild, cmake…) ──────────
-        Write-Host "[Invoke-RemoteBuild] Running build command: $BuildCommand"
-        $buildExit = Invoke-Command -Session $session -ScriptBlock {
-            param($workDir, $cmd, $artifactZip, $artifactSrc)
-            # Unbuffered Python output — lines appear in real-time instead of being held in buffer
-            $env:PYTHONUNBUFFERED = '1'
-            Set-Location $workDir
-            # Stream each output line via Write-Host — WinRM forwards Write-Host in real-time
-            & cmd /c "$cmd 2>&1" | ForEach-Object { Write-Host $_ }
-            $exit = $LASTEXITCODE
-
-            if ($exit -eq 0) {
-                $archiveDir = Split-Path $artifactZip -Parent
-                if (-not (Test-Path $archiveDir)) {
-                    New-Item -ItemType Directory -Path $archiveDir -Force | Out-Null
-                }
-                $srcPath = Join-Path $workDir $artifactSrc
-                Compress-Archive -Path $srcPath -DestinationPath $artifactZip -Force
-            }
-
-            return $exit
-        } -ArgumentList $GuestWorkDir, $BuildCommand, $GuestArtifactZip, $GuestArtifactSource
-
-        if ($buildExit -ne 0) {
-            throw "Build command failed (exit $buildExit)"
-        }
-    }
-    else {
-        # ── Default: dotnet restore + dotnet build ────────────────────────
-        Write-Host "[Invoke-RemoteBuild] Running dotnet restore..."
-        $restoreExit = Invoke-Command -Session $session -ScriptBlock {
-            param($workDir)
-            Set-Location $workDir
-            dotnet restore 2>&1 | ForEach-Object { Write-Host $_ }
-            return $LASTEXITCODE
-        } -ArgumentList $GuestWorkDir
-
-        if ($restoreExit -ne 0) {
-            throw "dotnet restore failed (exit $restoreExit)"
-        }
-
-        Write-Host "[Invoke-RemoteBuild] Running dotnet build (configuration: $Configuration)..."
-        $buildExit = Invoke-Command -Session $session -ScriptBlock {
-            param($workDir, $config, $artifactZip)
-            Set-Location $workDir
-            $outputDir = Join-Path $workDir 'bin\CIOutput'
-            dotnet build --configuration $config --output $outputDir 2>&1 | ForEach-Object { Write-Host $_ }
-            $exit = $LASTEXITCODE
-
-            if ($exit -eq 0) {
-                $archiveDir = Split-Path $artifactZip -Parent
-                if (-not (Test-Path $archiveDir)) {
-                    New-Item -ItemType Directory -Path $archiveDir -Force | Out-Null
-                }
-                Compress-Archive -Path "$outputDir\*" -DestinationPath $artifactZip -Force
-            }
-
-            return $exit
-        } -ArgumentList $GuestWorkDir, $Configuration, $GuestArtifactZip
-
-        if ($buildExit -ne 0) {
-            throw "dotnet build failed (exit $buildExit)"
-        }
-    }
-
-    Write-Host "[Invoke-RemoteBuild] Build succeeded. Artifact at $GuestArtifactZip"
 }
-finally {
-    Remove-PSSession $session -ErrorAction SilentlyContinue
+
+if ($Credential) {
+    Write-Host '[Invoke-RemoteBuild] -Credential ignored; Python CLI uses keyring (set -CredentialTarget to override target name).'
 }
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator build run @pyArgs
+exit $LASTEXITCODE

scripts/Invoke-RetentionPolicy.ps1

@@ -0,0 +1,144 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Purges old CI artifacts, logs, and stale IP leases based on retention policy.
+
+.DESCRIPTION
+    Removes per-job subdirectories under ArtifactDir and LogDir whose last-write
+    time is older than RetentionDays. If the monitored drive is below MinFreeGB,
+    switches automatically to AggressiveRetentionDays to reclaim space faster.
+
+    Also removes stale IP lease files under F:\CI\State\ip-leases\ that are
+    older than 12 hours (defensive cleanup for jobs that crashed without a finally).
+
+    Designed to run as a Windows Scheduled Task (see Register-CIScheduledTasks.ps1).
+    Safe to run while CI jobs are active — only deletes directories whose
+    last-write time predates the cutoff.
+
+.PARAMETER ArtifactDir
+    Directory containing per-job artifact subdirectories. Default: F:\CI\Artifacts
+
+.PARAMETER LogDir
+    Directory containing per-job log subdirectories. Default: F:\CI\Logs
+
+.PARAMETER RetentionDays
+    Normal retention threshold in days. Default: 30
+
+.PARAMETER AggressiveRetentionDays
+    Retention threshold used when drive free space drops below MinFreeGB. Default: 7
+
+.PARAMETER MinFreeGB
+    If drive free space is below this value, AggressiveRetentionDays is used instead
+    of RetentionDays and a warning is emitted. Default: 50
+
+.PARAMETER DriveLetter
+    Single drive letter (without colon) to check for free space. Default: F
+
+.EXAMPLE
+    # Dry run — lists what would be deleted
+    .\Invoke-RetentionPolicy.ps1 -WhatIf
+
+    # Live run
+    .\Invoke-RetentionPolicy.ps1
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [string] $ArtifactDir = 'F:\CI\Artifacts',
+    [string] $LogDir      = 'F:\CI\Logs',
+
+    [ValidateRange(1, 365)]
+    [int] $RetentionDays = 30,
+
+    [ValidateRange(1, 365)]
+    [int] $AggressiveRetentionDays = 7,
+
+    [ValidateRange(1, 1000)]
+    [int] $MinFreeGB = 50,
+
+    [ValidatePattern('^[A-Za-z]$')]
+    [string] $DriveLetter = 'F'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Continue'   # Don't abort on individual file errors
+
+# ── Determine effective retention threshold ───────────────────────────────────
+$drive = Get-PSDrive -Name $DriveLetter -ErrorAction SilentlyContinue
+$freeGB = if ($drive) { [math]::Round($drive.Free / 1GB, 1) } else { [double]::MaxValue }
+
+$aggressiveMode  = $freeGB -lt $MinFreeGB
+$effectiveDays   = if ($aggressiveMode) { $AggressiveRetentionDays } else { $RetentionDays }
+$cutoff          = (Get-Date).AddDays(-$effectiveDays)
+
+Write-Host "[RetentionPolicy] Drive ${DriveLetter}: free ${freeGB} GB"
+if ($aggressiveMode) {
+    Write-Warning "[RetentionPolicy] Free space below ${MinFreeGB} GB — aggressive retention: ${AggressiveRetentionDays}d"
+} else {
+    Write-Host "[RetentionPolicy] Normal retention: ${effectiveDays}d (cutoff: $($cutoff.ToString('yyyy-MM-dd')))"
+}
+
+# ── Helper: purge old subdirectories under a base dir ─────────────────────────
+function Remove-OldJobDirs {
+    [CmdletBinding(SupportsShouldProcess)]
+    param([string]$BaseDir, [string]$Label)
+
+    if (-not (Test-Path $BaseDir)) {
+        Write-Host "[RetentionPolicy] $Label dir not found: $BaseDir — skipping."
+        return
+    }
+
+    $old = Get-ChildItem -Path $BaseDir -Directory -ErrorAction SilentlyContinue |
+        Where-Object { $_.LastWriteTime -lt $cutoff }
+
+    if (-not @($old).Count) {
+        Write-Host "[RetentionPolicy] ${Label}: nothing to purge (cutoff: $($cutoff.ToString('yyyy-MM-dd')))."
+        return
+    }
+
+    foreach ($dir in $old) {
+        $agedays = [int]((Get-Date) - $dir.LastWriteTime).TotalDays
+        if ($PSCmdlet.ShouldProcess($dir.FullName, "Remove $Label dir (age: ${agedays}d)")) {
+            Remove-Item $dir.FullName -Recurse -Force -ErrorAction SilentlyContinue
+            Write-Host "[RetentionPolicy] Purged $Label (${agedays}d): $($dir.Name)"
+        }
+    }
+}
+
+Remove-OldJobDirs -BaseDir $ArtifactDir -Label 'artifact'
+Remove-OldJobDirs -BaseDir $LogDir      -Label 'log'
+
+# ── Stale IP lease cleanup (§2.1 defensive) ───────────────────────────────────
+# Lease files are normally deleted by Invoke-CIJob.ps1 finally block.
+# If the host crashed mid-job the lease file is never removed. Remove leases
+# older than 12 hours (well beyond any plausible build duration).
+$leasesDir    = 'F:\CI\State\ip-leases'
+$leaseCutoff  = (Get-Date).AddHours(-12)
+if (Test-Path $leasesDir) {
+    $staleLeases = Get-ChildItem -Path $leasesDir -File -Filter '*.lease' -ErrorAction SilentlyContinue |
+        Where-Object { $_.LastWriteTime -lt $leaseCutoff }
+    foreach ($lf in @($staleLeases)) {
+        if ($PSCmdlet.ShouldProcess($lf.FullName, 'Remove stale IP lease')) {
+            Remove-Item $lf.FullName -Force -ErrorAction SilentlyContinue
+            Write-Host "[RetentionPolicy] Removed stale IP lease: $($lf.Name)"
+        }
+    }
+}
+
+# ── Stale vm-start.lock cleanup ─────────────────────────────────────────────
+# The lock is released by Invoke-CIJob.ps1 normally. On host crash it persists;
+# the OS-level lock is gone after reboot but the file blocks subsequent IP-acquire
+# retries for 10 minutes and confuses operators. Remove if older than 30 minutes.
+$lockFile  = 'F:\CI\State\vm-start.lock'
+$lockCutoff = (Get-Date).AddMinutes(-30)
+if ((Test-Path $lockFile) -and (Get-Item $lockFile).LastWriteTime -lt $lockCutoff) {
+    if ($PSCmdlet.ShouldProcess($lockFile, 'Remove stale vm-start.lock')) {
+        $lockAgeMin = [int]((Get-Date) - (Get-Item $lockFile).LastWriteTime).TotalMinutes
+        Remove-Item $lockFile -Force -ErrorAction SilentlyContinue
+        Write-Host "[RetentionPolicy] Removed stale vm-start.lock (age: ${lockAgeMin} min)"
+    }
+}
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+$freeGBAfter = if ($drive) { [math]::Round((Get-PSDrive -Name $DriveLetter -ErrorAction SilentlyContinue).Free / 1GB, 1) } else { $freeGB }
+$delta       = [math]::Round($freeGBAfter - $freeGB, 1)
+Write-Host "[RetentionPolicy] Done. Drive ${DriveLetter}: free ${freeGBAfter} GB (delta: +${delta} GB)"

scripts/Measure-CIBenchmark.ps1

@@ -0,0 +1,248 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Measures CI infrastructure phase timings: clone, start, IP acquire, WinRM ready, destroy.
+
+.DESCRIPTION
+    Creates one or more ephemeral VMs from the template, times each phase, destroys
+    them, then prints a summary table. Results are appended to F:\CI\Logs\benchmark.jsonl
+    for long-term trend tracking (compare before/after §3.1 cache, §3.2 7-Zip, etc.).
+
+    Phases measured:
+      clone    — vmrun clone (linked clone from snapshot)
+      start    — vmrun start (until command returns)
+      ip       — vmrun getGuestIPAddress (polling until IP appears)
+      winrm    — TCP 5986 reachable (polling)
+      destroy  — stop + deleteVM + dir removal
+
+    No actual build is run. Phase 5 build timings come from invoke-ci.jsonl logs
+    produced by Invoke-CIJob.ps1.
+
+.PARAMETER TemplatePath
+    Full path to the template VM's .vmx file.
+    Default: F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
+
+.PARAMETER SnapshotName
+    Snapshot name to clone from. Default: BaseClean
+
+.PARAMETER CloneBaseDir
+    Directory for ephemeral clone folders. Default: F:\CI\BuildVMs
+
+.PARAMETER VmrunPath
+    Path to vmrun.exe.
+    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
+
+.PARAMETER Iterations
+    Number of clone→ready→destroy cycles to run. Multiple iterations reduce timing
+    variance from cold-cache effects. Default: 1
+
+.PARAMETER TimeoutSeconds
+    Maximum seconds to wait for IP and WinRM per iteration. Default: 300
+
+.PARAMETER OutputDir
+    Directory where benchmark.jsonl is appended. Default: F:\CI\Logs
+
+.EXAMPLE
+    # Single baseline run
+    .\Measure-CIBenchmark.ps1
+
+    # 3 iterations for average (first may be slow due to cold host disk cache)
+    .\Measure-CIBenchmark.ps1 -Iterations 3
+
+    # Custom snapshot
+    .\Measure-CIBenchmark.ps1 -SnapshotName BaseClean_20260510
+#>
+[CmdletBinding()]
+param(
+    [string] $TemplatePath   = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx',
+    [string] $SnapshotName   = 'BaseClean',
+    [string] $CloneBaseDir   = 'F:\CI\BuildVMs',
+    [string] $VmrunPath      = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe',
+
+    [ValidateRange(1, 10)]
+    [int] $Iterations = 1,
+
+    [ValidateRange(60, 600)]
+    [int] $TimeoutSeconds = 300,
+
+    [string] $OutputDir = 'F:\CI\Logs'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+$ProgressPreference   = 'SilentlyContinue'   # suppress Write-Progress (Test-NetConnection, IWR, etc.)
+
+Import-Module (Join-Path $PSScriptRoot '_Common.psm1') -Force
+Resolve-VmrunPath -VmrunPath $VmrunPath | Out-Null
+
+if (-not (Test-Path $TemplatePath -PathType Leaf)) {
+    throw "Template VMX not found: $TemplatePath"
+}
+if (-not (Test-Path $CloneBaseDir)) {
+    New-Item -ItemType Directory -Path $CloneBaseDir -Force | Out-Null
+}
+if (-not (Test-Path $OutputDir)) {
+    New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null
+}
+
+$benchmarkLog = Join-Path $OutputDir 'benchmark.jsonl'
+$results      = [System.Collections.Generic.List[pscustomobject]]::new()
+
+Write-Host ""
+Write-Host "=== CI Benchmark  template: $(Split-Path $TemplatePath -Leaf)  snapshot: $SnapshotName  iterations: $Iterations ==="
+Write-Host ""
+
+for ($i = 1; $i -le $Iterations; $i++) {
+    Write-Host "--- Iteration $i / $Iterations ---"
+    $runId    = "bench-$(Get-Date -Format 'yyyyMMdd-HHmmss')-$i"
+    $cloneVmx = $null
+    $cloneDir = $null
+
+    $t = [ordered]@{
+        clone   = $null
+        start   = $null
+        ip      = $null
+        winrm   = $null
+        destroy = $null
+        deltaKB = $null
+        vmIP    = $null
+        error   = $null
+    }
+
+    try {
+        # ── Phase: clone ──────────────────────────────────────────────────────
+        $cloneName = "Clone_${runId}"
+        $cloneDir  = Join-Path $CloneBaseDir $cloneName
+        $cloneVmx  = Join-Path $cloneDir "$cloneName.vmx"
+
+        Write-Host "[bench] Cloning..."
+        $sw = [System.Diagnostics.Stopwatch]::StartNew()
+        $null = Invoke-Vmrun -VmrunPath $VmrunPath -Operation clone `
+                  -Arguments @($TemplatePath, $cloneVmx, 'linked', '-snapshot', $SnapshotName) `
+                  -ThrowOnError
+        $t.clone = [math]::Round($sw.Elapsed.TotalSeconds, 2)
+        Write-Host "[bench] clone: $($t.clone)s"
+
+        # Measure linked-clone disk footprint
+        try {
+            $cloneSizeBytes = (Get-ChildItem -Path $cloneDir -Recurse -File -ErrorAction Stop |
+                Measure-Object -Property Length -Sum).Sum
+            $t.deltaKB = [math]::Round($cloneSizeBytes / 1KB, 0)
+            Write-Host "[bench] clone size: $($t.deltaKB) KB"
+        } catch {
+            Write-Warning "[bench] Could not measure clone size: $_"
+        }
+
+        # ── Phase: start ──────────────────────────────────────────────────────
+        Write-Host "[bench] Starting VM..."
+        $sw.Restart()
+        Invoke-Vmrun -VmrunPath $VmrunPath -Operation start `
+            -Arguments @($cloneVmx, 'nogui') -ThrowOnError | Out-Null
+        $t.start = [math]::Round($sw.Elapsed.TotalSeconds, 2)
+        Write-Host "[bench] start: $($t.start)s"
+
+        # ── Phase: IP acquire (primary: guestinfo.ci-ip, fallback: getGuestIPAddress) ──
+        Write-Host "[bench] Waiting for guest IP..."
+        $sw.Restart()
+        $vmIP = Get-GuestIPAddress -VmrunPath $VmrunPath -VmxPath $cloneVmx `
+                    -TimeoutSeconds $TimeoutSeconds
+        if (-not $vmIP) { throw "Timed out waiting for guest IP after $TimeoutSeconds s" }
+        $t.ip   = [math]::Round($sw.Elapsed.TotalSeconds, 2)
+        $t.vmIP = $vmIP
+        Write-Host "[bench] ip ($vmIP): $($t.ip)s"
+
+        # ── Phase: WinRM ready (poll TCP 5986) ────────────────────────────────
+        Write-Host "[bench] Waiting for WinRM (TCP 5986)..."
+        $sw.Restart()
+        $deadline = (Get-Date).AddSeconds($TimeoutSeconds)
+        $winrmUp  = $false
+        while ((Get-Date) -lt $deadline) {
+            $winrmUp = Test-NetConnection -ComputerName $vmIP -Port 5986 `
+                           -InformationLevel Quiet -WarningAction SilentlyContinue `
+                           -ErrorAction SilentlyContinue
+            if ($winrmUp) { break }
+            Start-Sleep -Seconds 3
+        }
+        if (-not $winrmUp) { throw "Timed out waiting for WinRM on $vmIP`:5986 after $TimeoutSeconds s" }
+        $t.winrm = [math]::Round($sw.Elapsed.TotalSeconds, 2)
+        Write-Host "[bench] winrm: $($t.winrm)s"
+    }
+    catch {
+        $t.error = "$_"
+        Write-Warning "[bench] Iteration $i failed: $_"
+    }
+    finally {
+        # ── Phase: destroy ────────────────────────────────────────────────────
+        if ($cloneVmx -and (Test-Path $cloneVmx -PathType Leaf)) {
+            Write-Host "[bench] Destroying clone..."
+            $sw = [System.Diagnostics.Stopwatch]::StartNew()
+            & (Join-Path $PSScriptRoot 'Remove-BuildVM.ps1') `
+                -VMPath $cloneVmx -VmrunPath $VmrunPath -GracefulTimeoutSeconds 10 `
+                -ErrorAction SilentlyContinue
+            $t.destroy = [math]::Round($sw.Elapsed.TotalSeconds, 2)
+            Write-Host "[bench] destroy: $($t.destroy)s"
+        } elseif ($cloneDir -and (Test-Path $cloneDir)) {
+            Remove-Item $cloneDir -Recurse -Force -ErrorAction SilentlyContinue
+        }
+    }
+
+    $totalBootSec = if ($t.ip -and $t.winrm) {
+        [math]::Round($t.clone + $t.start + $t.ip + $t.winrm, 2)
+    } else { $null }
+
+    $result = [pscustomobject]@{
+        ts           = (Get-Date -Format 'o')
+        runId        = $runId
+        iteration    = $i
+        template     = Split-Path $TemplatePath -Leaf
+        snapshot     = $SnapshotName
+        cloneSec     = $t.clone
+        startSec     = $t.start
+        ipSec        = $t.ip
+        winrmSec     = $t.winrm
+        destroySec   = $t.destroy
+        totalBootSec = $totalBootSec
+        deltaKB      = $t.deltaKB
+        vmIP         = $t.vmIP
+        error        = $t.error
+    }
+    $results.Add($result)
+
+    # Append to JSONL log
+    try {
+        $result | ConvertTo-Json -Compress -Depth 3 |
+            Add-Content -Path $benchmarkLog -Encoding UTF8 -ErrorAction Stop
+    } catch {
+        Write-Warning "[bench] Could not write benchmark.jsonl: $_"
+    }
+
+    Write-Host ""
+}
+
+# ── Summary table ─────────────────────────────────────────────────────────────
+Write-Host "=== Results ==="
+$results | Format-Table @(
+    @{ L = 'Iter';        E = { $_.iteration } }
+    @{ L = 'Clone(s)';   E = { $_.cloneSec } }
+    @{ L = 'Start(s)';   E = { $_.startSec } }
+    @{ L = 'IP(s)';      E = { $_.ipSec } }
+    @{ L = 'WinRM(s)';   E = { $_.winrmSec } }
+    @{ L = 'Destroy(s)'; E = { $_.destroySec } }
+    @{ L = 'Boot total'; E = { $_.totalBootSec } }
+    @{ L = 'Delta(KB)';  E = { $_.deltaKB } }
+    @{ L = 'IP';         E = { $_.vmIP } }
+    @{ L = 'Error';      E = { $_.error } }
+) -AutoSize
+
+if ($Iterations -gt 1) {
+    $ok = @($results | Where-Object { -not $_.error })
+    if ($ok.Count -gt 0) {
+        $avgBoot = [math]::Round(($ok | ForEach-Object { $_.totalBootSec } |
+            Measure-Object -Average).Average, 2)
+        Write-Host "Average boot-to-WinRM ($($ok.Count) successful runs): $avgBoot s"
+    }
+}
+
+Write-Host ""
+Write-Host "Results appended to: $benchmarkLog"
+

scripts/New-BuildVM.ps1

@@ -1,43 +1,10 @@
 #Requires -Version 5.1
-<#
-.SYNOPSIS
-    Creates a linked clone of the template VM for an ephemeral CI build.
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
 
-.DESCRIPTION
-    Uses vmrun.exe to create a linked clone from a frozen template snapshot.
-    Returns the full path to the new clone's .vmx file on success.
-    The template VM and its snapshot are never modified.
+# Shim: delegates to the Python ci_orchestrator CLI (`vm new`).
+# Original PS implementation moved to git history; see plans/A3-closeout.md.
 
-.PARAMETER TemplatePath
-    Full path to the template VM's .vmx file.
-    Example: F:\CI\Templates\WinBuild\WinBuild.vmx
-
-.PARAMETER SnapshotName
-    Name of the snapshot on the template VM to clone from.
-    Default: BaseClean
-
-.PARAMETER CloneBaseDir
-    Directory under which the new clone folder will be created.
-    The clone folder is named after the job ID and timestamp.
-    Example: F:\CI\BuildVMs
-
-.PARAMETER JobId
-    Unique identifier for the CI job (e.g. run ID from Gitea Actions).
-    Used to name the clone: Clone_{JobId}_{yyyyMMdd_HHmmss}
-
-.PARAMETER VmrunPath
-    Full path to vmrun.exe.
-    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
-
-.OUTPUTS
-    [string] Full path to the new clone's .vmx file.
-
-.EXAMPLE
-    $vmxPath = .\New-BuildVM.ps1 `
-        -TemplatePath "F:\CI\Templates\WinBuild\WinBuild.vmx" `
-        -CloneBaseDir "F:\CI\BuildVMs" `
-        -JobId "run-42"
-#>
 [CmdletBinding()]
 param(
     [Parameter(Mandatory)]
@@ -55,60 +22,15 @@ param(
     [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
 )
 
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-# --- Validate vmrun.exe ---
-if (-not (Test-Path $VmrunPath -PathType Leaf)) {
-    throw "vmrun.exe not found at: $VmrunPath`nInstall VMware Workstation Pro and update -VmrunPath if needed."
-}
-
-# --- Build clone path ---
-$timestamp  = Get-Date -Format 'yyyyMMdd_HHmmss'
-$cloneName  = "Clone_${JobId}_${timestamp}"
-$cloneDir   = Join-Path $CloneBaseDir $cloneName
-$cloneVmx   = Join-Path $cloneDir "$cloneName.vmx"
-
-# Ensure clone base dir exists
-if (-not (Test-Path $CloneBaseDir)) {
-    New-Item -ItemType Directory -Path $CloneBaseDir -Force | Out-Null
-}
-
-Write-Host "[New-BuildVM] Creating linked clone..."
-Write-Host "  Template  : $TemplatePath"
-Write-Host "  Snapshot  : $SnapshotName"
-Write-Host "  Clone VMX : $cloneVmx"
-
-$sw = [System.Diagnostics.Stopwatch]::StartNew()
-
-# --- Run vmrun clone ---
-$vmrunArgs = @(
-    '-T', 'ws',
-    'clone',
-    $TemplatePath,
-    $cloneVmx,
-    'linked',
-    '-snapshot', $SnapshotName
+$pyArgs = @(
+    '--template-path', $TemplatePath,
+    '--snapshot-name', $SnapshotName,
+    '--clone-base-dir', $CloneBaseDir,
+    '--job-id', $JobId,
+    '--vmrun-path', $VmrunPath
 )
 
-$result = & $VmrunPath @vmrunArgs 2>&1
-$exitCode = $LASTEXITCODE
-
-$sw.Stop()
-
-if ($exitCode -ne 0) {
-    # Clean up partial clone directory if it was created
-    if (Test-Path $cloneDir) {
-        Remove-Item $cloneDir -Recurse -Force -ErrorAction SilentlyContinue
-    }
-    throw "vmrun clone failed (exit $exitCode).`nOutput: $result"
-}
-
-if (-not (Test-Path $cloneVmx -PathType Leaf)) {
-    throw "vmrun reported success but clone VMX not found at: $cloneVmx"
-}
-
-Write-Host "[New-BuildVM] Clone created in $($sw.Elapsed.TotalSeconds.ToString('F1'))s : $cloneVmx"
-
-# Return the VMX path as output
-return $cloneVmx
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator vm new @pyArgs
+exit $LASTEXITCODE

scripts/Register-CIScheduledTasks.ps1

@@ -0,0 +1,198 @@
+#Requires -Version 5.1
+#Requires -RunAsAdministrator
+<#
+.SYNOPSIS
+    Registers Windows Scheduled Tasks for CI system maintenance.
+
+.DESCRIPTION
+    Creates or updates four tasks under the \CI\ task folder:
+
+      CI-CleanupOrphans   — Runs Cleanup-OrphanedBuildVMs.ps1 every 6 hours
+                            and at host startup. Destroys stale build VMs
+                            (those older than -MaxAgeHours, default 4) that
+                            were not cleaned up after a crash or timeout.
+
+      CI-RetentionPolicy  — Runs Invoke-RetentionPolicy.ps1 daily at 3:00 AM
+                            and at host startup (with a 15-min random delay).
+                            Purges old artifact and log directories per the
+                            configured retention window.
+
+      CI-DiskSpaceAlert   — Runs Watch-DiskSpace.ps1 every 15 minutes.
+                            Writes an Event Log warning and optional webhook
+                            when CI drive free space falls below 50 GB.
+
+      CI-RunnerHealth     — Runs Watch-RunnerHealth.ps1 every 15 minutes.
+                            Auto-restarts act_runner if stopped; rate-limited
+                            to 3 restarts per hour before requiring manual fix.
+
+    All tasks run as SYSTEM with highest privilege. Idempotent: safe to re-run
+    after updating the scripts — existing tasks are overwritten (-Force).
+
+.PARAMETER ScriptRoot
+    Directory containing the CI scripts. Default: N:\Code\Workspace\Local-CI-CD-System\scripts
+
+.PARAMETER MaxAgeHours
+    Passed to Cleanup-OrphanedBuildVMs.ps1. VMs older than this are treated as
+    orphaned. Must exceed the longest expected build duration. Default: 4
+
+.EXAMPLE
+    # Register (or update) tasks — run from an elevated PowerShell session
+    .\Register-CIScheduledTasks.ps1
+
+    # Preview what would be registered
+    .\Register-CIScheduledTasks.ps1 -WhatIf
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [string] $ScriptRoot  = 'N:\Code\Workspace\Local-CI-CD-System\scripts',
+
+    [ValidateRange(1, 168)]
+    [int] $MaxAgeHours = 4
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$psExe     = "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe"
+$taskPath  = '\CI\'
+$principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -RunLevel Highest
+
+# Ensure task folder exists (Register-ScheduledTask creates it, but be explicit)
+$schedulerService = New-Object -ComObject 'Schedule.Service'
+$schedulerService.Connect()
+$rootFolder = $schedulerService.GetFolder('\')
+try { $rootFolder.GetFolder('CI') | Out-Null }
+catch { $rootFolder.CreateFolder('CI') | Out-Null }
+[System.Runtime.InteropServices.Marshal]::ReleaseComObject($schedulerService) | Out-Null
+
+# ── Task 1: CI-CleanupOrphans ─────────────────────────────────────────────────
+$cleanupScript = Join-Path $ScriptRoot 'Cleanup-OrphanedBuildVMs.ps1'
+if (-not (Test-Path $cleanupScript -PathType Leaf)) {
+    Write-Warning "Script not found — skipping CI-CleanupOrphans: $cleanupScript"
+} else {
+    $cleanupAction = New-ScheduledTaskAction `
+        -Execute  $psExe `
+        -Argument "-NoProfile -NonInteractive -ExecutionPolicy Bypass -File `"$cleanupScript`" -MaxAgeHours $MaxAgeHours"
+
+    # Repeat every 6 hours indefinitely (Once trigger + RepetitionInterval)
+    $repeat6h = New-ScheduledTaskTrigger -Once -At '00:00' `
+        -RepetitionInterval (New-TimeSpan -Hours 6)
+    $atStartup = New-ScheduledTaskTrigger -AtStartup
+
+    $cleanupSettings = New-ScheduledTaskSettingsSet `
+        -ExecutionTimeLimit (New-TimeSpan -Hours 1) `
+        -MultipleInstances  IgnoreNew `
+        -StartWhenAvailable
+
+    if ($PSCmdlet.ShouldProcess('CI-CleanupOrphans', 'Register/update scheduled task')) {
+        Register-ScheduledTask `
+            -TaskName   'CI-CleanupOrphans' `
+            -TaskPath   $taskPath `
+            -Action     $cleanupAction `
+            -Trigger    @($repeat6h, $atStartup) `
+            -Principal  $principal `
+            -Settings   $cleanupSettings `
+            -Description "Destroys orphaned CI build VMs older than ${MaxAgeHours}h (Local CI/CD System)" `
+            -Force | Out-Null
+        Write-Host "[Register] CI-CleanupOrphans registered (every 6h + at startup, -MaxAgeHours $MaxAgeHours)." -ForegroundColor Green
+    }
+}
+
+# ── Task 2: CI-RetentionPolicy ────────────────────────────────────────────────
+$retentionScript = Join-Path $ScriptRoot 'Invoke-RetentionPolicy.ps1'
+if (-not (Test-Path $retentionScript -PathType Leaf)) {
+    Write-Warning "Script not found — skipping CI-RetentionPolicy: $retentionScript"
+} else {
+    $retentionAction = New-ScheduledTaskAction `
+        -Execute  $psExe `
+        -Argument "-NoProfile -NonInteractive -ExecutionPolicy Bypass -File `"$retentionScript`""
+
+    $daily3am  = New-ScheduledTaskTrigger -Daily -At '03:00' `
+        -RandomDelay (New-TimeSpan -Minutes 30)
+    $atStartup2 = New-ScheduledTaskTrigger -AtStartup `
+        -RandomDelay (New-TimeSpan -Minutes 15)
+
+    $retentionSettings = New-ScheduledTaskSettingsSet `
+        -ExecutionTimeLimit (New-TimeSpan -Hours 1) `
+        -MultipleInstances  IgnoreNew `
+        -StartWhenAvailable
+
+    if ($PSCmdlet.ShouldProcess('CI-RetentionPolicy', 'Register/update scheduled task')) {
+        Register-ScheduledTask `
+            -TaskName   'CI-RetentionPolicy' `
+            -TaskPath   $taskPath `
+            -Action     $retentionAction `
+            -Trigger    @($daily3am, $atStartup2) `
+            -Principal  $principal `
+            -Settings   $retentionSettings `
+            -Description 'Purges old CI artifacts, logs, and stale IP leases (Local CI/CD System)' `
+            -Force | Out-Null
+        Write-Host "[Register] CI-RetentionPolicy registered (daily 03:00 + at startup)." -ForegroundColor Green
+    }
+}
+
+# ── Task 3: CI-DiskSpaceAlert ─────────────────────────────────────────────────
+$diskScript = Join-Path $ScriptRoot 'Watch-DiskSpace.ps1'
+if (-not (Test-Path $diskScript -PathType Leaf)) {
+    Write-Warning "Script not found — skipping CI-DiskSpaceAlert: $diskScript"
+} else {
+    $diskAction = New-ScheduledTaskAction `
+        -Execute  $psExe `
+        -Argument "-NoProfile -NonInteractive -ExecutionPolicy Bypass -File `"$diskScript`""
+
+    # Every 15 minutes indefinitely
+    $disk15min = New-ScheduledTaskTrigger -Once -At '00:00' `
+        -RepetitionInterval (New-TimeSpan -Minutes 15)
+
+    $diskSettings = New-ScheduledTaskSettingsSet `
+        -ExecutionTimeLimit (New-TimeSpan -Minutes 5) `
+        -MultipleInstances  IgnoreNew `
+        -StartWhenAvailable
+
+    if ($PSCmdlet.ShouldProcess('CI-DiskSpaceAlert', 'Register/update scheduled task')) {
+        Register-ScheduledTask `
+            -TaskName   'CI-DiskSpaceAlert' `
+            -TaskPath   $taskPath `
+            -Action     $diskAction `
+            -Trigger    $disk15min `
+            -Principal  $principal `
+            -Settings   $diskSettings `
+            -Description 'Alerts via Event Log when CI drive free space drops below 50 GB (Local CI/CD System)' `
+            -Force | Out-Null
+        Write-Host "[Register] CI-DiskSpaceAlert registered (every 15 min)." -ForegroundColor Green
+    }
+}
+
+# ── Task 4: CI-RunnerHealth ───────────────────────────────────────────────────
+$healthScript = Join-Path $ScriptRoot 'Watch-RunnerHealth.ps1'
+if (-not (Test-Path $healthScript -PathType Leaf)) {
+    Write-Warning "Script not found — skipping CI-RunnerHealth: $healthScript"
+} else {
+    $healthAction = New-ScheduledTaskAction `
+        -Execute  $psExe `
+        -Argument "-NoProfile -NonInteractive -ExecutionPolicy Bypass -File `"$healthScript`""
+
+    # Every 15 minutes indefinitely
+    $health15min = New-ScheduledTaskTrigger -Once -At '00:00' `
+        -RepetitionInterval (New-TimeSpan -Minutes 15)
+
+    $healthSettings = New-ScheduledTaskSettingsSet `
+        -ExecutionTimeLimit (New-TimeSpan -Minutes 5) `
+        -MultipleInstances  IgnoreNew `
+        -StartWhenAvailable
+
+    if ($PSCmdlet.ShouldProcess('CI-RunnerHealth', 'Register/update scheduled task')) {
+        Register-ScheduledTask `
+            -TaskName   'CI-RunnerHealth' `
+            -TaskPath   $taskPath `
+            -Action     $healthAction `
+            -Trigger    $health15min `
+            -Principal  $principal `
+            -Settings   $healthSettings `
+            -Description 'Auto-restarts act_runner service if stopped; rate-limited to 3 restarts/h (Local CI/CD System)' `
+            -Force | Out-Null
+        Write-Host "[Register] CI-RunnerHealth registered (every 15 min, max 3 restarts/h)." -ForegroundColor Green
+    }
+}
+
+Write-Host "`n[Register] Done. Verify with: Get-ScheduledTask -TaskPath '\CI\' | Format-Table TaskName, State" -ForegroundColor Cyan

scripts/Remove-BuildVM.ps1

@@ -1,121 +1,40 @@
 #Requires -Version 5.1
-<#
-.SYNOPSIS
-    Stops and permanently deletes an ephemeral build VM.
-
-.DESCRIPTION
-    Performs a graceful shutdown (soft stop) with a timeout fallback to
-    a hard stop, then uses vmrun deleteVM to remove all VM files.
-    Finally, removes the clone directory from disk.
-
-    This script is designed to be called from a try/finally block so
-    it always runs, even on build failure.
-
-.PARAMETER VMPath
-    Full path to the clone VM's .vmx file.
-
-.PARAMETER VmrunPath
-    Full path to vmrun.exe.
-    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
-
-.PARAMETER GracefulTimeoutSeconds
-    Seconds to wait for graceful shutdown before forcing power-off.
-    Default: 15
-
-.EXAMPLE
-    .\Remove-BuildVM.ps1 -VMPath "F:\CI\BuildVMs\Clone_run-42_20260508_143022\Clone_run-42_20260508_143022.vmx"
-#>
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory)]
-    [string] $VMPath,
-
-    [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe',
-
-    [ValidateRange(5, 60)]
-    [int] $GracefulTimeoutSeconds = 15
-)
-
 Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Continue'   # Don't stop on errors — always try next step
+$ErrorActionPreference = 'Stop'
 
-$cloneDir = Split-Path $VMPath -Parent
-
-Write-Host "[Remove-BuildVM] Destroying VM: $VMPath"
-
-# ── Step 1: Check if VM exists at all ────────────────────────────────────────
-if (-not (Test-Path $VMPath -PathType Leaf)) {
-    Write-Warning "[Remove-BuildVM] VMX file not found — nothing to remove: $VMPath"
-    # Still attempt to remove the directory in case of partial clone
-    if (Test-Path $cloneDir) {
-        Remove-Item $cloneDir -Recurse -Force -ErrorAction SilentlyContinue
-    }
-    return
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A2-closeout.md.
+#
+# Callers (e.g. Measure-CIBenchmark.ps1) may pass PowerShell common
+# parameters like -ErrorAction SilentlyContinue. Those must NOT be
+# forwarded as --error-action etc. (the Python CLI rejects them).
+# Value-taking common params consume the following token too.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
 }
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
 
-# ── Step 2: Graceful stop ─────────────────────────────────────────────────────
-Write-Host "[Remove-BuildVM] Sending soft stop..."
-& $VmrunPath -T ws stop $VMPath soft 2>&1 | Out-Null
-
-$deadline = (Get-Date).AddSeconds($GracefulTimeoutSeconds)
-while ((Get-Date) -lt $deadline) {
-    Start-Sleep -Seconds 2
-    $stateOutput = & $VmrunPath -T ws getState $VMPath 2>&1
-    if ($stateOutput -notmatch 'running') {
-        Write-Host "[Remove-BuildVM] VM stopped gracefully."
-        break
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
     }
 }
 
-# ── Step 3: Force stop if still running ──────────────────────────────────────
-$stateOutput = & $VmrunPath -T ws getState $VMPath 2>&1
-if ($stateOutput -match 'running') {
-    Write-Host "[Remove-BuildVM] Graceful stop timed out — forcing hard stop..."
-    & $VmrunPath -T ws stop $VMPath hard 2>&1 | Out-Null
-}
-
-# Poll vmrun list until VMX is gone — vmware-vmx.exe may hold file locks briefly
-# after stop. Waiting for the entry to disappear ensures deleteVM won't race the
-# process exit.
-$vmxNorm         = $VMPath.Trim().ToLower()
-$releaseDeadline = (Get-Date).AddSeconds(20)
-while ((Get-Date) -lt $releaseDeadline) {
-    $listedVMs = & $VmrunPath -T ws list 2>&1 |
-        Where-Object { $_ -notmatch '^Total running' } |
-        ForEach-Object { "$_".Trim().ToLower() }
-    if ($listedVMs -notcontains $vmxNorm) { break }
-    Start-Sleep -Seconds 2
-}
-
-# ── Step 4: Delete VM via vmrun — retry up to 3× with backoff ────────────────
-Write-Host "[Remove-BuildVM] Deleting VM..."
-$deleteOutput = ''
-$deleteExit   = -1
-foreach ($delay in @(0, 3, 6)) {
-    if ($delay -gt 0) {
-        Write-Host "[Remove-BuildVM] Retrying deleteVM in ${delay}s..."
-        Start-Sleep -Seconds $delay
-    }
-    $deleteOutput = & $VmrunPath -T ws deleteVM $VMPath 2>&1
-    $deleteExit   = $LASTEXITCODE
-    if ($deleteExit -eq 0) { break }
-}
-
-if ($deleteExit -ne 0) {
-    Write-Warning "[Remove-BuildVM] vmrun deleteVM failed after retries (exit $deleteExit): $deleteOutput"
-    Write-Warning "[Remove-BuildVM] Will attempt manual directory removal."
-}
-
-# ── Step 5: Remove clone directory (catches any leftover files) ───────────────
-if (Test-Path $cloneDir) {
-    Write-Host "[Remove-BuildVM] Removing clone directory: $cloneDir"
-    Remove-Item $cloneDir -Recurse -Force -ErrorAction SilentlyContinue
-    if (Test-Path $cloneDir) {
-        Write-Warning "[Remove-BuildVM] Clone directory could not be fully removed: $cloneDir"
-        Write-Warning "           Manual cleanup required."
-    } else {
-        Write-Host "[Remove-BuildVM] Clone directory removed."
-    }
-}
-
-Write-Host "[Remove-BuildVM] VM destruction complete."
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator vm remove @pyArgs
+exit $LASTEXITCODE

scripts/Set-CIGuestCredential.ps1

@@ -0,0 +1,217 @@
+#Requires -Version 5.1
+#Requires -RunAsAdministrator
+<#
+.SYNOPSIS
+    Stores a CI guest-VM credential into the LocalSystem keyring vault.
+
+.DESCRIPTION
+    act_runner runs as the LocalSystem service account. Windows Credential
+    Manager / keyring vaults are per-user, so a credential added with
+    `cmdkey` or the Credential Manager UI under an interactive user is
+    invisible to the runner. The orchestrator then fails with:
+
+        Credential '<target>' not found in keyring.
+
+    This script writes the credential into the SYSTEM vault using the
+    production venv's `keyring` itself (the exact backend
+    `ci_orchestrator` reads with `keyring.get_credential(target, None)`),
+    via a transient SYSTEM scheduled task. Using keyring for both write
+    and read avoids cmdkey/keyring format and persistence mismatches.
+
+    Known-issue references:
+      plans/A1-closeout.md (KeyError: 'BuildVMGuest')
+      plans/implementation-plan-A-B.md (keyring under SYSTEM)
+
+    The plaintext password unavoidably transits a temporary .py file.
+    The file is created with an Administrators/SYSTEM-only ACL, overwritten
+    with random bytes, then deleted. The password is never placed in a
+    scheduled-task argument or the command line.
+
+.PARAMETER Target
+    Credential target name. Must match the runner env
+    GITEA_CI_GUEST_CRED_TARGET. Default: BuildVMGuest
+
+.PARAMETER UserName
+    Guest login username in the form the transport expects (e.g.
+    'WINBUILD\ci_build', '.\ci_build', or 'ci_build').
+
+.PARAMETER Password
+    Guest password as a SecureString. If omitted, prompted securely.
+
+.PARAMETER VenvPython
+    Path to the production venv interpreter act_runner uses. Default:
+    CI_VENV_PYTHON env var, else F:\CI\python\venv\Scripts\python.exe
+
+.PARAMETER SkipVerify
+    Skip the post-write read-back verification (also run as SYSTEM).
+
+.EXAMPLE
+    .\Set-CIGuestCredential.ps1 -UserName 'WINBUILD\ci_build'
+
+.EXAMPLE
+    # Non-interactive (e.g. from another provisioning script)
+    $pw = Read-Host 'pw' -AsSecureString
+    .\Set-CIGuestCredential.ps1 -Target BuildVMGuest -UserName '.\ci_build' -Password $pw
+
+.EXAMPLE
+    .\Set-CIGuestCredential.ps1 -UserName '.\ci_build' -WhatIf
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [ValidateNotNullOrEmpty()]
+    [string] $Target = 'BuildVMGuest',
+
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string] $UserName,
+
+    [System.Security.SecureString] $Password,
+
+    [string] $VenvPython = $(if ($env:CI_VENV_PYTHON) { $env:CI_VENV_PYTHON }
+                            else { 'F:\CI\python\venv\Scripts\python.exe' }),
+
+    [switch] $SkipVerify
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not (Test-Path -LiteralPath $VenvPython)) {
+    throw "venv interpreter not found: '$VenvPython'. Set -VenvPython or CI_VENV_PYTHON."
+}
+
+if (-not $Password) {
+    $Password = Read-Host "Password for '$UserName'" -AsSecureString
+}
+
+# --- Run a script block as SYSTEM via a transient scheduled task ----------
+function Invoke-AsSystem {
+    param(
+        [Parameter(Mandatory)] [string] $TaskName,
+        [Parameter(Mandatory)] [string] $Execute,
+        [Parameter(Mandatory)] [string] $Argument,
+        [int] $TimeoutSec = 30
+    )
+    $action    = New-ScheduledTaskAction -Execute $Execute -Argument $Argument
+    $principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' `
+                    -LogonType ServiceAccount -RunLevel Highest
+    Register-ScheduledTask -TaskName $TaskName -Action $action `
+        -Principal $principal -Force | Out-Null
+    try {
+        Start-ScheduledTask -TaskName $TaskName
+        $deadline = (Get-Date).AddSeconds($TimeoutSec)
+        do {
+            Start-Sleep -Milliseconds 500
+            $info = Get-ScheduledTaskInfo -TaskName $TaskName
+            $state = (Get-ScheduledTask -TaskName $TaskName).State
+        } while ($state -eq 'Running' -and (Get-Date) -lt $deadline)
+        return $info.LastTaskResult
+    }
+    finally {
+        Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false `
+            -ErrorAction SilentlyContinue
+    }
+}
+
+# --- Harden + shred helper for the transient secret file ------------------
+function Remove-Securely {
+    # Best-effort cleanup helper; ShouldProcess prompting is undesirable
+    # for an internal shred-and-delete of our own temp file.
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseShouldProcessForStateChangingFunctions', '')]
+    [CmdletBinding()]
+    param([Parameter(Mandatory)] [string] $Path)
+    if (-not (Test-Path -LiteralPath $Path)) { return }
+    try {
+        $len = (Get-Item -LiteralPath $Path).Length
+        if ($len -gt 0) {
+            $rnd = New-Object byte[] $len
+            [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($rnd)
+            [IO.File]::WriteAllBytes($Path, $rnd)
+        }
+    } catch {
+        Write-Verbose "secure overwrite failed (continuing to delete): $_"
+    }
+    Remove-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue
+}
+
+$tmpDir    = $env:TEMP
+$setPy     = Join-Path $tmpDir ("setcred_{0}.py"    -f ([guid]::NewGuid().ToString('N')))
+$verPy     = Join-Path $tmpDir ("vercred_{0}.py"    -f ([guid]::NewGuid().ToString('N')))
+$verOut    = Join-Path $tmpDir ("vercred_{0}.txt"   -f ([guid]::NewGuid().ToString('N')))
+
+if (-not $PSCmdlet.ShouldProcess("$Target ($UserName)",
+        "store credential in SYSTEM keyring vault")) {
+    return
+}
+
+try {
+    # Decrypt SecureString only at the moment of writing the temp script.
+    $bstr  = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($Password)
+    $plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
+    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
+
+    # Python literals: pass via triple-quoted raw-ish strings. Reject quotes
+    # that would break out of the literal rather than risk silent corruption.
+    if ($UserName -match "'''" -or $plain -match "'''") {
+        throw "UserName/Password contains a triple-quote sequence; unsupported."
+    }
+    $setBody = @"
+import keyring
+keyring.set_password(r'''$Target''', r'''$UserName''', r'''$plain''')
+print('OK')
+"@
+    Set-Content -LiteralPath $setPy -Value $setBody -Encoding UTF8
+    Remove-Variable plain -ErrorAction SilentlyContinue
+
+    # Lock the secret file down to SYSTEM + Administrators before it runs.
+    $acl = New-Object Security.AccessControl.FileSecurity
+    $acl.SetAccessRuleProtection($true, $false)
+    foreach ($id in 'SYSTEM', 'Administrators') {
+        $acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule(
+            $id, 'FullControl', 'Allow')))
+    }
+    Set-Acl -LiteralPath $setPy -AclObject $acl
+
+    $rc = Invoke-AsSystem -TaskName 'CI-SetGuestCred' `
+            -Execute $VenvPython -Argument "`"$setPy`""
+    if ($rc -ne 0) {
+        throw "keyring.set_password task exited with code $rc."
+    }
+    Write-Host "Stored '$Target' (user '$UserName') in the SYSTEM vault." `
+        -ForegroundColor Green
+}
+finally {
+    Remove-Securely -Path $setPy
+}
+
+if ($SkipVerify) { return }
+
+try {
+    $verBody = @"
+import keyring
+c = keyring.get_credential(r'''$Target''', None)
+open(r'''$verOut''', 'w', encoding='utf-8').write(
+    'NONE' if c is None else 'OK:' + c.username)
+"@
+    Set-Content -LiteralPath $verPy -Value $verBody -Encoding UTF8
+    Invoke-AsSystem -TaskName 'CI-VerifyGuestCred' `
+        -Execute $VenvPython -Argument "`"$verPy`"" | Out-Null
+
+    $result = if (Test-Path -LiteralPath $verOut) {
+        (Get-Content -LiteralPath $verOut -Raw).Trim()
+    } else { 'NONE' }
+
+    if ($result -like 'OK:*') {
+        Write-Host "Verified: SYSTEM keyring returns user '$($result.Substring(3))'." `
+            -ForegroundColor Green
+    }
+    else {
+        throw "Verification failed: SYSTEM keyring.get_credential('$Target', None) " +
+              "returned None. Credential did not persist."
+    }
+}
+finally {
+    Remove-Item -LiteralPath $verPy  -Force -ErrorAction SilentlyContinue
+    Remove-Item -LiteralPath $verOut -Force -ErrorAction SilentlyContinue
+}

scripts/Set-TemplateSharedFolders.ps1

@@ -0,0 +1,118 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Configures VMware shared folder entries in the CI template VMX for build cache sharing.
+
+.DESCRIPTION
+    Adds two shared folder mappings to the template VM's .vmx file:
+      nuget-cache  host: F:\CI\Cache\NuGet  guest: \\vmware-host\Shared Folders\nuget-cache
+      pip-cache    host: F:\CI\Cache\pip    guest: \\vmware-host\Shared Folders\pip-cache
+
+    These UNC paths are used by Invoke-RemoteBuild.ps1 -UseSharedCache to redirect
+    dotnet's NuGet package store and pip's download cache to persistent host-side
+    directories, avoiding repeat downloads across builds.
+
+    The script is idempotent: existing sharedFolder.* lines are removed before
+    the new block is written. A .bak copy of the original VMX is kept alongside it.
+
+    Prerequisites:
+      - Template VM must NOT be running when this script runs.
+      - VMware Tools (HGFS driver) must be installed in the template guest.
+      - Run once; all subsequent linked clones inherit the shared folder config.
+
+    After running: use Invoke-RemoteBuild.ps1 -UseSharedCache on builds that
+    target VMs cloned from this updated template.
+
+.PARAMETER TemplatePath
+    Full path to the template VM's .vmx file.
+    Default: F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
+
+.PARAMETER NuGetCacheDir
+    Host-side path for the NuGet package cache directory.
+    Default: F:\CI\Cache\NuGet
+
+.PARAMETER PipCacheDir
+    Host-side path for the pip download cache directory.
+    Default: F:\CI\Cache\pip
+
+.EXAMPLE
+    # Configure template (run from elevated PowerShell — template must be stopped)
+    .\Set-TemplateSharedFolders.ps1
+
+    # Preview changes without modifying files
+    .\Set-TemplateSharedFolders.ps1 -WhatIf
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [string] $TemplatePath  = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx',
+    [string] $NuGetCacheDir = 'F:\CI\Cache\NuGet',
+    [string] $PipCacheDir   = 'F:\CI\Cache\pip'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not (Test-Path $TemplatePath -PathType Leaf)) {
+    throw "Template VMX not found: $TemplatePath"
+}
+
+# ── Step 1: Ensure host cache directories exist ───────────────────────────────
+foreach ($dir in @($NuGetCacheDir, $PipCacheDir)) {
+    if (-not (Test-Path $dir)) {
+        if ($PSCmdlet.ShouldProcess($dir, 'Create host cache directory')) {
+            New-Item -ItemType Directory -Path $dir -Force | Out-Null
+            Write-Host "[SharedFolders] Created host cache dir: $dir"
+        }
+    } else {
+        Write-Host "[SharedFolders] Host cache dir exists: $dir"
+    }
+}
+
+# ── Step 2: Read VMX, strip existing sharedFolder + HGFS lines ───────────────
+$lines    = [System.IO.File]::ReadAllLines($TemplatePath, [System.Text.Encoding]::UTF8)
+$stripped = $lines | Where-Object {
+    $_ -notmatch '^sharedFolder' -and
+    $_ -notmatch '^isolation\.tools\.hgfs\.disable'
+}
+
+# ── Step 3: Build replacement sharedFolder block ──────────────────────────────
+# VMX hostPath requires double-escaped backslashes
+$nugetEsc = $NuGetCacheDir.Replace('\', '\\')
+$pipEsc   = $PipCacheDir.Replace('\', '\\')
+
+$sharedBlock = @(
+    'sharedFolder.maxNum = "2"'
+    'sharedFolder0.present = "TRUE"'
+    'sharedFolder0.enabled = "TRUE"'
+    'sharedFolder0.readAccess = "TRUE"'
+    'sharedFolder0.writeAccess = "TRUE"'
+    "sharedFolder0.hostPath = `"$nugetEsc`""
+    'sharedFolder0.guestName = "nuget-cache"'
+    'sharedFolder0.expiration = "never"'
+    'sharedFolder1.present = "TRUE"'
+    'sharedFolder1.enabled = "TRUE"'
+    'sharedFolder1.readAccess = "TRUE"'
+    'sharedFolder1.writeAccess = "TRUE"'
+    "sharedFolder1.hostPath = `"$pipEsc`""
+    'sharedFolder1.guestName = "pip-cache"'
+    'sharedFolder1.expiration = "never"'
+    'isolation.tools.hgfs.disable = "FALSE"'
+)
+
+$newLines = @($stripped) + $sharedBlock
+
+# ── Step 4: Backup and write VMX ─────────────────────────────────────────────
+if ($PSCmdlet.ShouldProcess($TemplatePath, 'Write updated VMX with shared folder entries')) {
+    $backupPath = "$TemplatePath.bak"
+    Copy-Item $TemplatePath $backupPath -Force
+    Write-Host "[SharedFolders] Original backed up: $backupPath"
+
+    [System.IO.File]::WriteAllLines($TemplatePath, $newLines, [System.Text.Encoding]::UTF8)
+
+    Write-Host "[SharedFolders] VMX updated: $TemplatePath"
+    Write-Host "[SharedFolders] Mappings:"
+    Write-Host "  nuget-cache  $NuGetCacheDir  ->  \\vmware-host\Shared Folders\nuget-cache"
+    Write-Host "  pip-cache    $PipCacheDir    ->  \\vmware-host\Shared Folders\pip-cache"
+    Write-Host "[SharedFolders] Next: run Invoke-RemoteBuild.ps1 -UseSharedCache to activate."
+}
+

scripts/Start-BurnInTest-Linux.ps1

@@ -0,0 +1,75 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Wrapper di lancio per Test-CapacityBurnIn.ps1 con il template Linux (LinuxBuild2404).
+
+.DESCRIPTION
+    Esegue il burn-in a 4 job / 3 round contro il repo burnin-dummy su Gitea,
+    usando il template Ubuntu 24.04. Speculare a Start-BurnInTest.ps1 (Windows).
+
+    Prerequisiti:
+      - Repo burnin-dummy su Gitea con build.sh nella root del branch main
+      - Credenziali guest nel Credential Manager target 'BuildVMGuest'
+        (usate per il PAT Gitea; SSH usa chiave F:\CI\keys\ci_linux)
+      - Gitea PAT nel Credential Manager target 'GiteaPAT'
+          New-StoredCredential -Target 'GiteaPAT' -UserName 'ci' -Password '<pat>' -Persist LocalMachine
+      - Template LinuxBuild2404 con snapshot BaseClean-Linux in stato powered-off
+      - VMware Tools attivo nel guest (per auto-detect IP)
+      - build.sh eseguibile (chmod +x) nel repo — oppure viene richiamato via bash
+
+    Esempi di utilizzo:
+        # Run completo (3 round, 4 job paralleli)
+        .\Start-BurnInTest-Linux.ps1
+
+        # Smoke veloce (1 round, 2 job)
+        .\Start-BurnInTest-Linux.ps1 -Rounds 1 -Parallelism 2
+
+        # Build piu' lungo per osservare concorrenza prolungata
+        .\Start-BurnInTest-Linux.ps1 -Rounds 1 -BuildCommand 'sleep 120'
+
+.PARAMETER Rounds
+    Numero di round sequenziali. Default: 3.
+
+.PARAMETER Parallelism
+    Job concorrenti per round. Default: 4.
+
+.PARAMETER BuildCommand
+    Comando da eseguire nel guest come passo build (eseguito via SSH).
+    Default: 'bash build.sh'
+
+.PARAMETER RoundTimeoutMinutes
+    Minuti massimi di attesa per ogni round prima di interrompere i job rimasti.
+    Default: 60.
+#>
+param(
+    [int]    $Rounds              = 3,
+    [int]    $Parallelism         = 4,
+    [string] $BuildCommand        = 'bash build.sh',
+    [int]    $RoundTimeoutMinutes = 60
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+$burnInParams = @{
+    RepoUrl               = 'https://gitea.emulab.it/Simone/burnin-dummy.git'
+    Branch                = 'main'
+    TemplatePath          = 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx'
+    SnapshotName          = 'BaseClean-Linux'
+    CloneBaseDir          = 'F:\CI\BuildVMs'
+    ArtifactBaseDir       = 'F:\CI\Artifacts'
+    GuestCredentialTarget = 'BuildVMGuest'
+    GiteaCredentialTarget = 'GiteaPAT'
+    VmrunPath             = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
+    GuestOS               = 'Linux'
+    BuildCommand          = $BuildCommand
+    Parallelism           = $Parallelism
+    Rounds                = $Rounds
+    RoundTimeoutMinutes   = $RoundTimeoutMinutes
+}
+
+& "$scriptDir\Test-CapacityBurnIn.ps1" @burnInParams
+
+exit $LASTEXITCODE

scripts/Start-BurnInTest.ps1

@@ -0,0 +1,79 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Wrapper di lancio per Test-CapacityBurnIn.ps1 con i parametri del lab locale.
+
+.DESCRIPTION
+    Esegue il burn-in a 4 job / 3 round contro il repo burnin-dummy su Gitea.
+    Tutti i parametri fissi del lab sono qui hardcoded; i parametri variabili
+    (Rounds, Parallelism, BuildCommand) possono essere sovrascritti da CLI.
+
+    Prerequisiti:
+      - Repo burnin-dummy creato su Gitea (anche vuoto con branch main)
+      - Credenziali guest nel Credential Manager target 'BuildVMGuest'
+      - Gitea PAT nel Credential Manager target 'GiteaPAT'
+          New-StoredCredential -Target 'GiteaPAT' -UserName 'ci' -Password '<pat>' -Persist LocalMachine
+      - Template WinBuild2025 con snapshot BaseClean in stato powered-off
+      - VMware Tools attivo nel guest (per auto-detect IP)
+
+    Esempi di utilizzo:
+        # Run completo (3 round, 4 job paralleli)
+        .\Start-BurnInTest.ps1
+
+        # Smoke veloce (1 round, 2 job)
+        .\Start-BurnInTest.ps1 -Rounds 1 -Parallelism 2
+
+        # Verifica parallelismo reale (build da 2 minuti, 1 round)
+        .\Start-BurnInTest.ps1 -Rounds 1 -BuildCommand 'Start-Sleep 120'
+
+.PARAMETER Rounds
+    Numero di round sequenziali. Default: 3.
+
+.PARAMETER Parallelism
+    Job concorrenti per round. Default: 4.
+
+.PARAMETER BuildCommand
+    Comando da eseguire nel guest come passo build (eseguito via cmd /c nel guest).
+    Default: 'ping 127.0.0.1 -n 31 > nul' (attesa ~30s, nessun output reale).
+    Quando il build command non produce la directory dist, Invoke-RemoteBuild crea
+    automaticamente un artifact placeholder (build-ok.txt in zip) per permettere
+    all'intero pipeline di completarsi.
+    Usare 'ping 127.0.0.1 -n 601 > nul' per mantenere 4 VM attive ~600s
+    e osservare la concorrenza prolungata.
+
+.PARAMETER RoundTimeoutMinutes
+    Minuti massimi di attesa per ogni round prima di interrompere i job rimasti.
+    Default: 60.
+#>
+param(
+    [int]    $Rounds              = 3,
+    [int]    $Parallelism         = 4,
+    [string] $BuildCommand        = 'powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File build.ps1',
+    [int]    $RoundTimeoutMinutes = 60
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+$burnInParams = @{
+    RepoUrl               = 'https://gitea.emulab.it/Simone/burnin-dummy.git'
+    Branch                = 'main'
+    TemplatePath          = 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+    SnapshotName          = 'BaseClean'
+    CloneBaseDir          = 'F:\CI\BuildVMs'
+    ArtifactBaseDir       = 'F:\CI\Artifacts'
+    GuestCredentialTarget = 'BuildVMGuest'
+    GiteaCredentialTarget = 'GiteaPAT'
+    VmrunPath             = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
+    GuestOS               = 'Auto'
+    BuildCommand          = $BuildCommand
+    Parallelism           = $Parallelism
+    Rounds                = $Rounds
+    RoundTimeoutMinutes   = $RoundTimeoutMinutes
+}
+
+& "$scriptDir\Test-CapacityBurnIn.ps1" @burnInParams
+
+exit $LASTEXITCODE

scripts/Test-CIGuestWinRM.ps1

@@ -0,0 +1,313 @@
+#Requires -Version 5.1
+#Requires -RunAsAdministrator
+<#
+.SYNOPSIS
+    Diagnoses WinRM reachability to a CI build VM from the runner's context.
+
+.DESCRIPTION
+    The orchestrator's readiness probe (WinRmTransport.is_ready) swallows
+    connection and auth errors and returns False, so a failing guest just
+    hangs "waiting for windows transport readiness" until timeout with no
+    cause in the log.
+
+    This script reproduces the exact probe the runner performs, but
+    surfaces the real error:
+
+      1. TCP test to the WinRM HTTPS port (network / listener / firewall).
+      2. A real pypsrp `execute_ps('$true')` against the guest, run as
+         SYSTEM (the act_runner account) so it reads the same SYSTEM
+         keyring vault credential the job uses. The full Python traceback
+         is captured and classified.
+
+    Classifications:
+      CONNECT  — port closed / refused / unreachable (guest WinRM
+                 listener or firewall; check template WinRM 5986 setup).
+      SSL      — TLS handshake/cert problem.
+      AUTH     — credential rejected (wrong password, or username form;
+                 try 'HOSTNAME\ci_build' instead of bare 'ci_build').
+      KEYRING  — credential missing from the SYSTEM vault (run
+                 Set-CIGuestCredential.ps1).
+      OK       — WinRM works; the hang is elsewhere.
+
+.PARAMETER IpAddress
+    Guest IP shown in the job log ("[job] guest IP: ...").
+
+.PARAMETER Target
+    Credential target in the SYSTEM keyring. Default: BuildVMGuest
+
+.PARAMETER Port
+    WinRM HTTPS port. Default: 5986
+
+.PARAMETER VenvPython
+    Production venv interpreter. Default: CI_VENV_PYTHON env, else
+    F:\CI\python\venv\Scripts\python.exe
+
+.PARAMETER TimeoutSec
+    Per-probe connection timeout (also the task wait budget). Default: 30
+
+.EXAMPLE
+    .\Test-CIGuestWinRM.ps1 -IpAddress 192.168.79.237
+
+.EXAMPLE
+    .\Test-CIGuestWinRM.ps1 -IpAddress 192.168.79.237 -Target BuildVMGuest -Port 5986
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string] $IpAddress,
+
+    [ValidateNotNullOrEmpty()]
+    [string] $Target = 'BuildVMGuest',
+
+    [ValidateRange(1, 65535)]
+    [int] $Port = 5986,
+
+    # Optional username override (password still read from the SYSTEM
+    # keyring). Use to test forms like 'HOSTNAME\ci_build' without
+    # re-storing the credential. Empty = use the keyring username.
+    [string] $UserName = '',
+
+    # Auth packages to try, in order. Local/workgroup accounts usually
+    # need 'ntlm' (Negotiate->Kerberos is meaningless without a domain).
+    [ValidateNotNullOrEmpty()]
+    [string[]] $AuthOrder = @('ntlm', 'negotiate'),
+
+    [string] $VenvPython = $(if ($env:CI_VENV_PYTHON) { $env:CI_VENV_PYTHON }
+                            else { 'F:\CI\python\venv\Scripts\python.exe' }),
+
+    [ValidateRange(5, 300)]
+    [int] $TimeoutSec = 30
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not (Test-Path -LiteralPath $VenvPython)) {
+    throw "venv interpreter not found: '$VenvPython'. Set -VenvPython or CI_VENV_PYTHON."
+}
+
+# ── 1. TCP reachability ───────────────────────────────────────────────────
+Write-Host "[1/2] TCP $IpAddress`:$Port ..." -ForegroundColor Cyan
+$tcp = Test-NetConnection -ComputerName $IpAddress -Port $Port `
+        -WarningAction SilentlyContinue
+if (-not $tcp.TcpTestSucceeded) {
+    Write-Host "  RESULT: CONNECT — port $Port closed/unreachable." `
+        -ForegroundColor Red
+    Write-Host "  WinRM HTTPS listener or guest firewall. Check the" `
+        -ForegroundColor Yellow
+    Write-Host "  Windows template WinRM 5986 setup (WINDOWS-TEMPLATE-SETUP.md)." `
+        -ForegroundColor Yellow
+    return
+}
+Write-Host "  port open." -ForegroundColor Green
+
+# ── 2a. Discover guest hostname from the WinRM TLS certificate CN ──────────
+# WinRM's self-signed cert CN is normally the guest computer name. Used to
+# build the COMPUTERNAME\user form NTLM needs for a local/workgroup account.
+$guestCn = ''
+try {
+    $tcpc = New-Object Net.Sockets.TcpClient
+    $tcpc.Connect($IpAddress, $Port)
+    $ssl = New-Object Net.Security.SslStream(
+        $tcpc.GetStream(), $false,
+        ([Net.Security.RemoteCertificateValidationCallback] { $true }))
+    $ssl.AuthenticateAsClient($IpAddress)
+    $cn = $ssl.RemoteCertificate.Subject  # e.g. "CN=WINBUILD"
+    if ($cn -match 'CN=([^,]+)') { $guestCn = $Matches[1].Trim() }
+    $ssl.Dispose(); $tcpc.Close()
+} catch {
+    Write-Verbose "cert CN probe failed (hostname auto-detect skipped): $_"
+}
+if ($guestCn) {
+    Write-Host "      guest cert CN (hostname): $guestCn" -ForegroundColor Cyan
+}
+
+# ── 2b. Build the username candidate matrix ───────────────────────────────
+$authList = ($AuthOrder | ForEach-Object { "'" + $_ + "'" }) -join ', '
+Write-Host "[2/2] pypsrp execute_ps as SYSTEM — auth order: $($AuthOrder -join ', ')" `
+    -ForegroundColor Cyan
+if ($UserName) {
+    Write-Host "      username override: $UserName" -ForegroundColor Cyan
+}
+
+$probePy  = Join-Path $env:TEMP ("winrmprobe_{0}.py"  -f ([guid]::NewGuid().ToString('N')))
+$probeOut = Join-Path $env:TEMP ("winrmprobe_{0}.txt" -f ([guid]::NewGuid().ToString('N')))
+
+$body = @"
+import keyring, traceback
+out   = r'''$probeOut'''
+auths = [$authList]
+override = r'''$UserName'''
+cn = r'''$guestCn'''
+c = keyring.get_credential(r'''$Target''', None)
+if c is None:
+    open(out, 'w', encoding='utf-8').write('KEYRING')
+else:
+    base = override if override else c.username
+    leaf = base.split('\\')[-1]                       # strip any DOMAIN\ prefix
+    users = [base]
+    if cn:
+        users.append(cn + '\\' + leaf)                # COMPUTERNAME\user
+    users.append('.\\' + leaf)                        # .\user
+    if cn:
+        users.append(leaf + '@' + cn)                 # user@COMPUTERNAME
+    # de-dup, keep order
+    seen, cand = set(), []
+    for u in users:
+        if u not in seen:
+            seen.add(u); cand.append(u)
+    from pypsrp.client import Client
+    lines, success = [], None
+    lines.append('cred user=%r pwlen=%d' % (c.username, len(c.password or '')))
+    for u in cand:
+        for a in auths:
+            try:
+                cl = Client(r'''$IpAddress''', username=u, password=c.password,
+                            port=$Port, ssl=True, cert_validation=False,
+                            auth=a, connection_timeout=$TimeoutSec)
+                so, se, rc = cl.execute_ps('`$true')
+                lines.append('user=%r auth=%s OK rc=%s' % (u, a, rc))
+                success = (u, a)
+                break
+            except Exception as e:
+                msg = (str(e).splitlines() or [''])[0]
+                lines.append('user=%r auth=%s FAIL %s: %s'
+                             % (u, a, type(e).__name__, msg))
+        if success:
+            break
+    if success:
+        hdr = 'OK user=%r auth=%s' % success
+        tb  = ''
+    else:
+        hdr = 'EXC (all combos failed)'
+        tb  = '\n' + traceback.format_exc()
+    open(out, 'w', encoding='utf-8').write(
+        hdr + '\n' + '\n'.join(lines) + tb)
+"@
+Set-Content -LiteralPath $probePy -Value $body -Encoding UTF8
+
+try {
+    $action    = New-ScheduledTaskAction -Execute $VenvPython -Argument "`"$probePy`""
+    $principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' `
+                    -LogonType ServiceAccount -RunLevel Highest
+    Register-ScheduledTask -TaskName 'CI-WinRmProbe' -Action $action `
+        -Principal $principal -Force | Out-Null
+    try {
+        Start-ScheduledTask -TaskName 'CI-WinRmProbe'
+        $deadline = (Get-Date).AddSeconds($TimeoutSec + 10)
+        do {
+            Start-Sleep -Milliseconds 500
+            $state = (Get-ScheduledTask -TaskName 'CI-WinRmProbe').State
+        } while ($state -eq 'Running' -and (Get-Date) -lt $deadline)
+    }
+    finally {
+        Unregister-ScheduledTask -TaskName 'CI-WinRmProbe' -Confirm:$false `
+            -ErrorAction SilentlyContinue
+    }
+
+    $raw = if (Test-Path -LiteralPath $probeOut) {
+        (Get-Content -LiteralPath $probeOut -Raw)
+    } else { '' }
+
+    if (-not $raw) {
+        Write-Host "  RESULT: probe produced no output (task may have failed)." `
+            -ForegroundColor Red
+        return
+    }
+
+    if ($raw -eq 'KEYRING') {
+        Write-Host "  RESULT: KEYRING — '$Target' not in the SYSTEM vault." `
+            -ForegroundColor Red
+        Write-Host "  Run: .\Set-CIGuestCredential.ps1 -UserName '<guest user>'" `
+            -ForegroundColor Yellow
+        return
+    }
+    if ($raw -like 'OK *') {
+        $okUser = if ($raw -match "OK user='([^']+)'") { $Matches[1] } else { '?' }
+        $okAuth = if ($raw -match 'auth=(\w+)')        { $Matches[1] } else { '?' }
+        Write-Host "  RESULT: OK — WinRM works." -ForegroundColor Green
+        Write-Host "  Winning combo: user='$okUser' auth='$okAuth'" `
+            -ForegroundColor Green
+        Write-Host $raw
+        Write-Host ""
+        $okLeaf  = $okUser.Split('\')[-1].Split('@')[0]
+        $needsQualified = ($okUser -ne $okLeaf)
+        if ($needsQualified) {
+            Write-Host "  -> FIX (credential): the stored bare username is rejected;" `
+                -ForegroundColor Yellow
+            Write-Host "     re-store in the working form:" -ForegroundColor Yellow
+            Write-Host "     .\scripts\Set-CIGuestCredential.ps1 -UserName '$okUser'" `
+                -ForegroundColor Yellow
+        }
+        if ($okAuth -ne 'negotiate') {
+            Write-Host "  -> FIX (code): WinRmTransport (src/ci_orchestrator/transport/winrm.py)" `
+                -ForegroundColor Yellow
+            Write-Host "     builds pypsrp Client() without auth= (default 'negotiate')." `
+                -ForegroundColor Yellow
+            Write-Host "     Pass auth='$okAuth' for local-account guests." `
+                -ForegroundColor Yellow
+        }
+        if (-not $needsQualified -and $okAuth -eq 'negotiate') {
+            Write-Host "  Transport auth/connect is fine; the hang is elsewhere." `
+                -ForegroundColor Yellow
+        }
+        return
+    }
+
+    # EXC ... : classify the traceback.
+    Write-Host "  RESULT: probe raised an exception:" -ForegroundColor Red
+    Write-Host $raw
+    $allFailed = $raw -like 'EXC (all combos failed)*'
+    $cls = switch -Regex ($raw) {
+        'CertificateError|SSLError|SSL:|certificate'      { 'SSL';     break }
+        '2146893043|UNKNOWN_CREDENTIALS|401|403|AuthenticationError|the user name or password|AccessDenied|access is denied' { 'AUTH'; break }
+        'ConnectionError|timed out|TimeoutError|refused|No route|Failed to establish|getaddrinfo|Max retries' { 'CONNECT'; break }
+        default { 'UNKNOWN' }
+    }
+    Write-Host ""
+    switch ($cls) {
+        'AUTH' {
+            if ($allFailed) {
+                Write-Host "  -> AUTH: EVERY user-form x auth combo was rejected with" `
+                    -ForegroundColor Yellow
+                Write-Host "     SEC_E_UNKNOWN_CREDENTIALS. Username form is NOT the cause." `
+                    -ForegroundColor Yellow
+                Write-Host "     Most likely: the password stored in the SYSTEM keyring is" `
+                    -ForegroundColor Yellow
+                Write-Host "     wrong / does not match the guest 'ci_build' account." `
+                    -ForegroundColor Yellow
+                Write-Host "     1. Confirm the real ci_build password in the template." `
+                    -ForegroundColor Yellow
+                Write-Host "     2. Re-run: .\scripts\Set-CIGuestCredential.ps1 -UserName 'ci_build'" `
+                    -ForegroundColor Yellow
+                Write-Host "     If the password is definitely correct, suspect the" `
+                    -ForegroundColor Yellow
+                Write-Host "     pyspnego SSPI provider under the SYSTEM account." `
+                    -ForegroundColor Yellow
+            }
+            else {
+                Write-Host "  -> AUTH: credential rejected for the tested form(s)." `
+                    -ForegroundColor Yellow
+                Write-Host "     Try a hostname-qualified form via Set-CIGuestCredential.ps1." `
+                    -ForegroundColor Yellow
+            }
+        }
+        'CONNECT' {
+            Write-Host "  -> CONNECT: WinRM service/listener not answering on the guest." `
+                -ForegroundColor Yellow
+        }
+        'SSL' {
+            Write-Host "  -> SSL: TLS/cert problem (probe uses cert_validation=False; investigate listener cert)." `
+                -ForegroundColor Yellow
+        }
+        default {
+            Write-Host "  -> UNKNOWN: inspect the traceback above." `
+                -ForegroundColor Yellow
+        }
+    }
+}
+finally {
+    Remove-Item -LiteralPath $probePy  -Force -ErrorAction SilentlyContinue
+    Remove-Item -LiteralPath $probeOut -Force -ErrorAction SilentlyContinue
+}

scripts/Test-CapacityBurnIn.ps1

@@ -0,0 +1,366 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Concurrency burn-in harness: runs N simultaneous Invoke-CIJob.ps1 jobs
+    for R rounds and asserts correct cleanup after each round.
+
+.DESCRIPTION
+    Launches $Parallelism child PowerShell processes (via Start-Job) all
+    running Invoke-CIJob.ps1 concurrently. After each round verifies that:
+      - All job exit codes were 0
+      - No clone directories for burn-in jobs remain in CloneBaseDir
+      - No stale vm-start.lock file remains (older than 5 min)
+
+    Exits 0 only when ALL rounds and assertions pass.
+
+.PARAMETER RepoUrl
+    Git URL to pass to Invoke-CIJob.ps1 as -RepoUrl.
+
+.PARAMETER Branch
+    Branch to build. Default: main
+
+.PARAMETER IPList
+    Optional array of IP addresses, one per concurrent job slot.
+    When provided, each job receives the corresponding -VMIPAddress (useful when
+    VMs have static IPs or per-slot DHCP reservations).
+    When omitted, -VMIPAddress is not passed to Invoke-CIJob.ps1, which then
+    auto-detects the IP via Get-GuestIPAddress (requires VMware Tools / ci-report-ip.service).
+    When provided, must have at least $Parallelism entries.
+
+.PARAMETER TemplatePath
+    VMX template path. Falls back to GITEA_CI_TEMPLATE_PATH env var.
+
+.PARAMETER SnapshotName
+    Snapshot to clone from. Falls back to GITEA_CI_SNAPSHOT_NAME env var.
+    Default: BaseClean
+
+.PARAMETER CloneBaseDir
+    Clone VM base directory. Falls back to GITEA_CI_CLONE_BASE_DIR env var.
+    Default: F:\CI\BuildVMs
+
+.PARAMETER ArtifactBaseDir
+    Artifact output directory. Default: F:\CI\Artifacts
+
+.PARAMETER GuestCredentialTarget
+    Windows Credential Manager target for guest credentials.
+    Default: BuildVMGuest
+
+.PARAMETER VmrunPath
+    Path to vmrun.exe.
+    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
+
+.PARAMETER GuestOS
+    Guest OS transport. Default: Auto (detected from VMX).
+
+.PARAMETER BuildCommand
+    Custom build command forwarded to Invoke-CIJob.ps1.
+    Default: empty (uses dotnet build).
+
+.PARAMETER Parallelism
+    Number of concurrent jobs per round. Default: 4.
+
+.PARAMETER Rounds
+    Number of sequential rounds. Default: 3.
+
+.PARAMETER RoundTimeoutMinutes
+    Maximum wait time per round before force-stopping remaining jobs.
+    Default: 60.
+
+.PARAMETER ScriptDir
+    Directory containing sibling CI scripts. Default: directory of this script.
+
+.EXAMPLE
+    .\Test-CapacityBurnIn.ps1 `
+        -RepoUrl 'http://gitea.local/ci/hello-world.git' `
+        -IPList '192.168.79.101','192.168.79.102','192.168.79.103','192.168.79.104' `
+        -Rounds 3 -Parallelism 4
+
+.EXAMPLE
+    # Quick smoke round (1 round, 2 jobs) — auto-detect IPs via VMware Tools
+    .\Test-CapacityBurnIn.ps1 `
+        -RepoUrl      'http://gitea.local/ci/hello-world.git' `
+        -TemplatePath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+        -Parallelism 2 -Rounds 1
+
+.EXAMPLE
+    # With explicit static IPs (DHCP reservations configured)
+    .\Test-CapacityBurnIn.ps1 `
+        -RepoUrl      'http://gitea.local/ci/hello-world.git' `
+        -IPList       '192.168.79.101','192.168.79.102' `
+        -TemplatePath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
+        -Parallelism 2 -Rounds 1
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [string] $RepoUrl,
+
+    [string[]] $IPList = @(),
+
+    [string] $Branch = 'main',
+
+    [string] $TemplatePath = $env:GITEA_CI_TEMPLATE_PATH,
+
+    [string] $SnapshotName = $(
+        if ($env:GITEA_CI_SNAPSHOT_NAME) { $env:GITEA_CI_SNAPSHOT_NAME } else { 'BaseClean' }
+    ),
+
+    [string] $CloneBaseDir = $(
+        if ($env:GITEA_CI_CLONE_BASE_DIR) { $env:GITEA_CI_CLONE_BASE_DIR } else { 'F:\CI\BuildVMs' }
+    ),
+
+    [string] $ArtifactBaseDir = 'F:\CI\Artifacts',
+
+    [string] $GuestCredentialTarget = 'BuildVMGuest',
+
+    # Credential Manager target for the Gitea PAT (used by Invoke-CIJob -UseGitClone).
+    # Store with: New-StoredCredential -Target 'GiteaPAT' -UserName '<user>' -Password '<pat>' -Persist LocalMachine
+    [string] $GiteaCredentialTarget = 'GiteaPAT',
+
+    [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe',
+
+    [ValidateSet('Windows', 'Linux', 'Auto')]
+    [string] $GuestOS = 'Auto',
+
+    [string] $BuildCommand = '',
+
+    [ValidateRange(1, 10)]
+    [int] $Parallelism = 4,
+
+    [ValidateRange(1, 10)]
+    [int] $Rounds = 3,
+
+    [ValidateRange(5, 240)]
+    [int] $RoundTimeoutMinutes = 60,
+
+    [string] $ScriptDir = $PSScriptRoot
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# ── Validate inputs ───────────────────────────────────────────────────────────
+if ($IPList.Count -gt 0 -and $IPList.Count -lt $Parallelism) {
+    throw "IPList must contain at least $Parallelism entries (got $($IPList.Count))."
+}
+if (-not $TemplatePath) {
+    throw "TemplatePath is required. Pass -TemplatePath or set GITEA_CI_TEMPLATE_PATH."
+}
+if (-not (Test-Path $TemplatePath -PathType Leaf)) {
+    throw "TemplatePath not found: $TemplatePath"
+}
+
+# Resolve script dir — $PSScriptRoot may be empty when dot-sourced interactively
+if (-not $ScriptDir) {
+    $ScriptDir = Split-Path $MyInvocation.MyCommand.Path -Parent
+}
+$invokeCIJobPath = Join-Path $ScriptDir 'Invoke-CIJob.ps1'
+if (-not (Test-Path $invokeCIJobPath -PathType Leaf)) {
+    throw "Invoke-CIJob.ps1 not found at: $invokeCIJobPath"
+}
+
+# ── State trackers ────────────────────────────────────────────────────────────
+$roundResults = [System.Collections.Generic.List[PSCustomObject]]::new()
+$totalPass    = 0
+$totalFail    = 0
+$roundsFailed = 0
+
+Write-Host '============================================================'
+Write-Host '[Test-CapacityBurnIn] Burn-in configuration:'
+Write-Host "  Parallelism    : $Parallelism"
+Write-Host "  Rounds         : $Rounds"
+Write-Host "  Round timeout  : ${RoundTimeoutMinutes}m"
+Write-Host "  Template       : $TemplatePath"
+Write-Host "  Snapshot       : $SnapshotName"
+Write-Host "  CloneBaseDir   : $CloneBaseDir"
+  $ipDisplay = if ($IPList.Count -ge $Parallelism) { $IPList[0..($Parallelism - 1)] -join ', ' } else { '(auto-detect via VMware Tools)' }
+  Write-Host "  IPs            : $ipDisplay"
+Write-Host '============================================================'
+
+for ($r = 1; $r -le $Rounds; $r++) {
+
+    Write-Host "`n[Round $r/$Rounds] Launching $Parallelism concurrent jobs..."
+    $roundStart = Get-Date
+
+    # ── Launch jobs ───────────────────────────────────────────────────────
+    $jobEntries = [System.Collections.Generic.List[hashtable]]::new()
+
+    for ($j = 1; $j -le $Parallelism; $j++) {
+        $jId    = "burnin-r${r}-j${j}-$(Get-Date -Format 'HHmmss')"
+        $ipAddr = if ($IPList.Count -ge $j) { $IPList[$j - 1] } else { '' }
+
+        # Build a flat string array for powershell.exe -File
+        $argList = [System.Collections.Generic.List[string]]::new()
+        $argList.Add('-NonInteractive')
+        $argList.Add('-ExecutionPolicy'); $argList.Add('Bypass')
+        $argList.Add('-File');            $argList.Add($invokeCIJobPath)
+        $argList.Add('-JobId');           $argList.Add($jId)
+        $argList.Add('-RepoUrl');         $argList.Add($RepoUrl)
+        $argList.Add('-Branch');          $argList.Add($Branch)
+        $argList.Add('-TemplatePath');    $argList.Add($TemplatePath)
+        $argList.Add('-SnapshotName');    $argList.Add($SnapshotName)
+        $argList.Add('-CloneBaseDir');    $argList.Add($CloneBaseDir)
+        $argList.Add('-ArtifactBaseDir'); $argList.Add($ArtifactBaseDir)
+        if ($ipAddr -ne '') {
+            $argList.Add('-VMIPAddress'); $argList.Add($ipAddr)
+        }
+        $argList.Add('-GuestCredentialTarget');  $argList.Add($GuestCredentialTarget)
+        $argList.Add('-GiteaCredentialTarget'); $argList.Add($GiteaCredentialTarget)
+        $argList.Add('-VmrunPath');            $argList.Add($VmrunPath)
+        $argList.Add('-GuestOS');         $argList.Add($GuestOS)
+        if ($BuildCommand -ne '') {
+            $argList.Add('-BuildCommand'); $argList.Add($BuildCommand)
+        }
+
+        $argArray = $argList.ToArray()
+
+        # Start-Job runs a new PS session; call powershell.exe as child process
+        # so exit $exitCode from Invoke-CIJob.ps1 is captured in $LASTEXITCODE.
+        # NOTE: do NOT name the parameter $Args — @Args is a PS reserved splatting
+        # alias for the automatic $Args variable (unbound arguments), which would
+        # be empty here since the parameter binding consumed all positional args.
+        $psJob = Start-Job -ScriptBlock {
+            param([string[]]$ChildArgs)
+            $out = & powershell.exe @ChildArgs 2>&1
+            [PSCustomObject]@{
+                ExitCode = $LASTEXITCODE
+                Output   = ($out -join "`n")
+            }
+        } -ArgumentList (, $argArray)
+
+        $jobEntries.Add(@{
+            PSJob = $psJob
+            JobId = $jId
+            IP    = $ipAddr
+            Slot  = $j
+        })
+
+        $ipDisplay2 = if ($ipAddr -ne '') { $ipAddr } else { '(auto)' }
+        Write-Host "  Slot $j — JobId=$jId  IP=$ipDisplay2  PSJob=$($psJob.Id)"
+    }
+
+    # ── Wait for round to complete ────────────────────────────────────────
+    Write-Host "  Waiting (timeout: ${RoundTimeoutMinutes}m)..."
+    $psJobArray = @($jobEntries | ForEach-Object { $_.PSJob })
+    $null = Wait-Job -Job $psJobArray -Timeout ($RoundTimeoutMinutes * 60)
+
+    # Force-stop anything still running (timeout exceeded)
+    foreach ($entry in $jobEntries) {
+        if ($entry.PSJob.State -eq 'Running') {
+            Write-Warning "  [Round $r] Slot $($entry.Slot) ($($entry.JobId)) still running after timeout — stopping."
+            Stop-Job $entry.PSJob
+        }
+    }
+
+    $roundElapsed = (Get-Date) - $roundStart
+    $roundPass = 0
+    $roundFail = 0
+
+    # ── Print per-job results ─────────────────────────────────────────────
+    Write-Host ''
+    Write-Host ('  ' + ('{0,-44} {1,-16} {2,-8} {3}' -f 'JobId', 'IP', 'Status', 'ExitCode'))
+    Write-Host ('  ' + ('{0,-44} {1,-16} {2,-8} {3}' -f ('-' * 44), ('-' * 16), ('-' * 8), ('-' * 8)))
+
+    foreach ($entry in $jobEntries) {
+        $savedState = $entry.PSJob.State
+        $result     = Receive-Job $entry.PSJob -ErrorAction SilentlyContinue
+        Remove-Job  $entry.PSJob -Force
+
+        if ($savedState -eq 'Stopped') {
+            $status = 'TIMEOUT'; $ec = -1
+        } elseif ($null -eq $result) {
+            $status = 'NO-RESULT'; $ec = -1
+        } else {
+            $ec     = $result.ExitCode
+            $status = if ($ec -eq 0) { 'PASS' } else { 'FAIL' }
+        }
+
+        Write-Host ('  ' + ('{0,-44} {1,-16} {2,-8} {3}' -f $entry.JobId, $entry.IP, $status, $ec))
+
+        # On failure, print the last 20 lines of output to aid diagnosis
+        if ($status -ne 'PASS' -and $null -ne $result -and $result.Output -ne '') {
+            $lines = $result.Output -split "`n"
+            $tail  = if ($lines.Count -gt 20) { $lines[-20..-1] } else { $lines }
+            Write-Host '  --- last output ---'
+            foreach ($line in $tail) { Write-Host "  $line" }
+            Write-Host '  ---'
+        }
+
+        if ($status -eq 'PASS') { $roundPass++ } else { $roundFail++ }
+    }
+
+    # ── Assert: no orphaned clone dirs ────────────────────────────────────
+    $orphaned = [System.Collections.Generic.List[string]]::new()
+    if (Test-Path $CloneBaseDir) {
+        foreach ($entry in $jobEntries) {
+            $dirs = Get-ChildItem -Path $CloneBaseDir -Directory -ErrorAction SilentlyContinue |
+                    Where-Object { $_.Name -like "Clone_$($entry.JobId)_*" }
+            if ($dirs) {
+                foreach ($d in $dirs) { $orphaned.Add($d.FullName) }
+            }
+        }
+    }
+
+    Write-Host ''
+    if ($orphaned.Count -eq 0) {
+        Write-Host "  Clone cleanup  : OK (0 orphaned)"
+    } else {
+        Write-Host "  Clone cleanup  : FAIL ($($orphaned.Count) orphaned directories)"
+        foreach ($p in $orphaned) { Write-Host "    $p" }
+        $roundFail++
+    }
+
+    # ── Assert: no stale lock file ────────────────────────────────────────
+    $lockPath  = Join-Path $CloneBaseDir 'vm-start.lock'
+    $staleLock = $false
+    if (Test-Path $lockPath) {
+        $ageMin = ((Get-Date) - (Get-Item $lockPath).LastWriteTime).TotalMinutes
+        if ($ageMin -gt 5) {
+            $staleLock = $true
+        }
+    }
+
+    if (-not $staleLock) {
+        Write-Host "  Lock cleanup   : OK"
+    } else {
+        Write-Host "  Lock cleanup   : FAIL (stale vm-start.lock present)"
+        $roundFail++
+    }
+
+    $roundStatus = if ($roundFail -eq 0) { 'PASS' } else { 'FAIL' }
+    Write-Host ("  [Round $r] Elapsed: {0:mm\:ss}  --  $roundStatus ($roundPass PASS, $roundFail FAIL)" -f $roundElapsed)
+
+    $totalPass += $roundPass
+    $totalFail += $roundFail
+    if ($roundFail -gt 0) { $roundsFailed++ }
+
+    $roundResults.Add([PSCustomObject]@{
+        Round     = $r
+        Pass      = $roundPass
+        Fail      = $roundFail
+        Status    = $roundStatus
+        ElapsedSec = [int]$roundElapsed.TotalSeconds
+    })
+}
+
+# ── Overall summary ───────────────────────────────────────────────────────────
+Write-Host "`n============================================================"
+Write-Host '[Test-CapacityBurnIn] SUMMARY'
+Write-Host ('  {0,-8} {1,-6} {2,-6} {3,-10} {4}' -f 'Round', 'Pass', 'Fail', 'Elapsed', 'Status')
+Write-Host ('  {0,-8} {1,-6} {2,-6} {3,-10} {4}' -f ('-'*8), ('-'*6), ('-'*6), ('-'*10), ('-'*8))
+foreach ($rr in $roundResults) {
+    Write-Host ('  {0,-8} {1,-6} {2,-6} {3,-10} {4}' -f $rr.Round, $rr.Pass, $rr.Fail, "$($rr.ElapsedSec)s", $rr.Status)
+}
+Write-Host ''
+Write-Host "  Total jobs : $($Rounds * $Parallelism)"
+Write-Host "  Passed     : $totalPass"
+Write-Host "  Failed     : $totalFail"
+Write-Host "  Rounds OK  : $($Rounds - $roundsFailed) / $Rounds"
+$overallStatus = if ($totalFail -eq 0) { 'PASS' } else { 'FAIL' }
+Write-Host "`n  OVERALL: $overallStatus"
+Write-Host '============================================================'
+
+if ($totalFail -gt 0) {
+    exit 1
+}
+exit 0

scripts/Test-E2E-Section3.3.ps1

@@ -0,0 +1,239 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    E2E test for §3.3 In-VM Git Clone feature.
+
+.DESCRIPTION
+    Runs nsis-plugin-nsinnounp build twice:
+    1. Without -UseGitClone (baseline: host-side zip-transfer)
+    2. With -UseGitClone (target: guest-side git clone)
+
+    Measures elapsed time, artifact size, and logs comparison.
+    Prerequisite: Template VM must have Git for Windows installed (§6.6).
+
+.PARAMETER BaselineJobId
+    Job ID for baseline run (host-side clone).
+    Default: e2e-baseline-<yyyyMMdd_HHmmss>
+
+.PARAMETER GuestCloneJobId
+    Job ID for guest-side clone run.
+    Default: e2e-guestclone-<yyyyMMdd_HHmmss>
+
+.PARAMETER Branch
+    Branch to build. Default: main
+
+.PARAMETER TemplatePath
+    Path to template VMX. Default: env:GITEA_CI_TEMPLATE_PATH or
+    F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
+
+.PARAMETER GuestRepoUrl
+    HTTP(S) URL for guest-side clone. Must be reachable from inside the VM.
+    Default: https://gitea.emulab.it/Simone/nsis-plugin-nsinnounp.git
+    NOTE: ssh://gitea-ci alias works only on the host (SSH config), not inside the VM.
+
+.PARAMETER SkipBaseline
+    If set, skip baseline run and only run with -UseGitClone.
+
+.PARAMETER SkipGuestClone
+    If set, skip guest-clone run and only run baseline.
+
+.EXAMPLE
+    # Full comparison (both runs):
+    .\Test-E2E-Section3.3.ps1
+
+    # Only test guest-clone mode (assume baseline already exists):
+    .\Test-E2E-Section3.3.ps1 -SkipBaseline
+
+    # Only test baseline:
+    .\Test-E2E-Section3.3.ps1 -SkipGuestClone
+#>
+[CmdletBinding()]
+param(
+    [string] $BaselineJobId   = "e2e-baseline-$(Get-Date -Format 'yyyyMMdd_HHmmss')",
+    [string] $GuestCloneJobId = "e2e-guestclone-$(Get-Date -Format 'yyyyMMdd_HHmmss')",
+    [string] $Branch          = 'main',
+    [string] $TemplatePath    = $(
+        if ($env:GITEA_CI_TEMPLATE_PATH) { $env:GITEA_CI_TEMPLATE_PATH }
+        else { 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' }
+    ),
+    # URL for host-side clone (SSH alias works on host)
+    [string] $HostRepoUrl     = 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git',
+    # URL for guest-side clone (must be HTTP reachable from inside VM — SSH alias not available in guest)
+    [string] $GuestRepoUrl    = 'https://gitea.emulab.it/Simone/nsis-plugin-nsinnounp.git',
+    [switch] $SkipBaseline,
+    [switch] $SkipGuestClone
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$scriptDir    = Split-Path $MyInvocation.MyCommand.Path -Parent
+$orchestrator = Join-Path $scriptDir 'Invoke-CIJob.ps1'
+
+# Common parameters (RepoUrl set per-mode below)
+$commonParams = @{
+    Branch               = $Branch
+    TemplatePath         = $TemplatePath
+    Submodules           = $true
+    BuildCommand         = 'python build_plugin.py --final --dist-dir dist'
+    GuestArtifactSource  = 'dist'
+    GuestCredentialTarget = 'BuildVMGuest'
+}
+
+function Format-Elapsed {
+    param([TimeSpan] $ts)
+    if ($ts.TotalHours -ge 1) {
+        return $ts.ToString('hh\:mm\:ss')
+    } else {
+        return $ts.ToString('mm\:ss\.ff')
+    }
+}
+
+function Invoke-Test {
+    param(
+        [string] $JobId,
+        [string] $Mode,
+        [switch] $UseGitClone,
+        [hashtable] $CommonParams
+    )
+
+    Write-Host ""
+    Write-Host "────────────────────────────────────────────────────────" -ForegroundColor Cyan
+    Write-Host " $Mode" -ForegroundColor Cyan
+    Write-Host "────────────────────────────────────────────────────────" -ForegroundColor Cyan
+    Write-Host " JobId  : $JobId"
+    Write-Host " Branch : $Branch"
+    Write-Host " Mode   : $(if ($UseGitClone) { 'Guest-side clone (-UseGitClone)' } else { 'Host-side zip-transfer (baseline)' })"
+    Write-Host ""
+
+    $params = $CommonParams.Clone()
+    $params['JobId'] = $JobId
+    if ($UseGitClone) {
+        $params['UseGitClone'] = $true
+        $params['RepoUrl']     = $script:GuestRepoUrl   # HTTP URL reachable from inside VM
+    } else {
+        $params['RepoUrl']     = $script:HostRepoUrl    # SSH alias — works on host
+    }
+
+    $startTime = Get-Date
+    $exitCode  = 0
+
+    try {
+        # Pipe to Out-Host so orchestrator output doesn't pollute this function's pipeline
+        & $orchestrator @params | Out-Host
+        $exitCode = $LASTEXITCODE
+    }
+    catch {
+        Write-Host "[Test] Orchestrator threw: $_" -ForegroundColor Red
+        $exitCode = 1
+    }
+
+    $elapsed = (Get-Date) - $startTime
+
+    if ($exitCode -ne 0) {
+        Write-Host "[Test] FAIL — exit code $exitCode after $(Format-Elapsed $elapsed)" -ForegroundColor Red
+        return @{ Success = $false; Elapsed = $elapsed; JobId = $JobId; Mode = $Mode }
+    }
+
+    $artifactDir = "F:\CI\Artifacts\$JobId"
+    $artifactZip = Join-Path $artifactDir 'artifacts.zip'
+
+    if (-not (Test-Path $artifactZip)) {
+        Write-Host "[Test] FAIL — artifact not found: $artifactZip" -ForegroundColor Red
+        return @{ Success = $false; Elapsed = $elapsed; JobId = $JobId; Mode = $Mode }
+    }
+
+    $zipSize = [math]::Round((Get-Item $artifactZip).Length / 1MB, 2)
+    Write-Host "[Test] PASS — $(Format-Elapsed $elapsed)" -ForegroundColor Green
+    Write-Host "       Artifact: $zipSize MB"
+    Write-Host "       Logs    : $artifactDir"
+
+    return @{ Success = $true; Elapsed = $elapsed; Size = $zipSize; JobId = $JobId; Mode = $Mode }
+}
+
+# ────────────────────────────────────────────────────────────────────────────
+# Test runs
+# ────────────────────────────────────────────────────────────────────────────
+
+Write-Host ""
+Write-Host "╔════════════════════════════════════════════════════════╗" -ForegroundColor Yellow
+Write-Host "║  §3.3 E2E Test: In-VM Git Clone vs Host-side Zip       ║" -ForegroundColor Yellow
+Write-Host "╚════════════════════════════════════════════════════════╝" -ForegroundColor Yellow
+
+$baselineResult = $null
+$guestCloneResult = $null
+
+if (-not $SkipBaseline) {
+    $baselineResult = Invoke-Test -JobId $BaselineJobId -Mode "BASELINE (host-side zip)" -CommonParams $commonParams
+}
+
+if (-not $SkipGuestClone) {
+    $guestCloneResult = Invoke-Test -JobId $GuestCloneJobId -Mode "GUEST CLONE (-UseGitClone)" -UseGitClone -CommonParams $commonParams
+}
+
+# ────────────────────────────────────────────────────────────────────────────
+# Summary
+# ────────────────────────────────────────────────────────────────────────────
+
+Write-Host ""
+Write-Host "════════════════════════════════════════════════════════" -ForegroundColor Cyan
+Write-Host " SUMMARY" -ForegroundColor Cyan
+Write-Host "════════════════════════════════════════════════════════" -ForegroundColor Cyan
+
+if ($baselineResult -and $guestCloneResult) {
+    if ($baselineResult.Success -and $guestCloneResult.Success) {
+        $baselineTime = $baselineResult.Elapsed.TotalSeconds
+        $guestTime    = $guestCloneResult.Elapsed.TotalSeconds
+        $diff         = $baselineTime - $guestTime
+        $pctChange    = [math]::Round(($diff / $baselineTime) * 100, 1)
+
+        Write-Host ""
+        Write-Host "Baseline (host-side):     $(Format-Elapsed $baselineResult.Elapsed) / $($baselineResult.Size) MB"
+        Write-Host "Guest clone (-UseGit):    $(Format-Elapsed $guestCloneResult.Elapsed) / $($guestCloneResult.Size) MB"
+        Write-Host ""
+        Write-Host "Difference:               $([math]::Round($diff, 1)) sec ($pctChange%)" -ForegroundColor $(if ($diff -gt 0) { 'Green' } else { 'Red' })
+        Write-Host ""
+
+        if ($diff -gt 0) {
+            Write-Host "✓ §3.3 guest-clone is FASTER by $(Format-Elapsed ([TimeSpan]::FromSeconds($diff)))" -ForegroundColor Green
+        }
+        else {
+            Write-Host "[WARN] Host-side is faster by $(Format-Elapsed ([TimeSpan]::FromSeconds(-$diff)))" -ForegroundColor Yellow
+        }
+    }
+    else {
+        Write-Host ""
+        Write-Host "One or both tests failed. Review logs above." -ForegroundColor Red
+        Write-Host ""
+        if ($baselineResult.Success) {
+            Write-Host "  Baseline: ✓ PASS"
+        }
+        else {
+            Write-Host "  Baseline: ✗ FAIL"
+        }
+        if ($guestCloneResult.Success) {
+            Write-Host "  Guest:    ✓ PASS"
+        }
+        else {
+            Write-Host "  Guest:    ✗ FAIL"
+        }
+    }
+}
+elseif ($baselineResult) {
+    Write-Host ""
+    Write-Host "Baseline (host-side): $(if ($baselineResult.Success) { '✓ PASS' } else { '✗ FAIL' })" -ForegroundColor $(if ($baselineResult.Success) { 'Green' } else { 'Red' })
+    if ($baselineResult.Success) {
+        Write-Host "  Time: $(Format-Elapsed $baselineResult.Elapsed)"
+    }
+}
+elseif ($guestCloneResult) {
+    Write-Host ""
+    Write-Host "Guest clone (-UseGit): $(if ($guestCloneResult.Success) { '✓ PASS' } else { '✗ FAIL' })" -ForegroundColor $(if ($guestCloneResult.Success) { 'Green' } else { 'Red' })
+    if ($guestCloneResult.Success) {
+        Write-Host "  Time: $(Format-Elapsed $guestCloneResult.Elapsed)"
+    }
+}
+
+Write-Host ""
+Write-Host "Logs: F:\CI\Logs\$BaselineJobId or $GuestCloneJobId" -ForegroundColor Gray
+Write-Host "════════════════════════════════════════════════════════" -ForegroundColor Cyan

scripts/Test-Ns7zipBuild-Linux.ps1

@@ -0,0 +1,167 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Runs a full end-to-end CI test build of nsis-plugin-ns7zip on the Linux template.
+
+.DESCRIPTION
+    Invokes Invoke-CIJob.ps1 with the ns7zip repo parameters targeting the Linux
+    build template (LinuxBuild2404) and verifies the artifact was produced.
+    The Linux build cross-compiles Windows DLLs via mingw-w64.
+
+    Exits 0 on success, 1 on failure.
+
+.PARAMETER JobId
+    Job identifier used for artifact and log directory names.
+    Default: e2e-ns7zip-linux-<yyyyMMdd_HHmmss>
+
+.PARAMETER Branch
+    Branch to build. Default: main
+
+.PARAMETER Commit
+    Optional specific commit SHA. Default: empty (HEAD of branch).
+
+.PARAMETER Config
+    Plugin config to build: x86-ansi | x86-unicode | x64-unicode. Default: x64-unicode
+
+.PARAMETER ZipVersion
+    7-Zip version (Linux-supported subset): 25.01 | 26.00 | 26.01 | zstd. Default: 26.01
+
+.PARAMETER TemplatePath
+    Path to the Linux template VMX. Default: env:GITEA_CI_LINUX_TEMPLATE_PATH or
+    F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
+
+.PARAMETER SnapshotName
+    Snapshot name to clone from. Default: BaseClean-Linux
+
+.PARAMETER SshKeyPath
+    SSH private key for the ci_build user in the guest. Default: F:\CI\keys\ci_linux
+
+.PARAMETER UseGitClone
+    If set, skips host-side git clone and delegates cloning to the guest VM.
+    Uses -GuestRepoUrl (HTTP) instead of the SSH alias URL.
+    Mirrors the -UseGitClone mode of Invoke-CIJob.ps1 (same as §3.3 for Windows).
+
+.PARAMETER GuestRepoUrl
+    HTTP(S) URL used for in-VM clone when -UseGitClone is set.
+    Must be reachable from inside the Linux guest VM.
+    Default: https://gitea.emulab.it/Simone/nsis-plugin-ns7zip.git
+
+.PARAMETER VerifyArtifact
+    If set, expands artifacts.zip (or scans the dir) and checks that at least one DLL is present.
+    Default: $true
+
+.EXAMPLE
+    .\Test-Ns7zipBuild-Linux.ps1
+
+    .\Test-Ns7zipBuild-Linux.ps1 -Config x86-unicode -ZipVersion 26.00
+
+    # Guest-side clone (no host clone, guest fetches via HTTPS):
+    .\Test-Ns7zipBuild-Linux.ps1 -UseGitClone
+#>
+[CmdletBinding()]
+param(
+    [string] $JobId        = "e2e-ns7zip-linux-$(Get-Date -Format 'yyyyMMdd_HHmmss')",
+    [string] $Branch       = 'main',
+    [string] $Commit       = '',
+    [ValidateSet('x86-ansi', 'x86-unicode', 'x64-unicode')]
+    [string] $Config       = 'x64-unicode',
+    [ValidateSet('25.01', '26.00', '26.01', 'zstd')]
+    [string] $ZipVersion   = '26.01',
+    [string] $TemplatePath = $(
+        if ($env:GITEA_CI_LINUX_TEMPLATE_PATH) { $env:GITEA_CI_LINUX_TEMPLATE_PATH }
+        else { 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' }
+    ),
+    [string] $SnapshotName = 'BaseClean-Linux',
+    [string] $SshKeyPath   = 'F:\CI\keys\ci_linux',
+    [switch] $UseGitClone,
+    [string] $GuestRepoUrl  = 'https://gitea.emulab.it/Simone/nsis-plugin-ns7zip.git',
+    [switch] $VerifyArtifact = $true
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$scriptDir    = Split-Path $MyInvocation.MyCommand.Path -Parent
+$orchestrator = Join-Path $scriptDir 'Invoke-CIJob.ps1'
+$artifactDir  = "F:\CI\Artifacts\$JobId"
+
+Write-Host "============================================================"
+Write-Host " nsis-plugin-ns7zip Linux e2e test"
+Write-Host " JobId      : $JobId"
+Write-Host " Branch     : $Branch"
+if ($Commit) { Write-Host " Commit     : $Commit" }
+Write-Host " Config     : $Config"
+Write-Host " 7-Zip ver  : $ZipVersion"
+Write-Host " Template   : $TemplatePath"
+Write-Host " Snapshot   : $SnapshotName"
+Write-Host " Artifacts  : $artifactDir"
+Write-Host " Clone mode : $(if ($UseGitClone) { 'in-VM git clone (-UseGitClone)' } else { 'host clone + tar/scp' })"
+Write-Host "============================================================"
+Write-Host ""
+
+# ns7zip Linux build copies built DLLs under plugins/<config>/nsis7z.dll
+$buildCmd = "python3 build_plugin.py --host linux --7zip-version $ZipVersion --configs $Config --verbose"
+
+# Without -UseGitClone: host clones via SSH alias, transfers source via tar+scp.
+# With    -UseGitClone: host clone is skipped; guest clones via HTTPS URL.
+$repoUrl = if ($UseGitClone) { $GuestRepoUrl } else { 'ssh://gitea-ci/Simone/nsis-plugin-ns7zip.git' }
+
+$params = @{
+    JobId               = $JobId
+    RepoUrl             = $repoUrl
+    Branch              = $Branch
+    TemplatePath        = $TemplatePath
+    SnapshotName        = $SnapshotName
+    Submodules          = $true
+    BuildCommand        = $buildCmd
+    GuestArtifactSource = 'plugins'
+    GuestOS             = 'Linux'
+    SshKeyPath          = $SshKeyPath
+    SshUser             = 'ci_build'
+}
+if ($UseGitClone)    { $params['UseGitClone'] = $true }
+if ($Commit -ne '') { $params['Commit'] = $Commit }
+
+$startTime = Get-Date
+$exitCode  = 0
+
+try {
+    & $orchestrator @params
+    $exitCode = $LASTEXITCODE
+}
+catch {
+    Write-Host "[Test] Invoke-CIJob.ps1 threw: $_"
+    $exitCode = 1
+}
+
+$elapsed = (Get-Date) - $startTime
+Write-Host ""
+Write-Host "============================================================"
+
+if ($exitCode -ne 0) {
+    Write-Host "[Test] FAIL - Invoke-CIJob.ps1 exited $exitCode after $($elapsed.ToString('mm\:ss'))" -ForegroundColor Red
+    exit 1
+}
+
+# Verify at least one .dll arrived from the guest
+if ($VerifyArtifact) {
+    if (-not (Test-Path $artifactDir)) {
+        Write-Host "[Test] FAIL - artifact directory not found: $artifactDir" -ForegroundColor Red
+        exit 1
+    }
+    $dlls = @(Get-ChildItem -Path $artifactDir -Recurse -Filter '*.dll' -ErrorAction SilentlyContinue)
+    if ($dlls.Count -eq 0) {
+        Write-Host "[Test] FAIL - no .dll found under $artifactDir" -ForegroundColor Red
+        Get-ChildItem -Path $artifactDir -Recurse -ErrorAction SilentlyContinue | ForEach-Object {
+            Write-Host "  $($_.FullName)"
+        }
+        exit 1
+    }
+    foreach ($dll in $dlls) {
+        $kb = [math]::Round($dll.Length / 1KB)
+        Write-Host "[Test] Artifact OK: $($dll.FullName) ($kb KB)"
+    }
+}
+
+Write-Host "[Test] PASS - completed in $($elapsed.ToString('mm\:ss'))" -ForegroundColor Green
+exit 0

scripts/Test-NsinnounpBuild-Linux.ps1

@@ -0,0 +1,173 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Runs a full end-to-end CI test build of nsis-plugin-nsinnounp on the Linux template.
+
+.DESCRIPTION
+    Invokes Invoke-CIJob.ps1 with the nsinnounp repo parameters targeting the Linux
+    build template (LinuxBuild2404) and verifies the artifact was produced.
+    Useful for smoke-testing the Linux CI pipeline after changes to scripts or
+    the LinuxBuild2404 template VM.
+
+    Exits 0 on success, 1 on failure.
+
+.PARAMETER JobId
+    Job identifier used for artifact and log directory names.
+    Default: e2e-linux-<yyyyMMdd_HHmmss>
+
+.PARAMETER Branch
+    Branch to build. Default: main
+
+.PARAMETER Commit
+    Optional specific commit SHA. Default: empty (HEAD of branch).
+
+.PARAMETER TemplatePath
+    Path to the Linux template VMX.
+    Default: env:GITEA_CI_LINUX_TEMPLATE_PATH or
+    F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
+
+.PARAMETER SnapshotName
+    Snapshot name to clone from. Default: BaseClean-Linux
+
+.PARAMETER SshKeyPath
+    SSH private key for the ci_build user in the guest.
+    Default: F:\CI\keys\ci_linux
+
+.PARAMETER VerifyArtifact
+    If set, expands artifacts.zip and checks that at least one file is present.
+    Default: $true
+
+.EXAMPLE
+    # Quick smoke test (HEAD of main):
+    .\Test-NsinnounpBuild-Linux.ps1
+
+    # Test a specific commit:
+    .\Test-NsinnounpBuild-Linux.ps1 -Commit abc1234 -VerifyArtifact
+
+    # Custom job ID:
+    .\Test-NsinnounpBuild-Linux.ps1 -JobId 'e2e-linux-001'
+#>
+[CmdletBinding()]
+param(
+    [string] $JobId        = "e2e-linux-$(Get-Date -Format 'yyyyMMdd_HHmmss')",
+    [string] $Branch       = 'main',
+    [string] $Commit       = '',
+    [string] $TemplatePath = $(
+        if ($env:GITEA_CI_LINUX_TEMPLATE_PATH) { $env:GITEA_CI_LINUX_TEMPLATE_PATH }
+        else { 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' }
+    ),
+    [string] $SnapshotName = 'BaseClean-Linux',
+    [string] $SshKeyPath   = 'F:\CI\keys\ci_linux',
+    [switch] $VerifyArtifact = $true
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$scriptDir    = Split-Path $MyInvocation.MyCommand.Path -Parent
+$orchestrator = Join-Path $scriptDir 'Invoke-CIJob.ps1'
+$artifactDir  = "F:\CI\Artifacts\$JobId"
+$artifactZip  = Join-Path $artifactDir 'artifacts.zip'
+
+Write-Host "============================================================"
+Write-Host " nsinnounp Linux e2e test"
+Write-Host " JobId    : $JobId"
+Write-Host " Branch   : $Branch"
+if ($Commit) { Write-Host " Commit   : $Commit" }
+Write-Host " Template : $TemplatePath"
+Write-Host " Snapshot : $SnapshotName"
+Write-Host " Artifacts: $artifactDir"
+Write-Host "============================================================"
+Write-Host ""
+
+$params = @{
+    JobId               = $JobId
+    RepoUrl             = 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git'
+    Branch              = $Branch
+    TemplatePath        = $TemplatePath
+    SnapshotName        = $SnapshotName
+    Submodules          = $true
+    BuildCommand        = 'python3 build_plugin.py --final --dist-dir dist'
+    GuestArtifactSource = 'dist'
+    GuestOS             = 'Linux'
+    SshKeyPath          = $SshKeyPath
+    SshUser             = 'ci_build'
+}
+if ($Commit -ne '') { $params['Commit'] = $Commit }
+
+$startTime = Get-Date
+$exitCode  = 0
+
+try {
+    & $orchestrator @params
+    $exitCode = $LASTEXITCODE
+}
+catch {
+    Write-Host "[Test] Invoke-CIJob.ps1 threw: $_"
+    $exitCode = 1
+}
+
+$elapsed = (Get-Date) - $startTime
+Write-Host ""
+Write-Host "============================================================"
+
+if ($exitCode -ne 0) {
+    Write-Host "[Test] FAIL — Invoke-CIJob.ps1 exited $exitCode after $($elapsed.ToString('mm\:ss'))" -ForegroundColor Red
+    exit 1
+}
+
+# Verify artifact zip exists and is non-empty
+if (-not (Test-Path $artifactZip)) {
+    Write-Host "[Test] FAIL — artifact not found: $artifactZip" -ForegroundColor Red
+    exit 1
+}
+$zipSize = [math]::Round((Get-Item $artifactZip).Length / 1KB)
+Write-Host "[Test] Artifact OK: $artifactZip ($zipSize KB)"
+
+# Optional: expand and verify expected files are present
+if ($VerifyArtifact) {
+    $extractDir = Join-Path $artifactDir 'verify'
+    Write-Host "[Test] Expanding artifact for verification..."
+    if (Test-Path $extractDir) { Remove-Item $extractDir -Recurse -Force }
+    Expand-Archive -Path $artifactZip -DestinationPath $extractDir -Force
+
+    # Accept either Windows cross-compiled artifacts (mingw) or native Linux artifacts
+    $expectedPatterns = @(
+        '*nsInnoUnp*'
+    )
+    $allFound = $true
+    foreach ($pattern in $expectedPatterns) {
+        $found = Get-ChildItem -Path $extractDir -Filter $pattern -Recurse -ErrorAction SilentlyContinue
+        if ($found) {
+            Write-Host "[Test]   OK: $($found.Count) file(s) matching '$pattern'"
+            $found | ForEach-Object { Write-Host "[Test]      $($_.Name)" }
+        }
+        else {
+            Write-Host "[Test]   MISSING: no files matching '$pattern'" -ForegroundColor Red
+            $allFound = $false
+        }
+    }
+
+    # Fallback: accept any non-empty dist
+    if (-not $allFound) {
+        $allFiles = @(Get-ChildItem -Path $extractDir -Recurse -File -ErrorAction SilentlyContinue)
+        if ($allFiles.Count -gt 0) {
+            Write-Host "[Test]   NOTE: pattern check failed but $($allFiles.Count) file(s) found in dist:" -ForegroundColor Yellow
+            $allFiles | ForEach-Object { Write-Host "[Test]      $($_.Name)" }
+            Write-Host "[Test]   Update -expectedPatterns in this script to match actual Linux output." -ForegroundColor Yellow
+            $allFound = $true
+        }
+    }
+
+    Remove-Item $extractDir -Recurse -Force -ErrorAction SilentlyContinue
+
+    if (-not $allFound) {
+        Write-Host "[Test] FAIL — artifact missing expected files." -ForegroundColor Red
+        exit 1
+    }
+}
+
+Write-Host "[Test] PASS — $JobId completed in $($elapsed.ToString('mm\:ss'))" -ForegroundColor Green
+Write-Host "       Artifacts: $artifactDir"
+Write-Host "============================================================"
+exit 0

scripts/Test-NsinnounpBuild.ps1

@@ -22,7 +22,7 @@
 
 .PARAMETER TemplatePath
     Path to template VMX. Default: env:GITEA_CI_TEMPLATE_PATH or
-    F:\CI\Templates\WinBuild\CI-WinBuild.vmx
+    F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
 
 .PARAMETER VerifyArtifact
     If set, unzips artifacts.zip and verifies expected DLL/EXE names
@@ -143,3 +143,4 @@ Write-Host "[Test] PASS — $JobId completed in $($elapsed.ToString('mm\:ss'))"
 Write-Host "       Artifacts: $artifactDir"
 Write-Host "============================================================"
 exit 0
+

scripts/Test-Smoke.ps1

@@ -0,0 +1,166 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Smoke test for the CI pipeline. Validates the full lifecycle end-to-end
+    using a trivial no-op build.
+
+.DESCRIPTION
+    Invokes Invoke-CIJob.ps1 with a minimal build command (write a marker file)
+    and checks that the pipeline completes successfully:
+      - Invoke-CIJob.ps1 exits 0
+      - Artifact directory is created: F:\CI\Artifacts\<JobId>\
+      - invoke-ci.jsonl contains a job-success event
+
+    This script can be run directly on the CI host without act_runner.
+    It is also invoked by gitea/workflows/self-test.yml via the composite action.
+
+.PARAMETER GuestOS
+    Guest OS template to use. Windows (default) or Linux.
+
+.PARAMETER TemplatePath
+    Override the VMX template path. Defaults to the standard template for
+    the chosen GuestOS.
+
+.PARAMETER SnapshotName
+    Snapshot to clone from. Default: BaseClean (Windows) or BaseClean-Linux (Linux).
+
+.PARAMETER JobId
+    Job ID for this test run. Default: smoke-<timestamp>.
+
+.PARAMETER VmrunPath
+    Path to vmrun.exe. Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
+
+.EXAMPLE
+    # Test Windows template
+    .\Test-Smoke.ps1
+
+.EXAMPLE
+    # Test Linux template
+    .\Test-Smoke.ps1 -GuestOS Linux
+#>
+[CmdletBinding()]
+param(
+    [ValidateSet('Windows', 'Linux')]
+    [string] $GuestOS = 'Windows',
+
+    [string] $TemplatePath,
+
+    [string] $SnapshotName,
+
+    [string] $JobId = "smoke-$(Get-Date -Format 'yyyyMMdd-HHmmss')",
+
+    [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe',
+
+    [string] $ArtifactBaseDir = 'F:\CI\Artifacts',
+
+    [string] $LogDir = 'F:\CI\Logs'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = $PSScriptRoot
+
+# ── Resolve defaults ──────────────────────────────────────────────────────────
+if (-not $TemplatePath) {
+    if ($GuestOS -eq 'Linux') {
+        $TemplatePath = if ($env:GITEA_CI_LINUX_TEMPLATE_PATH) {
+            $env:GITEA_CI_LINUX_TEMPLATE_PATH
+        } else {
+            'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx'
+        }
+    } else {
+        $TemplatePath = if ($env:GITEA_CI_TEMPLATE_PATH) {
+            $env:GITEA_CI_TEMPLATE_PATH
+        } else {
+            'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx'
+        }
+    }
+}
+
+if (-not $SnapshotName) {
+    $SnapshotName = if ($GuestOS -eq 'Linux') { 'BaseClean-Linux' } else { 'BaseClean' }
+}
+
+# ── Build command ─────────────────────────────────────────────────────────────
+# Writes a marker file to the standard output directory for the chosen OS.
+if ($GuestOS -eq 'Linux') {
+    $buildCommand  = 'mkdir -p /opt/ci/output && echo smoke-ok > /opt/ci/output/smoke.txt'
+    $artifactSource = '/opt/ci/output'
+} else {
+    $buildCommand  = 'New-Item -ItemType Directory -Path C:\CI\output -Force | Out-Null; Set-Content C:\CI\output\smoke.txt "smoke-ok"'
+    $artifactSource = 'C:\CI\output'
+}
+
+Write-Host "============================================================"
+Write-Host "[Test-Smoke] GuestOS   : $GuestOS"
+Write-Host "[Test-Smoke] Template  : $TemplatePath"
+Write-Host "[Test-Smoke] Snapshot  : $SnapshotName"
+Write-Host "[Test-Smoke] JobId     : $JobId"
+Write-Host "============================================================"
+
+# ── Run the pipeline ──────────────────────────────────────────────────────────
+$invokeParams = @{
+    JobId                = $JobId
+    RepoUrl              = 'https://example.invalid/smoke-test.git'   # never cloned; UseGitClone omitted
+    Branch               = 'main'
+    TemplatePath         = $TemplatePath
+    SnapshotName         = $SnapshotName
+    BuildCommand         = $buildCommand
+    GuestArtifactSource  = $artifactSource
+    ArtifactBaseDir      = $ArtifactBaseDir
+    LogDir               = $LogDir
+    GuestOS              = $GuestOS
+    VmrunPath            = $VmrunPath
+}
+
+$invokeScript = Join-Path $scriptDir 'Invoke-CIJob.ps1'
+& $invokeScript @invokeParams
+$pipelineExit = $LASTEXITCODE
+
+# ── Assert artifacts ──────────────────────────────────────────────────────────
+$artifactDir = Join-Path $ArtifactBaseDir $JobId
+$jsonlPath   = Join-Path $LogDir $JobId 'invoke-ci.jsonl'
+
+Write-Host "`n[Test-Smoke] Verifying results..."
+
+$pass = $true
+
+if ($pipelineExit -ne 0) {
+    Write-Host "[Test-Smoke] FAIL: Invoke-CIJob.ps1 exited $pipelineExit" -ForegroundColor Red
+    $pass = $false
+} else {
+    Write-Host "[Test-Smoke] OK: pipeline exit 0" -ForegroundColor Green
+}
+
+if (Test-Path $artifactDir) {
+    Write-Host "[Test-Smoke] OK: artifact dir exists: $artifactDir" -ForegroundColor Green
+} else {
+    Write-Host "[Test-Smoke] FAIL: artifact dir not found: $artifactDir" -ForegroundColor Red
+    $pass = $false
+}
+
+if (Test-Path $jsonlPath) {
+    $jobSuccess = Get-Content $jsonlPath -Raw -ErrorAction SilentlyContinue |
+        Where-Object { $_ } |
+        ForEach-Object { $_ } |
+        Where-Object { $_ -match '"phase"\s*:\s*"job"' -and $_ -match '"status"\s*:\s*"success"' }
+    if ($jobSuccess) {
+        Write-Host "[Test-Smoke] OK: JSONL contains job/success event" -ForegroundColor Green
+    } else {
+        Write-Host "[Test-Smoke] FAIL: JSONL missing job/success event in: $jsonlPath" -ForegroundColor Red
+        $pass = $false
+    }
+} else {
+    Write-Host "[Test-Smoke] FAIL: JSONL log not found: $jsonlPath" -ForegroundColor Red
+    $pass = $false
+}
+
+Write-Host ''
+if ($pass) {
+    Write-Host "[Test-Smoke] PASSED — $GuestOS smoke test completed successfully." -ForegroundColor Green
+    exit 0
+} else {
+    Write-Host "[Test-Smoke] FAILED — one or more checks did not pass." -ForegroundColor Red
+    exit 1
+}

scripts/Validate-HostState.ps1

@@ -0,0 +1,190 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Validates host-side security prerequisites for the CI system.
+
+.DESCRIPTION
+    Checks that:
+      1. The SSH private key for Linux guest access exists and has restrictive ACLs
+         (only the current user and SYSTEM/Administrators may read it).
+      2. The Windows Credential Manager target used by CI guest sessions is accessible.
+      3. The CI key directories exist with expected permissions.
+
+    Run after `Setup-Host.ps1` and any time credentials or keys are rotated.
+    Exits with code 0 on all-pass, non-zero if any check fails.
+
+.PARAMETER SshKeyPath
+    Path to the SSH private key used for Linux guest access.
+    Default: F:\CI\keys\ci_linux
+
+.PARAMETER GuestCredTarget
+    Windows Credential Manager target name for Windows guest credentials.
+    Default: BuildVMGuest
+
+.PARAMETER CIRootDir
+    Root CI directory to verify existence.
+    Default: F:\CI
+
+.EXAMPLE
+    .\Validate-HostState.ps1
+
+.EXAMPLE
+    .\Validate-HostState.ps1 -SshKeyPath 'F:\CI\keys\ci_linux' -Verbose
+#>
+[CmdletBinding()]
+param(
+    [string] $SshKeyPath      = 'F:\CI\keys\ci_linux',
+    [string] $GuestCredTarget = 'BuildVMGuest',
+    [string] $CIRootDir       = 'F:\CI'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+$script:passCount = 0
+$script:failCount = 0
+
+function Write-Check {
+    param([string]$Label, [scriptblock]$Test)
+    try {
+        $result = & $Test
+        if ($result) {
+            Write-Host "  [OK]  $Label"
+            $script:passCount++
+        } else {
+            Write-Host "  [FAIL] $Label"
+            $script:failCount++
+        }
+    } catch {
+        Write-Host "  [FAIL] $Label — $_"
+        $script:failCount++
+    }
+}
+
+# ── Check 1: SSH key file exists ──────────────────────────────────────────────
+
+Write-Host "`n=== SSH Key ($SshKeyPath) ==="
+
+Write-Check "SSH private key file exists" {
+    Test-Path $SshKeyPath -PathType Leaf
+}
+
+Write-Check "SSH public key file exists" {
+    Test-Path "${SshKeyPath}.pub" -PathType Leaf
+}
+
+# Check ACLs: only SYSTEM, Administrators, and the current user should have access
+Write-Check "SSH key ACL — no unexpected identities" {
+    if (-not (Test-Path $SshKeyPath -PathType Leaf)) { return $false }
+
+    $acl = Get-Acl -Path $SshKeyPath
+    $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+
+    # Allowed identities (case-insensitive prefix matching)
+    $allowedPatterns = @(
+        'NT AUTHORITY\SYSTEM',
+        'BUILTIN\Administrators',
+        $currentUser
+    )
+
+    $unexpected = @()
+    foreach ($ace in $acl.Access) {
+        $identity = $ace.IdentityReference.Value
+        $matched  = $false
+        foreach ($pattern in $allowedPatterns) {
+            if ($identity -ieq $pattern) { $matched = $true; break }
+        }
+        if (-not $matched) {
+            $unexpected += $identity
+        }
+    }
+
+    if ($unexpected.Count -gt 0) {
+        Write-Verbose "[ACL] Unexpected identities on SSH key: $($unexpected -join ', ')"
+        return $false
+    }
+    return $true
+}
+
+Write-Check "SSH key not world-readable (Everyone/Users absent)" {
+    if (-not (Test-Path $SshKeyPath -PathType Leaf)) { return $false }
+
+    $acl = Get-Acl -Path $SshKeyPath
+    $broad = $acl.Access | Where-Object {
+        $id = $_.IdentityReference.Value
+        $id -ilike '*Everyone*' -or $id -ilike 'BUILTIN\Users'
+    }
+    return ($null -eq $broad -or @($broad).Count -eq 0)
+}
+
+# ── Check 2: Credential Manager target ────────────────────────────────────────
+
+Write-Host "`n=== Credential Manager (target: $GuestCredTarget) ==="
+
+Write-Check "CredentialManager module available" {
+    $null -ne (Get-Module -Name CredentialManager -ListAvailable -ErrorAction SilentlyContinue)
+}
+
+Write-Check "Credential target '$GuestCredTarget' accessible" {
+    # Use cmdkey.exe as a fallback — avoids requiring CredentialManager module
+    $cmdkeyOut = & cmdkey.exe /list:$GuestCredTarget 2>&1 | Out-String
+    if ($cmdkeyOut -imatch [regex]::Escape($GuestCredTarget)) {
+        return $true
+    }
+
+    # Try via CredentialManager module if available
+    if ($null -ne (Get-Module -Name CredentialManager -ListAvailable -ErrorAction SilentlyContinue)) {
+        Import-Module CredentialManager -ErrorAction SilentlyContinue
+        $cred = Get-StoredCredential -Target $GuestCredTarget -ErrorAction SilentlyContinue
+        return ($null -ne $cred)
+    }
+
+    return $false
+}
+
+# ── Check 3: CI directory structure ───────────────────────────────────────────
+
+Write-Host "`n=== CI Directory Structure ($CIRootDir) ==="
+
+$requiredDirs = @(
+    'BuildVMs',
+    'Artifacts',
+    'Logs',
+    'State',
+    'keys',
+    'Cache\NuGet',
+    'Cache\pip',
+    'Templates'
+)
+
+foreach ($rel in $requiredDirs) {
+    $full = Join-Path $CIRootDir $rel
+    Write-Check "Directory exists: $rel" { Test-Path $full -PathType Container }
+}
+
+# ── Check 4: vmrun.exe reachable ──────────────────────────────────────────────
+
+Write-Host "`n=== VMware ==="
+
+Write-Check "vmrun.exe found in PATH or default location" {
+    $vmrunDefault = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
+    $inPath = $null -ne (Get-Command 'vmrun.exe' -ErrorAction SilentlyContinue)
+    $atDefault = Test-Path $vmrunDefault -PathType Leaf
+    $inPath -or $atDefault
+}
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+
+Write-Host "`n=== Summary ==="
+Write-Host "  Passed : $($script:passCount)"
+Write-Host "  Failed : $($script:failCount)"
+
+if ($script:failCount -gt 0) {
+    Write-Host "`n[Validate-HostState] $($script:failCount) check(s) failed. Review output above." -ForegroundColor Red
+    exit 1
+} else {
+    Write-Host "`n[Validate-HostState] All checks passed." -ForegroundColor Green
+    exit 0
+}

scripts/Wait-VMReady.ps1

@@ -1,128 +1,37 @@
-#Requires -Version 5.1
-<#
-.SYNOPSIS
-    Waits until a build VM is fully ready to accept WinRM connections.
-
-.DESCRIPTION
-    Performs a three-phase readiness check in a polling loop:
-      1. vmrun getState returns "running"
-      2. ICMP ping succeeds
-      3. Test-WSMan (WinRM) responds without error
-
-    Throws if the VM does not become ready within the timeout period.
-
-.PARAMETER VMPath
-    Full path to the clone VM's .vmx file.
-
-.PARAMETER IPAddress
-    IP address of the VM on the build network (e.g. 192.168.11.101).
-
-.PARAMETER TimeoutSeconds
-    Maximum seconds to wait for the VM to become ready.
-    Default: 300 (5 minutes)
-
-.PARAMETER PollIntervalSeconds
-    Seconds between readiness checks.
-    Default: 5
-
-.PARAMETER VmrunPath
-    Full path to vmrun.exe.
-    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
-
-.EXAMPLE
-    .\Wait-VMReady.ps1 `
-        -VMPath    "F:\CI\BuildVMs\Clone_run-42_20260508_143022\Clone_run-42_20260508_143022.vmx" `
-        -IPAddress "192.168.11.101"
-#>
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory)]
-    [string] $VMPath,
-
-    [Parameter(Mandatory)]
-    [ValidatePattern('^(\d{1,3}\.){3}\d{1,3}$')]
-    [string] $IPAddress,
-
-    [ValidateRange(30, 600)]
-    [int] $TimeoutSeconds = 300,
-
-    [ValidateRange(3, 30)]
-    [int] $PollIntervalSeconds = 5,
-
-    [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe',
-
-    # Skip ICMP ping phase (phase 2). Useful when the guest firewall blocks ICMP
-    # but WinRM (TCP 5985) is open. Phase 1 (vmrun state) and phase 3 (WinRM)
-    # are still checked.
-    [switch] $SkipPing
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-if (-not (Test-Path $VmrunPath -PathType Leaf)) {
-    throw "vmrun.exe not found at: $VmrunPath"
-}
-
-$deadline    = (Get-Date).AddSeconds($TimeoutSeconds)
-$attempt     = 0
-$phase       = 'vmrun-state'   # tracks current phase for informative output
-$lastPhase   = ''
-
-Write-Host "[Wait-VMReady] Waiting for VM ready (timeout: ${TimeoutSeconds}s, IP: $IPAddress)..."
-
-while ((Get-Date) -lt $deadline) {
-    $attempt++
-
-    # ── Phase 1: VM must be running ─────────────────────────────────────
-    # vmrun has no getState; getGuestIPAddress exits non-zero when the VM
-    # is not powered on. Native commands don't throw — check exit code only.
-    & $VmrunPath getGuestIPAddress $VMPath 2>&1 | Out-Null
-    $isRunning = ($LASTEXITCODE -eq 0)
-
-    if (-not $isRunning) {
-        if ($phase -ne 'vmrun-state') {
-            $phase = 'vmrun-state'
-        }
-        if ($lastPhase -ne $phase) {
-            Write-Host "[Wait-VMReady] Phase 1/3: waiting for VM to enter running state..."
-            $lastPhase = $phase
-        }
-        Start-Sleep -Seconds $PollIntervalSeconds
-        continue
-    }
-
-    # ── Phase 2: Network ping (optional) ───────────────────────────────
-    if (-not $SkipPing) {
-        $pingOk = Test-Connection -ComputerName $IPAddress -Count 1 -Quiet -ErrorAction SilentlyContinue
-
-        if (-not $pingOk) {
-            $phase = 'ping'
-            if ($lastPhase -ne $phase) {
-                Write-Host "[Wait-VMReady] Phase 2/3: VM running, waiting for network (ping $IPAddress)..."
-                $lastPhase = $phase
-            }
-            Start-Sleep -Seconds $PollIntervalSeconds
-            continue
-        }
-    }
-
-    # ── Phase 3: WinRM responsive ────────────────────────────────────────
-    try {
-        Test-WSMan -ComputerName $IPAddress -ErrorAction Stop | Out-Null
-        # Success — VM is ready
-        Write-Host "[Wait-VMReady] VM ready after ~$([int]($attempt * $PollIntervalSeconds))s (attempt $attempt)."
-        return
-    }
-    catch {
-        $phase = 'winrm'
-        if ($lastPhase -ne $phase) {
-            Write-Host "[Wait-VMReady] Phase 3/3: ping OK, waiting for WinRM on port 5985..."
-            $lastPhase = $phase
-        }
-        Start-Sleep -Seconds $PollIntervalSeconds
-        continue
-    }
-}
-
-throw "[Wait-VMReady] Timed out after ${TimeoutSeconds}s waiting for VM at $IPAddress to become ready. Last phase: $phase"
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A2-closeout.md.
+# PowerShell common params (-ErrorAction etc.) must not be forwarded
+# to the Python CLI. Value-taking ones also consume the next token.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
+}
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
+
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
+    }
+}
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator wait-ready @pyArgs
+exit $LASTEXITCODE

scripts/Watch-DiskSpace.ps1

@@ -0,0 +1,37 @@
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A2-closeout.md.
+# PowerShell common params (-ErrorAction etc.) must not be forwarded
+# to the Python CLI. Value-taking ones also consume the next token.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
+}
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
+
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
+    }
+}
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator monitor disk @pyArgs
+exit $LASTEXITCODE

scripts/Watch-RunnerHealth.ps1

@@ -0,0 +1,37 @@
+#Requires -Version 5.1
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Shim: delegates to the Python ci_orchestrator CLI.
+# Original PS implementation moved to git history; see plans/A2-closeout.md.
+# PowerShell common params (-ErrorAction etc.) must not be forwarded
+# to the Python CLI. Value-taking ones also consume the next token.
+$commonWithValue = @{
+    erroraction = $true; warningaction = $true; informationaction = $true
+    progressaction = $true; errorvariable = $true; warningvariable = $true
+    informationvariable = $true; outvariable = $true; outbuffer = $true
+    pipelinevariable = $true
+}
+$commonSwitch = @{ verbose = $true; debug = $true; whatif = $true; confirm = $true }
+
+$pyArgs = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = $args[$i]
+    if ($a -is [string] -and $a.Length -gt 1 -and $a.StartsWith('-') -and -not $a.StartsWith('--')) {
+        $name  = $a.Substring(1)
+        $lname = $name.ToLower()
+        if ($commonSwitch.ContainsKey($lname)) { continue }
+        if ($commonWithValue.ContainsKey($lname)) { $i++; continue }
+        $kebab = [Regex]::Replace($name, '(?<=[a-z0-9])([A-Z])', '-$1')
+        $kebab = [Regex]::Replace($kebab, '([A-Z]+)([A-Z][a-z])', '$1-$2')
+        $pyArgs += '--' + $kebab.ToLower()
+    }
+    else {
+        $pyArgs += $a
+    }
+}
+
+$venvPython = $env:CI_VENV_PYTHON
+if (-not $venvPython) { $venvPython = 'F:\CI\python\venv\Scripts\python.exe' }
+& $venvPython -m ci_orchestrator monitor runner @pyArgs
+exit $LASTEXITCODE

scripts/_Common.psm1

@@ -0,0 +1,421 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Shared helper functions for the Local CI/CD System scripts.
+
+.DESCRIPTION
+    Import this module at the top of any CI script that needs WinRM session
+    options or vmrun wrappers:
+
+        Import-Module (Join-Path $PSScriptRoot '_Common.psm1') -Force
+
+    Exported functions:
+      New-CISessionOption  — PSSessionOption for WinRM over self-signed TLS
+      Resolve-VmrunPath    — Validates vmrun.exe path, throws if missing
+      Invoke-Vmrun         — Uniform vmrun -T ws wrapper; returns ExitCode + Output
+#>
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function New-CISessionOption {
+<#
+.SYNOPSIS
+    Returns a PSSessionOption for WinRM HTTPS with self-signed certificate.
+.DESCRIPTION
+    All CI build VMs use a self-signed TLS cert on WinRM port 5986.
+    This option set skips CA, CN, and revocation checks — appropriate for
+    an isolated lab network where PKI is not present.
+.OUTPUTS
+    [System.Management.Automation.Remoting.PSSessionOption]
+#>
+    [OutputType([System.Management.Automation.Remoting.PSSessionOption])]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '',
+        Justification = 'New-CISessionOption creates an in-memory PSSessionOption object; no system state is changed.')]
+    [CmdletBinding()]
+    param()
+    New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
+}
+
+function Resolve-VmrunPath {
+<#
+.SYNOPSIS
+    Validates that vmrun.exe exists at the specified path and returns it.
+.DESCRIPTION
+    Throws a descriptive error if the file is not found, rather than letting
+    a later & call fail with a less useful message.
+.PARAMETER VmrunPath
+    Full path to vmrun.exe.
+    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
+.OUTPUTS
+    [string] The validated VmrunPath.
+#>
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
+    )
+    if (-not (Test-Path $VmrunPath -PathType Leaf)) {
+        throw "vmrun.exe not found at: $VmrunPath`nInstall VMware Workstation Pro and update -VmrunPath."
+    }
+    return $VmrunPath
+}
+
+function Invoke-Vmrun {
+<#
+.SYNOPSIS
+    Runs a vmrun -T ws <Operation> command and returns output and exit code.
+.DESCRIPTION
+    Uniform wrapper so all vmrun calls share the same -T ws flag and output
+    capture pattern. Use -ThrowOnError for operations that must succeed
+    (clone, start); omit it for best-effort operations (stop, getState).
+.PARAMETER VmrunPath
+    Full path to vmrun.exe.
+.PARAMETER Operation
+    vmrun sub-command: clone, start, stop, deleteVM, list, getState,
+    listSnapshots, getGuestIPAddress, etc.
+.PARAMETER Arguments
+    Additional positional arguments after the operation name.
+.PARAMETER ThrowOnError
+    When set, throws if vmrun exits non-zero.
+.OUTPUTS
+    [pscustomobject] with:
+      ExitCode [int]     — vmrun exit code
+      Output   [string[]] — combined stdout/stderr lines
+#>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)] [string]   $VmrunPath,
+        [Parameter(Mandatory)] [string]   $Operation,
+        [string[]]                        $Arguments    = @(),
+        [switch]                          $ThrowOnError
+    )
+    $cmdArgs = @('-T', 'ws', $Operation) + $Arguments
+    $output  = & $VmrunPath @cmdArgs 2>&1
+    $exit    = $LASTEXITCODE
+
+    if ($ThrowOnError -and $exit -ne 0) {
+        throw "vmrun $Operation failed (exit $exit): $($output -join '; ')"
+    }
+
+    return [pscustomobject]@{
+        ExitCode = $exit
+        Output   = $output
+    }
+}
+
+function Invoke-VmrunBounded {
+<#
+.SYNOPSIS
+    Runs a vmrun -T ws <Operation> command with a hard wall-clock timeout.
+.DESCRIPTION
+    Uses [System.Diagnostics.Process] directly (not Start-Process -PassThru) because
+    Start-Process in PowerShell 5.1 does not reliably populate Process.ExitCode after
+    WaitForExit(ms) when output is redirected. ReadToEndAsync() is used for stdout and
+    stderr to prevent deadlock if output buffers fill up before the process exits.
+
+    Use for lifecycle operations: start (180s), stop (60s), deleteVM (90s).
+    Keep Invoke-Vmrun for fast queries: list, readVariable, getGuestIPAddress, getState.
+.PARAMETER VmrunPath
+    Full path to vmrun.exe.
+.PARAMETER Operation
+    vmrun sub-command (start, stop, deleteVM, clone, …).
+.PARAMETER Arguments
+    Additional positional arguments after the operation name.
+.PARAMETER TimeoutSeconds
+    Hard timeout in seconds. Process is killed if not finished within this time.
+    Default: 120.
+.PARAMETER ThrowOnTimeout
+    When set, throws if the timeout is reached before vmrun exits.
+.PARAMETER ThrowOnError
+    When set, throws if vmrun exits with a non-zero code.
+.OUTPUTS
+    [pscustomobject] with:
+      ExitCode       [int]    — vmrun exit code (-1 if killed due to timeout)
+      Output         [string] — combined stdout/stderr text
+      TimedOut       [bool]   — true if the process was killed for exceeding TimeoutSeconds
+      ElapsedSeconds [double] — wall-clock seconds from start to exit/kill
+#>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)] [string]   $VmrunPath,
+        [Parameter(Mandatory)] [string]   $Operation,
+        [string[]]                        $Arguments      = @(),
+        [int]                             $TimeoutSeconds = 120,
+        [switch]                          $ThrowOnTimeout,
+        [switch]                          $ThrowOnError
+    )
+
+    $cmdArgs = @('-T', 'ws', $Operation) + $Arguments
+
+    # Quote tokens that contain spaces so the argument string is correct when
+    # passed to ProcessStartInfo.Arguments as a single string.
+    $quotedArgs = $cmdArgs | ForEach-Object {
+        if ($_ -match '\s') { '"' + ($_ -replace '"', '""') + '"' } else { $_ }
+    }
+    $argStr = $quotedArgs -join ' '
+
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName               = $VmrunPath
+    $psi.Arguments              = $argStr
+    $psi.UseShellExecute        = $false
+    $psi.CreateNoWindow         = $true
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError  = $true
+
+    $proc     = New-Object System.Diagnostics.Process
+    $proc.StartInfo = $psi
+    $sw       = [System.Diagnostics.Stopwatch]::StartNew()
+    $timedOut = $false
+
+    [void]$proc.Start()
+
+    # Begin async reads before WaitForExit to avoid deadlock when output buffers fill.
+    $stdoutTask = $proc.StandardOutput.ReadToEndAsync()
+    $stderrTask = $proc.StandardError.ReadToEndAsync()
+
+    $exited = $proc.WaitForExit($TimeoutSeconds * 1000)
+    if (-not $exited) {
+        $timedOut = $true
+        # Kill the entire process tree (taskkill /T) to release any inherited pipe
+        # handles held by child processes (e.g. cmd.exe spawning ping.exe in tests,
+        # or vmrun spawning helper subprocesses). Plain proc.Kill() only kills the
+        # direct process; child processes keep the write end of stdout open.
+        & taskkill /F /T /PID $proc.Id 2>&1 | Out-Null
+    }
+    $sw.Stop()
+
+    $outputText = ''
+    if (-not $timedOut) {
+        # Process exited normally: drain stdout/stderr (up to 5s safety net).
+        [void][System.Threading.Tasks.Task]::WhenAll($stdoutTask, $stderrTask).Wait(5000)
+        $stdoutText = ''
+        $stderrText = ''
+        if ($stdoutTask.Status -eq [System.Threading.Tasks.TaskStatus]::RanToCompletion) {
+            $stdoutText = $stdoutTask.Result
+        }
+        if ($stderrTask.Status -eq [System.Threading.Tasks.TaskStatus]::RanToCompletion) {
+            $stderrText = $stderrTask.Result
+        }
+        $parts      = @($stdoutText, $stderrText) | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }
+        $outputText = ($parts | ForEach-Object { $_.TrimEnd() }) -join "`n"
+    }
+    # When timed-out: process was killed; output is irrelevant and potentially
+    # incomplete. Skip drain entirely — no point blocking for a killed process.
+
+    $exitCode = if ($timedOut) { -1 } else { $proc.ExitCode }
+
+    $result = [pscustomobject]@{
+        ExitCode       = $exitCode
+        Output         = $outputText
+        TimedOut       = $timedOut
+        ElapsedSeconds = [math]::Round($sw.Elapsed.TotalSeconds, 1)
+    }
+
+    if ($timedOut -and $ThrowOnTimeout) {
+        throw "vmrun $Operation timed out after ${TimeoutSeconds}s"
+    }
+    if (-not $timedOut -and $exitCode -ne 0 -and $ThrowOnError) {
+        throw "vmrun $Operation failed (exit $exitCode): $outputText"
+    }
+
+    return $result
+}
+
+function Get-GuestIPAddress {
+<#
+.SYNOPSIS
+    Polls a running VMware guest VM until its IP address is available, then returns it.
+.DESCRIPTION
+    Primary method: reads the 'ci-ip' guestVar written by ci-report-ip.service (Linux)
+    or the equivalent guest-side script via vmware-rpctool. This uses the VMware VMCI
+    channel and does not require TCP/IP connectivity from the host.
+
+    Fallback: vmrun getGuestIPAddress (reliable on Windows guests; may be slow on Linux).
+
+    Returns the detected IP as a plain string, or an empty string if the timeout expires.
+.PARAMETER VmrunPath
+    Full path to vmrun.exe.
+.PARAMETER VmxPath
+    Full path to the clone VM's .vmx file.
+.PARAMETER TimeoutSeconds
+    Maximum seconds to poll before giving up. Default: 120.
+.OUTPUTS
+    [string] Detected IPv4 address, or empty string on timeout.
+#>
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)] [string] $VmrunPath,
+        [Parameter(Mandatory)] [string] $VmxPath,
+        [int]                           $TimeoutSeconds = 120
+    )
+
+    Write-Host "[Get-GuestIPAddress] Polling for VM IP (max ${TimeoutSeconds}s)..."
+    $deadline = (Get-Date).AddSeconds($TimeoutSeconds)
+    $attempt  = 0
+
+    while ((Get-Date) -lt $deadline) {
+        $attempt++
+
+        # Primary: guestinfo.ci-ip written by ci-report-ip.service via vmware-rpctool.
+        # NOTE: vmrun readVariable guestVar reads WITHOUT the 'guestinfo.' prefix.
+        $savedEap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
+        $ipOut = (& $VmrunPath -T ws readVariable $VmxPath guestVar 'ci-ip' 2>&1).Trim()
+        $ipRc  = $LASTEXITCODE
+        $ErrorActionPreference = $savedEap
+
+        if ($attempt -le 3 -or ($attempt % 10 -eq 0)) {
+            Write-Host "[Get-GuestIPAddress] [attempt $attempt] guestVar ci-ip: rc=$ipRc out='$ipOut'"
+        }
+        if ($ipRc -eq 0 -and $ipOut -match '^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$') {
+            Write-Host "[Get-GuestIPAddress] IP via guestinfo: $ipOut"
+            return $ipOut
+        }
+
+        # Fallback: vmrun getGuestIPAddress (VMware Tools / open-vm-tools required).
+        $savedEap = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
+        $ipOut2 = (& $VmrunPath -T ws getGuestIPAddress $VmxPath 2>&1).Trim()
+        $ipRc2  = $LASTEXITCODE
+        $ErrorActionPreference = $savedEap
+
+        if ($ipRc2 -eq 0 -and $ipOut2 -match '^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$') {
+            Write-Host "[Get-GuestIPAddress] IP via getGuestIPAddress: $ipOut2"
+            return $ipOut2
+        }
+
+        Start-Sleep -Seconds 2
+    }
+
+    return ''
+}
+
+function Get-GuestDiagnostics {
+<#
+.SYNOPSIS
+    Best-effort collection of guest diagnostics after a build failure.
+    Never throws — always safe to call from a catch/finally block.
+
+.PARAMETER IPAddress
+    IP address of the guest VM.
+
+.PARAMETER GuestOS
+    'Windows' or 'Linux'.
+
+.PARAMETER Credential
+    PSCredential for WinRM (Windows guests). Ignored for Linux.
+
+.PARAMETER SshKeyPath
+    Path to SSH private key (Linux guests). Ignored for Windows.
+
+.PARAMETER SshUser
+    SSH username (Linux guests). Default: ci_build.
+
+.PARAMETER DestinationDir
+    Host directory where diagnostics files are written.
+#>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)] [string]      $IPAddress,
+        [Parameter(Mandatory)] [ValidateSet('Windows','Linux')]
+                               [string]      $GuestOS,
+        [pscredential]                       $Credential,
+        [string]                             $SshKeyPath,
+        [string]                             $SshUser          = 'ci_build',
+        [Parameter(Mandatory)] [string]      $DestinationDir
+    )
+
+    Write-Host "[Diagnostics] Collecting guest diagnostics from $IPAddress ($GuestOS) -> $DestinationDir"
+    try {
+        if (-not (Test-Path $DestinationDir)) {
+            New-Item -ItemType Directory -Path $DestinationDir -Force | Out-Null
+        }
+    } catch {
+        Write-Warning "[Diagnostics] Could not create destination dir: $_"
+        return
+    }
+
+    if ($GuestOS -eq 'Windows') {
+        if (-not $Credential) {
+            Write-Warning "[Diagnostics] No Credential supplied for Windows guest — skipping."
+            return
+        }
+        try {
+            $sessionOption = New-CISessionOption
+            $session = New-PSSession -ComputerName $IPAddress `
+                           -Credential $Credential `
+                           -SessionOption $sessionOption `
+                           -ErrorAction Stop
+            try {
+                # Collect: event log errors (last 50), running processes, disk usage
+                $diagScript = {
+                    $out = [System.Text.StringBuilder]::new()
+                    [void]$out.AppendLine("=== System Event Log (last 50 errors) ===")
+                    Get-EventLog -LogName System -EntryType Error -Newest 50 -ErrorAction SilentlyContinue |
+                        ForEach-Object { [void]$out.AppendLine("$($_.TimeGenerated) $($_.Source): $($_.Message)") }
+                    [void]$out.AppendLine("`n=== Running Processes ===")
+                    Get-Process -ErrorAction SilentlyContinue |
+                        Sort-Object CPU -Descending |
+                        Select-Object -First 30 |
+                        ForEach-Object { [void]$out.AppendLine("$($_.Name) PID=$($_.Id) CPU=$($_.CPU)") }
+                    [void]$out.AppendLine("`n=== Disk Free Space ===")
+                    Get-PSDrive -PSProvider FileSystem -ErrorAction SilentlyContinue |
+                        ForEach-Object { [void]$out.AppendLine("$($_.Name): Free=$([math]::Round($_.Free/1GB,1))GB Used=$([math]::Round($_.Used/1GB,1))GB") }
+                    $out.ToString()
+                }
+                $diagText = Invoke-Command -Session $session -ScriptBlock $diagScript -ErrorAction Stop
+                $diagText | Set-Content -Path (Join-Path $DestinationDir 'guest-diag.txt') -Encoding UTF8
+                Write-Host "[Diagnostics] Windows diagnostics written."
+
+                # Best-effort: copy CI build log
+                $buildLog = 'C:\CI\build.log'
+                try {
+                    Copy-Item -FromSession $session -Path $buildLog `
+                        -Destination (Join-Path $DestinationDir 'build.log') `
+                        -ErrorAction Stop
+                    Write-Host "[Diagnostics] Build log copied."
+                } catch {
+                    Write-Host "[Diagnostics] Build log not found in guest (skipping)."
+                }
+            } finally {
+                Remove-PSSession $session -ErrorAction SilentlyContinue
+            }
+        } catch {
+            Write-Warning "[Diagnostics] Windows guest diagnostics failed (non-fatal): $_"
+        }
+    }
+    else {
+        # Linux
+        if (-not $SshKeyPath) {
+            Write-Warning "[Diagnostics] No SshKeyPath supplied for Linux guest — skipping."
+            return
+        }
+        $sshOpts = @('-i', $SshKeyPath, '-o', 'StrictHostKeyChecking=no',
+                     '-o', 'UserKnownHostsFile=NUL',
+                     '-o', 'ConnectTimeout=10', '-o', 'BatchMode=yes')
+        try {
+            # Collect: journalctl errors, ps, df
+            $diagCmd = "journalctl -p err -n 50 --no-pager 2>/dev/null; echo '=== ps ==='; ps aux --sort=-%cpu | head -30; echo '=== df ==='; df -h"
+            $savedEap = $ErrorActionPreference
+            $ErrorActionPreference = 'Continue'
+            $diagOutput = & ssh.exe @sshOpts "${SshUser}@${IPAddress}" $diagCmd 2>&1
+            $ErrorActionPreference = $savedEap
+            $diagOutput | Set-Content -Path (Join-Path $DestinationDir 'guest-diag.txt') -Encoding UTF8
+            Write-Host "[Diagnostics] Linux diagnostics written."
+
+            # Best-effort: copy CI build log
+            $scpSrc = "${SshUser}@${IPAddress}:/opt/ci/build/ci-build.log"
+            $scpDst = Join-Path $DestinationDir 'build.log'
+            $ErrorActionPreference = 'Continue'
+            & scp.exe @sshOpts $scpSrc $scpDst 2>&1 | Out-Null
+            $ErrorActionPreference = $savedEap
+            if (Test-Path $scpDst) { Write-Host "[Diagnostics] Build log copied." }
+            else                   { Write-Host "[Diagnostics] Build log not found in guest (skipping)." }
+        } catch {
+            Write-Warning "[Diagnostics] Linux guest diagnostics failed (non-fatal): $_"
+        }
+    }
+}
+
+Export-ModuleMember -Function New-CISessionOption, Resolve-VmrunPath, Invoke-Vmrun, Invoke-VmrunBounded, Get-GuestIPAddress, Get-GuestDiagnostics

scripts/_Transport.psm1

@@ -0,0 +1,201 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    SSH/SCP transport helpers for Linux build VMs.
+
+.DESCRIPTION
+    SSH-only transport layer for the Linux branch of the CI/CD system.
+    The existing WinRM transport (used by Windows VMs) is NOT modified.
+
+    Exported functions:
+      Invoke-SshCommand  — run a command in a Linux guest via ssh.exe
+      Copy-SshItem       — copy files to/from a Linux guest via scp.exe
+      Test-SshReady      — poll until SSH is ready (port 22 open + login succeeds)
+
+    Requirements:
+      - ssh.exe and scp.exe in PATH (default on Windows 11 / Server 2022)
+      - SSH private key at the path provided
+      - Guest user must be set up for key-based auth (no passphrase)
+#>
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+$ProgressPreference   = 'SilentlyContinue'   # suppress Write-Progress (Test-NetConnection, IWR, etc.)
+
+function Invoke-SshCommand {
+    <#
+    .SYNOPSIS
+        Run a command in a Linux guest via ssh.exe
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $IP,
+
+        [string] $User = 'ci_build',
+
+        [string] $KeyPath = 'F:\CI\keys\ci_linux',
+
+        [Parameter(Mandatory)]
+        [string] $Command,
+
+        [int] $ConnectTimeout = 10,
+
+        # Persistent known_hosts file for CI jobs.
+        # When non-empty: StrictHostKeyChecking=accept-new + this file.
+        # When empty (default): permissive mode (StrictHostKeyChecking=no, UserKnownHostsFile=NUL)
+        # — used during template provisioning when host key is not yet known.
+        [string] $KnownHostsFile = '',
+
+        # Capture + return stdout/stderr instead of printing to console.
+        [switch] $PassThru,
+
+        # Don't throw on non-zero exit — just return the output.
+        [switch] $AllowFail
+    )
+
+    if ($KnownHostsFile -ne '') {
+        $sshHostKeyOpts = @('-o', 'StrictHostKeyChecking=accept-new', '-o', "UserKnownHostsFile=$KnownHostsFile")
+    } else {
+        $sshHostKeyOpts = @('-o', 'StrictHostKeyChecking=no', '-o', 'UserKnownHostsFile=NUL')
+    }
+    $sshArgs = @(
+        '-i', $KeyPath
+    ) + $sshHostKeyOpts + @(
+        '-o', "ConnectTimeout=$ConnectTimeout",
+        '-o', 'BatchMode=yes',
+        "$User@$IP",
+        $Command
+    )
+
+    if ($PassThru) {
+        $output = & ssh @sshArgs 2>&1
+        $exit   = $LASTEXITCODE
+    }
+    else {
+        & ssh @sshArgs
+        $exit   = $LASTEXITCODE
+        $output = @()
+    }
+
+    if ($exit -ne 0 -and -not $AllowFail) {
+        throw "[SSH] Command failed (exit $exit): $Command"
+    }
+
+    return [pscustomobject]@{
+        ExitCode = [int]$exit
+        Output   = [string[]]$output
+    }
+}
+
+function Copy-SshItem {
+    <#
+    .SYNOPSIS
+        Copy files to/from Linux guest via scp.exe
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Source,
+
+        [Parameter(Mandatory)]
+        [string] $Destination,
+
+        # Guest IP — used to build user@host prefix when Direction is set.
+        [string] $IP = '',
+
+        [string] $User = 'ci_build',
+
+        [Parameter(Mandatory)]
+        [string] $KeyPath,
+
+        [ValidateSet('ToGuest', 'FromGuest', 'Direct')]
+        [string] $Direction = 'Direct',
+
+        # Pass -r to scp (recursive copy).
+        [switch] $Recurse,
+
+        [int] $ConnectTimeout = 10,
+
+        # Persistent known_hosts file for CI jobs.
+        # When non-empty: StrictHostKeyChecking=accept-new + this file.
+        # When empty (default): permissive mode — used during template provisioning.
+        [string] $KnownHostsFile = ''
+    )
+
+    if ($Direction -eq 'ToGuest') {
+        $Destination = "$User@${IP}:$Destination"
+    }
+    elseif ($Direction -eq 'FromGuest') {
+        $Source = "$User@${IP}:$Source"
+    }
+    # Direction = 'Direct': use Source + Destination as-is
+
+    if ($KnownHostsFile -ne '') {
+        $scpHostKeyOpts = @('-o', 'StrictHostKeyChecking=accept-new', '-o', "UserKnownHostsFile=$KnownHostsFile")
+    } else {
+        $scpHostKeyOpts = @('-o', 'StrictHostKeyChecking=no', '-o', 'UserKnownHostsFile=NUL')
+    }
+    $scpArgs = @(
+        '-i', $KeyPath
+    ) + $scpHostKeyOpts + @(
+        '-o', "ConnectTimeout=$ConnectTimeout"
+    )
+    if ($Recurse) { $scpArgs += '-r' }
+    $scpArgs += @($Source, $Destination)
+
+    & scp @scpArgs
+    if ($LASTEXITCODE -ne 0) {
+        throw "[SCP] Copy failed (exit $LASTEXITCODE): $Source -> $Destination"
+    }
+}
+
+function Test-SshReady {
+    <#
+    .SYNOPSIS
+        Poll until SSH port 22 is open and a login command succeeds.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $IP,
+
+        [string] $User = 'ci_build',
+
+        [string] $KeyPath = 'F:\CI\keys\ci_linux',
+
+        [int] $TimeoutSec = 300,
+
+        [int] $PollSec = 10
+    )
+
+    $deadline = (Get-Date).AddSeconds($TimeoutSec)
+
+    # Phase 1: wait for port 22 to be open
+    $portOpen = $false
+    while (-not $portOpen -and (Get-Date) -lt $deadline) {
+        $portOpen = (Test-NetConnection -ComputerName $IP -Port 22 `
+            -InformationLevel Quiet -WarningAction SilentlyContinue `
+            -ErrorAction SilentlyContinue)
+        if (-not $portOpen) {
+            Start-Sleep -Seconds $PollSec
+        }
+    }
+
+    if (-not $portOpen) {
+        throw "[Test-SshReady] Timed out after ${TimeoutSec}s waiting for SSH at $IP"
+    }
+
+    # Phase 2: try ssh echo — success when output contains 'ready'
+    while ((Get-Date) -lt $deadline) {
+        $result = Invoke-SshCommand -IP $IP -User $User -KeyPath $KeyPath `
+            -Command 'echo ready' -AllowFail -PassThru
+        if ($result.ExitCode -eq 0 -and ($result.Output -join '') -like '*ready*') {
+            return $true
+        }
+        Start-Sleep -Seconds $PollSec
+    }
+
+    throw "[Test-SshReady] Timed out after ${TimeoutSec}s waiting for SSH at $IP"
+}
+
+Export-ModuleMember -Function Invoke-SshCommand, Copy-SshItem, Test-SshReady

src/ci_orchestrator/__init__.py

@@ -0,0 +1,9 @@
+"""Local CI/CD orchestrator package.
+
+Phase A: Python rewrite of the PowerShell-based orchestrator.
+See plans/implementation-plan-A-B.md for the full scope.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

src/ci_orchestrator/__main__.py

@@ -0,0 +1,48 @@
+"""CLI entry point.
+
+Phase A2 ships ``wait-ready``, ``vm`` (remove/cleanup), ``monitor``
+(disk/runner) and ``report`` (job). Phase A3 adds ``vm new``, ``build``,
+``artifacts``. Subsequent phases add ``job``.
+"""
+
+from __future__ import annotations
+
+import time as time
+
+import click
+
+from ci_orchestrator import __version__
+from ci_orchestrator.commands.artifacts import artifacts
+from ci_orchestrator.commands.build import build
+from ci_orchestrator.commands.job import job
+from ci_orchestrator.commands.monitor import monitor
+from ci_orchestrator.commands.report import report
+from ci_orchestrator.commands.vm import vm
+
+# Re-export so legacy A1 tests that patched ``cli_module.<name>`` keep working.
+from ci_orchestrator.commands.wait import (  # noqa: F401  (intentional re-exports)
+    KeyringCredentialStore,
+    SshTransport,
+    WinRmTransport,
+    load_backend,
+    wait_ready,
+)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="ci-orchestrator")
+def cli() -> None:
+    """Local CI/CD orchestrator."""
+
+
+cli.add_command(wait_ready)
+cli.add_command(vm)
+cli.add_command(build)
+cli.add_command(artifacts)
+cli.add_command(monitor)
+cli.add_command(report)
+cli.add_command(job)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

src/ci_orchestrator/backends/__init__.py

@@ -0,0 +1,30 @@
+"""VM backend implementations.
+
+The :class:`~ci_orchestrator.backends.protocol.VmBackend` Protocol defines
+the neutral interface every backend must satisfy. Phase A ships only the
+:class:`~ci_orchestrator.backends.workstation.WorkstationVmrunBackend`;
+Phase C will add an ESXi backend behind the same interface.
+"""
+
+from __future__ import annotations
+
+from ci_orchestrator.backends.protocol import VmBackend, VmHandle, VmState
+from ci_orchestrator.backends.workstation import WorkstationVmrunBackend
+
+__all__ = ["VmBackend", "VmHandle", "VmState", "WorkstationVmrunBackend", "load_backend"]
+
+
+def load_backend(config: object) -> VmBackend:
+    """Factory: pick a backend implementation from ``config.backend.type``.
+
+    Phase C hook: when the ESXi backend lands, this function will dispatch
+    on ``config.backend.type``. For now only ``workstation`` is supported.
+    """
+    backend_type = getattr(getattr(config, "backend", None), "type", "workstation")
+    if backend_type != "workstation":
+        raise NotImplementedError(
+            f"Backend type '{backend_type}' is not implemented. "
+            "Only 'workstation' is available in Phase A."
+        )
+    vmrun_path = getattr(config, "vmrun_path", None)
+    return WorkstationVmrunBackend(vmrun_path=vmrun_path)

src/ci_orchestrator/backends/errors.py

@@ -0,0 +1,24 @@
+"""Backend error hierarchy."""
+
+from __future__ import annotations
+
+
+class BackendError(RuntimeError):
+    """Base error for VM backend failures."""
+
+
+class BackendNotAvailable(BackendError):
+    """Backend tooling (e.g. ``vmrun``) is missing or unusable."""
+
+
+class BackendOperationFailed(BackendError):
+    """A backend operation (clone, start, ...) returned a non-zero status."""
+
+    def __init__(self, operation: str, returncode: int, output: str) -> None:
+        super().__init__(
+            f"Backend operation '{operation}' failed "
+            f"(exit={returncode}): {output.strip() or '<no output>'}"
+        )
+        self.operation = operation
+        self.returncode = returncode
+        self.output = output

src/ci_orchestrator/backends/protocol.py

@@ -0,0 +1,81 @@
+"""Neutral VM backend Protocol.
+
+Phase C hook: keep names hypervisor-agnostic. ``clone_linked``, ``start``,
+``stop``, ``delete``, ``get_ip``, ``list_snapshots`` map cleanly onto both
+``vmrun`` and pyVmomi (vSphere). Identifiers are opaque strings (a VMX path
+on Workstation, a managed object reference on ESXi).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+
+class VmState(StrEnum):
+    """Coarse VM power state, normalised across backends."""
+
+    POWERED_OFF = "powered_off"
+    POWERED_ON = "powered_on"
+    SUSPENDED = "suspended"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class VmHandle:
+    """Opaque reference to a VM managed by a backend.
+
+    ``identifier`` is backend-specific (a VMX path for Workstation, a
+    managed object reference for vSphere). Callers MUST treat it as opaque.
+    """
+
+    identifier: str
+    name: str | None = None
+
+
+class VmBackend(Protocol):
+    """Hypervisor-agnostic VM operations.
+
+    All methods raise :class:`~ci_orchestrator.backends.errors.BackendError`
+    on failure. Implementations are free to add backend-specific kwargs but
+    MUST honour the documented signature for the listed parameters.
+    """
+
+    def clone_linked(
+        self,
+        template: str,
+        snapshot: str,
+        name: str,
+        destination: str | None = None,
+    ) -> VmHandle:
+        """Create a linked clone of ``template`` at snapshot ``snapshot``."""
+        ...
+
+    def start(self, handle: VmHandle, headless: bool = True) -> None:
+        """Power on the VM."""
+        ...
+
+    def stop(self, handle: VmHandle, hard: bool = False) -> None:
+        """Power off the VM. ``hard=True`` requests a forced power-off."""
+        ...
+
+    def delete(self, handle: VmHandle) -> None:
+        """Remove the VM from inventory and delete its files."""
+        ...
+
+    def get_ip(self, handle: VmHandle, timeout: float = 0.0) -> str | None:
+        """Return the guest's primary IP, or ``None`` if not yet known."""
+        ...
+
+    def list_snapshots(self, handle: VmHandle) -> list[str]:
+        """Return snapshot names defined on ``handle``."""
+        ...
+
+    def is_running(self, handle: VmHandle) -> bool:
+        """Return ``True`` if the VM appears in the running-VM list.
+
+        Implementations MUST NOT rely on guest tools (e.g. ``vmrun
+        getGuestIPAddress``) for this check — see ``AGENTS.md`` error #10.
+        """
+        ...