commands: bump to 3f98090 (log-name kebab-case in analysis skills)

workflow_dispatch-only, mirroring the agent release contract: validate
the runner script (PS parse + ASCII-only, it runs as SYSTEM on every
enrolling device), wix 5 build, upload versioned + stable blob names to
the agent container (no-cache, no legacy mirror - the MSI channel never
existed there), HEAD-verify the public alias serves the fresh bytes,
Sigstore provenance attestation. MSI version stays source-controlled in
Package.wxs - bumped to 1.0.2 (runner: encoding fix + bootstrap-msi.log
rename). Customer download:
https://download.autopilotmonitor.com/agent/AutopilotMonitor-Bootstrap.msi

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.github/workflows/build-agent.yml

@@ -194,8 +194,8 @@ jobs:
           # Dev variant = literal-string substitution of the two URL/manifest defaults.
           # Both are uploaded only on -PublishAsStable runs (versioned namespace doesn't carry bootstrap).
           if ('${{ inputs.publish_as_stable }}' -eq 'true') {
-            $stableUrl = '$AgentDownloadUrl = "https://autopilotmonitor.blob.core.windows.net/agent/AutopilotMonitor-Agent.zip"'
-            $devUrl    = '$AgentDownloadUrl = "https://autopilotmonitor.blob.core.windows.net/agent/AutopilotMonitor-Agent-dev.zip"'
+            $stableUrl = '$AgentDownloadUrl = "https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip"'
+            $devUrl    = '$AgentDownloadUrl = "https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent-dev.zip"'
             $stableMan = '$VersionJsonName = "version.json"'
             $devMan    = '$VersionJsonName = "version-dev.json"'
 
@@ -270,6 +270,12 @@ jobs:
             if (Test-Path "scripts/Bootstrap/Test-ShouldBootstrapAgent.ps1") {
               Send-Blob -Local "scripts/Bootstrap/Test-ShouldBootstrapAgent.ps1" -BlobName "Test-ShouldBootstrapAgent.ps1" -ContentType "text/plain; charset=utf-8"
             }
+
+            # Customer-side Graph add-on grant script -- docs and admin UI link
+            # https://download.autopilotmonitor.com/agent/Grant-AutopilotMonitorAddOn.ps1
+            if (Test-Path "scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1") {
+              Send-Blob -Local "scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1" -BlobName "Grant-AutopilotMonitorAddOn.ps1" -ContentType "text/plain; charset=utf-8"
+            }
           }
 
           # Update AdminConfiguration LatestAgentV2* -- ONLY on stable cutover. The hash-oracle

.github/workflows/build-msi.yml

@@ -0,0 +1,134 @@
+name: Build & Publish Bootstrap MSI
+
+# Thin MDM LOB delivery vehicle for WDP (Autopilot v2) — see
+# src/Agent/AutopilotMonitor.BootstrapMsi/Package.wxs. The MSI carries no bootstrap
+# logic (only the runner script that downloads the CURRENT server-hosted
+# Install-AutopilotMonitor.ps1), so it is rebuilt rarely: only when the runner script
+# or the WiX package changes. Version lives in Package.wxs — bump it there before
+# dispatching so Intune LOB update detection sees a new ProductVersion.
+
+on:
+  workflow_dispatch:
+    inputs:
+      upload_blob:
+        description: 'Upload to blob (customer-facing via download.autopilotmonitor.com/agent/)'
+        required: true
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+  id-token: write      # keyless Sigstore signing (artifact attestation)
+  attestations: write  # store the provenance attestation
+
+env:
+  MSI_PROJECT_DIR: src/Agent/AutopilotMonitor.BootstrapMsi
+  RUNNER_SCRIPT: src/Agent/AutopilotMonitor.BootstrapMsi/Invoke-BootstrapDownload.ps1
+  STABLE_MSI: AutopilotMonitor-Bootstrap.msi
+
+jobs:
+  build:
+    runs-on: windows-latest
+    name: Build Bootstrap MSI
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      # The runner executes as SYSTEM on every enrolling device — a parse error or
+      # non-ASCII mojibake (PS 5.1 codepage roulette) must fail the build, not the fleet.
+      - name: Validate runner script (parse + ASCII-only)
+        shell: pwsh
+        run: |
+          $errs = $null
+          [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $env:RUNNER_SCRIPT), [ref]$null, [ref]$errs) | Out-Null
+          if ($errs) { $errs | ForEach-Object { Write-Error $_.ToString() }; exit 1 }
+          if ((Get-Content $env:RUNNER_SCRIPT -Raw) -match '[^\x00-\x7F]') {
+            Write-Error "Runner script contains non-ASCII characters"
+            exit 1
+          }
+          Write-Host "Runner script parse + ASCII check passed"
+
+      - name: Read MSI version from Package.wxs
+        id: version
+        shell: pwsh
+        run: |
+          $wxs = Get-Content "$env:MSI_PROJECT_DIR/Package.wxs" -Raw
+          if ($wxs -notmatch 'Version="(\d+\.\d+\.\d+)"') {
+            Write-Error "Could not parse Version from Package.wxs"
+            exit 1
+          }
+          $version = $Matches[1]
+          Write-Host "MSI version (from Package.wxs): $version"
+          "version=$version" >> $env:GITHUB_OUTPUT
+
+      - name: Install WiX toolset
+        run: dotnet tool install --global wix --version "5.*"
+
+      - name: Build MSI
+        shell: pwsh
+        run: |
+          wix build "$env:MSI_PROJECT_DIR/Package.wxs" -arch x64 -o $env:STABLE_MSI
+          if (-not (Test-Path $env:STABLE_MSI)) { Write-Error "wix build produced no MSI"; exit 1 }
+          $sha256 = (Get-FileHash $env:STABLE_MSI -Algorithm SHA256).Hash.ToLowerInvariant()
+          Write-Host "Built $env:STABLE_MSI ($([math]::Round((Get-Item $env:STABLE_MSI).Length / 1KB)) KB)"
+          Write-Host "SHA-256: $sha256"
+
+      - name: Upload to Azure Blob Storage
+        if: inputs.upload_blob
+        shell: pwsh
+        run: |
+          $containerUrl = "https://autopilotmonitoreu.blob.core.windows.net/agent"
+          $sasToken = "${{ secrets.AZURE_BLOB_AGENT_SAS_TOKEN }}".TrimStart('?')
+          $version = "${{ steps.version.outputs.version }}"
+
+          # Same Send-Blob contract as build-agent.yml: no-cache on every blob because the
+          # stable name rotates in place behind the download alias. No legacy mirror — the
+          # MSI channel never existed on the legacy account.
+          function Send-Blob {
+            param([string]$Local, [string]$BlobName)
+            $bytes = [System.IO.File]::ReadAllBytes($Local)
+            $headers = @{
+              "x-ms-blob-type" = "BlockBlob"
+              "Content-Type" = "application/octet-stream"
+              "x-ms-blob-cache-control" = "no-cache"
+            }
+            $md5 = [System.Security.Cryptography.MD5]::Create()
+            $headers["Content-MD5"] = [Convert]::ToBase64String($md5.ComputeHash($bytes))
+            $md5.Dispose()
+            Write-Host "Uploading $BlobName ($([math]::Round($bytes.Length / 1KB)) KB)..."
+            Invoke-RestMethod -Uri "$containerUrl/$BlobName`?$sasToken" -Method Put -Headers $headers -Body $bytes
+            Write-Host "  uploaded $BlobName"
+          }
+
+          # Versioned copy for provenance/rollback + stable customer-facing name.
+          Send-Blob -Local $env:STABLE_MSI -BlobName "AutopilotMonitor-Bootstrap-v$version.msi"
+          Send-Blob -Local $env:STABLE_MSI -BlobName $env:STABLE_MSI
+
+      # E2E: the Front Door route /agent/* must serve the fresh bytes on the public alias.
+      - name: Verify download alias serves the MSI
+        if: inputs.upload_blob
+        shell: pwsh
+        run: |
+          $localSize = (Get-Item $env:STABLE_MSI).Length
+          $resp = Invoke-WebRequest -Uri "https://download.autopilotmonitor.com/agent/$env:STABLE_MSI" -Method Head -UseBasicParsing
+          if ($resp.StatusCode -ne 200) { Write-Error "Alias HEAD returned $($resp.StatusCode)"; exit 1 }
+          $remoteSize = [long]$resp.Headers['Content-Length'][0]
+          if ($remoteSize -ne $localSize) {
+            Write-Error "Size mismatch: alias serves $remoteSize bytes, local MSI is $localSize bytes"
+            exit 1
+          }
+          Write-Host "Alias verified: https://download.autopilotmonitor.com/agent/$env:STABLE_MSI ($remoteSize bytes)"
+
+      # Sigstore keyless provenance, same as the agent ZIP. Verify:
+      # gh attestation verify AutopilotMonitor-Bootstrap.msi --repo okieselbach/AutopilotMonitor
+      - name: Attest build provenance (MSI)
+        uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: ${{ env.STABLE_MSI }}
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: AutopilotMonitor-Bootstrap-v${{ steps.version.outputs.version }}
+          path: ${{ env.STABLE_MSI }}

.github/workflows/ci.yml

@@ -63,15 +63,26 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: '20'
+          node-version: '22'
           cache: npm
           cache-dependency-path: src/Web/autopilot-monitor-web/package-lock.json
 
       - run: npm ci
 
+      # next-env.d.ts + .next type stubs are gitignored (Next-managed since
+      # v16); typegen generates them so tsc sees the same types as a build.
+      - name: Generate Next.js types
+        run: npx next typegen
+
       - name: Typecheck
         run: npx tsc --noEmit
 
+      # Errors fail outright, and so does ANY warning: the codebase is
+      # warning-clean and must stay that way — fix new findings, never
+      # raise the cap.
+      - name: Lint
+        run: npm run lint -- --max-warnings 0
+
       - name: Tests
         run: npm test
 
@@ -86,7 +97,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: '20'
+          node-version: '22'
           cache: npm
           cache-dependency-path: src/McpServer/autopilot-monitor-mcp/package-lock.json
 
@@ -95,8 +106,22 @@ jobs:
       - name: Typecheck
         run: npx tsc --noEmit
 
+      # The vector-search tests tokenize with the real all-MiniLM-L6-v2 model
+      # (~23 MB tokenizer + ONNX weights). transformers.js caches under
+      # node_modules by default, which npm ci recreates — so every CI run
+      # re-downloaded from huggingface.co and rate-limits (429) failed the job
+      # (run 31252869254). Persist the model across runs instead; HF_CACHE_DIR
+      # is honored by vector-search-provider.ts.
+      - name: Cache embedding model
+        uses: actions/cache@v6
+        with:
+          path: ${{ github.workspace }}/.hf-cache
+          key: hf-model-Xenova-all-MiniLM-L6-v2
+
       - name: Tests
         run: npm test
+        env:
+          HF_CACHE_DIR: ${{ github.workspace }}/.hf-cache
 
   guardrails-in-sync:
     name: Generated guardrails match rules/guardrails.json
@@ -106,7 +131,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Regenerate
         run: node rules/scripts/combine.js

.github/workflows/codeql.yml

@@ -57,7 +57,7 @@ jobs:
           dotnet-version: '10.0.x'
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@v4.37.3
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -68,6 +68,6 @@ jobs:
         run: dotnet build AutopilotMonitor.sln --configuration Release
 
       - name: Analyze
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@v4.37.3
         with:
           category: /language:${{ matrix.language }}

.github/workflows/combine-rules.yml

@@ -8,6 +8,7 @@ on:
       - 'rules/ime-log-patterns/**'
       - 'rules/schema/**'
       - 'rules/scripts/**'
+      - 'rules/guardrails.json'
   pull_request:
     paths:
       - 'rules/gather/**'
@@ -15,6 +16,7 @@ on:
       - 'rules/ime-log-patterns/**'
       - 'rules/schema/**'
       - 'rules/scripts/**'
+      - 'rules/guardrails.json'
 
 jobs:
   validate-and-combine:
@@ -26,7 +28,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install ajv-cli
         run: npm install -g ajv-cli ajv-formats
@@ -55,9 +57,11 @@ jobs:
       - name: Combine rules into dist/
         run: node rules/scripts/combine.js
 
-      - name: Commit dist/ changes
+      - name: Commit generated outputs
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
         uses: stefanzweifel/git-auto-commit-action@v7
         with:
-          commit_message: "chore: regenerate rules/dist from individual files"
-          file_pattern: "rules/dist/*"
+          commit_message: "chore: regenerate rules/dist + generated TS from individual files"
+          # combine.js writes THREE outputs; committing only dist/ would silently discard
+          # the two generated TS modules and leave the guardrails-in-sync CI check red.
+          file_pattern: "rules/dist/* src/Web/autopilot-monitor-web/utils/guardrails.generated.ts src/McpServer/autopilot-monitor-mcp/src/rule-authoring.generated.ts"

.github/workflows/deploy-web.yml

@@ -16,11 +16,20 @@ on:
       - 'src/Web/autopilot-monitor-web/**'
       - '.github/workflows/deploy-web.yml'
 
+env:
+  PORTAL_VERSION_URL: https://portal.autopilotmonitor.com/version.json
+  VERSIONS_CONTAINER: https://autopilotmonitoreu.blob.core.windows.net/versions
+
 jobs:
   build_and_deploy_job:
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.action != 'closed')
     runs-on: ubuntu-latest
     name: Build and Deploy Job
+    # Dependabot PRs run without repo secrets, so the deploy token is absent.
+    # Surface it as an env var so the deploy step can gate on it — secrets
+    # cannot be referenced directly in an `if:` expression.
+    env:
+      DEPLOY_TOKEN: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
     steps:
       - uses: actions/checkout@v7
         with:
@@ -28,35 +37,99 @@ jobs:
           fetch-depth: 0  # Full history needed for git-based sitemap lastmod dates
       - name: Build And Deploy
         id: builddeploy
+        # Skip (green) instead of failing when the token is missing (Dependabot
+        # PRs); real deploys on main and internal PRs still have it.
+        if: env.DEPLOY_TOKEN != ''
         uses: Azure/static-web-apps-deploy@v1
         env:
           NEXT_PUBLIC_ENTRA_CLIENT_ID: ${{ vars.NEXT_PUBLIC_ENTRA_CLIENT_ID }}
+          # Dual app-reg window: previous app registration (unset = single-app behaviour)
+          # and the default app for browsers without a stored selection (legacy|primary).
+          NEXT_PUBLIC_ENTRA_LEGACY_CLIENT_ID: ${{ vars.NEXT_PUBLIC_ENTRA_LEGACY_CLIENT_ID }}
+          NEXT_PUBLIC_ENTRA_DEFAULT_APP: ${{ vars.NEXT_PUBLIC_ENTRA_DEFAULT_APP }}
           NEXT_PUBLIC_ENTRA_REDIRECT_URI: ${{ vars.NEXT_PUBLIC_ENTRA_REDIRECT_URI }}
           NEXT_PUBLIC_ENTRA_POST_LOGOUT_REDIRECT_URI: ${{ vars.NEXT_PUBLIC_ENTRA_POST_LOGOUT_REDIRECT_URI }}
           NEXT_PUBLIC_API_BASE_URL: ${{ vars.NEXT_PUBLIC_API_BASE_URL }}
           NEXT_PUBLIC_PLATFORM_STATS_MANIFEST_URL: ${{ vars.NEXT_PUBLIC_PLATFORM_STATS_MANIFEST_URL }}
           NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING: ${{ secrets.NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING }}
+          # Build stamp for public/version.json (scripts/generate-version.js in prebuild);
+          # the verify step below polls the deployed file for exactly this commit.
+          GITHUB_SHA: ${{ github.sha }}
         with:
           azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
           repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
-          # Dependabot PRs run without repo secrets, so the deploy token is absent.
-          # Skip (green) instead of failing the check; real deploys on main still have the token.
-          skip_deploy_on_missing_secrets: true
           action: "upload"
           ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
           # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
           app_location: "src/Web/autopilot-monitor-web" # App source code path
           api_location: "" # Api source code path - optional
-          output_location: "" # Built app content directory - optional
+          # Static export (next.config output:'export'): Oryx runs `npm run build`
+          # and uploads the exported out/ directory as plain static files — no
+          # managed SSR runtime is provisioned anymore. (No is_static_export
+          # input on this action version; Oryx detects the export from
+          # next.config + output_location.)
+          output_location: "out" # Built app content directory - optional
           ###### End of Repository/Build Configurations ######
 
+      # The SWA action reporting success proves the upload, not that the production host
+      # serves the new build — verify against the live /version.json (Cache-Control:
+      # no-store via staticwebapp.config.json) before publishing the version manifest.
+      # PR builds deploy to per-PR preview environments, so only main deploys are verified.
+      - name: Verify deployed portal build is live
+        if: env.DEPLOY_TOKEN != '' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        shell: pwsh
+        run: |
+          $expectedCommit = '${{ github.sha }}'.Substring(0, 7)
+          $deadline = [DateTime]::UtcNow.AddMinutes(5)
+          $attempt = 0
+
+          while ([DateTime]::UtcNow -lt $deadline) {
+            $attempt++
+            try {
+              $v = Invoke-RestMethod -Uri '${{ env.PORTAL_VERSION_URL }}' -Method Get -TimeoutSec 30 -Headers @{ 'Cache-Control' = 'no-cache' }
+              if ($v.commit -eq $expectedCommit) {
+                Write-Host "Live after $attempt attempt(s): web @ $($v.commit), built $($v.buildUtc)"
+                exit 0
+              }
+              Write-Host "Attempt ${attempt}: serving $($v.commit) -- waiting for $expectedCommit"
+            } catch {
+              Write-Host "Attempt ${attempt}: /version.json not answering yet -- $($_.Exception.Message)"
+            }
+            Start-Sleep -Seconds 15
+          }
+
+          throw "Portal did not serve commit $expectedCommit within 5 minutes -- deployment not verified, version manifest NOT published"
+
+      # Cross-component deploy record, written last and only on a verified deploy —
+      # same contract as versions/backend.json and versions/mcp.json.
+      - name: Publish version manifest
+        if: env.DEPLOY_TOKEN != '' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        shell: pwsh
+        run: |
+          $manifest = [ordered]@{
+            component   = 'web'
+            commit      = '${{ github.sha }}'.Substring(0, 7)
+            deployedUtc = [DateTime]::UtcNow.ToString('o')
+            runId       = '${{ github.run_id }}'
+          } | ConvertTo-Json
+
+          $sas = '${{ secrets.AZURE_BLOB_VERSIONS_SAS_TOKEN }}'.TrimStart('?')
+          $url = "${{ env.VERSIONS_CONTAINER }}/web.json?$sas"
+          # no-cache: rotating pointer, must never be served stale by any fronting cache.
+          Invoke-RestMethod -Uri $url -Method Put -Headers @{ 'x-ms-blob-type' = 'BlockBlob'; 'x-ms-blob-cache-control' = 'no-cache' } -Body $manifest -ContentType 'application/json' | Out-Null
+          Write-Host "Published versions/web.json"
+          Write-Host $manifest
+
   close_pull_request_job:
     if: github.event_name == 'pull_request' && github.event.action == 'closed'
     runs-on: ubuntu-latest
     name: Close Pull Request Job
+    env:
+      DEPLOY_TOKEN: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
     steps:
       - name: Close Pull Request
         id: closepullrequest
+        if: env.DEPLOY_TOKEN != ''
         uses: Azure/static-web-apps-deploy@v1
         with:
           azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}

.github/workflows/pester.yml

@@ -0,0 +1,61 @@
+name: Pester (Bootstrap scripts)
+
+# Runs the Pester suite for the Intune bootstrap scripts under Windows PowerShell 5.1
+# (the runtime IME uses to execute platform scripts) so guard/relax logic changes are
+# verified without resetting a device. Like ci.yml it reports rather than blocks.
+
+on:
+  push:
+    branches: [main]
+    paths: ['scripts/Bootstrap/**']
+  pull_request:
+    branches: [main]
+    paths: ['scripts/Bootstrap/**']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pester-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pester:
+    name: Bootstrap guard tests (PS 5.1)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install Pester 5+
+        shell: powershell
+        run: |
+          Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force -Scope CurrentUser | Out-Null
+          Install-Module Pester -Scope CurrentUser -Force -SkipPublisherCheck -MinimumVersion 5.5.0
+
+      - name: Run Pester
+        shell: powershell
+        run: |
+          Import-Module Pester -MinimumVersion 5.5.0
+          $c = New-PesterConfiguration
+          $c.Run.Path = 'scripts/Bootstrap'
+          $c.Run.Exit = $true
+          $c.Output.Verbosity = 'Detailed'
+          Invoke-Pester -Configuration $c
+
+      - name: Guard scripts stay pure ASCII
+        shell: powershell
+        run: |
+          $failed = $false
+          Get-ChildItem 'scripts/Bootstrap' -Filter '*.ps1' | ForEach-Object {
+            $bytes = [System.IO.File]::ReadAllBytes($_.FullName)
+            for ($i = 0; $i -lt $bytes.Length; $i++) {
+              if ($bytes[$i] -gt 127) {
+                Write-Host "::error file=scripts/Bootstrap/$($_.Name)::Non-ASCII byte 0x$('{0:X2}' -f $bytes[$i]) at offset $i. PS 5.1 (IME) reads BOM-less files as ANSI and corrupts multi-byte chars."
+                $failed = $true
+                break
+              }
+            }
+          }
+          if ($failed) { exit 1 }
+          Write-Host 'All bootstrap scripts are pure ASCII.'

.gitignore

@@ -53,6 +53,9 @@ __azurite_db*__.json
 node_modules/
 .next/
 out/
+# Managed by Next.js since v16 (regenerated by next dev/build/typegen; path
+# inside flips between .next/types and .next/dev/types) — must not be tracked.
+next-env.d.ts
 build/
 dist/
 !rules/dist/
@@ -148,3 +151,16 @@ plans/REFACTOR_AGENT_V2.md
 scripts/Backup/setup-backup-container.ps1
 docs/Introduction-AutopilotMonitor.pptx
 docs/~$Introduction-AutopilotMonitor.pptx
+
+# Playwright MCP browser artifacts (snapshots, screenshots, console logs)
+.playwright-mcp/
+
+# Web build stamp: generated by scripts/generate-version.js on every build (buildUtc
+# changes each run) and served at /version.json from the static export.
+src/Web/autopilot-monitor-web/public/version.json
+
+
+# Local IME binaries scratch used by the /ime-decompile skill (MSI + msiexec-
+# extracted payload per version, for grepping in binaries). Decompilates live in
+# the private ime-decompiles repo, MSIs in the ime-archive blob - this stays local.
+ime-files/

.mcp.json

@@ -3,6 +3,10 @@
     "autopilot-monitor": {
       "type": "http",
       "url": "https://mcp.autopilotmonitor.com/mcp"
+    },
+    "playwright": {
+      "command": "cmd",
+      "args": ["/c", "npx", "@playwright/mcp@latest"]
     }
   }
 }

Directory.Build.props

@@ -0,0 +1,12 @@
+<Project>
+  <!-- Warning freeze (2026-08-13, backlog cleared to zero): every .NET build in this repo
+       must stay warning-free. Compiler, MSBuild and NuGet restore warnings are all fatal.
+       Exception: NuGet audit advisories (NU1901-NU1904) stay warnings — a CVE published
+       against an already-referenced package must not block an unrelated hotfix deploy;
+       advisories are handled by bumping the package, not by failing the build. -->
+  <PropertyGroup>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <MSBuildTreatWarningsAsErrors>true</MSBuildTreatWarningsAsErrors>
+    <WarningsNotAsErrors>NU1901;NU1902;NU1903;NU1904</WarningsNotAsErrors>
+  </PropertyGroup>
+</Project>

README.md

@@ -1,14 +1,14 @@
 # <img src="docs/images/logo.svg" height="28" alt="" /> AutopilotMonitor
 
-[![Status](https://img.shields.io/badge/status-Private%20Preview-orange)](https://www.autopilotmonitor.com)
+[![Status](https://img.shields.io/badge/status-live-brightgreen)](https://www.autopilotmonitor.com)
 [![License](https://img.shields.io/badge/license-MIT%20%2B%20AGPL--3.0-blue)](LICENSE)
 [![Website](https://img.shields.io/badge/website-autopilotmonitor.com-2ea44f)](https://www.autopilotmonitor.com)
 
 Advanced monitoring and troubleshooting solution for Windows Autopilot deployments. Gain full visibility into every enrollment session with a detailed event timeline, fleet health dashboards, and session reporting. Define custom analysis rules to automatically detect issues and gather rules to collect targeted evidence. Retrieve diagnostics packages on demand, configure agent settings like auto-reboot behavior and automatic timezone adjustment — all managed centrally from the web dashboard.
 
-## Private Preview
+## Availability
 
-Autopilot Monitor is currently running as a **Private Preview**. Visit **[autopilotmonitor.com](https://www.autopilotmonitor.com)** to request access and learn more.
+Autopilot Monitor is **publicly available** — the Community plan is free. Sign in with your work account at **[autopilotmonitor.com](https://www.autopilotmonitor.com)**; new organizations complete a short activation step after first sign-in.
 
 <p align="center">
   <img src="docs/images/SessionList.png" width="45%" />

docs/agent/autopilot-ztd-diagnostics.md

@@ -21,6 +21,14 @@ three of them to turn the `autopilot_profile_missing` warning from a guess into
 evidence-backed verdict, and the backend rule engine uses the error-code map for
 known-issue enrichment.
 
+Windows 365 Cloud PC exception: on Cloud PCs (`CloudPcDetector.DetectIsCloudPc()`)
+`ProfileAvailable=0` is the expected state — Cloud PCs are provisioned by the Windows 365
+service, not by Autopilot. The event is still emitted with the full evidence payload plus
+an `isCloudPc` marker, but as severity Info with a "this is expected" message instead of
+a Warning (`DeviceInfoCollector.ResolveAutopilotProfileMissingPresentation`). The portal's
+Autopilot Profile card mirrors this: a neutral note for Cloud PC sessions
+(`session.isCloudPc` or the event marker), the amber warning otherwise.
+
 Consumers in this repo:
 
 * `ZtdEvidence.cs` (agent) — one-shot event-log query + `Diagnostics\Autopilot` registry
@@ -119,6 +127,19 @@ normal IME deployment flow. Spam containment, in order:
    payload; the event's own timestamp is the emission time, so the session's `StartedAt`
    (which the backend aligns to the earliest event) is not dragged backwards.
 
+Presentation (2026-07-28, customer feedback — an unannounced wall of pre-agent Error
+events read like a live failure):
+
+- The scan buffers the (capped) record set, first emits an **Info summary event**
+  (`modern_deployment_log`, payload `backfillSummary: true` + `replayedCount` /
+  `droppedOverCap` / `lookbackMinutes`) announcing the replay block, then replays the
+  records **oldest-first** so the timeline sequence follows event-log chronology.
+- The web timeline (`EventTimeline.tsx`) badges `backfilled: true` events („⟲ Backfilled",
+  slate, explanatory tooltip) and renders the original `timeCreated` as the row time with a
+  "(reported …)" suffix; the expanded metadata block gains a `Recorded` line. Severity is
+  deliberately **not** downgraded — unresolved pre-agent errors must still surface in the
+  Error filter.
+
 # Schema — Error codes (backend known-issue map)
 
 Codes documented in the known-issues / troubleshooting-FAQ pages that appear in ESP/enrollment

docs/agent/continue-anyway-observation.md

@@ -0,0 +1,114 @@
+---
+type: Concept
+title: Continue-Anyway Observation Mode — Device-Phase ESP Failure Defang
+description: Operator-set tenant opt-in that turns an immediate Device-phase ESP terminal failure on a Continue-Anyway-enabled profile into a bounded 60-minute observation; the DAD-validated real-user desktop plus the Hello gate detect the true end, and the session completes as Succeeded with an esp-soft-failure marker.
+resource: /src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Edge.cs
+tags:
+  - agent
+  - decision-engine
+  - esp
+  - continue-anyway
+  - soft-failure
+  - tenant-config
+timestamp: 2026-08-08T00:00:00+02:00
+---
+
+# Continue-Anyway Observation Mode
+
+## Problem
+
+A Classic user-driven enrollment whose Device ESP hits the configured terminal timeout
+(`syncFailureTimeoutMinutes`, typically 30) fails **before AccountSetup is ever entered**.
+The classic advisory defang (`HandleEspTerminalFailureV1`) requires
+`AccountSetupEnteredUtc != null`, so these sessions hard-fail immediately — even when the
+ESP profile allows "Continue anyway" and users demonstrably dismiss the failure screen and
+reach a working desktop. A fleet held at the timeout wall by one slow blocking app then
+shows ~100% Failed (tenant c9787ba2: 948/1000 `esp_terminal_failure`, culprit "Encompass
+Hybrid Installer"), which tells the tenant nothing.
+
+## Mechanism
+
+Opt-in flow (default off — absence keeps the immediate hard fail):
+
+1. **Tenant setting** `EnableEspContinueAnywayObservation` (`TenantConfiguration`,
+   operator-set only, NOT exposed in the tenant admin settings UI; the toggle lives in
+   the Global-Admin tenant management modal next to Bootstrap Token / Unrestricted Mode,
+   and the field is GA-gated on both write paths — the generic PUT silently reverts it
+   for tenant admins, the field patch rejects it with 400) → served via `agent/config`
+   (`AgentConfigResponse`, ConfigVersion 37).
+2. **Agent** stamps `espContinueAnywayObservationEnabled=true` into the
+   `EspConfigDetected` signal payload (both emitters: the orchestrator FirstSync
+   bootstrap and `DeviceInfoCollector.PostEspConfigDetectedSignal`) — only when enabled,
+   so the kernel stays config-free and replay/recovery reconstruct the fact from the
+   signal log.
+3. **Engine** (`HandleEspTerminalFailureV1`): a terminal ESP failure is defanged into an
+   `esp_failure_advisory` (`advisoryReason=esp_failure_defanged_continueanyway_observation`)
+   when ALL hold: profile allows Continue-Anyway, observation opt-in observed,
+   `AccountSetupEnteredUtc == null`, and the scenario is Classic/Unknown with
+   `PreProvisioningSide=None` and no registry self-deploying marker (WhiteGlove /
+   SelfDeploying / DevicePreparation have no interactive user to press the button).
+4. **Observation window**: the shared `AdvisoryCompletion` deadline is armed with a
+   **60-minute** window (classic advisory: 30) — long enough for failure screen →
+   Continue anyway → sign-in → desktop, or a full device-phase re-run via "Try again".
+
+## Detecting the real end
+
+The active-advisory-without-AccountSetup shape is unique to this arming site, so
+`IsContinueAnywayObservationActive(state)` (advisory recorded ∧ not resolved ∧
+AccountSetup never entered) needs no separate opt-in re-check. Three outcomes:
+
+* **Continue anyway** — the DAD-validated real-user desktop arrives (defaultuser0/SYSTEM
+  excluded at the detector) and the Hello gate is satisfied (resolved, or policy
+  explicitly disabled without an observed wizard): `HandleDesktopArrivedV1` completes
+  eagerly through Finalizing (trigger `DesktopArrived:ContinueAnywayObservation`) — the
+  session end reflects the real end, not the window edge. The IME user-session gate is
+  deliberately waived: it anchors on `AccountSetupEnteredUtc`, which is structurally
+  absent here. The terminal `enrollment_complete` carries `espSoftFailure=true`,
+  `completionSource=continue_anyway_observation` and the failed category; the backend
+  stamps `EspSoftFailure`/`CompletionSource` on the Sessions row (+ SessionsIndex
+  mirror) and the web renders the amber "with issues" badge plus a detail banner.
+  Sessions completing under the CLASSIC advisory (AccountSetup entered) carry the same
+  marker with `completionSource=continue_anyway_post_accountsetup`.
+* **Try again** — the ESP re-runs the failed category; `DeviceSetupProvisioningComplete`
+  resolves the advisory via the 4910a5a5 recovery hook (`esp_failure_advisory_resolved`)
+  and the session continues on the normal rails, completing clean (no marker).
+* **Nothing** — the window expires: un-defang to `enrollment_failed` with the original
+  `esp_terminal_failure` reason and
+  `advisoryReason=continue_anyway_observation_window_expired_without_completion_evidence`;
+  `LastFailureTrigger=EspTerminalFailure` keeps the likely-stuck app promotion on. Every
+  observed session therefore still gets a terminal verdict ≤ ~60 min after the failure.
+
+Deadline-fire edge cases mirror the classic paths: desktop + unknown Hello promotes to
+`AwaitingHello` with the HelloSafety window (never-observed promote), and enforcement
+progress since arming re-arms the window (30-min re-arm, convergent) instead of failing a
+device mid-"Try again".
+
+## Status semantics
+
+No new terminal status: the session is `Succeeded` + `EspSoftFailure=true` (user
+decision 2026-08-08). Success-rate conventions stay untouched; honesty lives in the
+badge, the detail banner, and ANALYZE-ESP-004 (which continues to fire on the un-defang
+expiry path via `mayHaveContinuedAnyway`).
+
+# Examples
+
+Session `53d1e9f6-4eef-4f3b-a999-c63e96c5148d` (tenant c9787ba2, 2026-08-07) is the
+motivating shape: DeviceSetup/Certificates failed at the 30-min wall while "Encompass
+Hybrid Installer" was still installing, AccountSetup 0/5, Continue-Anyway allowed —
+hard-failed under the default semantics.
+
+Tests: `ContinueAnywayObservationTests` (DecisionCore.Tests) — defang, 60-min arming,
+opt-out/scenario regressions, eager desktop completion with marker, clean-completion
+marker absence, expiry un-defang, hello promotes, category recovery.
+
+# Citations
+
+* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Edge.cs` — arming site,
+  observation branches in `HandleAdvisoryCompletionDeadlineFired`,
+  `IsContinueAnywayObservationActive`.
+* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Classic.cs` —
+  `HandleDesktopArrivedV1` observation completion, `BuildEnrollmentCompleteEffect`
+  soft-failure marker.
+* `src/Backend/AutopilotMonitor.Functions/Services/EventIngestProcessor.Classification.cs`
+  / `TableStorageService.Sessions.cs` — session stamping + index mirror.
+* `src/Web/autopilot-monitor-web/components/SessionStatusBadge.tsx` — amber badge.

docs/agent/esp-policy-provider-stall.md

@@ -0,0 +1,151 @@
+---
+type: Concept
+title: ESP Policy-Provider Stall Detection — the no-timeout Setup/Apps wait and the co-management Sidecar gap
+description: Why the ESP's Apps wait is keyed to the Intune-registered "Sidecar" provider by name — a foreign provider (ConfigMgr) with TrackingPoliciesCreated=1 does not satisfy it — plus the classic never-completes stall, and how the always-on two-arm esp_policy_provider_stalled tripwire (reason=provider_incomplete | sidecar_provider_missing, 15-min wall-clock dwell, StartupEventGate cross-restart dedup) surfaces both.
+resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/EspPolicyProviderProbe.cs
+tags:
+  - agent
+  - esp
+  - enrollment-status-tracking
+  - co-management
+  - stall-detection
+timestamp: 2026-07-24T00:00:00+02:00
+---
+
+# ESP Policy-Provider Stall Detection
+
+## Schema
+
+The Enrollment Status Page decides when its "Apps" category may progress from
+"Identifying" using the **EnrollmentStatusTracking CSP**
+(<https://learn.microsoft.com/en-us/windows/client-management/mdm/enrollmentstatustracking-csp>),
+mirrored in the registry under
+`HKLM\SOFTWARE\Microsoft\Windows\Autopilot\EnrollmentStatusTracking\{Device|<UserSID>}\…`.
+Two contracts matter:
+
+1. **`Setup/Apps/PolicyProviders/<Name>`** — per the CSP doc: *"Existence of this node
+   indicates to the ESP that it shouldn't show the tracking status message until the
+   TrackingPoliciesCreated node has been set to true."* This wait has **no timeout**. A
+   registered provider that never sets `TrackingPoliciesCreated=1` parks the ESP at
+   "Apps (Identifying)" indefinitely — observed for days in the field. Exists in device
+   scope (`Device`) and user scope (`S-<SID>`, appears at sign-in).
+2. **`DevicePreparation/PolicyProviders/<Name>/InstallationState`** — must reach 2
+   (NotRequired) or 3 (Completed); 1=NotInstalled, 4=Error. Device scope only. The ESP
+   applies a default 15-minute timeout here, so these stalls self-surface as ESP errors —
+   the detector still records them for the diagnostic trail.
+
+Known provider names: **`Sidecar` is the Intune Management Extension** (the CSP doc names
+"Intune's agents, such as SideCar"); **`ConfigMgr`** is the Configuration Manager client,
+registered during Autopilot-into-co-management — the troubleshooting section of
+<https://learn.microsoft.com/en-us/intune/configmgr/comanage/autopilot-enrollment> queries
+exactly these registry paths. The same document states that ESP policy providers **are not
+aware of each other** and that **pre-provisioning is unsupported** with Autopilot into
+co-management.
+
+## The field case (issue #106)
+
+A tenant pre-provisions devices and installs the ConfigMgr client as a blocking app.
+Occasionally the user-phase ESP reaches "Apps (Identifying)" and never leaves it — for
+hours to days. On those devices `Device\Setup\Apps\PolicyProviders` contains **only a
+`ConfigMgr` key (no `Sidecar`)** — and, per the customer's follow-up, **`TrackingPoliciesCreated=1`
+IS set under it**. The provider is "complete" by the CSP value contract, yet the ESP
+still waits. Manually renaming the key to `Sidecar` — which creates no tracking entries,
+only satisfies the name — unblocks the ESP instantly.
+
+The naive CSP-doc reading ("any provider with TrackingPoliciesCreated=1 satisfies the
+wait") is therefore wrong for this case. What the evidence supports instead: provider
+nodes are registered **by the Intune service at enrollment**, and its ESP-policy WAP
+payload always registers `Sidecar` (ConfigMgr joins only via a co-management settings
+policy — see the payload documented by Niehaus). The ESP waits on the provider it
+expects **by name**; a foreign provider occupying the slot does not satisfy it,
+regardless of its completion values. On the affected devices the CM client (installed
+as a plain Win32 app, no co-management settings policy) evidently displaced the
+Sidecar node — consistent with Microsoft's warning that providers "aren't currently
+aware of others" and that pre-provisioning is unsupported with co-management. The exact
+CloudExperienceHost mechanism is not publicly documented; the registry signature —
+setupApps providers present, `Sidecar` absent — is deterministic either way.
+
+## Detection
+
+`EspPolicyProviderProbe` (fail-soft, static, `ScopedOverride` test seam — structural clone
+of `EspTrackingInfoProbe`) enumerates all providers in both kinds and scopes.
+`EspPolicyProviderStallDetector` evaluates a pure transition function on a 60-second tick
+from the always-on `EspPolicyProviderStallHost` — **two arms**, same 15-minute wall-clock
+dwell, one shared event type discriminated by `reason`:
+
+* **Arm 1, `reason=provider_incomplete`** — a provider **continuously incomplete for
+  ≥ 15 minutes**. The dwell clock starts at first incomplete observation and resets on
+  completion or disappearance. Missing values parse as incomplete
+  (fail-toward-observation). Catches e.g. Sidecar itself never reporting.
+* **Arm 2, `reason=sidecar_provider_missing`** — **≥ 1 `Setup\Apps` provider registered
+  but none named `Sidecar`**, continuously for ≥ 15 minutes. Deliberately ignores
+  provider completeness (the field case had `TrackingPoliciesCreated=1`). Sidecar
+  registering later — the legitimate startup ordering — clears the condition and resets
+  the clock. DevicePreparation-only snapshots don't activate it.
+* When both arms cross in the same round, ONE event is emitted and
+  `sidecar_provider_missing` wins as `reason` (it explains the hang regardless of the
+  foreign provider's state).
+* Missing root key / empty provider list = normal early enrollment: clears all dwell
+  state (both arms), never fires.
+* One `esp_policy_provider_stalled` **Warning** per newly stalled condition set
+  (`ImmediateUpload`), one-shot per condition in-process, cross-restart deduped via a
+  `StartupEventGate` fingerprint over the sorted currently-active fired conditions
+  (provider keys + a `sidecarMissing` sentinel) — a restart into the same stall stays
+  silent, a new condition joining re-reports.
+* Payload: `reason`, `providers[]` (full table: name, scope, kind, raw values, complete
+  flag), `stalledProviders[]` with `stalledForMinutes`, `sidecarMissingForMinutes`
+  (arm 2 only), `sidecarRegistered`, `dwellMinutes`.
+* **Purely observational**: emitted via `InformationalEventPost` (dispatch-guard exempt
+  pass-through) — never touches decision state. No config toggle, no ConfigVersion bump
+  (precedent: `disk_space_low`).
+
+Deliberately **not** built on `StallProbeCollector` (its idle clock resets on any session
+activity — a provider stall coexists with a chatty session) and not on the periodic
+collectors (idle-stopped after 15 minutes — exactly the dormant window the dwell must
+observe).
+
+## Guardrail companion
+
+`rules/guardrails.json` allow-lists `SOFTWARE\Microsoft\Windows\Autopilot` (category
+"Autopilot / OOBE / Setup") so tenants can build their own gather rules on the subtree —
+e.g. a `not_exists` registry rule on the `Sidecar` provider key. The subtree carries
+deployment state only (provider registrations, tracking lists, app IDs, per-user SIDs);
+sensitivity is at or below existing entries. Enforcement is agent-side (embedded
+resource), so both the detector and the guardrail change ship with the agent release.
+
+## Examples
+
+Customer-case event (abbreviated) — note the provider is "complete" by CSP values, the
+hang is carried entirely by `reason=sidecar_provider_missing`:
+
+```json
+{
+  "eventType": "esp_policy_provider_stalled",
+  "severity": "Warning",
+  "data": {
+    "reason": "sidecar_provider_missing",
+    "dwellMinutes": 15,
+    "sidecarRegistered": false,
+    "sidecarMissingForMinutes": 15.0,
+    "providers": [
+      { "name": "ConfigMgr", "scope": "device", "kind": "setupApps",
+        "trackingPoliciesCreated": 1, "installationState": null, "complete": true }
+    ],
+    "stalledProviders": []
+  }
+}
+```
+
+`reason=sidecar_provider_missing` is the co-management signature;
+`reason=provider_incomplete` with `sidecarRegistered=true` covers a stalled Sidecar or
+third-party provider — the generalized contract violation.
+
+# Citations
+
+* EnrollmentStatusTracking CSP — <https://learn.microsoft.com/en-us/windows/client-management/mdm/enrollmentstatustracking-csp>
+* Windows Autopilot into co-management (requirements, provider-conflict warning, troubleshooting registry paths) — <https://learn.microsoft.com/en-us/intune/configmgr/comanage/autopilot-enrollment>
+* Troubleshoot the ESP (models app tracking exclusively via the `Sidecar` subkey) — <https://learn.microsoft.com/en-us/troubleshoot/mem/intune/device-enrollment/understand-troubleshoot-esp>
+* Niehaus: the Intune ESP-policy WAP payload registering the provider nodes (`Sidecar` always, `ConfigMgr` only with a co-management settings policy) — <https://oofhours.com/2023/08/25/run-an-sccm-task-sequence-during-autopilot/>
+* Niehaus: ESP tracks arbitrarily named providers when they are properly registered — <https://oofhours.com/2023/09/18/track-anything-using-esp/>
+* Agent code: `EspPolicyProviderProbe.cs`, `EspPolicyProviderStallDetector.cs`, `EspPolicyProviderStallHost.cs` (SystemSignals / Orchestration.Hosts)
+* Related: [MDM Reboot Coalescing](mdm-reboot-coalescing.md), [Gather-Rule Guardrails](../rules/gather-rule-guardrails.md)

docs/agent/gather-rule-debug-log.md

@@ -0,0 +1,126 @@
+---
+type: Concept
+title: Gather Rule Debug Log — the per-tenant evaluation trace for rules that produce nothing
+description: EnableGatherRuleDebugLog (ConfigVersion 36) makes the agent write a local trace file explaining every gather-rule evaluation decision — scope skips, missing intervalSeconds, on_change suppression, empty collector results, logparser position/parse-mode/no-match outcomes — so customers can self-diagnose rules that never show up in the timeline.
+resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleDebugLog.cs
+tags:
+  - agent
+  - gather-rules
+  - diagnostics
+  - tenant-configuration
+timestamp: 2026-07-28T00:00:00+02:00
+---
+
+# Gather Rule Debug Log
+
+## Schema
+
+### The problem
+
+A gather rule that produces no timeline events is indistinguishable from a rule that
+never ran. The pipeline has many *silent-nothing* exits — before this feature, none of
+them were visible to the customer:
+
+| # | Decision point | Where |
+|---|---|---|
+| 1 | Rule delivered but `Enabled=false` | `GatherRuleExecutor.UpdateRules` |
+| 2 | `trigger=interval` without `intervalSeconds` — never runs | `UpdateRules` timer filter |
+| 3 | Interval timer's first tick comes only after one **full** interval | `UpdateRules` timer creation |
+| 4 | Out of phase scope (`activePhases` / `activeFromPhase` not latched); incl. `currentPhase=Unknown` before the first phase signal | `IsRuleInScopeLocked` |
+| 5 | phase_change / phase_exit dedup — once per (rule, phase) | `OnPhaseChanged` |
+| 6 | Collector returned an **empty** result (e.g. `emitOnlyIfExists=true` and target absent) | `ExecuteRule` |
+| 7 | `emit_mode=on_change` — result hash unchanged, emit suppressed | `ShouldEmitOnChange` |
+| 8 | Guard blocked the target (emits `security_warning`, but the rule yields no data) | `GatherRuleContext.EmitSecurityWarning` |
+| 9 | logparser: no files matched, position tracker says nothing new, regex no-match, plain-text file parsed in default `cmtrace` mode, `maxLines` cap, wildcard capped at 20 files | `LogParserCollector` |
+| 10 | Rule execution threw (agent log had only the message, no stack) | `ExecuteRule` catch |
+
+### The setting
+
+`TenantConfiguration.EnableGatherRuleDebugLog` (`bool?`, default null→false), served to the
+agent as `AgentConfigResponse.EnableGatherRuleDebugLog` — **ConfigVersion 36**. Portal:
+Settings → Agent → Settings, toggle "Gather Rule Debug Log", stored via the usual
+tenant-config roundtrip (`TableConfigRepository` Store+Map). Also shown in the admin
+tenant-config report.
+
+`RemoteConfigMerger` projects the bool onto a runtime path (same pattern as
+`EnableImeMatchLog`): `true` → `Constants.GatherRuleDebugLogPath` =
+`%ProgramData%\AutopilotMonitor\Logs\gather-rules-debug.log`; `false` → null, unless a
+`--gather-debug-log <path>` CLI override supplied a non-default path. The field is not
+security-sensitive and deliberately **survives the offline config cache**.
+
+### The trace file
+
+`GatherRuleDebugLog` is an append-only writer held by `GatherRuleExecutor` and exposed
+to collectors via `GatherRuleContext.DebugLog(ruleId, stage, message)` (null-safe no-op
+when disabled — zero cost on the normal path). Line format:
+
+```
+2026-07-28T09:15:02.123Z | RULE-ID | stage | message
+```
+
+Stages: `config` (registration summary per rule, header, zero-rules note), `phase`
+(enrollment-phase transition marker `phase change: Old -> New`, ruleId `-` — every
+rule-level line below it reads against the new phase), `trigger` (timer scheduled,
+phase/event fired, dedup), `scope` (skips with reason incl. current phase), `exec`
+(execution start), `collector` (null/empty results with likely cause), `guard`
+(allowlist block), `emit` (event emitted, hash change), `suppress` (on_change
+suppression with hash prefix + streak), `logparser` (per-file outcome: lines read,
+position range, match count, parse failures, regex timeouts, mode; plus the
+`format=text` hint when every line fails CMTrace parsing; plus one line **per regex
+match** — line number, matched text, capture groups — capped at 10 per file per run),
+`error` (full exception **with stack trace** — the agent log keeps only the message;
+an invalid logparser regex is reported here including the offending pattern string).
+
+Volume control: 10 MB cap with a single `.old` rotation generation (~20 MB worst case).
+Every write failure is swallowed — tracing must never break gathering. The trace never
+leaves the device on its own — but because it lives in the agent log folder
+(`Constants.LogDirectory`), the diagnostics package (`DiagnosticsPackageService`,
+`*.log` pattern, `AgentLogs/` section) picks it up automatically, so a customer-initiated
+diagnostics upload hands the trace to support without manual copying.
+
+### Semantics
+
+* **No hot-reload** — the flag is consumed once when `DefaultComponentFactory` builds
+  the `GatherRuleExecutorHost` at session start (per-enrollment lifecycle, same as
+  `EnableImeMatchLog`). Enable it in the tenant, then the *next* enrollment writes the
+  trace.
+* **Zero-rules case is traced too** — flag on + backend delivered no gather rules →
+  a one-shot standalone `config` line, so the file is never just absent.
+* **`--run-gather-rules` always traces** (operator diagnostic mode; CLI override or
+  default path) and mirrors every line to the console under `--console`.
+
+## Examples
+
+A logparser rule with `emit_mode=on_change` that "delivers nothing" becomes:
+
+```
+... | LP-01 | config | registered: trigger=interval, collector=logparser, target=C:\...\app.log, unscoped, emitMode=on_change, interval=300s
+... | LP-01 | trigger | interval timer scheduled every 300s (first run after one full interval — no immediate execution)
+... | -     | phase | phase change: DeviceSetup -> AccountSetup
+... | LP-01 | exec | executing: collector=logparser, target=C:\...\app.log
+... | LP-01 | logparser | app.log: read 1000 lines from position 0->81234, matched 0, parseFailures=1000, regexTimeouts=0, mode=cmtrace
+... | LP-01 | logparser | every line failed CMTrace parsing — if this is a plain-text log, set parameter format=text
+```
+
+— the answer ("plain-text log parsed in CMTrace mode") is in the file.
+
+A matching rule shows *how* it matched (capped at 10 per-match lines per file per run):
+
+```
+... | LP-02 | logparser | setupact.log: line 42 matched "Error 0x80070005" — groups: code="0x80070005"
+... | LP-02 | logparser | setupact.log: read 500 lines from position 0->40123, matched 1, parseFailures=0, regexTimeouts=0, mode=text
+```
+
+and a broken regex names itself:
+
+```
+... | LP-03 | error | invalid regex pattern '([unclosed' — rule can never match: Invalid pattern '([unclosed' at offset 10. Not enough )'s.
+```
+
+## Citations
+
+* Executor + trace points: `../../src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs`
+* Writer: `../../src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleDebugLog.cs`
+* Config projection: `../../src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/RemoteConfigMerger.cs`
+* Backend serve + ConfigVersion: `../../src/Backend/AutopilotMonitor.Functions/Functions/Config/GetAgentConfigFunction.cs`
+* Phase scoping / emit mode background: `../rules/gather-rule-phase-scoping.md`

docs/agent/logs-and-persistence.md

@@ -53,7 +53,7 @@ every line; the spool fsyncs only items flagged `RequiresImmediateFlush`.
 | Event sequence | `State\event-sequence.json` | `{ LastAssignedSequence }` | atomic | none; survives WhiteGlove Part-2 resume |
 | Spool | `Spool\spool.jsonl` | JSONL (`TelemetryItem`/line) | only `RequiresImmediateFlush` items | none — never truncated, cursor skips uploaded items |
 | Upload cursor | `Spool\upload-cursor.json` | `{ LastUploadedItemId }` | atomic | idempotent, never regresses |
-| Agent trace log | `Logs\agent_YYYYMMDD[_NNN].log` | text `[utc] [LEVEL] msg` | no | 50 MB → suffix rotation; consumed by `/diag-agent-log` |
+| Agent trace log | `Logs\agent.log` (segments `agent-NNN.log`) | text `[utc] [LEVEL] msg` | no | 50 MB → suffix rotation; consumed by `/diag-agent-log` |
 | Crash dump + record | `Crashes\<stem>.dmp` + `.json` | MiniDump + JSON | n/a (process dying) | 5 files / 7 days |
 | Startup-event gate | `State\startup-event-state.json` | JSON dict | no (atomic) | cross-reboot dedup of one-shot probes |
 | Bandwidth state | `State\bandwidth-state.json` | JSON samples/counters | no (atomic) | reboot-survivor for the DO bandwidth estimate |

docs/agent/overview.md

@@ -146,7 +146,7 @@ snapshots) are executed by the `EffectRunner` — the reducer itself is pure. De
 | `\Agent\` | deployed binaries |
 | `\State\` | decision persistence (SignalLog, Journal, Snapshot), `enrollment-complete.marker`, `final-status.json`, self-update state, `.quarantine/`, `.part1-<ts>/` |
 | `\Spool\` | telemetry spool (offline queue) |
-| `\Logs\` | agent trace log, `crash_*.log`, `ime_pattern_matches.log` |
+| `\Logs\` | agent trace log (`agent.log`), `crash-*.log`, `ime-pattern-matches.log` |
 | `\Config\` | `remote-config.json` cache |
 | `\Agent-Update\`, `\Updates\` | self-update staging/download |
 

docs/agent/registry-app-state-pillar.md

@@ -0,0 +1,89 @@
+---
+type: concept
+title: Registry App-State Second Pillar
+description: Why the agent reads IME's authoritative per-app state straight from the registry (Win32Apps / EspTrackingWin32Apps / StatusServiceReports), how the snapshot-and-diff observer works, and how registry/log reconciliation doubles as the built-in IME log-pattern drift alarm.
+resource: agent
+tags: [ime, registry, win32apps, observability, reconciliation, pattern-drift, wdp]
+timestamp: 2026-08-18
+---
+
+# Schema
+
+## Why a second pillar
+
+The 2026-08-17 audit of the decompiled IME (1.97.107 / 1.104.102) proved that IME log
+wording is an unstable contract: Microsoft removed the old V1/V2 processing pipeline
+(killing 9 patterns silently), reworded the post-remediation line, changed the
+report-delta quoting between 1.97 and 1.104, and deleted `[DO TEL]` entirely. The
+registry, by contrast, is IME's *internal product contract* — the ESP page and Intune
+reporting consume it — and cannot drift casually.
+
+Architecture decision (Oliver, 2026-08-17): **hybrid**. Logs stay the narrative
+(downloads, retries, exit codes, scripts — the timeline). The registry is the stable
+truth for terminal state. Divergence between the two IS the alarm that log patterns
+drifted — turning silent data loss into a Warning event.
+
+## Observed surfaces
+
+All under `HKLM\SOFTWARE\Microsoft\IntuneManagementExtension` (64-bit view), verified
+against decompiled IME source:
+
+| Surface | Content |
+|---|---|
+| `Win32Apps\<userGuid>\<appGuid>_<rev>` | `EnforcementStateMessage` JSON (EnforcementState + ErrorCode), `ExitCode`, `Intent`. Device context = `Guid.Empty` user. Non-GUID subkeys (GRS, OperationalState, Reporting, ProvisioningProgress) are skipped. |
+| `EspTrackingWin32Apps\<userGuid>\<appGuid>_<rev>` | Which apps IME registered for ESP tracking, `EspTrackingWin32AppPhase`. |
+| `SideCarPolicies\StatusServiceReports\<userGuid>\<appId>` | The `AppInstallStatusReport` the ESP page renders (`Status`: 1000=Installed, 1001=Installing, 3000=Failed, 2000er=NotApplicable). |
+
+## Mechanism
+
+`ImeRegistryAppStateObserver` + `ImeRegistryAppStateHost` (always-on, no config gate —
+precedent `EspPolicyProviderStallHost`):
+
+- **One recursive `RegistryWatcher`** on the IME root covers all three surfaces;
+  changes are debounced (2 s trailing edge) into a tick. A 60-s periodic tick is both
+  the reconciliation-settle evaluator and the poll-only fallback when the watcher
+  fails to arm (`collector_degraded`, once).
+- **Snapshot-and-diff**: `RegNotifyChangeKeyValue` gives coalesced key-scope edges
+  only, so every tick re-reads the surfaces and diffs against the previous snapshot.
+- **Silent baseline**: the state present at agent start is captured without events.
+  Win32Apps keys survive re-enrollments — replaying them would be the registry twin
+  of the historic-IME-replay bug. Only apps that *change during the session* are
+  reported or judged.
+- **`registry_app_state`** (Info): emitted per real field change
+  (enforcementState/errorCode/exitCode/statusServiceStatus/espTracked/espPhase),
+  capped at 200/session (cap announced once as Warning).
+- **`app_state_reconciliation`** (Warning, once per app, immediate upload): after a
+  changed entry has been terminal (EnforcementState 1000er=success / 5000er=error,
+  or StatusService 1000er/3000) for ≥ 90 s, its outcome is compared against the
+  log-derived `AppPackageState` from `ImeLogHost.AllKnownPackageStates`. Divergence
+  reasons: `registry_error_log_installed`, `registry_success_log_error`,
+  `app_unknown_to_log_tracking` (only when the tracker is actively tracking apps —
+  an idle tracker is not judgeable).
+- **Pure observability**: nothing feeds the DecisionEngine (same rule as
+  oobe-state observability).
+
+## WDP reuse (Paket 3)
+
+The same host archetype (RegistryWatcher subtree + debounce + snapshot-diff) is the
+intended vehicle for WDP live progress: watch
+`HKLM\SOFTWARE\Microsoft\Provisioning\AutopilotSettings\DevicePreparation\BootstrapperAgent`
+(`ProgressUpdates` rows, `ResumeContext.ProvisioningResult` terminal marker) with the
+RealmJoinWatcher appearance-watcher pattern for not-yet-existing keys, plus an
+Event-142 channel watcher (`Microsoft-Autopilot-BootstrapperAgent/BootstrapperAgentServiceLogProvider`,
+channel handling precedent in `DiagnosticsPackageService`). Win32Apps keys are written
+on WDP devices too — the pillar works on both rails unchanged.
+
+# Examples
+
+Timeline evidence of a drifted pattern set: apps install fine (registry says
+EnforcementState 1000) but the timeline shows no `app_install_completed` — each app
+raises one `app_state_reconciliation` with `reason=app_unknown_to_log_tracking`.
+Operator response: run `/ime-pattern-validate` against the session, fix patterns,
+backend-deploy (no agent release needed for pattern fixes).
+
+# Citations
+
+- `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/ImeRegistryAppStateObserver.cs`
+- `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/Hosts/ImeRegistryAppStateHost.cs`
+- `tasks/ime-v1-code-audit-2026-08-17.md` (decompiled-source audit; registry surface catalog)
+- Decompile archive: `okieselbach/ime-decompiles` (private), `C:\Code\GitHubRepos\ime-decompiles\<version>\decompiled`

docs/agent/secureboot-ca2023-detection.md

@@ -37,6 +37,21 @@ Fail-soft contract like `OobeStateReader`: never throws; failures map to status
 (`not_uefi` = legacy BIOS via `ERROR_INVALID_FUNCTION`, `variable_not_found`,
 `privilege_denied`, `error_<code>`).
 
+This is the repo's only privilege-adjustment code, so it also carries the ownership rules
+any future one should copy:
+
+* The process token lives in a `SafeHandle` assigned by the P/Invoke marshaler, so the CLR
+  owns it from the moment `OpenProcessToken` returns — the critical finalizer releases it
+  even if `Dispose` never runs (async exception before the instance reaches its `using`).
+* The restore obligation is recorded immediately after the successful `AdjustTokenPrivileges`,
+  and only when the privilege was not *already* enabled; nothing that can throw sits between
+  the adjustment and that assignment. `Dispose` is idempotent, swallows a failed restore, and
+  releases the handle in a `finally`.
+* The privilege is adjusted on the **process** token, so enable → read → restore is a
+  process-wide side effect and runs under a static gate. Without it a concurrent reader would
+  see "already enabled", correctly skip its own restore, and then lose the privilege mid-read
+  when the first reader disposes — a spurious `privilege_denied` on a machine that holds it.
+
 Fields land on the existing `secureboot_status` event (once per agent start,
 restart-deduped by the StartupEventGate): `uefiFirmwareReadStatus`, per-cert booleans
 (`uefiDbHasWindowsUefiCa2023`, `uefiDbHasWindowsProductionPca2011`,

docs/backend/app-version-regression-radar.md

@@ -0,0 +1,98 @@
+---
+type: Concept
+title: App Version Duration Regression Radar
+description: How the radar detects app versions whose median install duration regressed vs. the previous version (median lift ≥2x plus an absolute floor over first-seen-ordered versions), how alert episodes live in the appversionregression tracker keyspace, and which surfaces show them.
+resource: src/Backend/AutopilotMonitor.Functions/Helpers/AppVersionRegressionRadar.cs
+tags:
+  - backend
+  - apps
+  - regression-radar
+  - insights
+timestamp: 2026-08-13T12:00:00+02:00
+---
+
+# App Version Duration Regression Radar
+
+Detects "version X made this app's installs much slower" — the concrete, quotable insight
+("median install duration rose from 11 to 29 min after version X") — from the per-(session,
+app) `AppInstallSummaries` rows. Duration only: failure-rate per version is already visible
+in the apps dashboard's `versionBreakdown`, and rate regressions belong to Wilson-interval
+statistics, not medians.
+
+# Schema
+
+## Signal & detection
+
+Per (tenant, app), the MEASURED install population is: `Status == "Succeeded"`, terminal
+state not Skipped/Postponed, `MetricsMath.HasMeasuredDuration` (1s..6h — 0s means the start
+was unobserved, above 6h means back-stamped batches), no `AppIdCollision`, non-empty
+`AppVersion`. Versions are ordered by FIRST-SEEN install time (min `StartedAt`), never by
+string comparison ("9.1" vs "2024.10" would lie). The comparison pair is always the newest
+version (the one with the most recent measured install) vs. the version with the latest
+first-seen strictly before it.
+
+MEDIANS, not means (nearest-rank, shared with the apps dashboard via
+`AppsAnalyticsHelper.Percentile`) — one back-stamped straggler must not fire a fleet alert.
+A regression fires only when ALL hold over the trailing 35-day horizon:
+
+1. both versions have ≥ 10 measured installs;
+2. current median ≥ 2× the previous version's median;
+3. absolute increase ≥ 300 s (a 20s→45s app is noise, not an incident).
+
+## Suppression & limits
+
+* Parallel ring rollouts can make "previous" a concurrently-deployed version — accepted in
+  v1; the episode key (app, current version) still caps it at one bell per version.
+* Platform kill switch: app setting `AppVersionRegressionRadarDisabled=true` skips the
+  radar (fail-open — it only notifies, never mutates data).
+* One cross-tenant install-summary read per pass (the same query the global apps dashboard
+  runs), grouped by tenant; per-tenant failures are non-fatal.
+
+## Alert episodes (tracker keyspace)
+
+An episode lives as `appversionregression|{app-lower}|{version-lower}` (table-key-sanitized;
+raw AppName/CurrentVersion live in columns, the mapper never parses the RowKey) in the
+notification-tracker table, next to the `ruleregression|` keyspace: the row IS the dedup
+(bell + ops event fire exactly once per episode) and the `versionRegressions[]` payload —
+both medians, both sample counts, lift. Numbers refresh on every radar pass while the
+episode stays active; `FirstNotifiedAt` never moves. The episode closes (dedup re-arms) when
+the alerted version drains under 10 measured installs in the horizon or its recomputed
+median falls back under 1.5× the previous version's median; the tracker's 30-day retention
+sweep also re-arms, so a month-old still-burning regression rings once more by design.
+
+## Notification chain (v1: bell + ops event)
+
+* Tenant bell `app_version_duration_regression` (audience: Admin), href
+  `/apps/detail?name={app}&days=35` (canonical `appDetailUrl` shape). Message carries the
+  full numbers so the admin can verify without a portal round-trip.
+* Ops event `AppVersionDurationRegression` (Tenant category, Warning) — dual-registered in
+  the web `OPS_EVENT_TYPES` catalog so operators can wire Telegram/Teams/Slack alert rules.
+
+## Surfaces
+
+* `apps/{appName}/analytics` (+ global twin with `?tenantId=`) responds with
+  `versionRegressions[]` (empty for the cross-tenant aggregate — episodes are per-tenant
+  rows), and `versionBreakdown[]` rows now carry `measuredInstalls` /
+  `medianDurationSeconds` / `p95DurationSeconds`.
+* Apps detail page: amber "↑ Duration regression" banner above the version cards and a
+  "Median Install Duration by Version" bar chart.
+
+# Examples
+
+A tenant ships Contoso VPN 2.4.0 after 2.3.9. 2.3.9 has 40 measured installs, median 660s;
+2.4.0 accumulates 12 measured installs with median 1740s. Lift 2.6×, absolute +1080s →
+episode `appversionregression|contoso vpn|2.4.0` opens, one bell + one ops event fire.
+Subsequent passes refresh the numbers only. When 2.4.1 replaces 2.4.0 and 2.4.0 drains
+below 10 measured installs in the horizon, the episode deletes and the dedup re-arms.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Helpers/AppVersionRegressionRadar.cs` — pure core
+  (gates, first-seen ordering, re-arm).
+* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.AppVersionRegression.cs`
+  — orchestration, kill switch, bell/ops-event emission, wording contract.
+* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableHardwareRejectionNotificationTracker.cs`
+  — episode keyspace, entity round-trip.
+* `src/Shared/AutopilotMonitor.Shared/Models/Metrics/AppVersionRegressionAlert.cs` — persisted
+  alert payload.
+* [Rule Regression Radar](rule-regression-radar.md) — the sibling pattern this radar mirrors.

docs/backend/cloudpc-device-validation.md

@@ -0,0 +1,142 @@
+---
+type: Concept
+title: W365 Cloud PC Device Validation — Cert-CN-Bound Fallback Validator
+description: Why Windows 365 Cloud PCs can never pass the Autopilot serial lookup, and how the CloudPc validator admits exactly the tenant's service-provisioned Cloud PCs by binding the MDM certificate's Subject CN (= Intune device id) to the Graph virtualEndpoint/cloudPCs inventory.
+resource: src/Backend/AutopilotMonitor.Functions/Security/CloudPcDeviceValidator.cs
+tags:
+  - backend
+  - security
+  - device-validation
+  - windows365
+  - cloudpc
+  - graph
+timestamp: 2026-08-06T00:00:00+02:00
+---
+
+# W365 Cloud PC Device Validation
+
+Windows 365 Cloud PCs are provisioned headless by the Windows 365 service and are
+**structurally never Autopilot-registered** — the serial lookup against
+`windowsAutopilotDeviceIdentities` (and the Corporate Identifier fallback, whose
+serials nobody can pre-import for VMs minted at provisioning time) always misses.
+Before this validator, a Cloud PC agent died in the 403 "Device not registered"
+even though its mTLS cert was perfectly valid, so Cloud PC first-connect
+enrollment (Account Setup, RealmJoin, Hello) could not be monitored.
+
+# Schema — the validator chain
+
+`SecurityValidator.ValidateRequestAsync` stage 4 runs the same chain for every
+device; there is **no device-type routing** and the local W365 markers
+(Windows365 registry key, CloudManagedDesktopExtension service) are never
+consulted for auth — they gain an attacker nothing:
+
+1. **Autopilot serial lookup** (`ValidateAutopilotDevice`) — unchanged primary.
+2. **Corporate Identifier** (`ValidateCorporateIdentifier`) — unchanged fallback.
+3. **CloudPc** (`ValidateCloudPcDevice`, default off) — only reached when 1+2
+   missed. Extracts the Intune device id from the **chain-validated** client
+   certificate's Subject CN (`TryGetIntuneDeviceIdFromCertSubject`: CN present
+   AND canonical GUID, else definitive reject) and requires a `cloudPC` object
+   with `managedDeviceId eq <CN>` in the claimed tenant
+   (`GET /v1.0/deviceManagement/virtualEndpoint/cloudPCs?$filter=…`).
+   `ValidatedBy = ValidatorType.CloudPc (5)`.
+
+Only machines actually provisioned by the Windows 365 service have a `cloudPC`
+object — a regular Intune-enrolled non-Autopilot device still ends in the 403,
+so the "Autopilot devices only" contract of stages 1–2 is not widened. The
+tenant hard gate accepts `ValidateCloudPcDevice` as a third satisfying flag.
+
+## Why the cert CN, not headers or local markers
+
+Field-verified 2026-08-06 on a real W365 Enterprise Cloud PC (gktatooine.net):
+
+- MDM client cert Subject `CN=07623d56-…` == Intune `managedDevice.id` ==
+  `cloudPC.managedDeviceId`. The CN cannot be forged without the Intune MDM
+  Device CA (chain pinned to embedded roots, `CustomRootTrust`).
+- `$filter=managedDeviceId eq '…'` is supported server-side on **v1.0** — no
+  paging fallback needed.
+- `managedDevice.serialNumber` matches local `Win32_BIOS.SerialNumber` exactly;
+  the "Cloud PC Enterprise …" model string exists **only** in Graph, never in
+  local WMI (local WMI reports Manufacturer='Microsoft Corporation',
+  Model='Virtual Machine').
+
+Threat model: a valid Intune cert from a *different* tenant fails (its CN does
+not exist in the claimed tenant's Cloud PC inventory — this is a *tenant
+binding* the serial-based validators do not have); spoofed serial headers and
+faked local W365 markers are irrelevant (never consulted); a rogue enrolled VM
+with doctored SMBIOS cannot mint a `cloudPC` object (service-side state, not
+device-reported inventory — the reason the model-string gate was rejected).
+Retired/deprovisioned Cloud PCs disappear from the inventory and their
+validation dies with them (compensates the absent cert revocation check).
+Residual: a compromised *legitimate* Cloud PC of the tenant — same trust level
+as any tenant device today, rate-limited by cert thumbprint.
+
+## Graph permission plumbing
+
+- Optional add-on permission `CloudPC.Read.All` — NOT part of the default
+  consent set. Feature `W365CloudPcValidation` in `GraphFeatureCatalog` →
+  surfaces automatically in the "Optional Graph capabilities" UI (the feature
+  table and grant command are backend-driven) and in
+  `Grant-AutopilotMonitorAddOn.ps1` (`-Features W365CloudPcValidation`).
+  `GraphFeatureCatalogSyncTests` pins C# catalog ↔ grant script (previously
+  comment-only lock-step).
+- A Graph **403** (permission not granted) is a definitive negative (cached
+  5 min), NOT transient — a 503 Retry-After loop cannot fix a missing grant.
+  The error message names the add-on feature.
+- Same resilience contract as `AutopilotDeviceValidator`: 30/5 min
+  positive/negative cache, 2 attempts, transient → agent-facing 503.
+
+## Bootstrap script interplay (v2.3-dev.3)
+
+The Cloud-PC relax in `Install-AutopilotMonitor-dev.ps1` additionally exempts
+**guard 4** (12 h uptime window): a Cloud PC runs headless for days before the
+user's first connect, and the monitorable phase (Account Setup) only starts at
+that first connect — the single-fresh-profile window (< 15 min) is the time
+anchor there, not boot uptime. The OOBE-restore trigger keeps the uptime guard.
+
+## Agent-side IsCloudPc flag + decision-engine expectation
+
+Same change set, agent side. `CloudPcDetector` (V2.Core) re-uses the bootstrap's
+field-verified marker AND — `HKLM\SOFTWARE\Microsoft\Windows365` key **plus**
+installed `CloudManagedDesktopExtension` service (probed via its
+`HKLM\SYSTEM\CurrentControlSet\Services` key; the agent deliberately has no
+`System.ServiceProcess` dependency). SKIP-safe: any error resolves `false`.
+
+Three independent transport rails, never an auth input:
+
+- **Session metadata** — `SessionRegistration.IsCloudPc` →
+  Sessions table (sticky-true OR across re-registrations, like
+  `IsSelfDeployingProfile`) → SessionsIndex full mirror → `SessionSummary` →
+  search filter `isCloudPc` (portal, `/api/search/sessions`, `/api/raw/sessions`,
+  MCP `search_sessions`/`query_raw_sessions`). Agent-reported and unverified —
+  can legitimately disagree with the server-derived `ValidatedBy = CloudPc`
+  (e.g. Cloud PC admitted via a stage that ran earlier).
+- **Distress channel** — `DistressReport.IsCloudPc` (captured once at
+  `DistressReporter` construction, `BackendClientFactory`) rides every pre-auth
+  distress report → `DistressReportEntry.IsCloudPc` → the "Devices Not
+  Registered" report aggregates it **sticky-true** per serial
+  (`GetDeviceNotRegisteredFunction`) and the portal insight renders a Cloud PC
+  badge plus a hint pointing at the Cloud PC validation toggle + the
+  `W365CloudPcValidation` add-on. Same UNVERIFIED contract as all distress
+  fields; rows from older agents read false. Fits the existing 1536-byte
+  payload cap without a bump.
+- **Decision engine** — the marker rides the `EnrollmentFactsObserved` payload
+  (`isCloudPc`), is recorded set-once for BOTH values in
+  `EnrollmentScenarioObservations.CloudPc`, and annotates the scenario profile
+  reason `cloud_pc_first_connect:no_device_esp_expected`. That is the
+  engine-recorded expectation "no Device ESP phase will appear": Device-ESP ran
+  headless at provisioning, the session starts at Account Setup. Deliberately
+  reason+observation only — no completion arm depends on DeviceSetup, `Mode`
+  is still classified by AccountSetup/IME signals (Classic), and `EspConfig`
+  keeps the *configured* FirstSync semantics. The positive marker surfaces as
+  `cloud_pc_marker` in the terminal audit-trail signal census.
+
+# Citations
+
+- `src/Backend/AutopilotMonitor.Functions/Security/CloudPcDeviceValidator.cs`
+- `src/Backend/AutopilotMonitor.Functions/Security/SecurityValidator.cs` — stage 4 chain, `TryGetIntuneDeviceIdFromCertSubject`
+- `src/Shared/AutopilotMonitor.Shared/Models/Graph/GraphFeatureCatalog.cs` — `W365CloudPcValidation`
+- `scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1` — customer-side grant
+- `scripts/Bootstrap/Install-AutopilotMonitor-dev.ps1` — Cloud-PC relax + guard-4 exemption
+- `src/Backend/AutopilotMonitor.Functions.Tests/CloudPcDeviceValidatorTests.cs`, `SecurityValidatorTests.cs`, `GraphFeatureCatalogSyncTests.cs`
+- `src/Agent/AutopilotMonitor.Agent.V2.Core/Security/CloudPcDetector.cs` — agent-side marker AND
+- `src/Shared/AutopilotMonitor.DecisionCore/State/EnrollmentScenarioObservations.cs` — `CloudPc` fact; reason annotation in `EnrollmentScenarioProfileUpdater`

docs/backend/device-journeys.md

@@ -0,0 +1,122 @@
+---
+type: Concept
+title: Device Journeys & First-Time-Right (F2)
+description: How a device's terminal enrollment attempts are grouped into journeys (device key, junk-serial exclusion, first-success end, 30-day gap), where the DeviceHistories chain and the daily FTR aggregates are computed, stored and pruned, and which surfaces serve them.
+resource: src/Backend/AutopilotMonitor.Functions/Helpers/DeviceJourneyCalculator.cs
+tags:
+  - backend
+  - metrics
+  - device-history
+  - first-time-right
+  - insights
+timestamp: 2026-07-27T12:00:00+02:00
+---
+
+# Device Journeys & First-Time-Right (F2)
+
+Answers "how many devices enrolled right on the first try?" and "show me every attempt
+this device made". Session success rate hides wipe-and-retry loops — every retry that
+eventually succeeds counts as a success; First-Time-Right (FTR) exposes the real pain.
+All grouping semantics live server-side in `DeviceJourneyCalculator` (JourneyVersion 1);
+no consumer re-derives them.
+
+# Schema
+
+## Device key
+
+`(TenantId, normalized serial)` — normalization is trim + lower-case. Junk/placeholder
+serials are excluded entirely (never a chain, never in FTR, disclosed as a per-day
+exclusion count): `System Serial Number`, `To Be Filled By O.E.M.`, `Default string`,
+`0`, `None`, `INVALID`, `Unknown` (the agent's WMI-failure sentinel), empty, or shorter
+than 4 characters. A motherboard swap changes the serial and therefore the device key;
+re-enrollment under a different tenant is a separate key by design.
+
+## Journey
+
+Terminal sessions of a device key ordered by StartedAt. The terminal set is
+**Succeeded / Failed / Incomplete** — `Pending` (a sealed WhiteGlove part 1),
+`AwaitingUser`, `Stalled` and `InProgress` are OPEN sessions and never attempts.
+
+* A journey **ends** with the first terminal success; the next session starts a new
+  journey (redeployment).
+* A gap of **more than 30 days** since the previous attempt's terminal moment
+  (`CompletedAt`, fallback StartedAt) starts a new journey even without a success
+  (device shelved/repurposed). Constant, not a setting — production gaps: median 4.9 h,
+  92 % < 7 d.
+* WhiteGlove part 1 + part 2 share ONE session row, so a completed WG enrollment is ONE
+  attempt; a WG device still waiting for its user session leaves the journey open —
+  never a failed attempt.
+* **Attempt count** = terminal sessions in the journey (`Failed` and `Incomplete` are
+  non-successful attempts).
+* **FTR rate** = completed journeys with attempt count 1 ÷ all completed journeys.
+  Open and gap-abandoned journeys never enter numerator or denominator.
+
+Durations shown for attempts are the sessions' authoritative `DurationSeconds` verbatim
+(WhiteGlove pause excluded; `Incomplete` deliberately has none) — never
+`CompletedAt − StartedAt`, which is later in ~25 % of terminal sessions.
+
+## Persistence & compute
+
+* `DeviceHistories` (PK = TenantId, RK = percent-encoded normalized serial): the chain of
+  the device's terminal session refs `{sessionId, startedAt, completedAt, status,
+  enrollmentType, isPreProvisioned, durationSeconds, adminMarked}` capped at the 20 most
+  recent, plus derived `CurrentJourneyAttempts` (the LAST journey's attempts — the
+  banner's "Attempt N"), `JourneyCount` (chain-scoped) and `JourneyVersion`. Written
+  inline at the session-terminal single-writer seam
+  (`TableSessionRepository.UpdateSessionStatusAsync`, all three terminal statuses,
+  DeletionState-guarded) so the session banner is fresh; healed by the maintenance sweep.
+  Deliberately NOT part of the per-session deletion manifest — the row aggregates many
+  sessions. Wiped on tenant offboarding.
+* Sweep (`SweepDeviceJourneysAsync`, 30-day rolling window, 2h tick): (1) drops chain
+  refs of deleted sessions **tombstone-driven** — every session deletion (cascade and
+  retention both run through the cascade worker) leaves a `SessionTombstones` marker for
+  ~7 days, far longer than the sweep cadence, and even an expired-but-unpruned marker is
+  valid deletion evidence; a chain left empty deletes its row. (2) Merges the window's
+  terminal sessions into their chains (backfill, inline-miss healing, re-terminal
+  reclassifications). (3) Recomputes the daily FTR aggregates idempotently.
+* `DeviceJourneyAggregates` (PK = TenantId or `global`, RK = `{yyyy-MM-dd}`): per day —
+  completed journeys, first-time-right count, attempt histogram, junk-serial exclusion
+  count, `JourneyVersion`. A journey buckets on the StartedAt date of its completing
+  success session (the platform's StartedAt-date convention; late terminals converge via
+  the sweep). All counts are **additive**, so a window rate is the ratio of summed daily
+  rows — there is no rolling-window row (unlike the median-based time-attribution
+  aggregates, which cannot merge). 180-day retention. Rows exist below the ≥20 UI gate
+  on purpose (the UI needs the n for "insufficient data (n=…)").
+
+# Surfaces
+
+* `GET api/metrics/device-history?serialNumber=&sessionId=` (MemberRead + tenant query
+  param — the same route serves the web banner and MCP; a Global Admin passes `tenantId`)
+  — the chain plus, with `sessionId`, that session's server-computed attempt number
+  (live sessions get their would-be position via a virtual non-successful attempt, so the
+  redeploy and gap rules apply). `history: null` = no recorded history.
+* `GET api/metrics/device-journeys?days=` (MemberRead) /
+  `GET api/global/metrics/device-journeys?days=&tenantId=` (GlobalReadOrAdmin) —
+  `{ windowDays, totals, daily, repeatDevices }`. The days selector is honored because
+  counts are additive. Without `tenantId` the global variant serves the cross-tenant
+  aggregate rows and `repeatDevices: null` — a per-device list would require scanning
+  every tenant's partition.
+* Repeat devices (violator list, capped 10): devices whose LAST journey took ≥2 attempts
+  and whose newest terminal session falls inside the window, ordered by attempts then
+  recency; the failure reason comes from the newest failed attempt (bounded point-reads).
+* Web: "Attempt N for this device · View history" banner on session detail (expandable
+  chain); "First-time-right" section on Fleet Health (rate + weekly trend + attempt
+  histogram + repeat devices). MCP: `get_device_history` (serial mode / fleet FTR mode).
+
+# Examples
+
+A device fails ESP twice and succeeds on the third try within one week: one journey,
+three attempts, completed — counts once in the FTR denominator, not in the numerator,
+and the histogram's bucket `3` gains one. The same device redeployed a month later and
+succeeding immediately starts journey 2 with attempt count 1 — first-time-right. A
+device with `serialNumber = "Unknown"` (WMI failure) never gets a chain; its terminal
+sessions surface only as that day's disclosed exclusion count.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Helpers/DeviceJourneyCalculator.cs` — device key, junk list, grouping, attempt numbers (JourneyVersion 1).
+* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.DeviceHistory.cs` — persistence + inline seam entry.
+* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.DeviceJourneys.cs` — sweep, tombstone pruning, daily aggregation.
+* `src/Backend/AutopilotMonitor.Functions/Functions/Metrics/GetDeviceJourneyFunctions.cs` — read surfaces.
+* `src/Backend/AutopilotMonitor.Functions.Tests/DeviceJourneyAndFtrTests.cs` — table-driven grouping/aggregation/attempt-number tests.
+* `tasks/insights-expansion-spec.md` — F2 specification and source-data audit (§0.5).

docs/backend/lifecycle-manifests-and-session-scope.md

@@ -0,0 +1,62 @@
+---
+type: concept
+title: Lifecycle Manifests & Session Scope Resolution
+description: The enforced completeness nets added by the fragility-audit P5/P6 remediation — table lifecycle buckets, the SessionsIndex field manifest, the single session-scope resolver with its SessionTenantLookup point-read, and the server-side dashboard free-text search.
+resource: backend
+tags: [lifecycle, offboarding, sessionsindex, manifest, scope-resolution, search, performance]
+timestamp: 2026-08-13
+---
+
+# Schema
+
+Four mechanisms replace hand-synchronized copies with a declared source plus tests that fail on drift.
+
+## 1. Table lifecycle buckets
+
+Every table in `Constants.TableNames` must belong to at least one deletion lifecycle:
+
+| Bucket | Mechanism | Source of truth |
+|---|---|---|
+| Tenant-offboarding wipe | `TenantOffboardingHandler` bucket arrays (`TenantPartitionTables`, `CompositePartitionTables`, `DiscriminatorTables`, `PropertyOnlyTables`, `RowKeyTables`, `ArchivedRuleTables`) + the one-off `TenantConfiguration` final delete | handler arrays (read via reflection by the test) |
+| Per-session cascade | `DeletionManifestBuilder.BuildAsync` step list (incl. the Final tombstone → Sessions + SessionsIndex) | a real manifest built against an empty-inventory fake |
+| Kept by design | reviewed exception list with per-table reasons | `TableLifecycleBucketTests.KeptByDesign` |
+
+`TableLifecycleBucketTests` (Functions.Tests) asserts: constants set-equal `TableNames.All`, no table unclassified, kept-by-design disjoint from every wipe path, bucket entries are real constants, offboarding buckets disjoint except documented multi-membership (`BootstrapSessions`).
+
+**Not covered mechanically:** whether a bucket's key shape matches the table's writer. That was the UsageMetrics bug (PK=date, RK=tenantId sat in the exact-PK bucket; the wipe matched 0 rows) — SafeWipe **Variant D** (`WipeByRowKeyAsync`, `RowKey eq '{tenantId}'`) now covers RowKey-anchored tables. Read the writer's `new TableEntity(pk, rk)` before classifying a new table.
+
+## 2. SessionsIndex field manifest
+
+`SessionIndexFieldManifest` (Functions/Services) declares the full-mirror column set: `AlwaysProjected` (32, written with defaults on every rebuild), `ConditionallyProjected` (18, written only when present), `PrimaryOnly` (4 — ServerActions + deletion-CAS fields that never touch the index). `SessionIndexFieldManifestTests` pins `BuildSessionIndexEntity` against it bidirectionally (full-row fixture built from a test-local sample table, NOT from the manifest — deriving the fixture from the manifest would make the check circular), pins that every manifest field influences `MapToSessionSummary`, and pins the rebuild's `TableUpdateMode.Replace` (a merge-mode upsert could never clear a conditional column the primary blanked). `MergeSessionIndexAsync` logs a warning for merged keys outside the manifest (fail-soft drift guard).
+
+## 3. Session scope resolution (one implementation)
+
+`RequestContextExtensions.ResolveSessionScopeAsync(ctx, sessionRepo, sessionId, requireGlobalAdmin)` is the single implementation of the former 15-site copy-paste fallback ("which tenant owns this session?"):
+
+- Non-global callers always keep the middleware-validated `TargetTenantId`.
+- Global-scope callers resolve via `ISessionRepository.ResolveSessionTenantIdAsync` — a point-read on **SessionTenantLookup** (PK=sessionId, RK="tenant") with a legacy cross-partition SessionsIndex scan fallback that self-heals the lookup row, so the scan is paid at most once per pre-table session.
+- `requireGlobalAdmin: true` on WRITE paths gates the cross-tenant reach on `IsGlobalAdmin` so a read-only Global Reader can never steer a write into a foreign tenant.
+- Unknown session → `TargetTenantId`, leaving each endpoint's own not-found semantics (404 / empty 200 / 400) in charge.
+- Delegated (MSP) callers deliberately get NO fallback — extending it to `AllowedTenantIds` is a pending user decision.
+
+The lookup row is written at session registration (fail-soft), deleted by the cascade one step before the tombstone, and rebuildable from Sessions (not in the critical-backup set). The former lazy triggers (`events.Count == 0` → scan) are gone: empty-but-owned results no longer pay a table scan, and endpoints resolve upfront.
+
+Related enforcement added with the migration: `RecomputeTriggerGate` — `?reanalyze=true` and `?rescan=true` on the MemberRead session routes are actions (delete + rewrite stored results) and now 403 for Viewer / Global Reader / cross-tenant tenant roles (Global Admin or own-tenant Admin/Operator only).
+
+## 4. Server-side dashboard search
+
+`q=` on `/api/search/sessions` + `/api/global/search/sessions`: case-insensitive substring over exactly the fields the dashboard's client-side filter searches (device name, serial, manufacturer, model, status, sessionId, geo, agent version, OS fields — NOT the client-derived date/duration/blocked tokens; a server-only field would produce ghost results the client filters back out). Azure Tables has no substring operator, so the scan path backfills whole Azure pages until it has `pageSize` matches (max 10 pages per request, continuation at a page boundary — gap-free). `q` is bound into the pagination fingerprint. The web dashboard's `searchAll()` (useDashboardSessions) follows nextLink up to 10 requests / 50 matches and dedupe-merges results into the loaded list (`mergeSessionsById`), replacing the former `loadAll()` walk that downloaded the entire session history to search it client-side. Delegated callers in cross-tenant mode keep the legacy full sweep (the global search route has no delegated tier).
+
+# Examples
+
+Adding a new table: classify it in one lifecycle path before `TableLifecycleBucketTests` lets it ship — offboarding bucket (check the writer's PK/RK shape first), deletion-manifest step, or `KeptByDesign` with a reason.
+
+Adding a mirrored SessionsIndex field: manifest entry + `BuildSessionIndexEntity` write + `MapToSessionSummary` read + a sample value in the test — any missing step is red.
+
+# Citations
+
+- `src/Backend/AutopilotMonitor.Functions.Tests/TableLifecycleBucketTests.cs`
+- `src/Backend/AutopilotMonitor.Functions/Services/SessionIndexFieldManifest.cs`
+- `src/Backend/AutopilotMonitor.Functions/Helpers/RequestContext.cs` (`ResolveSessionScopeAsync`)
+- `src/Backend/AutopilotMonitor.Functions/Services/Offboarding/SafeWipeService.cs` (Variant D)
+- `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.AgentApi.cs` (`MatchesFreeText`, backfill loop)

docs/backend/oobe-bootstrap-go-flow.md

@@ -0,0 +1,107 @@
+---
+type: Concept
+title: OOBE Bootstrap go-Code Flow — Always-200 Script Endpoint
+description: The full lifecycle of the bootstrap short-code — created in the portal, typed as `irm go.autopilotmonitor.com/CODE | iex` at Shift+F10, served by GetBootstrapScriptFunction as an always-HTTP-200 PowerShell script — including the two-line injection defense and the rate-limit story behind Front Door.
+resource: src/Backend/AutopilotMonitor.Functions/Functions/Bootstrap/GetBootstrapScriptFunction.cs
+tags:
+  - backend
+  - bootstrap
+  - security
+  - oobe
+timestamp: 2026-07-28T00:00:00+02:00
+---
+
+# OOBE Bootstrap go-Code Flow
+
+Bootstrap Sessions let a technician install the agent **before** Intune
+enrollment: an admin creates a short-lived session in the portal (Settings →
+Bootstrap Sessions), hands the technician a short URL, and the technician types
+`irm https://go.autopilotmonitor.com/CODE | iex` into a Shift+F10 console
+during OOBE. The URL is deliberately short because it is typed by hand on a
+device that has no clipboard.
+
+# Lifecycle
+
+1. **Create** — `POST /api/bootstrap/sessions` (`BootstrapManagerOrGA`).
+   `BootstrapSessionService.CreateAsync` mints an unambiguous-charset short
+   code + a GUID token, validity clamped 1–168 h. The response's `bootstrapUrl`
+   is built from `Constants.BootstrapGoBaseUrl` — the single producer of the
+   absolute URL (pinned by `CreateBootstrapSessionUrlShapeTests`).
+2. **Serve** — `GET /api/bootstrap/go/{code}` (`GetBootstrapScriptFunction`,
+   `PublicAnonymous`). Customers reach it through the Front Door custom domain
+   `go.autopilotmonitor.com`, whose `/*` route rewrites onto the API path.
+   Validation runs in-process (`ValidateCodeAsync` + the tenant's
+   `BootstrapTokenEnabled` gate) — no HTTP hop to the validate endpoint.
+3. **Install** — the generated script downloads the agent ZIP from
+   `Constants.AgentDownloadBaseUrl`, extracts, and runs
+   `--install --no-auth --bootstrap-token … --tenant-id …`. The agent monitors
+   from OOBE start, switches to certificate auth after Intune enrollment, and
+   self-destructs on completion.
+
+The legacy Next.js `/go/[code]` route (SSR on the SWA) stays alive only for
+URLs issued before the migration and is removed with the static-export PR —
+see the transition rule in [URL Registry](../url-registry.md).
+
+# Always-200 contract
+
+Every response — success, invalid format, unknown/expired code, disabled
+feature, rate limit, internal error — is **HTTP 200 `text/plain`**. The
+consumer is `irm | iex`: a non-2xx status would make `irm` throw an opaque
+exception on the OOBE console, while a 200 error script surfaces the actual
+message via `Write-Host 'ERROR: …'`. Consequences:
+
+- Failures are invisible in status-code metrics; the compensating signal is the
+  `LogWarning` per rejection (code + client IP).
+- Error messages are capped at 200 chars **before** quote-escaping and
+  single-quote-doubled — a hostile upstream message cannot break out of the
+  `Write-Host` literal.
+
+A disabled tenant returns the **same generic message** as an unknown code — no
+enumeration oracle for whether a code exists.
+
+# Injection defense (two lines)
+
+The script runs as SYSTEM during OOBE, so interpolation is treated as a
+security boundary:
+
+1. **`BootstrapScriptValueValidator`** — tenantId/token must be exact canonical
+   GUIDs, the download URL must be https on an allow-listed host
+   (`AgentDownloadBaseUrl`/`AgentBlobBaseUrl` hosts) with the strict
+   `/agent/….zip` path shape, expiry must be future and ≤ 14 days. No accepted
+   value can contain `$`, quotes, backticks, spaces, or newlines. Kept even
+   though values are produced in-process — defense-in-depth against tampered
+   table data.
+2. **Single-quoted PS literals** — every interpolated value sits inside
+   single-quoted PowerShell strings, which do not expand `$()`, `$var`, or
+   backticks.
+
+The template is a C# raw string with `__TOKEN__` placeholders substituted via
+`Replace` (never `$`-interpolation — the script is full of PS `$vars`).
+`OobeBootstrapScriptGeneratorTests` pins byte parity with the original
+TypeScript template through a golden file, so the legacy route and the backend
+serve identical scripts during the transition.
+
+# Rate limiting behind Front Door
+
+The endpoint self-limits per client IP (`bootstrap-script:{ip}`, 20/min via
+`ClientIpExtractor.GetRateLimitClientIp`) — anonymous routes are skipped by
+`UserRateLimitMiddleware` and must bring their own limiter. Because traffic
+arrives through Front Door, the rightmost X-Forwarded-For hop resolves to AFD
+egress IPs and buckets would collapse (the shared-bucket 429 incident class);
+the AFD-aware extraction therefore honors `X-Azure-ClientIP` only when
+`X-Azure-FDID` matches the `FrontDoorProfileId` app setting (fail-closed to
+the trusted-hop path otherwise). Verified post-deploy 2026-07-29: real client
+IPs are keyed, not AFD egress.
+
+Front Door route caching is DISABLED for this route: the body inlines the
+bearer token, so a cache hit would replay one requester's token to another.
+`NoStoreCacheMiddleware` covers the `/api/bootstrap/go/` prefix.
+
+# Citations
+
+- `src/Backend/AutopilotMonitor.Functions/Functions/Bootstrap/GetBootstrapScriptFunction.cs`
+- `src/Backend/AutopilotMonitor.Functions/Functions/Bootstrap/OobeBootstrapScriptGenerator.cs`
+- `src/Backend/AutopilotMonitor.Functions/Security/BootstrapScriptValueValidator.cs`
+- `src/Backend/AutopilotMonitor.Functions.Tests/OobeBootstrapScriptGeneratorTests.cs` — golden parity
+- `src/Web/autopilot-monitor-web/app/go/[code]/route.ts` — legacy route (transition only)
+- [URL Registry](../url-registry.md) — go-URL registry entries + transition rule

docs/backend/rule-regression-radar.md

@@ -0,0 +1,112 @@
+---
+type: Concept
+title: Rule Regression Radar (F3)
+description: How the radar detects analyze rules whose hit rate suddenly rose (7-day window vs 28-day baseline, Wilson-separated), which suppressions keep it quiet, how alert episodes live in the notification tracker, and which surfaces show them.
+resource: src/Backend/AutopilotMonitor.Functions/Helpers/RuleRegressionRadar.cs
+tags:
+  - backend
+  - rules
+  - regression-radar
+  - insights
+timestamp: 2026-07-27T16:00:00+02:00
+---
+
+# Rule Regression Radar (F3)
+
+Detects "this analyze rule suddenly fires much more often" before helpdesk volume does, and
+says what the spike correlates with — with honest statistics and honest wording. Analyze
+rules only in v1: their daily stats are audit-verified session-deduplicated
+(`FireCount` ≈ distinct sessions with a hit, `SessionsEvaluated` the same-source
+denominator). Gather rules are excluded until their per-batch stats dedup is fixed —
+never silently included with bad math.
+
+# Schema
+
+## Signal & detection
+
+Per (tenant, ruleId), daily hit rate = `FireCount ÷ SessionsEvaluated` from the
+`RuleStats` rows — RATES, not counts (absolute counts spike with every rollout wave).
+A regression fires only when ALL hold for the trailing 7-day window vs. the prior
+28-day baseline:
+
+1. window has ≥ 5 hit sessions AND ≥ 20 evaluated sessions;
+2. window rate ≥ 2× baseline rate;
+3. the Wilson 95 % intervals are disjoint in the increase direction
+   (`MetricsMath.WilsonInterval` / `RateIncreaseSeparated` — deterministic, unit-pinned),
+   so small-n noise never alerts.
+
+## Suppression (false positives are trust damage)
+
+* Rule entity missing (deleted) — never alerts.
+* Rule younger than baseline + window (`CreatedAt` within 35 days — grace period for new
+  rules; the entity timestamp is the honest gate, a stats-row count would fail on
+  low-volume tenants whose quiet days simply have no rows).
+* Rule edited inside the window (`UpdatedAt` ≥ window start) — edits legitimately change
+  hit rates.
+* Empty baseline denominator (rule disabled throughout the baseline).
+* Platform kill switch: app setting `RuleRegressionRadarDisabled=true` skips the radar
+  (fail-open — it only notifies, never mutates data).
+
+## Alert episodes (tracker keyspace)
+
+An episode lives as `ruleregression|{ruleId}` in the notification-tracker table
+(the `tpmpss|` pattern): the row IS the dedup (bell + ops event fire exactly once per
+episode), the badge state and the `regressions[]` payload — window/baseline counts,
+rates, lift (null for a zero-baseline "new signal" — no finite lift is invented), window
+dates, and the dimension concentration captured at first fire. Numbers refresh on every
+radar pass while the episode stays active; `FirstNotifiedAt` never moves. The episode
+closes (badge clears, dedup re-arms) when the window rate falls back under 1.5× baseline
+or fires stop entirely; the tracker's 30-day retention sweep also re-arms, so a
+month-old still-burning regression rings once more by design.
+
+## Dimension correlation (on fire only)
+
+Hit sessions (RuleResults scan: tenant partition range + RowKey = ruleId + DetectedAt in
+window, intersected with the window's sessions) are compared against all window sessions
+across `osBuild`, `model` (manufacturer + model), `agentVersion` and `imeVersion`. The
+top value by lift is reported with BOTH shares — wording contract: "X % of affected
+sessions are on … vs Y % of all sessions — correlated, not necessarily causal". No value
+with ≥ 5 hit sessions at ≥ 2× lift → "no clear dimension concentration"; a correlation
+failure also yields no claim. App-version correlation for `ANALYZE-APP-*` rules is a
+follow-up (needs rule→app matching semantics), tracked with the gather-rule fix.
+
+## Compute & alert path
+
+Runs in the daily maintenance pass right after the rule-stats aggregation
+(`RunRuleRegressionRadarAsync`), anchored on YESTERDAY — whole days only, a partial
+today would understate the window rate. One 35-day stats read covers all tenants;
+evaluation is the pure `RuleRegressionRadar` core. On a NEW episode:
+
+1. `RuleFrequencyRegression` ops event (category Tenant, Warning) with the full numbers
+   — dual-registered in the web `OPS_EVENT_TYPES` catalog for alert-rule routing.
+2. Tenant bell notification (type `rule_frequency_regression`, Admin audience) with the
+   same numbers and a deep link to the rule's card (`/analyze-rules#rule-card-{ruleId}`).
+   A sessions-list pre-filtered to rule hits needs a rule filter the session search does
+   not have yet — follow-up alongside the gather-rule work.
+3. v1 channel: bell + ops event only. Provider fan-out (webhook/Telegram) follows once
+   alert quality is proven — a noisy first version burns trust permanently.
+
+# Surfaces
+
+* `GET api/metrics/rule-stats` (and the global variant with `tenantId`) carries
+  `regressions[]` — the active episodes. MCP `get_rule_stats` inherits the block.
+* Analyze-rules page: per-rule 30-day fire-count sparkline (densified from the `trend`
+  rows the endpoint already served) and a red "↑ Regression" badge while an episode is
+  active, with the full numbers in the tooltip.
+
+# Examples
+
+A rule firing on 2 % of sessions for a month jumps to 15 % over a week (15/100 vs
+10/500): lift 7.5×, Wilson-separated → one bell, one ops event, badge until the rate
+falls back under 3 %. The same jump on 5/20 sessions with a 12 % baseline stays silent —
+the intervals overlap, so the spike is not statistically real yet. A rule that never
+fired in the baseline and now hits 15 % alerts as a "new signal" with no lift figure.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Helpers/RuleRegressionRadar.cs` — gates, suppression, re-arm, dimension concentration.
+* `src/Backend/AutopilotMonitor.Functions/Helpers/MetricsMath.cs` — Wilson interval + separation primitive.
+* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.RuleRegression.cs` — sweep, episode reconcile, bell/ops wiring.
+* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableHardwareRejectionNotificationTracker.cs` — episode keyspace.
+* `src/Backend/AutopilotMonitor.Functions.Tests/RuleRegressionRadarTests.cs` — hand-computed Wilson vectors + every suppression branch.
+* `tasks/insights-expansion-spec.md` — F3 specification and source-data audit (§0.5).

docs/backend/server-actions-on-demand-diagnostics.md

@@ -0,0 +1,102 @@
+---
+type: Concept
+title: ServerActions & On-Demand Diagnostics Collection
+description: The queue-on-session, deliver-on-ingest ServerAction channel (terminate_session / rotate_config / request_diagnostics), the operator-tier authorization split, the portal's Collect Logs flow including the admin quick-config path, and why the offboarding cascade sweeps the hosted diagnostics prefix.
+resource: /src/Backend/AutopilotMonitor.Functions/Functions/Sessions/QueueSessionActionFunction.cs
+tags:
+  - backend
+  - agent
+  - web
+  - server-actions
+  - diagnostics
+  - authorization
+timestamp: 2026-07-24T00:00:00+02:00
+---
+
+# Schema
+
+**Channel.** A `ServerAction` (`Type`, `Reason`, `RuleId`, `Params`, `QueuedAt`) is queued onto
+`Sessions.PendingActionsJson` by server-side writers — the admin endpoint
+`POST /api/sessions/{sessionId}/actions`, the RuleEngine, maintenance — and delivered
+piggy-backed on the agent's next ingest response. No polling channel exists; delivery latency
+equals the agent's telemetry cadence (seconds to ~1 minute during enrollment). Delivery is
+at-least-once: the agent's `ServerActionDispatcher` dedups on `Type|RuleId|QueuedAt` and
+processes a batch sequentially in queue order. Unknown types are logged and skipped, so new
+types roll out server-first. Every action emits `server_action_received` and then
+`server_action_executed` or `server_action_failed` into the session timeline.
+
+**Authorization (two layers).** The route sits on `EndpointPolicy.TenantAdminOrOperator`
+(tenant Admin, tenant Operator, or Global Admin — no Viewer, no Global Reader: it is a write
+tier). Because the route serves multiple action kinds, `QueueSessionActionFunction`
+re-gates per type via `IsTypeAllowedForCaller`: Operators may queue only
+`request_diagnostics`; `terminate_session` and `rotate_config` require
+`RequestContext.IsTenantAdmin || IsGlobalAdmin` (403 otherwise). Any route on this tier with
+a multi-kind body MUST follow this same in-function re-gating pattern.
+
+**On-demand collection (`request_diagnostics`).** The dispatcher calls
+`DiagnosticsPackageService.CreateAndUploadAsync(enrollmentSucceeded: false, suffix:
+"server-requested")` — producing `AgentDiagnostics-{sessionId}-{timestamp}-server-requested.zip`.
+Passing `enrollmentSucceeded: false` is what makes on-demand collection work under
+`DiagnosticsUploadMode=OnFailure`; only `Off` (or an unconfigured destination) blocks it,
+surfacing as `server_action_failed`. The `diagnostics_uploaded` event stamps
+`DiagnosticsBlobName` + `Destination` onto the Sessions row (latest wins — an on-demand name
+is later replaced by the terminal package), and the SignalR `sessionUpdate` delta carries the
+field, so the portal's Download button flips live.
+
+**Portal flow (Collect Logs, session detail header).** The button is always rendered; the
+disabled states carry tooltips (inactive session, cross-tenant view, missing role, diagnostics
+not configured) as a deliberate nudge. Members below Admin cannot read the tenant config, so
+the member-readable feature-flags endpoint exposes `diagnosticsUploadConfigured`
+(`mode != Off && (customer SAS present || destination Hosted)`). Progress tracking is
+sequence-based (backend-assigned, monotonic), never timestamp-based — agent clock skew and
+at-least-once redelivery of older actions cannot produce false matches
+(`collectLogsLogic.ts`). Cross-tenant views are gated off because `TenantHelper.GetTenantId`
+resolves the tenant strictly from the caller's JWT.
+
+**Admin quick-config.** For an unconfigured tenant, a Tenant Admin's click opens a dialog
+that switches the tenant to `Destination=Hosted`, `Mode=OnFailure` (GET full config → patch
+exactly those two fields → PUT verbatim), then queues `rotate_config` **before**
+`request_diagnostics` — the dispatcher's sequential ordering guarantees the agent refetches
+the now-enabled config (the `RemoteConfigMerger` applies diagnostics fields live, remote wins)
+before building the package. This works against the already-deployed agent fleet; a
+"one-time override" variant would not, because the `mode=Off` check is client-side in
+`CreateAndUploadAsync` and the deployed handler reads no params.
+
+**Offboarding cascade.** Latest-wins on `DiagnosticsBlobName` means a session can leave more
+hosted blobs behind than the deletion manifest references. The cascade's Hosted branch
+therefore sweeps the canonical prefix `{tenantId}/AgentDiagnostics-{sessionId}-`
+(`HostedDiagnosticsBlobService.DeleteBySessionPrefixAsync`) plus the manifest-named blob as
+belt-and-braces; a non-GUID legacy `SessionId` degrades to the single-name delete instead of
+poisoning the cascade. The CustomerSas branch is unchanged (delete only with the `d`
+permission; the customer's lifecycle rules stay authoritative).
+
+# Examples
+
+Queue an on-demand collection (Admin or Operator, own tenant):
+
+```
+POST /api/sessions/{sessionId}/actions
+{ "type": "request_diagnostics", "reason": "On-demand log collection from portal" }
+→ 202 { "success": true, "queuedAt": "..." }
+```
+
+Operator queueing an admin-only type:
+
+```
+POST /api/sessions/{sessionId}/actions
+{ "type": "terminate_session" }
+→ 403 { "message": "Action type 'terminate_session' requires the Tenant Admin role" }
+```
+
+Timeline for a successful round trip: `server_action_received` → `server_action_executed`
+(with `blobName`) → `diagnostics_uploaded` → Sessions row + SignalR delta carry the new
+`DiagnosticsBlobName`.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Functions/Sessions/QueueSessionActionFunction.cs` — allowed types, per-type caller gate.
+* `src/Backend/AutopilotMonitor.Functions/Security/EndpointAccessPolicyCatalog.cs` — `TenantAdminOrOperator` tier definition.
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Runtime/ServerActionDispatcher.cs` — dedup, sequential dispatch, telemetry contract.
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Runtime/DiagnosticsPackageService.cs` — mode gates, archive build, suffix.
+* `src/Backend/AutopilotMonitor.Functions/Services/Diagnostics/DiagnosticsBlobCascadeDeleter.cs` — hosted prefix sweep.
+* `src/Web/autopilot-monitor-web/app/sessions/[sessionId]/components/collectLogsLogic.ts` — button gating matrix, sequence-based progress evaluation.

docs/backend/session-annotations.md

@@ -0,0 +1,122 @@
+---
+type: Concept
+title: Session Annotations — Role-Separated Human Verdicts
+description: The SessionAnnotations table (PK=tenantId, RK={sessionId}_{lane}) storing per-session human verdicts + notes in three role lanes (operator / tenantadmin / globaladmin), the per-lane write matrix with own-tenant binding, the platform-internal GA lane, the fired-rule-id snapshot that makes annotations rule-quality labels, and the portal/MCP surfaces.
+resource: /src/Backend/AutopilotMonitor.Functions/Functions/Annotations/UpsertSessionAnnotationFunction.cs
+tags:
+  - backend
+  - web
+  - mcp
+  - annotations
+  - authorization
+  - rule-quality
+timestamp: 2026-08-11T00:00:00+02:00
+---
+
+# Schema
+
+**Table.** `SessionAnnotations`: PartitionKey = `tenantId`, RowKey = `{sessionId}_{lane}` with
+lane ∈ `operator | tenantadmin | globaladmin` (a closed set — `AnnotationLanes.All`). One row per
+session + lane, edited in place; per-session reads use the RK range `ge '{sid}_' / lt '{sid}_~'`.
+Serialization lives only in `TableSessionAnnotationRepository.StoreAnnotation`/`MapAnnotation`
+(round-trip-pinned; corrupt `RuleIdsJson` degrades to an empty list on read).
+
+**Row.** `Verdict` (nullable: `root_cause_confirmed | analysis_wrong | different_problem |
+inconclusive`), `Note` (nullable, ≤ 4096 chars), `AuthorUpn`/`AuthorDisplayName` (last editor),
+`CreatedByUpn`/`CreatedAtUtc` (first writer, immutable across edits), `UpdatedAtUtc`, and
+`RuleIdsJson` — a **snapshot of the rule ids that had fired for the session at write time**
+(from `IRuleRepository.GetRuleResultsAsync`, fail-soft to empty). The snapshot is what turns an
+annotation into a rule-quality label without a join: filtering annotations by `ruleId` + `verdict`
+yields confirmed vs false-positive counts per rule even after results are re-analyzed or deleted.
+
+**Verdict + note are independently optional**; a PUT with both null **deletes** the lane row
+(there is no DELETE route). Author identity is always stamped server-side from the JWT
+(`TenantHelper.GetUserDisplayName` + `RequestContext.UserPrincipalName`) — a body-supplied
+author never wins (same anti-spoof contract as the gather-rule PUT-upserts).
+
+# Authorization
+
+Routes (all in `EndpointAccessPolicyCatalog`):
+
+| Route | Policy | Notes |
+| --- | --- | --- |
+| `GET sessions/{sessionId}/annotations` | `MemberRead` + QueryParam | handler filters the GA lane |
+| `PUT sessions/{sessionId}/annotations/{lane}` | `TenantAdminOrOperator` + QueryParam | re-gated per lane in-function |
+| `GET global/session-annotations` | `GlobalReadOrAdmin` + QueryParam | evaluation stream; delegated ("MSP") readers are rescue-admitted on a managed `?tenantId=` only |
+
+**Per-lane write matrix** (`UpsertSessionAnnotationFunction.IsLaneWritableByCaller`, an
+`internal static` pure function like `QueueSessionActionFunction.IsTypeAllowedForCaller`):
+`operator` → tenant Operator or tenant Admin; `tenantadmin` → tenant Admin; `globaladmin` →
+Global Admin only. **Own-tenant binding:** the session's tenant is resolved *before* the gate
+(GA cross-tenant fallback via `FindSessionTenantIdAsync`), and tenant-role inputs are zeroed
+when the resolved tenant differs from the caller's JWT tenant — so a GA who is also an admin of
+their home tenant can never write another tenant's operator/tenantadmin lanes. Cross-tenant, a
+GA writes exactly the `globaladmin` lane (the platform labeling flow).
+
+**GA lane is platform-internal.** `GetSessionAnnotationsFunction.FilterLanesForCaller` drops the
+`globaladmin` lane for every caller without `HasGlobalScope` (tenant members and delegated
+admins). Both list endpoints enforce the same rule server-side via the repository's
+`excludeGlobalAdminLane` OData clause — on the global route this matters exactly for the
+delegated-rescue path, which reaches it without global scope. Tenant lanes are readable by all
+members of that tenant.
+
+**Audit.** Non-GA writes/clears log `LogAuditEntryAsync(..., "SessionAnnotation",
+"{sessionId}/{lane}", ...)`; GA writes are skipped (platform-internal labeling must not surface
+in the tenant-visible audit log — same convention as GA session-report submissions).
+
+# Lifecycle
+
+* **Per-session cascade delete**: three exact-RK steps (one per lane) in `DeletionManifestBuilder`
+  (orders 17–19; inventory 20/21, tombstone 22). `ComputePreflightCounts` sums repeated-table
+  steps so the `sessionAnnotations` count covers all lanes.
+* **Tenant offboarding**: `SessionAnnotations` is in the PK=tenantId wipe list — deliberately
+  wiped, unlike `Feedback` (annotations are customer session data, not product feedback).
+* **Backup**: member of `Constants.CriticalBackupTables.All` — hand-labeled data is the most
+  expensive data on the platform to lose.
+* Being in `Constants.TableNames.All` auto-creates the table at startup and exposes it to the
+  raw `list_tables`/`query_table` tools.
+
+# Surfaces
+
+* **Portal**: `SessionAnnotationsCard` on the session detail page (`#section-annotations`, after
+  Analysis; registered in BOTH the section div and the `sessionSections` sidebar registry). The
+  card mirrors the matrix via the pure module `sessionAnnotationLogic.ts` (vitest-pinned) and
+  uses the explicit-Save pattern; the backend re-gates every save. Collapsed by default with a
+  count + verdict-pill summary header.
+* **Portal overview page** `/annotations` (Monitoring sidebar group — deliberately NO new
+  "Insights" group; Fleet Health & co. are insights too and a second analytics group would
+  dilute both): tenant-scoped list backed by `GET sessions/annotations/list`
+  (`ListTenantSessionAnnotationsFunction`, MemberRead + QueryParam). The path sits under the
+  `/api/sessions` client-cert exclusion prefix (rename-over-exclusion convention; the Azure
+  exclusion list is portal-only config) and uses THREE segments because a two-segment literal
+  would be eaten by the `sessions/{sessionId}` route template. The tenant is always the
+  middleware-validated `TargetTenantId`, and for callers without global scope the repository
+  adds a server-side `Lane ne 'globaladmin'` OData clause — hidden rows never consume page
+  budget, and an explicit lane=globaladmin filter self-contradicts to an empty page. Rows
+  deep-link to `sessions?id=…#section-annotations`. The page carries the standard tenant
+  switcher (`useAggregatedAdminScope` + `TenantScopeSelector`): a GA/Reader defaults to the
+  "All tenants" aggregate (the portal twin of MCP's `list_session_annotations`) with per-tenant
+  drill-down, a delegated ("MSP") admin gets the managed subset; cross-tenant scopes route to
+  `GET global/session-annotations`, a tenant column appears, and deep links carry the row's
+  `tenantId`.
+* **MCP read**: `get_session_summary` carries an `annotations` key (4th parallel leg, fail-soft
+  null); `list_session_annotations` (`ga`-gated) is the evaluation stream with `tenantId / lane /
+  verdict / ruleId / dateFrom / dateTo` filters and nextLink pagination. The `ruleId` filter is
+  applied server-side but client-of-Azure (substring on the JSON column), so the backend
+  back-fills short pages by looping the Azure continuation (bounded rounds) — filtered-out rows
+  never consume page budget.
+* **MCP write**: `annotate_session` (`strictGa`-gated, MUTATING) always PUTs the `globaladmin`
+  lane — no lane argument by design. This is the frictionless labeling path after a session-debug.
+* **Session reports**: `SessionReportService.SubmitReportAsync` snapshots ALL lanes into
+  `annotations.json` inside the report ZIP (`annotationCount` in report-metadata.json; fail-soft).
+  Safe because report blobs are readable only through the GA-only session-reports routes, and
+  valuable because the ZIP outlives the session's retention/delete.
+
+# Citations
+
+* `src/Shared/AutopilotMonitor.Shared/Models/SessionAnnotation.cs` — model, lanes, verdicts.
+* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableSessionAnnotationRepository.cs` — Store/Map + query back-fill.
+* `src/Backend/AutopilotMonitor.Functions/Functions/Annotations/` — the three endpoints.
+* `src/Backend/AutopilotMonitor.Functions/Pagination/SessionAnnotationsPagination.cs` — filter-bound continuation tokens.
+* `src/Web/autopilot-monitor-web/app/sessions/components/sessionAnnotationLogic.ts` — portal matrix mirror.
+* `src/McpServer/autopilot-monitor-mcp/src/tools/admin.ts` — `list_session_annotations`, `annotate_session`.

docs/backend/tenant-activation-welcome-mail.md

@@ -0,0 +1,75 @@
+---
+type: concept
+title: Tenant Activation & the Once-Only Welcome Mail
+description: How a signup becomes an activated tenant (manual approve or auto-approve queue), and how the welcome mail is sent exactly once even though activation and the user-provided address race each other.
+resource: backend
+tags: [activation, auto-approve, welcome-email, preview-whitelist, race]
+timestamp: 2026-08-02
+---
+
+# Schema
+
+## Activation
+
+A tenant is **activated** when the row `PartitionKey={tenantId}, RowKey="approved"` exists
+in the `PreviewWhitelist` table (legacy name kept on purpose). Everything else in the
+portal gates on that row via `PreviewWhitelistService.IsApprovedAsync` (5 min positive /
+30 s negative cache).
+
+Two activation routes, one shared implementation
+(`TenantApprovalService.ApproveWithSideEffectsAsync`):
+
+* **Manual**: Global Admin approves in the admin panel (`POST /api/preview/whitelist/{tenantId}`).
+* **Auto**: signup unconditionally enqueues a `tenant-auto-approve` envelope; the queue
+  worker (`TenantAutoApproveHandler`) re-checks the `AutoApproveNewTenants` flag
+  (uncached, fail-closed), the suspension gate (fresh config read), then approves.
+  Typical latency: ~1 minute after signup.
+
+The whitelist add is a **conditional INSERT** (`AddEntityAsync`, 409 = lost) — storage
+arbitrates concurrent activations; exactly one caller runs the side effects
+(TenantAdmin auto-promote of the signup UPN, welcome mail, `TenantAutoApproved` ops event).
+
+## The welcome-mail race
+
+The welcome mail goes to the **notification email** (`RowKey="notification-email"` in the
+same table) — the only reliable address: it is typed by the user on the activation-pending
+page (`PUT /api/preview/notification-email`). The signup admin UPN may have no mailbox and
+`ContactEmail` is merely seeded from the notification email.
+
+That makes activation and address entry concurrent writers. With auto-approve, activation
+usually wins (observed in production: approve at T+64 s, address saved at T+69 s → the
+approval path found no address and the mail was silently skipped).
+
+**Arbitration — write-then-read on both sides plus a send-once marker:**
+
+* The approval path writes the `approved` row, then reads the address.
+* The save path (`SavePreviewNotificationEmail`) writes the address row, then checks
+  approval **fresh** (`IsApprovedFreshAsync` — the 30 s negative cache would hide the
+  activation for exactly this window).
+* Since both do write-then-read, at least one sees both halves and calls
+  `TenantApprovalService.TrySendWelcomeEmailAsync`.
+* There, a conditional insert of `RowKey="welcome-email-sent"` decides who actually
+  sends: at most one wins. The marker is consumed strictly **after** the address check —
+  consuming it without an address would permanently suppress the mail.
+
+Marker lifecycle: revoke (`RevokeAsync`) deletes it (re-approve = fresh activation =
+fresh mail); the offboarding cascade wipes the whole `PreviewWhitelist` partition anyway.
+The Global-Admin resend endpoint (`POST /api/preview/send-welcome-email/{tenantId}`)
+always sends (explicit intent) and consumes the marker best-effort so the automatic
+paths never duplicate afterwards.
+
+# Examples
+
+* Auto-approve wins the race: approve at T+64 s finds no address → logs "deferred to the
+  notification-email save path"; user saves address at T+69 s → save path sees approved
+  (fresh read), wins the marker, sends. Response carries `welcomeEmailSent: true`.
+* Address saved before manual approve (classic shape): approval path finds the address,
+  wins the marker, sends; a later re-save of the same address does not re-send.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Services/TenantApprovalService.cs` — shared activation + `TrySendWelcomeEmailAsync`
+* `src/Backend/AutopilotMonitor.Functions/Services/Activation/TenantAutoApproveHandler.cs` — queue-side gates
+* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/PreviewWhitelistFunction.cs` — save-path trigger, GA resend
+* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableConfigRepository.cs` — conditional inserts (approved / welcome-email-sent)
+* `src/Backend/AutopilotMonitor.Functions.Tests/TenantApprovalServiceTests.cs` — ordering + dedup pins

docs/backend/time-attribution.md

@@ -0,0 +1,124 @@
+---
+type: Concept
+title: Enrollment Time Attribution (F1)
+description: How a terminal session's wall clock is partitioned into named segments with an explicit unattributed remainder, how ESP-blocking apps and reboots are attributed, and where breakdowns and fleet aggregates are computed, stored and served.
+resource: src/Backend/AutopilotMonitor.Functions/Helpers/TimeAttributionCalculator.cs
+tags:
+  - backend
+  - metrics
+  - time-attribution
+  - insights
+timestamp: 2026-07-26T20:00:00+02:00
+---
+
+# Enrollment Time Attribution (F1)
+
+Answers "where did the 47 minutes go?" per session and per fleet. Every number is
+traceable to observed events; a missing signal produces "unknown" or an explicit
+unattributed remainder — never a guess, and the partition is never normalized to 100 %.
+
+# Schema
+
+## Invariant
+
+For every computed breakdown:
+
+```
+sum(span seconds) + UnattributedSeconds == WallClockSeconds == session DurationSeconds
+```
+
+`DurationSeconds` is the authoritative wall clock — for WhiteGlove it is part 1 + part 2
+WITHOUT the pause, and re-terminal stamps move `CompletedAt`, so `CompletedAt − StartedAt`
+is never used (it diverges in ~25 % of terminal sessions). Span seconds are floored;
+sub-second dust lands in the unattributed remainder.
+
+## Observation windows
+
+Windows are end-anchored on authoritative timestamps and constructed so their lengths sum
+exactly to `DurationSeconds`:
+
+* Non-WhiteGlove: one window `[CompletedAt − DurationSeconds, CompletedAt]`.
+* WhiteGlove (ONE session row, two windows): part 2 = `[ResumedAt, CompletedAt]`; part 1 =
+  `[part1End − (DurationSeconds − part2), part1End]` where `part1End` is anchored on the
+  `whiteglove_part1_complete` event. The pause between the windows is never attributed.
+  Fallback anchors set the `WhiteGloveAnchorsIncomplete` quality flag.
+
+## Segments
+
+Spans are sliced at phase-declaration events (only declaration events carry
+`Phase != Unknown`) plus `desktop_arrived`, in canonical Sequence order; anchors whose
+timestamp runs backward are dropped (`ClockSkewDropped`).
+
+| EnrollmentPhase | Segment key |
+|---|---|
+| Start / DevicePreparation / DeviceSetup | `device_prep` |
+| AppsDevice | `esp_apps` |
+| AccountSetup / FinalizingSetup | `identity_hello` |
+| AppsUser | `user_esp` |
+| Complete, `desktop_arrived` event | `desktop_handoff` |
+| Failed | attribution ends — tail stays unattributed |
+
+## ESP-blocking apps (positive evidence only)
+
+Per-app intervals use EVENT timestamps (first started/download event → LAST terminal
+event, covering IME retries) — never the agent payload timing, which freezes at the first
+terminal transition. Blocking membership joins the app id against the session's latest
+list-carrying `esp_config_detected` emission: listed ⇒ blocking; absent ⇒ unknown, never
+false (`BlockingSetUnknown` / `BlockingSetTruncated` flags). Critical-path occupancy =
+overlap-merged union of blocking intervals clipped to the `esp_apps` spans;
+`EspAppsOccupancySeconds` is null (unknown) when no lists were observed.
+
+The fleet what-if bound per app X is `max(0, cpEnd − cpEndWithoutX)` (latest interval end
+with vs. without X; the idle gap before X counts — the ESP also waits for X to start).
+It is an upper bound by construction; every consumer says "up to", never "you will save".
+
+## Reboots
+
+`system_reboot_detected` is detection-time-stamped by the NEXT agent run; the real boot
+moment is its `lastBootUtc` payload. Reboot spans are therefore the event-stream gap
+bracketing `lastBootUtc`, deduped per boot, clipped to the observation windows, and carried
+as a cross-cutting annotation (they overlap the segment they started in — never a slice of
+the partition).
+
+## Persistence & compute
+
+* `SessionTimeBreakdowns` (PK = TenantId, RK = SessionId): spans, reboot spans, blocking
+  intervals (top 20 + uncapped count), quality flags, `AttributionVersion`. Written once at
+  the session-terminal single-writer seam (`TableSessionRepository.UpdateSessionStatusAsync`,
+  Succeeded/Failed only — Incomplete deliberately has no duration). Deleted with its session
+  (deletion-manifest step) and on tenant offboarding.
+* Self-healing 30-day maintenance sweep (2h tick): backfills missing breakdowns, folds
+  late-terminating sessions into their StartedAt-date aggregates, and enforces version
+  purity — a stale-version row whose events aged out counts as missing, never mixed.
+* `TimeAttributionAggregates` (PK = TenantId or `global`, RK = `{yyyy-MM-dd}|{class}` and
+  `rolling30|{class}`): per enrollment class (`user_driven`, `whiteglove`, `self_deploying`,
+  `device_preparation` — never mixed) median/p75/p90 per segment over the fixed six-segment
+  stack (incl. `unattributed`; a session without a segment contributes 0), plus top blocking
+  apps (≥5 sessions per app row). Clean/flagged/missing counts are part of every row; rows
+  exist below the ≥20 UI gate on purpose (the UI needs the n for "insufficient data (n=…)").
+  Daily rows retain 180 days; `rolling30` rows are refreshed whole (a median of per-day
+  medians is not the range median — the rolling rows are the honest range statistics).
+
+## Surfaces
+
+* `GET api/sessions/{sessionId}/time-attribution` (MemberRead + tenant query param) —
+  breakdown row or `breakdown: null` (pre-feature / non-terminal / Incomplete = no lane).
+* `GET api/metrics/time-attribution` (MemberRead) / `GET api/global/metrics/time-attribution`
+  (GlobalReadOrAdmin, optional `tenantId`) — `{ windowDays, classes (rolling), daily }`.
+* Web: attribution lane under the session-detail phase timeline; "Time attribution" section
+  on Fleet Health. MCP: `get_time_attribution` (sessionId mode / fleet mode).
+
+# Examples
+
+A 30-minute user-driven session: `device_prep` 5m → `esp_apps` 10m (occupancy 4m by one
+blocking app) → `identity_hello` 8m → `user_esp` 5m → `desktop_handoff` 2m, unattributed 0.
+A WhiteGlove session with a 2-day pause reports wall clock = part1 + part2 only; the resume
+gap before the first part-2 phase declaration is unattributed, not guessed.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Helpers/TimeAttributionCalculator.cs` — calculator + semantics (AttributionVersion 1).
+* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.TimeAttribution.cs` — persistence.
+* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.Aggregation.cs` — sweep + aggregation.
+* `src/Backend/AutopilotMonitor.Functions.Tests/TimeAttributionCalculatorTests.cs` — golden fixtures pinning the invariant.
+* `tasks/insights-expansion-spec.md` — F1 specification and source-data audit (§0.5).

docs/drift-guards.md

@@ -0,0 +1,106 @@
+---
+type: Concept
+title: Drift Guards — SignalR Names, RowKeys, Config Sections, Scoped Routing
+description: The 2026-08 fragility-audit follow-up contracts that turn formerly hand-synchronized mirrors into enforced ones — SignalR message-name catalog, the inverted-tick RowKey codec, tombstone table tagging, the OkAsync ratchet, per-section config PATCH, and the web's scoped-endpoint builders.
+resource: /src/Backend/AutopilotMonitor.Functions.Tests/OkAsyncBaselineGuardTests.cs
+tags:
+  - contracts
+  - guard-tests
+  - signalr
+  - web
+timestamp: 2026-08-13T00:00:00+02:00
+---
+
+# Drift Guards
+
+Follow-up to the 2026-08 fragility audit (see [Lifecycle Manifests & Session Scope
+Resolution](backend/lifecycle-manifests-and-session-scope.md) for the earlier rounds).
+Each section below replaces a hand-synchronized mirror with an enforced contract: a
+change on one side now fails a build, a type check, or a test on the other side.
+
+# Schema
+
+## SignalR message names — one catalog, typed on both ends
+
+`Constants.SignalRMessages` (Shared) is the complete catalog of SignalR target names.
+Backend senders (output bindings and the imperative `SignalRNotificationService`)
+reference the constants; the hub name is `SignalRGroupHelper.HubName`. The catalog is
+exported into `shared-manifests.json` (`signalRMessages` section) by
+`SharedManifestParityTests`, and the web's `SignalRContext.on/off` type their event
+name against the generated union (`lib/signalrMessages.ts`) — subscribing to a name
+the backend never sends is a tsc error, not a silent no-op. `newevents` is the one
+legacy lowercase name; it is a persisted wire name, do not "fix" the casing.
+
+## Inverted-tick RowKeys — one codec
+
+`RowKeyCodec` (Functions/Helpers) is the single encoder/decoder for
+`rev(t) = MaxTicks - t.Ticks` RowKeys. Every writer routes through it; the persisted
+per-table shapes (D19 standard, AuditLogs `!`-prefix, UserActivity's legacy D20 width,
+ConfigurationBackups' 28-char truncation) are pinned by `RowKeyCodecTests` and must
+never change — a width/prefix change reorders live tables against their existing rows.
+`BusinessTimestamp` keeps the OData clause builders and delegates decode to the codec.
+
+## Tombstone rows carry their table
+
+`DeletionRowDump.Table` names the source table on FINAL (Tombstone) rows — the one
+step that mixes two tables while `DeletionStep.Table` is null.
+`DeletionTombstoneTables.Resolve` is the only consumer-side resolution (delete +
+restore + dry-run); the historical `Contains('_')` RowKey-shape heuristic survives
+solely as the fallback for manifests written before the field existed and must outlive
+one full manifest-retention cycle.
+
+## Anonymous OkAsync responses — frozen, shrink-only
+
+`OkAsyncBaselineGuardTests` freezes the 44 existing `req.OkAsync(new { … })` call
+sites as a per-file baseline. A new anonymous response (new file or count above
+baseline) fails; converting a site to a typed DTO (Shared response models, picked up
+by the manifest parity tests) fails too until its baseline entry is lowered — the debt
+list stays truthful and only ever shrinks.
+
+## Tenant settings — per-section PATCH
+
+The web's Settings sections no longer PUT the full ~92-field configuration. Each
+section's exact write surface lives in `app/settings/sectionFieldMap.ts` (owned fields
+plus documented `alsoWrites` write-throughs); `saveConfiguration` diffs those fields
+against the loaded config and PATCHes only the changes through
+`PATCH config/{tenantId}/fields` — the transactional endpoint (CAS + fail-closed
+backup + exactly-these-fields verify + auto-rollback) that previously served MCP only.
+The policy line is TenantAdminOrGA; a tenant admin runs on the stricter
+`TenantConfigCallerTier.TenantAdmin` whose deny-list turns GA-only fields into
+explicit 400s. Deploy order: backend before web. `sectionFieldMap.test.ts` pins
+field↔section ownership (each field exactly one owner, all fields on the model, none
+server-denied); backups/revert stay GlobalAdminOnly.
+
+## Scoped endpoint routing — one decision object
+
+`lib/scopedApi.ts` owns the tenant/global endpoint-pair choice: pages pass their scope
+hook object (`routeGlobal`, `selectedTenantId`, `effectiveTenantId`) instead of
+hand-rolling `routeGlobal ? global(..., sel || undefined) : tenant(tid, ...)` with the
+tenant parameter at a different position per pair. `useGlobalAdminScope` is now a thin
+projection over `useAggregatedAdminScope` (one hook, aggregated as a mode) via the
+pure `resolveConcreteScopeView`. `lib/scopedFetch.ts` adds the shared JSON+ok-check
+fetch layer. `lib/navVisibility.ts` extracts the sidebar's roles × nav-config × guard
+logic; its matrix test also ratchets the known "sidebar shows it, guard bounces it"
+mismatches (plain Operator and GlobalReader vs. `/settings` — pending a user decision).
+
+# Examples
+
+Renaming a SignalR message end to end: change the constant in
+`Constants.SignalRMessages` → `AM_WRITE_SHARED_MANIFESTS=1 dotnet test --filter
+SharedManifestParityTests` → `node scripts/generate-shared-manifest-types.js` → tsc
+now flags every stale web subscription literal.
+
+Adding a field to a Settings section: add it to the section in `sectionFieldMap.ts`
+(tsc validates the name against the manifest), wire the form state into the
+`updatedConfig` construction in `TenantConfigContext`, and extend the expected-fields
+list in `sectionFieldMap.test.ts`.
+
+# Citations
+
+- `src/Shared/AutopilotMonitor.Shared/Constants.cs` — SignalRMessages catalog
+- `src/Backend/AutopilotMonitor.Functions/Helpers/RowKeyCodec.cs` + `RowKeyCodecTests.cs`
+- `src/Shared/AutopilotMonitor.Shared/Models/Deletion/DeletionManifest.cs` — `DeletionRowDump.Table`, `DeletionTombstoneTables`
+- `src/Backend/AutopilotMonitor.Functions.Tests/OkAsyncBaselineGuardTests.cs`
+- `src/Web/autopilot-monitor-web/app/settings/sectionFieldMap.ts` + `__tests__/sectionFieldMap.test.ts`
+- `src/Web/autopilot-monitor-web/lib/scopedApi.ts`, `lib/navVisibility.ts`, `hooks/concreteAdminScopeView.ts`
+- [Version Contract](versioning.md) — the web `/version.json` stamp + deploy verify added in the same round

docs/index.md

@@ -14,27 +14,49 @@ https://docs.autopilotmonitor.com (separate repository).
 * [Architecture Guide](architecture.md) - High-level architecture overview and solution layout for contributors.
 * [Version Contract](versioning.md) - One version shape for agent, backend and MCP: the ETag-CAS counter blob that mints build numbers, and the manifests published only after a deploy is verified live.
 * [URL Registry](url-registry.md) - Every well-known host lives in one registry file per component (Constants.cs / utils/config.ts / src/config.ts), enforced by guard tests; includes the agent-download migration to the download alias and its deploy-order constraint.
+* [Drift Guards](drift-guards.md) - The 2026-08 fragility-audit follow-up contracts: SignalR message-name catalog (typed on both ends), the inverted-tick RowKey codec, tombstone table tagging, the shrink-only OkAsync baseline, per-section config PATCH with the section field map, and the web's scoped-endpoint builders + sidebar visibility matrix.
 
 # Agent
 
 * [V2 Agent](agent/index.md) - How the on-device agent works: [runtime overview](agent/overview.md), [decision engine](agent/decision-engine.md) (reducer, signals, completion arms), [logs & persistence](agent/logs-and-persistence.md) (signal log, snapshot, crash recovery), [Hello wizard un-skip](agent/hello-wizard-unskip.md) (why a single "WHfB disabled" read never decides completion), [Autopilot ZTD diagnostics](agent/autopilot-ztd-diagnostics.md) (event IDs, diagnostic registry, endpoints, error-code map).
 * [Build Counter Blob](agent/build-counter-blob.md) - How agent build numbers are minted: shared counter blob with ETag-CAS so local and CI builds never collide; CI additionally attests build provenance (Sigstore).
 * [Agent Endpoint Migration](agent/endpoint-migration.md) - How the backend re-homes agents to a new API base URL via the config channel (backend move or per-tenant region move): live-fetch-only, allowlist-validated on both sides, one hop, kill wins.
+* [Gather Rule Debug Log](agent/gather-rule-debug-log.md) - EnableGatherRuleDebugLog (ConfigVersion 36): the per-tenant local trace file that explains every gather-rule evaluation decision — scope skips, on_change suppression, empty collector results, logparser position/parse-mode outcomes — for rules that produce no timeline events.
 * [MDM Reboot Coalescing](agent/mdm-reboot-coalescing.md) - Attributing the mid-ESP coalesced reboot ("second sign-in") to the device-assigned policy URIs that forced it: aggregated DM-Enterprise 2800 observations (neutral, flush-time watermark) + the ANALYZE-ESP-005 advisory gated on an actually-observed reboot.
 * [Secure Boot CA-2023 Detection](agent/secureboot-ca2023-detection.md) - Why ANALYZE-SEC-001 v3 reads the UEFI db/KEK variables directly instead of trusting the SecureBoot\Servicing registry, and how the one-sided uefiCa2023FirmwareConfirmed marker plus a not_exists precondition give absence-tolerant suppression across old and new agents.
+* [Continue-Anyway Observation Mode](agent/continue-anyway-observation.md) - EnableEspContinueAnywayObservation (ConfigVersion 37, operator-set): Device-phase ESP terminal failures on Continue-Anyway profiles get a bounded 60-min observation instead of an immediate hard fail; the DAD-validated real-user desktop + Hello gate detect the true end, the session completes Succeeded + EspSoftFailure (amber "with issues" badge), expiry un-defangs to the original esp_terminal_failure.
+* [Registry App-State Second Pillar](agent/registry-app-state-pillar.md) - IME's authoritative per-app state read straight from the registry (Win32Apps EnforcementStateMessage, EspTrackingWin32Apps, StatusServiceReports) via a snapshot-and-diff watcher; registry/log reconciliation doubles as the built-in IME log-pattern drift alarm.
+* [ESP Policy-Provider Stall Detection](agent/esp-policy-provider-stall.md) - The EnrollmentStatusTracking CSP's no-timeout Setup/Apps wait is keyed to the Intune-registered "Sidecar" provider by NAME: co-management's "ConfigMgr" parks the user ESP at "Apps (Identifying)" for days even with TrackingPoliciesCreated=1 (issue #106); the always-on two-arm esp_policy_provider_stalled tripwire (provider_incomplete | sidecar_provider_missing) and the SOFTWARE\Microsoft\Windows\Autopilot gather-rule allowlist entry that surface it.
 
 # Rules
 
 * [Gather Rule Phase Scoping, One-Shot Triggers & Emit-on-Change](rules/gather-rule-phase-scoping.md) - Restricting gather rules to enrollment phases (activePhases / activeFromPhase sticky latch), one-shot collection at a phase's start/end (phase_change / phase_exit), and emitMode "on_change" result-dedup.
 * [Gather Rule Guardrails](rules/gather-rule-guardrails.md) - Why the allowlists in rules/guardrails.json are enforced on the agent and nowhere else, which hard blocks survive unrestricted mode, and the rule that every collector must call a guard and emit security_warning on refusal.
+* [Rule Authoring Surface](rules/rule-authoring-surface.md) - How customer AIs author rules against the real contract: the baked MCP resources (guide/schemas/guardrails via combine.js), the MCP-local validate_rule pre-flight, and the side-effect-free POST rules/analyze/dryrun whose trace twin shares the production evaluators (parity + side-effect-freedom pinned by tests).
+* [Analyze Rule Evaluation Triggers](rules/analyze-rule-triggers.md) - Opt-in `evaluateOn` interim triggers (`whiteglove_sealed`, `on_event:<type>`) so rules can fire before a session is terminal, with RuleResults update-semantics (interim → finalize/resolve, NotifiedAt notification dedupe) replacing the permanent dedupe freeze, KO/stat suppression on interim runs, the ingest-side cached trigger registry, and the authoring lints that keep interim rules monotonic.
 
 # Backend
 
 * [Business Timestamps](backend/business-timestamps.md) - Why the Azure Tables system Timestamp is never authoritative (migrations reset it), and the OccurredUtc + RowKey-decode compensation for AuditLogs/OpsEvents/Events after the 2026-07-18 migration.
+* [OOBE Bootstrap go-Code Flow](backend/oobe-bootstrap-go-flow.md) - The bootstrap short-code lifecycle (portal-created session → `irm go.autopilotmonitor.com/CODE | iex` at Shift+F10 → GetBootstrapScriptFunction), the always-HTTP-200 text/plain contract, the two-line injection defense (GUID/URL/expiry validator + single-quoted PS literals, golden-pinned against the legacy TS template), and the per-IP rate-limit story behind Front Door.
+* [Device Journeys & First-Time-Right](backend/device-journeys.md) - How a device's terminal enrollment attempts are grouped into journeys (trim+casefold device key with junk-serial exclusion, first-success end, 30-day gap, WhiteGlove = one attempt), the DeviceHistories chain with its tombstone-driven deleted-session pruning, the additive daily FTR aggregates, and the banner/fleet/MCP surfaces.
+* [Enrollment Time Attribution](backend/time-attribution.md) - How a terminal session's authoritative wall clock (DurationSeconds, WhiteGlove pause excluded) is partitioned into named segments with an explicit unattributed remainder, ESP-blocking apps as positive evidence with "up to" what-if bounds, reboot spans from event gaps, and the breakdown/aggregate tables the sweep maintains.
+* [Rule Regression Radar](backend/rule-regression-radar.md) - How analyze-rule hit-rate regressions are detected (7-day window ≥2× the 28-day baseline with disjoint Wilson intervals), which suppressions keep the radar quiet (grace period, edit-in-window, kill switch), how alert episodes live in the ruleregression tracker keyspace with re-arm semantics, and the on-fire dimension correlation with its "correlated, not necessarily causal" wording contract.
+* [App Version Duration Regression Radar](backend/app-version-regression-radar.md) - How app versions whose median install duration regressed vs. the previous version are detected (first-seen-ordered versions, median lift ≥2× plus a 5-minute absolute floor over measured installs only), how alert episodes live in the appversionregression tracker keyspace with drain/median re-arm semantics, and the bell/ops-event/analytics surfaces.
+* [Tenant Activation & the Once-Only Welcome Mail](backend/tenant-activation-welcome-mail.md) - How a signup becomes an activated tenant (manual approve or the auto-approve queue), and the write-then-read + conditional-marker arbitration that sends the welcome mail exactly once even though activation and the user-typed notification address race each other.
+* [W365 Cloud PC Device Validation](backend/cloudpc-device-validation.md) - Why Cloud PCs can never pass the Autopilot serial lookup, and the cert-CN-bound CloudPc fallback validator: Subject CN (= Intune device id) matched against the tenant's Graph virtualEndpoint/cloudPCs inventory — admits exactly the service-provisioned Cloud PCs, nothing else.
+* [ServerActions & On-Demand Diagnostics](backend/server-actions-on-demand-diagnostics.md) - The queue-on-session, deliver-on-ingest action channel, the TenantAdminOrOperator tier with in-function per-type re-gating, the portal's Collect Logs flow (quick-config orders rotate_config before request_diagnostics), and the hosted-prefix sweep in the offboarding cascade.
+* [Session Annotations](backend/session-annotations.md) - Role-separated human verdicts on sessions (operator / tenantadmin / globaladmin lanes, one row each): the per-lane write matrix with own-tenant binding, the platform-internal GA lane, the fired-rule-id snapshot that makes annotations rule-quality labels, and the portal card + MCP list/annotate surfaces.
+* [Lifecycle Manifests & Session Scope Resolution](backend/lifecycle-manifests-and-session-scope.md) - The fragility-audit P5/P6 completeness nets: every table classified into a deletion lifecycle (offboarding buckets incl. the RowKey-anchored SafeWipe Variant D, per-session cascade, kept-by-design), the SessionsIndex field manifest with bidirectional builder/reader pinning, the single ResolveSessionScopeAsync helper backed by the SessionTenantLookup point-read, and the server-side dashboard free-text search (q=) with its page-backfill loop.
 
 # MCP Server
 
 * [MCP Docs Corpus](mcp/docs-corpus.md) - How the published customer documentation becomes the `search_docs` corpus: CRLF-safe heading chunking, build-time embedding as a third precomputed section, and why a docs edit needs an MCP redeploy.
+* [MCP Tool Telemetry](mcp/tool-telemetry.md) - The three telemetry layers for judging tool quality: backend App Insights via X-MCP-Tool-Name, the per-user usage table, and the MCP_TOOL_LOGGING stderr lines (soft errors, result size vs. cap, zero-hit searches, Zod rejections).
+
+# Web Portal
+
+* [Portal Navigation Prefetch & the SWA Runtime Bottleneck](web/portal-navigation-prefetch.md) - Why every navigation Link sets `prefetch={false}`: the App Router's viewport prefetch fans out one RSC request per visible link and the Static Web Apps SSR runtime queues them server-side into a multi-minute tail. Records the follow-up measurement (the Standard plan changed nothing; the prefetch storm was an accidental keep-alive), where browser telemetry actually lives, and why this curl build cannot be trusted for HTTP versions.
 
 # Security & Identity
 

docs/log.md

@@ -1,6 +1,118 @@
 # Log
 
-## 2026-07-23
+## 2026-08-18
+
+* **Update**: `agent/logs-and-persistence.md`, `agent/overview.md`, `agent/gather-rule-debug-log.md` — log files renamed to unified kebab-case: `agent.log` (date rotation dropped; size segments `agent-NNN.log`), `bootstrap-script.log` (was `bootstrap_agent.log`), `bootstrap-msi.log` (was `msi-bootstrap.log`), `crash-*.log`, `gather-rules-debug.log`, `ime-pattern-matches.log`. Old names still appear in archives from pre-rename agents.
+* **New**: `agent/registry-app-state-pillar.md` — the registry second pillar for IME app state (audit follow-up): snapshot-and-diff watcher on `HKLM\...\IntuneManagementExtension` (Win32Apps / EspTrackingWin32Apps / StatusServiceReports), `registry_app_state` + `app_state_reconciliation` events, silent startup baseline, WDP reuse notes.
+
+## 2026-08-17
+
+* **Update**: `mcp/tool-telemetry.md` — the `tool_call` stderr line now carries `errorMessage` (capped at 300 chars; thrown message or the leading `toolError` text, absent on success), so error drilldowns name the failure class instead of guessing from args. Same change: `get_rule_stats` omits the per-rule daily `trend` rows by default (they drove 50% of calls over the response cap at platform scope); `includeTrends=true` opts back in, the response carries a `trendsNote` marker when stripped.
+
+## 2026-08-14 (later)
+
+* **Update**: `rules/analyze-rule-triggers.md` — status SPEC → IMPLEMENTED. Shipped: `evaluateOn` on the analyze-rule schema (grammar-validated server-side and in validate_rule), `AnalyzeRunContext`-driven engine runs (Terminal/Interim/Reanalyze) with the RuleResult lifecycle columns (FirstDetectedAt/LastEvaluatedAt/IsInterim/ResolvedAt/NotifiedAt), interim rule filtering + KO/stat suppression, resolve/finalize update-semantics, the NotifiedAt one-send-per-(session,rule) notification dedupe (preserved across the manual reanalyze rebuild), the ingest-side `InterimTriggerRegistry` (5-min TTL, fail-soft) gating `interim_trigger` / `whiteglove_sealed` enqueues, the three MCP authoring lints, web preliminary/resolved rendering, and ANALYZE-ID-004 as the first interim-enabled rule.
+
+## 2026-08-14
+
+* **Creation**: Added `rules/analyze-rule-triggers.md` — SPEC for opt-in `evaluateOn` interim evaluation of analyze rules: `enrollment_end` default preserves today's behavior, `whiteglove_sealed` + `on_event:<type>` close the WhiteGlove notification gap and the never-terminal stuck-session gap; RuleResults update-semantics (FirstDetectedAt/IsInterim/ResolvedAt/NotifiedAt) replace the permanent dedupe freeze; interim runs suppress KO + stats, notifications fire on first detection; three new validate_rule lints (terminal-precondition trap, unknown trigger type, KO-on-interim).
+
+## 2026-08-13 (late evening)
+
+* **Creation**: Added `drift-guards.md` — the fragility-audit follow-up contracts (P5.x + P7): SignalR message-name catalog in `Constants.SignalRMessages`, exported through the shared manifest and typed into the web's `SignalRContext.on/off` union; the `RowKeyCodec` single encoder for inverted-tick RowKeys (persisted widths pinned, incl. UserActivity's legacy D20); `DeletionRowDump.Table` on tombstone rows with `DeletionTombstoneTables.Resolve` replacing the duplicated `Contains('_')` heuristic (legacy fallback retained one retention cycle); the shrink-only `OkAsyncBaselineGuardTests` per-file baseline (44 sites frozen); the Settings per-section PATCH (section field map + diff-based `config/{tenantId}/fields` writes on the TenantAdmin caller tier); and the web's `scopedApi` endpoint-pair builders, single admin-scope hook, `navVisibility` matrix and guard-consistency ratchet.
+
+* **Update**: `versioning.md` — the web portal joins the version contract commit-only: `public/version.json` generated at build time from `GITHUB_SHA`, served with `Cache-Control: no-store`, polled by `deploy-web.yml` until the deployed commit matches before `versions/web.json` is published.
+
+## 2026-08-13 (evening)
+
+* **Creation**: Added `backend/lifecycle-manifests-and-session-scope.md` — the fragility-audit P5/P6 completeness nets: (1) `TableLifecycleBucketTests` classifies every `TableNames` constant into offboarding-wipe / per-session-cascade / kept-by-design (fixed en route: UsageMetrics wiped via the new RowKey-anchored SafeWipe Variant D — the exact-PK wipe matched 0 rows; PlatformStats tenant partition + ScriptNameCache added to the tenant-PK bucket); (2) `SessionIndexFieldManifest` as the declared SessionsIndex column set with bidirectional builder/reader test pinning, Replace-mode full rebuilds, and a fail-soft merge-key guard; (3) `ResolveSessionScopeAsync` as the single session-scope fallback (16 former copies), backed by the new `SessionTenantLookup` point-read table (scan fallback + self-heal, cascade step before the tombstone), plus the `RecomputeTriggerGate` 403 for reanalyze/rescan by read-only roles; (4) server-side dashboard free-text search (`q=`) with page-backfill loop and fingerprint binding, replacing the client's full-history loadAll sweep.
+
+* **Creation**: Added `backend/app-version-regression-radar.md` — app-version duration regression radar: per (tenant, app) the newest version's median measured install duration (nearest-rank; population Succeeded + non-skip + `HasMeasuredDuration` + no AppId collision + non-empty AppVersion) is compared against the previous version (first-seen ordering, never string sort); fires at median lift ≥2× AND ≥300s absolute with ≥10 measured installs on both sides. Episodes live as `appversionregression|{app}|{version}` tracker rows (one bell `app_version_duration_regression` + one `AppVersionDurationRegression` ops event per episode, refresh keeps `FirstNotifiedAt`, re-arm on drain/median-recovery/30d retention). Surfaces: `versionRegressions[]` + per-version `measuredInstalls`/`medianDurationSeconds`/`p95DurationSeconds` in the apps analytics responses, amber banner + duration-by-version chart on the apps detail page. Kill switch `AppVersionRegressionRadarDisabled`.
+
+## 2026-08-13
+
+* **Update**: `backend/session-annotations.md` — the `/annotations` portal overview page now carries the standard tenant switcher (GA/Reader: "All tenants" aggregate + per-tenant drill-down via `GET global/session-annotations`; delegated: managed subset), with a tenant column and tenant-qualified session deep links. The global list endpoint now derives `excludeGlobalAdminLane` from `HasGlobalScope`, so delegated-rescue callers on their managed `?tenantId=` path never receive the platform-internal `globaladmin` lane (endpoint-test-pinned).
+
+## 2026-08-12
+
+* **Update**: `agent/autopilot-ztd-diagnostics.md` — Windows 365 Cloud PC exception documented: on Cloud PCs `ProfileAvailable=0` is expected (provisioned by the Windows 365 service, not Autopilot), so `autopilot_profile_missing` is emitted as Info with a Cloud-PC-specific message and an `isCloudPc` payload marker (`ResolveAutopilotProfileMissingPresentation`); the portal's Autopilot Profile card renders a neutral note instead of the amber warning for Cloud PC sessions (`session.isCloudPc` or the event marker).
+
+## 2026-08-11 (later)
+
+* **Creation**: Added `backend/session-annotations.md` — session annotations: the new `SessionAnnotations` table (PK=tenantId, RK=`{sessionId}_{lane}`, lanes operator/tenantadmin/globaladmin) storing structured verdicts (`root_cause_confirmed | analysis_wrong | different_problem | inconclusive`) + notes with server-stamped authorship and a fired-rule-id snapshot for join-free rule-quality evaluation. Per-lane write matrix re-gated in-function with own-tenant binding (a GA writes only the platform-internal `globaladmin` lane cross-tenant; tenant callers never see that lane). Surfaces: portal `SessionAnnotationsCard` (session detail, after Analysis), MCP `list_session_annotations` (ga) + `annotate_session` (strictGa, always the GA lane) + `annotations` key in `get_session_summary`. Lifecycle: per-session cascade steps 17–19, offboarding wipe, critical-backup member.
+
+## 2026-08-11
+
+* **Update**: `rules/gather-rule-guardrails.md` — hard-block mirroring closed across all pre-flight layers: `rules/guardrails.json` now also mirrors `blockedCommandPatterns` + `maxCommandLength` and carries `C:\Windows\System32\config` in `blockedFilePrefixes`; portal (`guardValidation.ts`) and MCP (`rule-validation.ts`) apply them in agent order (before the unrestricted-mode early-return), so a command the agent hard-blocks no longer shows "Allowed" in unrestricted tenants. `GuardrailsParityTests` pins the JSON mirror to the C# constants. MCP `validate_rule` additionally validates `json`/`xml` targets with file semantics (the schema's `collectorType` enum was missing both) and rejects `activePhases`+`activeFromPhase` set together (backend 400 parity). Author stamping extended to PUT-upserts: tenant and global gather-rule updates stamp the caller's JWT display name before the service call, so an upsert of a non-existing ruleId can no longer store a payload-supplied author (true updates still preserve the original author).
+
+## 2026-08-10
+
+* **Update**: `rules/gather-rule-guardrails.md` — WMI matcher generalized from literal prefix matching to shape parsing: `SELECT <* | property-list> FROM <class>` is allowed when the class is derived from the existing `SELECT * FROM <class>` entries (a projection is a strict subset; motivated by `SELECT BatteryStatus FROM Win32_Battery` + `on_change` battery polling that `SELECT *` defeats via fluctuating charge %). Same algorithm mirrored agent/portal/MCP; guardrails.json unchanged. Portal now also gates enabling on the client-side validation (invalid-target custom rules create disabled, cannot be toggled on, force-disable on invalid edit, "Blocked on devices" badge) — UX only, the agent guard stays the boundary. Gather-rule Author is now stamped from the creator's JWT (display name → UPN) at create and immutable on update.
+
+* **New**: `agent/continue-anyway-observation.md` — Continue-Anyway observation mode (`EnableEspContinueAnywayObservation`, ConfigVersion 37, operator-set): Device-phase ESP terminal failures on Continue-Anyway profiles are defanged into a 60-min observation window (Classic/Unknown, non-pre-prov only); real-user desktop + Hello gate complete the session as Succeeded + `EspSoftFailure`/`CompletionSource` (amber "with issues" badge + detail banner), category recovery resolves clean, expiry un-defangs to the original `esp_terminal_failure`. Registered in the Agent index section. Related backend fix (no doc): the auto-analyze enqueue now carries a 30 s `visibilityTimeout` so rule evaluation no longer races the agent's terminal flush (ANALYZE-ESP-004's `{{appName}}` placeholder).
+
+## 2026-08-07 (later)
+
+* **Update**: `backend/cloudpc-device-validation.md` — third `IsCloudPc` transport rail: the pre-auth distress channel. `DistressReport.IsCloudPc` (CloudPcDetector verdict captured at `DistressReporter` construction) → `DistressReportEntry`/table column → "Devices Not Registered" aggregation (sticky-true per serial, same OR semantics as the Sessions merge) → portal Cloud PC badge + actionable hint ("enable Windows 365 Cloud PC Validation + W365CloudPcValidation add-on"). Motivated by the first W365 field run: the rejected Cloud PC showed up as anonymous "Microsoft Corporation / Virtual Machine" with no clue that the fix is the Cloud PC validator, not Autopilot registration. UNVERIFIED like all distress fields; ≤18 bytes, fits the 1536-byte cap.
+
+## 2026-08-07
+
+* **Update**: `backend/cloudpc-device-validation.md` — the "deliberately out of scope" follow-up landed in the same PR: agent-side `IsCloudPc` flag (`CloudPcDetector`, bootstrap-verified marker AND: Windows365 key + CloudManagedDesktopExtension service key, SKIP-safe) rides two rails — `SessionRegistration` → Sessions/Index (sticky-true) → `SessionSummary` + `isCloudPc` search filter (portal/raw/MCP), and the `EnrollmentFactsObserved` payload → `EnrollmentScenarioObservations.CloudPc` (set-once, both values) with profile reason `cloud_pc_first_connect:no_device_esp_expected` + `cloud_pc_marker` in the audit-trail census. Reason+observation only: no completion arm depends on DeviceSetup, Mode stays AccountSetup/IME-classified, EspConfig keeps configured-FirstSync semantics. Never an auth input.
+
+## 2026-08-06
+
+* **Creation**: Added `backend/cloudpc-device-validation.md` — the CloudPc fallback validator (`ValidatorType.CloudPc = 5`, tenant flag `ValidateCloudPcDevice`): W365 Cloud PCs are structurally never Autopilot-registered, so stage 4 gains a third stage that binds the chain-validated MDM cert's Subject CN (= Intune device id, field-verified on a real Cloud PC) to the tenant's `virtualEndpoint/cloudPCs` inventory — admits exactly the service-provisioned Cloud PCs, no device-type routing, local W365 markers never consulted for auth. New optional Graph add-on `W365CloudPcValidation` → `CloudPC.Read.All` (catalog + grant script now pinned by `GraphFeatureCatalogSyncTests`; Graph 403 = definitive "grant missing", not transient). Bootstrap dev script v2.3-dev.3 exempts guard 4 (uptime) while the Cloud-PC relax is active — the fresh-profile window is the time anchor at first connect, not boot uptime. Follow-up deliberately out of scope: agent-side `IsCloudPc` classification + decision-engine "no Device ESP" expectation.
+
+## 2026-08-05 (later)
+
+* **Update**: `rules/rule-authoring-surface.md` — new section `POST /api/rules/gather/test-pattern`: the logparser pattern tester (agent-exact .NET matching: no IgnoreCase, first-match-per-line, cmtrace vs text mode, verbatim format=text hint), motivated by a field incident where a PHP-verified regex behaved differently under .NET. `CmTraceLogParser` moved Agent → `AutopilotMonitor.Shared.Logging` so agent and backend share the ONE parsing implementation (timestamp caveat: AssumeLocal = server TZ on backend, endpoint reports no timestamps). MCP: new `test_log_pattern` tool, logparser lint in `validate_rule`, guide gains the case-sensitivity/engine-mismatch pitfalls.
+
+## 2026-08-05
+
+* **Creation**: Added `mcp/tool-telemetry.md` — the three MCP tool-telemetry layers (App Insights `McpToolName`, per-user usage table, `MCP_TOOL_LOGGING` stderr lines) and the new quality signals: soft-error capture (`toolError` returns instead of throwing, so backend telemetry counted those calls as successes), `resultChars`/`overCap` vs. the inline-size hint, bounded args summaries, caller scope, `search_zero_hit` on the three search tools (unmet-demand signal), and `tool_call_rejected` for JSON-RPC-level Zod/unknown-tool rejections sniffed at the `/mcp` route (previously invisible everywhere). Bicep default for `toolLoggingEnabled` flipped to `true` (documented desired state; live flag set via `az containerapp update`).
+* **Creation**: Added `rules/rule-authoring-surface.md` — the AI-assisted rule-authoring stack: three deterministic MCP resources (`rule_authoring_guide` hand-written, `rule_schemas` + `rule_guardrails` generated into `rule-authoring.generated.ts` by a new combine.js emitter, drift-guarded twice), the MCP-local `validate_rule` (ajv 2020-12 against the single-rule $defs, guardrail pre-flight mirroring GatherRuleGuards matching semantics incl. hard blocks, semantic lint for schema-valid-but-dead rules), and the side-effect-free `POST /api/rules/analyze/dryrun` (TenantAdminOrGlobalReader; `RuleEngine.DryRun.cs` trace twin sharing the production evaluators, all-conditions trace with per-condition evidence + matchingEventCount, parity and side-effect-freedom pinned by RuleEngineDryRunTests). MCP `test_analyze_rule` wraps the endpoint with `{{token}}`-interpolated previews; `author-rule` prompt drives the draft → validate → dry-run loop. Deliberately absent: gather-rule remote execution, rule writes via MCP.
+
+## 2026-08-04
+
+* **Update**: `rules/gather-rule-phase-scoping.md` — new section "Which phase feeds the triggers": `GatherRuleExecutorHost` now drives `phase_change`/`phase_exit`/`on_event` gather triggers (and the phase-scope gates) from the post-reduce `TimelineEventStream` (every emitted event's `(eventType, phase)` published by `EventTimelineEmitter`) instead of the pre-reduce `SignalIngress.SignalPosted` payloads. Trigger: session `32312a32` (RealmJoin tenant rsneuffen.de) — a Phase-Start rule on FinalizingSetup fired at the raw ESP-exit `EspPhaseChanged(FinalizingSetup)` signal, 7 minutes before the engine's RealmJoin-gated `phase_transition(FinalizingSetup)`, reading `HKLM\SOFTWARE\RealmJoin\Custom\BIOS` before the RealmJoin package created it. Phase triggers now fire exactly when the timeline shows the phase; `on_event` additionally sees engine-emitted event types (`enrollment_complete`, `realmjoin_resolved`, …) for the first time in V2, restoring V1 semantics and the documented end-of-enrollment pattern. Other raw-signal hosts (DeviceInfo, keep-awake, PPKG) deliberately unchanged.
+
+## 2026-08-02
+
+* **Creation**: Added `backend/tenant-activation-welcome-mail.md` — triggered by the first production auto-approve (activation at signup+64 s, notification address saved at +69 s → welcome mail silently skipped, since the approval path is the only sender and reads the address once). Fix documented in the doc: the notification-email save path now also triggers the send (`PUT /api/preview/notification-email` → fresh approval check `IsApprovedFreshAsync`, bypassing the 30 s negative cache), and a conditional-insert `welcome-email-sent` marker in `PreviewWhitelist` makes the send once-only across both racing paths (marker consumed strictly after the address check; revoke clears it, offboarding wipes the partition, the GA resend endpoint sends unconditionally and consumes it best-effort).
+
+## 2026-07-29
+
+* **Update**: `agent/gather-rule-debug-log.md` — three trace enrichments: (1) new `phase` stage writing an enrollment-phase transition marker (`phase change: Old -> New`, ruleId `-`) so every rule-level line reads against the current phase; (2) logparser now writes one line per regex match — line number, matched text, capture groups — capped at 10 per file per run (the per-file summary keeps the full count); (3) the invalid-regex `error` line includes the offending pattern string.
+
+* **Update**: `url-registry.md` (+ `web/portal-navigation-prefetch.md` context) — the portal is now a **full static export** (`output: 'export'`, `trailingSlash: true`): the SWA serves plain files, the managed SSR runtime — the portal's last cold-start source ("Backend call failure" > 45 s) — no longer exists. Detail routes moved from path params to query strings (`/sessions?id=`, `/sessions/inspector?id=`, `/diagnosis?id=`, `/apps/detail?name=`, `/admin/backups/detail?id=`, `/admin/customs-archive/detail?tenantId=&rowKey=`) with all 21 link sites going through the new single-definition builders in `lib/routes.ts`; the 9 `[section]` families prerender via `generateStaticParams` server shells (37 pages, `dynamicParams=false`), server `redirect()` index pages became `ClientRedirect` shells. Legacy PATH-shaped deep links (sent Teams/Slack/webhook notifications hold `/sessions/{id}` forever) are preserved permanently: SWA wildcard rewrites serve the family page and the globally mounted `LegacyPathRedirect` rewrites to the canonical query URL (hash + query preserved; mapping pinned by `lib/__tests__/legacyPathRedirect.test.ts`). `middleware.ts` host routing became the client-side `HostRoutingGuard` (prefix list moved to `lib/hostRouting.ts`); the legacy `/go/[code]` route + `bootstrapValidation.ts` are deleted (BootstrapSessions table verified free of pre-cutover active sessions). `staticwebapp.config.json` now carries the 19 docs/marketing redirects (order-sensitive), the legacy rewrites, `404.html` override and ALL security headers incl. the literalized prod CSP — guarded by the new `swaConfig.guard.test.ts`; maintenance mode changed from whole-file swap to a first-routes-entry insert (README rewritten). Backend notification deep links go through the new `Constants.PortalSessionUrl` (query shape, pinned). Deploy: `deploy-web.yml` uploads `out/` with `is_static_export: true`.
+
+* **Creation**: Added `backend/oobe-bootstrap-go-flow.md` (and a `Bootstrap go-URL` section + web-registry update in `url-registry.md`) — the OOBE bootstrap script endpoint moved from the portal's Next.js `/go/[code]` SSR route into the Function App (`GET /api/bootstrap/go/{code}`, `GetBootstrapScriptFunction`), unblocking the portal's static export; the customer URL became **`go.autopilotmonitor.com/{code}`** (Front Door custom domain, `/*` route with origin-path rewrite, caching disabled — the script inlines the bearer token). New `Constants.BootstrapGoBaseUrl` (single producer via `CreateBootstrapSessionFunction`) + web `BOOTSTRAP_GO_URL` (display only); both guard host lists extended. Security invariants ported to C#: `BootstrapScriptValueValidator` (exact-GUID tenantId/token, https + host-allowlist + `/agent/….zip` path, expiry ≤ 14 d) and `OobeBootstrapScriptGenerator` (Replace-token raw-string template, single-quoted PS literals, 200-char error cap before quote-doubling; always-HTTP-200 text/plain contract for `irm | iex`). Endpoint is `PublicAnonymous` in the catalog, `NoStoreCacheMiddleware`-covered, self-rate-limited `bootstrap-script:{ip}` 20/min (rate-limit reply is also a 200 error script). Tests: golden byte-parity against the TS template, validator invariants incl. hostile-URL cases, format-gate table, and the previously missing BootstrapUrl shape pin. Transition: the legacy www route + `middleware.ts` `/go` prefix stay alive for pre-migration URLs (validity ≤ 168 h) and are removed in the static-export PR no earlier than 168 h after the last www URL was issued. Customer docs `network-endpoints.md` gained the `go.` host (device-facing, Bootstrap-Sessions-only).
+
+* **Update**: `agent/autopilot-ztd-diagnostics.md` — presentation layer for the startup error backfill (customer feedback: an unannounced wall of pre-agent Error events with a single identical timestamp read like a live failure). Agent: the backfill scan now buffers the capped record set, emits an Info summary event first (`modern_deployment_log`, `backfillSummary: true` + `replayedCount`/`droppedOverCap`/`lookbackMinutes`), then replays oldest-first so the timeline sequence follows event-log chronology. Web: `EventTimeline.tsx` badges `backfilled: true` events („⟲ Backfilled", tooltip) and renders the original `timeCreated` as the row time with a "(reported …)" suffix plus a `Recorded` metadata line — works retroactively for already-stored events. Severity is deliberately not downgraded.
+
+* **Creation**: Added `agent/gather-rule-debug-log.md` — the new per-tenant setting `EnableGatherRuleDebugLog` (ConfigVersion 35 → 36, portal toggle under Settings → Agent, `EnableImeMatchLog`-style bool→path projection in `RemoteConfigMerger`). When enabled, the agent writes `%ProgramData%\AutopilotMonitor\Logs\gather_rules_debug.log`: one pipe-delimited line per evaluation decision across ten previously silent "produced nothing" exits — disabled rules, `interval` without `intervalSeconds` (never runs), the first-tick-after-one-full-interval window, phase-scope skips incl. `currentPhase=Unknown`, per-(rule, phase) dedup, empty collector results (`emitOnlyIfExists`), `on_change` hash suppression (hash prefix + streak), guard blocks, logparser per-file outcomes (position skips, parse failures with a `format=text` hint when every line fails CMTrace parsing, `maxLines`/wildcard caps), and full exception stacks that the agent log drops. 10 MB cap + one `.old` generation; no hot-reload (per-enrollment lifecycle); flag survives the offline config cache; `--run-gather-rules` always traces and echoes under `--console`; zero-rules delivery leaves a one-line file instead of nothing. Side fix: `GatherRuleExecutorHost` now passes the logger into `InformationalEventPost`, so gather-event emissions appear in the agent DEBUG log.
+
+* **Correction + Update**: `web/portal-navigation-prefetch.md`. The HTTP/1.1 claim in the 2026-07-27 entry below is **wrong** and has been struck from the document: `portal.autopilotmonitor.com` negotiates **h2**, verified by `openssl s_client -alpn h2,http/1.1` and a .NET `HttpClient` returning `HTTP/2.0`. The false reading came from the Windows/Schannel curl build in this environment, which has no HTTP/2 support and therefore always reports `1.1` — do not use it to determine HTTP versions. There is no six-connection cap in play; the queue is server-side in the SWA SSR runtime, which does not change the fix or the evidence, only the mechanism. Added an `Outcome` section with 20 h of post-change telemetry: the Free → Standard plan change (16:02:44 UTC) produced **no measurable latency gain** once stratified by the gap to the previous request (p50 Free → Standard: `<10s` 85 → 95 ms, `5-30min` 429 → 441 ms; tail rates 1.64 %/0.374 % over 2 s/10 s vs 6 and 1 events at n = 258 against 4.2 and 1.0 expected; `browserTimings` Mann-Whitney z = −0.24, p = 0.81). The freezes were removed by `prefetch={false}` (16:34:13 UTC): worst `browserTimings.totalDuration` 225,277 → 4,856 ms. The prefetch storm was also an **accidental keep-alive** — requests under 10 s apart fell from 85 % to 46 %, and on the identical never-cacheable `/sessions/{id}` route the median rose 87 → 211 ms and p90 465 → 1,480 ms, with one 11,441 ms abandoned request (`resultCode 0`) after 517 minutes idle. Synthetic bursts warm the runtime and must not be used to benchmark this (round 1 p50 288 ms vs rounds 4–25 p50 113 ms).
+
+## 2026-07-27
+
+* **Creation**: Added `web/portal-navigation-prefetch.md` (and a `Web Portal` section to the index) — root cause of the minute-long portal freezes. `GlobalSidebar` and `Navbar` render the whole navigation on every page, so the App Router's default viewport prefetch issued one `?_rsc=` request per visible link against `portal.autopilotmonitor.com` (~10,400 in 14 days). *(The original entry attributed the freeze to HTTP/1.1 and a six-connection-per-origin cap — see the 2026-07-28 correction; the queue is server-side.)* When the Static Web Apps managed runtime queued the prefetches (p50 91 ms, p95 896 ms, but max 234 s / 21 samples over 30 s), the navigation the user wanted was stuck behind that queue. Measured on the 2026-07-27 17:25 CEST incident: `/admin/presence?_rsc=` 151 s, three siblings finishing within 340 ms of each other at ~37.5 s, all `200`, while the backend API answered in 1.6–2.2 s and `browserTimings` showed `networkDuration` 16 ms against `processingDuration` 225 s. Every navigation Link now sets `prefetch={false}` — these routes are client components behind `ProtectedRoute` that fetch their own data, so the prefetched RSC payload carried no benefit. The doc also records that browser telemetry lives in a **separate** App Insights resource (`AUTOPILOT_MONITOR_WEB_APPINSIGHTS_ID`) that the MCP `query_backend_logs` tool cannot reach, which is why the freezes left no trace in the backend logs.
+
+* **Creation**: Added `backend/rule-regression-radar.md` — F3 regression radar (analyze rules only; gather rules wait for their per-batch stats dedup fix): per (tenant, rule) daily hit rate from `RuleStats`, firing only when the trailing 7-day window has ≥5 hit sessions and ≥20 evaluated sessions, the rate is ≥2× the prior 28-day baseline AND the Wilson 95 % intervals are disjoint (deterministic `MetricsMath` primitive with hand-computed test vectors). Suppressed for deleted rules, rules younger than baseline+window (`CreatedAt` grace), rules edited inside the window (`UpdatedAt`), empty baselines, and the `RuleRegressionRadarDisabled` app-setting kill switch. Alert episodes live as `ruleregression|{ruleId}` tracker rows (one bell + one `RuleFrequencyRegression` ops event per episode; numbers refreshed while active; re-armed under 1.5× baseline, on fire-stop, or by the 30-day tracker retention). On-fire dimension correlation over osBuild/model/agentVersion/imeVersion with the "correlated, not necessarily causal" wording contract. Surfaces: `regressions[]` in the rule-stats response (MCP inherits), the analyze-rules page's 30-day sparkline and regression badge.
+
+* **Creation**: Added `backend/device-journeys.md` — F2 device history / First-Time-Right: the device key (trim + case-fold serial, junk/placeholder exclusion incl. the agent's `Unknown` WMI sentinel), journey grouping over the terminal set Succeeded/Failed/Incomplete (first success ends a journey, a >30-day gap from the previous attempt's CompletedAt starts one, WhiteGlove's single session row is ONE attempt, open sessions are never attempts), the `DeviceHistories` chain (cap 20, written inline at the terminal seam, healed by the sweep, deleted-session refs pruned tombstone-driven, deliberately not in the per-session deletion manifest) and the additive `DeviceJourneyAggregates` daily rows (window rate = ratio of sums — no rolling row needed, 180-day retention). Surfaces: the session-detail "Attempt N" banner with server-computed attempt numbers (virtual-attempt rule for live sessions), the Fleet Health First-time-right section (≥20-journey gate, attempt histogram, repeat-devices violator list), and the MCP `get_device_history` tool (serial mode / fleet FTR mode).
+
+## 2026-07-25
+
+* **Update**: `agent/secureboot-ca2023-detection.md` — review follow-up on 90012d9 hardened the privilege scope, the repo's only privilege-adjustment code and therefore the precedent for any future one. The process token moved from a raw `IntPtr` to a `SafeHandle` assigned by the P/Invoke marshaler, so the CLR owns it from the moment `OpenProcessToken` returns and the critical finalizer releases it even when `Dispose` never runs — previously an async exception between the successful open and the caller's `using` leaked the handle *with the privilege enabled and no owner left to restore it*. `Dispose` became idempotent and now releases the handle in a `finally`, so a throwing restore cannot strand it; the restore obligation is recorded immediately after the successful `AdjustTokenPrivileges` with nothing throwable in between. The whole enable → read → restore sequence runs under a static gate because the privilege is adjusted on the *process* token: a concurrent reader would see "already enabled", correctly skip its own restore, and then lose the privilege mid-read when the first reader disposed, reporting `privilege_denied` on a machine that holds it.
+
+## 2026-07-24
+
+* **Creation**: Added `backend/server-actions-on-demand-diagnostics.md` — the ServerAction channel (queue on `Sessions.PendingActionsJson`, deliver piggy-backed on the next ingest response, at-least-once with `Type|RuleId|QueuedAt` dedup and sequential dispatch) and the on-demand log collection built on it: the portal's always-visible **Collect Logs** button, the new `EndpointPolicy.TenantAdminOrOperator` tier with the mandatory in-function per-type re-gate (Operators queue only `request_diagnostics`), the member-readable `diagnosticsUploadConfigured` feature flag, the admin quick-config path that must queue `rotate_config` before `request_diagnostics` (works against the deployed fleet — a one-time override would not, the mode gate is agent-side), sequence-based progress matching immune to agent clock skew, and the offboarding cascade's hosted-prefix sweep closing the latest-wins orphan-blob gap.
+
+* **Update**: `agent/esp-policy-provider-stall.md` — the customer's follow-up on issue #106 corrected the field-case mechanics: `TrackingPoliciesCreated=1` WAS set under the foreign `ConfigMgr` provider, so the ESP ignores a foreign provider's completion values and waits on the Intune-registered `Sidecar` provider by name (the rename to `Sidecar` creates no tracking entries yet unblocks instantly). The completeness-keyed detector would have missed exactly this — the incident it was built for. The tripwire is now two-armed under one event type discriminated by `reason`: `provider_incomplete` (unchanged dwell on continuously-incomplete providers) and `sidecar_provider_missing` (≥ 1 Setup/Apps provider registered without `Sidecar`, completeness deliberately ignored, clock reset when Sidecar registers later). Sidecar-missing wins the `reason` when both arms cross in one round; the cross-restart fingerprint gains a `sidecarMissing` sentinel; payload adds `reason` and `sidecarMissingForMinutes`. Evidence for the name-keyed wait: Niehaus' documented Intune WAP payload always registers `Sidecar` (ConfigMgr only via a co-management settings policy) and Microsoft's ESP troubleshooting models app tracking exclusively through the Sidecar subkey.
+
+* **Creation**: Added `agent/esp-policy-provider-stall.md` — a customer diagnosed that pre-provisioned devices with the ConfigMgr client as a blocking app occasionally park the user ESP at "Apps (Identifying)" for days: only a `ConfigMgr` provider is registered under `EnrollmentStatusTracking\Device\Setup\Apps\PolicyProviders` (no `Sidecar` = IME) and `TrackingPoliciesCreated` never becomes 1 — a wait the CSP defines without any timeout; renaming the key to `Sidecar` unblocks immediately. The agent now ships the always-on `esp_policy_provider_stalled` tripwire (60-s tick, 15-min continuous-incompleteness dwell, one-shot per provider, `StartupEventGate` fingerprint across restarts, purely observational via the InformationalEvent rail — no toggle, no ConfigVersion bump), generalized to any provider in both `Setup/Apps` and `DevicePreparation` kinds rather than hardcoding the ConfigMgr case. Companion change: `SOFTWARE\Microsoft\Windows\Autopilot` joins the gather-rule registry allowlist so tenants can target the subtree with custom rules (e.g. `not_exists` on the Sidecar key).
 
 * **Creation**: Added `agent/secureboot-ca2023-detection.md` — ANALYZE-SEC-001 warned on devices whose firmware already carried the 2023 certificate, because the agent only read the `SecureBoot\Servicing\UEFICA2023Status` registry value, which mirrors the Windows Update rollout rather than the firmware (customer report). The agent now reads the UEFI `db`/`KEK` variables natively (`GetFirmwareEnvironmentVariableExW` with `SeSystemEnvironmentPrivilege` enabled on the process token — first privilege-adjustment code in the repo) and emits per-certificate booleans on `secureboot_status`. Suppression rides on a one-sided marker, `uefiCa2023FirmwareConfirmed`, emitted only on positive confirmation: the engine's `not_exists` precondition fails on any present value, so a two-sided boolean could not distinguish "confirmed" from "checked and missing", while the marker's absence keeps old agents and firmware-missing devices on the v2 path. Rule v3.0.0 is therefore safe to seed before the agent release.
 
@@ -42,6 +154,10 @@
 
 * **Creation**: Added `agent/endpoint-migration.md` — config-channel agent re-home (`MigrateToApiBaseUrl` on `GET agent/config`, ConfigVersion 33): backend or per-tenant API-URL moves without DNS indirection (impossible due to mTLS/Flex-TLS). Live-fetch-only with cache strip, `AgentEndpointMigrationRules` allowlist validated on both sides, one hop, kill-switch wins. Built as the lesson from the 2026-07-18 WEU→GWC cutover, which hard-cut all in-flight agents.
 
+## 2026-07-26
+
+* **Creation**: Added `backend/time-attribution.md` — the F1 enrollment time attribution: exact-partition invariant against the session's authoritative DurationSeconds, two-window WhiteGlove model, segment mapping from phase-declaration events, positive-evidence ESP-blocking join with "up to" what-if bounds, reboot spans from event gaps around `lastBootUtc`, and the SessionTimeBreakdowns / TimeAttributionAggregates tables with their terminal-seam + maintenance-sweep compute paths and read surfaces (web lane, fleet panel, MCP `get_time_attribution`).
+
 ## 2026-07-17
 
 * **Creation**: Added `agent/build-counter-blob.md` — agent build numbers now come from a shared public counter blob (`buildcounter-v{N}.txt`, reserve-before-build with ETag-CAS) so local `build.ps1` and CI `build-agent.yml` builds can never mint the same number. Documents the CI parity fixes (SummaryDialog.exe.config in the ZIP, EXE-vs-manifest version check, hash-oracle update gated on stable cutover) and the Sigstore provenance attestation on CI-built ZIPs.

docs/mcp/tool-telemetry.md

@@ -0,0 +1,84 @@
+---
+type: concept
+title: MCP Tool Telemetry
+description: The three telemetry layers for judging MCP tool quality — backend App Insights via X-MCP-Tool-Name, the per-user usage table, and the MCP_TOOL_LOGGING stderr lines that carry the signals the backend cannot see (soft errors, result size vs. cap, zero-hit searches, Zod rejections).
+resource: src/McpServer/autopilot-monitor-mcp/src/telemetry.ts
+tags: [mcp, telemetry, observability, tool-quality]
+timestamp: 2026-08-05
+---
+
+# Schema
+
+Three layers answer "are the MCP tools doing their job, and are tools missing?":
+
+1. **Backend App Insights** — every tool handler runs inside `withToolTelemetry`
+   (`src/telemetry.ts`), which propagates the tool name via AsyncLocalStorage so
+   `apiFetch` stamps `X-MCP-Tool-Name` on each backend request.
+   `RequestTelemetryMiddleware` copies it into the request telemetry as
+   `McpToolName`: per-tool call volume, latency percentiles and HTTP failure
+   rates by KQL. Blind spot: tools that never call the backend, and handler-level
+   soft errors (see layer 3).
+2. **Usage table** — `McpQuotaEnforcementMiddleware.TrackUsage` counts per
+   user/day under the key `toolname:endpoint`; surfaced by the `get_api_usage`
+   tool. Counts only, every call counts as success.
+3. **stderr JSON lines** (`MCP_TOOL_LOGGING=true`, queryable via Container App
+   Logs) — the layer that carries what the other two structurally cannot:
+   - `tool_call`: duration, `isError` **including soft errors** (handlers never
+     throw — `toolError` *returns* `isError: true`, so backend-only telemetry
+     records those calls as successes), `errorMessage` (capped; the thrown
+     message or the first lines of the `toolError` text, which name the error
+     class — HTTP status / timeout / auth / not found; absent on success),
+     `resultChars` + `overCap` (result
+     exceeds the tool's `anthropic/maxResultSizeChars` hint → the host truncates
+     it; a frequently-overCap tool needs tighter defaults or projections), a
+     size-bounded args summary, and the caller scope (ga/delegated/tenant).
+     This is the ONLY telemetry for backend-free tools: `search_docs`,
+     `validate_rule`, `get_resource`, the local ranking of `search_knowledge`.
+   - `search_zero_hit`: query text (capped) whenever `search_events` /
+     `search_knowledge` / `search_docs` return zero results — the most direct
+     "missing docs / missing knowledge / missing tool?" demand signal.
+   - `tool_call_rejected`: rejections the SDK answers *before* any handler runs
+     (Zod argument validation, unknown/disabled tool). Two non-obvious facts,
+     both found by live verification: SDK 1.30 wraps these McpErrors as a
+     *successful* JSON-RPC response whose result is `{ isError: true, text:
+     "MCP error <code>: …" }` — a JSON-RPC error envelope never exists for
+     them — and the Hono bridge (`getRequestListener`) may stream the body as
+     `res.write` chunks with a bare `res.end()`. The sniffer in the `/mcp`
+     route therefore wraps both `write` and `end`, reassembles up to 10 KB and
+     matches both shapes (`attachToolCallRejectionSniffer` in `telemetry.ts`).
+     Handler soft errors never carry the `MCP error` prefix, so they are not
+     double-logged. This is the strongest "the schema or description confuses
+     the model" signal and was previously invisible everywhere.
+
+The env flag defaults to `true` in `infra/mcp-server.bicep` (documented desired
+state — the template is not routinely deployed; the live flag is set with
+`az containerapp update --set-env-vars MCP_TOOL_LOGGING=true`).
+
+# Examples
+
+Count zero-hit queries to find unmet demand (Log Analytics):
+
+```kusto
+ContainerAppConsoleLogs_CL
+| where Log_s has '"type":"search_zero_hit"'
+| extend d = parse_json(Log_s)
+| summarize count() by tostring(d.tool), tostring(d.query)
+```
+
+Per-tool soft-error and truncation rates:
+
+```kusto
+ContainerAppConsoleLogs_CL
+| where Log_s has '"type":"tool_call"'
+| extend d = parse_json(Log_s)
+| summarize calls = count(), errors = countif(d.isError == true),
+            overCap = countif(d.overCap == true), p95ms = percentile(tolong(d.durationMs), 95)
+  by tool = tostring(d.tool)
+```
+
+# Citations
+
+- `src/McpServer/autopilot-monitor-mcp/src/telemetry.ts` — wrapper + log emitters
+- `src/McpServer/autopilot-monitor-mcp/src/index.ts` — `/mcp` rejection sniffer
+- `src/Backend/AutopilotMonitor.Functions/Middleware/RequestTelemetryMiddleware.cs` — `McpToolName` stamping
+- `src/Backend/AutopilotMonitor.Functions/Middleware/McpQuotaEnforcementMiddleware.cs` — usage-table counting

docs/rules/analyze-rule-triggers.md

@@ -0,0 +1,118 @@
+---
+type: Concept
+title: Analyze Rule Evaluation Triggers (evaluateOn)
+description: "Opt-in interim evaluation of analyze rules before a session is terminal — enrollment_end stays the default, whiteglove_sealed and on_event:<type> triggers close the WhiteGlove notification gap and the never-terminal stuck-session gap with one mechanism, backed by update-semantics on RuleResults instead of the permanent dedupe freeze."
+resource: backend/rule-engine
+tags: [rules, analyze, triggers, notifications, whiteglove]
+timestamp: 2026-08-14
+---
+
+# Status
+
+**IMPLEMENTED 2026-08-14** (same day the spec was approved). The open product decisions below were confirmed as "no" for v1. Key implementation anchors: `AnalyzeRuleTriggers` (Shared — grammar + matching helpers, shared by engine, ingest registry and CRUD validation), `AnalyzeRunContext` / `AnalysisOutcome.ResolvedResults` (RuleEngine), `InterimTriggerRegistry` (5-min-TTL per-tenant cache for the ingest hot path, fail-soft), `AnalyzeOnEnrollmentEndHandler` interim branch, `EvaluateOnJson` + five RuleResult lifecycle columns in `TableStorageService.Rules`. ANALYZE-ID-004 ships as the first interim-enabled rule (`on_event:hybrid_login_pending`, repetition-gated at threshold 75).
+
+# Problem
+
+Analyze rules run at exactly three points today, all of them terminal or near-terminal:
+
+1. `enrollment_complete` / `enrollment_failed` observed at ingest (`EventIngestProcessor.cs`, classification → analyze envelope).
+2. The maintenance sweep terminalizing a silent session (Failed / Incomplete + synthetic `session_timeout`, `MaintenanceService.cs`).
+3. The vulnerability-correlation rerun (`vulnerability_correlated` reason — incremental, no stats).
+
+Two incident classes fall through this model:
+
+- **WhiteGlove gap (sits-d, 2026-08-11):** `whiteglove_complete` seals a session to Pending but enqueues no analyze run. A rule that should alert at the end of pre-provisioning (technician still at the bench) never fires, and when Part 2 eventually terminalizes days later, the permanent per-(session, rule) dedupe means a finding that sneaked in earlier (e.g. via the vuln-rerun backdoor) is frozen and never notifies.
+- **Never-terminal stuck sessions (esa-logistics, 2026-08-13/14):** a session looping in Account Setup (user signs in daily, hybrid affinity never establishes) resets the 5h inactivity clock on every logon. It is never terminalized, therefore never analyzed — the exact sessions where a diagnosis would help most (ANALYZE-ID-004, ANALYZE-APP-015) produce no finding while the customer watches the device loop.
+
+Both gaps share one root cause: *evaluation time is hard-wired to session end*. Gather rules already solved the analogous problem on-device with declarative triggers (`startup` / `phase_change` / `phase_exit` / `interval` / `on_event`); analyze rules need the server-side equivalent.
+
+# Design Overview
+
+Add an optional `evaluateOn` array to the analyze-rule schema. Absent field ⇒ `["enrollment_end"]` ⇒ **today's behavior, bit-for-bit, for every existing rule**.
+
+```
+"evaluateOn": ["enrollment_end", "on_event:hybrid_login_pending"]
+```
+
+Trigger grammar (v1):
+
+| Trigger | Fires when | Notes |
+|---|---|---|
+| `enrollment_end` | terminal analyze run (complete / failed / sweep-terminalized) | default; also the **finalization pass** for interim results (below) |
+| `whiteglove_sealed` | ingest classifies the first genuine `whiteglove_complete` (session → Pending, `isPreProvisioned`) | duplicate seals do not re-trigger |
+| `on_event:<eventType>` | an ingest batch contains ≥1 event of `<eventType>` | `<eventType>` validated against the event-types catalog; phase boundaries are covered by `on_event:phase_transition` / `on_event:esp_phase_changed` — no separate phase grammar needed, since every run evaluates the full stream anyway |
+
+Explicitly **not** in v1: interval/timer triggers (no cheap host for them; the sweep remains the only clock), and `on_event` filters on data fields (the rule's own conditions do that — the trigger only decides *when* to look).
+
+# Pipeline Changes
+
+## Ingest (producer side)
+
+- `EventIngestProcessor` already classifies each stored batch. After classification, intersect the batch's event types with the tenant's **trigger registry** (the set of `on_event` types across the tenant's active rules — derivable from `AnalyzeRuleService`'s merged rule load, cached alongside it). Non-empty intersection ⇒ enqueue one envelope `Reason=interim_trigger`, carrying the matched trigger event types. Reuse the existing 30s visibility delay (terminal-flush ordering argument in `AzureQueueAnalyzeOnEnrollmentEndProducer` applies to interim batches too).
+- The `whiteglove_complete` seal path (`EventIngestProcessor.Classification.cs`) enqueues `Reason=whiteglove_sealed` — only on the first seal, only for `isPreProvisioned`.
+- Terminal enqueue (`CompletionEvent` / `FailureEvent`) is unchanged.
+
+## Handler / engine (consumer side)
+
+`AnalyzeOnEnrollmentEndHandler` branches by reason today (primary vs. `vulnerability_correlated`); interim reasons become a third branch. The engine call gets a run context instead of the bare `reanalyze` flag:
+
+| Aspect | Terminal run (`enrollment_end`) | Interim run (`whiteglove_sealed`, `interim_trigger`) |
+|---|---|---|
+| Rule set | ALL active rules (interim-triggered ones get their finalization pass here) | only rules whose `evaluateOn` matches the reason / one of the batch's trigger types |
+| KO (`MarkSessionAsFailed`) | applies (unchanged) | **suppressed** — a Pending/InProgress session must never be flipped Failed by an interim pass (`TryMarkSessionFailedFromRuleAsync` is skipped; the terminal run re-fires the rule and applies KO then) |
+| Platform stat `IssuesDetected` | counted | skipped (like vuln rerun) |
+| Per-rule fire stats | counted | skipped (like vuln rerun) — keeps the terminal-only stats convention and the Rule Regression Radar baselines clean |
+| Channel notifications | new findings notify (unchanged) | new findings notify — **this is the point** of both gaps |
+| SignalR results-available | yes | yes (live update of an open session page) |
+
+## Result lifecycle: update semantics replace the dedupe freeze
+
+Today the engine skips any rule that already has a stored `RuleResult` row for the session (`RuleEngine.AnalyzeSessionAsync`, existing-results lookup) — findings are frozen at first write, which is precisely the WG-gap failure mode ("dedupe permanent").
+
+New model — `RuleResult` gains four fields (`FirstDetectedAt`, `LastEvaluatedAt`, `IsInterim`, `ResolvedAt`, plus `NotifiedAt` for the notification marker):
+
+- **Interim run:** rules in scope are (re-)evaluated even when a row exists. Fired ⇒ upsert (evidence/confidence refreshed, `FirstDetectedAt` preserved, `IsInterim=true`). Not fired + existing interim row ⇒ `ResolvedAt` set (kept for audit; excluded from issue counts and default UI).
+- **Terminal run:** every rule that has an interim row is re-evaluated regardless of dedupe (finalization). Fired ⇒ row finalized (`IsInterim=false`, evidence refreshed — fixes the stale-template-field freeze, e.g. the ESP-004 `{{appName}}` case). Not fired (typically a `not_exists` precondition on `enrollment_complete` now failing because the session healed) ⇒ `ResolvedAt` set. Rules without interim rows keep today's skip-if-exists dedupe.
+- **Notification dedupe** moves off "row exists" onto `NotifiedAt` on the row: notify once per (session, rule) at first fire — interim or terminal, whichever comes first; refreshes and finalization do not re-notify. The manual `reanalyze=true` path must **preserve** `NotifiedAt` across its rebuild (today it deletes rows; delete-and-recreate would silently re-arm notifications) and keeps its designed never-notify behavior.
+- Legacy rows (null new fields) read as final/terminal — no migration.
+
+# Authoring Guardrails (validate_rule lints)
+
+Interim evaluation changes what a rule's conditions mean mid-flight. Three new lints in the MCP `validate_rule` pre-flight (and the baked authoring guide):
+
+1. **Terminal-precondition trap (warning):** `evaluateOn` contains an interim trigger AND a precondition is `not_exists` on `enrollment_complete` / `enrollment_failed` / `session_timeout`. Mid-run these pass trivially — the rule needs conditions that are *monotonic* (once true on the growing event stream, stays true) or repetition-gated. Worked example: ANALYZE-APP-015 must NOT get an interim trigger as-is — even successful sessions transiently show its "completion signal deferred" + `pending>=1` pattern (the terminal precondition is its only gate). ANALYZE-ID-004 is interim-safe by construction (threshold 65 requires repeated `hybrid_login_pending`).
+2. **Unknown trigger event type (error):** `on_event:<type>` not in the event-types catalog.
+3. **KO-on-interim (warning):** `markSessionAsFailedDefault: true` on a rule whose only triggers are interim — the KO would never apply until terminal; say so.
+
+# Cost & Safety
+
+- Interim runs are bounded by trigger frequency, and the chosen v1 triggers are rare by construction (`hybrid_login_pending` ≤1 per boot, `whiteglove_sealed` once per session). High-frequency telemetry event types (performance_snapshot, agent_metrics_snapshot, download_progress, network churn, log_entry, agent_trace, stall_probe_check) are **hard-blocked** as `on_event` triggers, not merely advised against: the CRUD write is rejected (`AnalyzeRuleTriggers.BlockedOnEventTypes`, code-only enforcement), the runtime matcher drops them from any row that slipped in (defense in depth — the trigger registry and the engine both go through `OnEventTypes`), and the MCP lint reports them as an error. The JSON mirror lives in `rules/guardrails.json` (`blockedInterimTriggerEventTypes`) with a parity test pinning it to the C# set — the same pattern the gather hard blocks use. If a legitimate rare-but-bursty type ever hurts, a per-(session, reason) throttle marker is the v2 lever.
+- Each run loads the full event stream once (existing engine behavior, no change); rule filtering makes interim passes strictly cheaper than terminal ones.
+- Queue semantics (retry via visibility timeout, poison after MaxDequeueCount, idempotent partial-success re-runs) are inherited unchanged; upserts keep idempotency.
+
+# Surfaces
+
+- **Web session page:** interim findings render live (existing SignalR results-available notification) with a "preliminary" badge on `IsInterim`; `ResolvedAt` rows hidden by default behind a toggle.
+- **MCP:** `get_session(includeAnalysis)` / `get_session_summary` expose `isInterim` / `resolvedAt`; `list_session_annotations`' fired-rule snapshot semantics unchanged (labels bind to whatever was fired at annotation time).
+- **Success-rate / platform stats:** terminal-only convention untouched (interim runs record no stats).
+
+# Application to the Motivating Cases
+
+- WG battery rule (sits-d): `evaluateOn: ["enrollment_end", "whiteglove_sealed"]` — technician gets the channel alert at the bench; Part-2 terminal pass finalizes or resolves the finding.
+- Hybrid-affinity stuck (esa): ANALYZE-ID-004 gets `evaluateOn: ["enrollment_end", "on_event:hybrid_login_pending"]` — the second overdue-login event (threshold 65) produces a live finding on the still-InProgress session. ANALYZE-APP-015 stays `enrollment_end`-only until its conditions are hardened (lint 1).
+
+# Product Decisions (settled 2026-08-14)
+
+1. Notify-on-resolve (a "finding healed" message)? **No** (v1) — resolution is visible in UI/MCP.
+2. Re-notify on severity/confidence escalation of an existing finding? **No** (v1) — one notification per finding.
+3. `whiteglove_sealed` runs allowing KO rules to flip Pending → Failed? **No** — the Pending state is the WhiteGlove contract; suppression is unconditional for interim.
+
+# Citations
+
+- `src/Backend/AutopilotMonitor.Functions/Services/EventIngestProcessor.cs` — terminal-only enqueue (classification → analyze envelope).
+- `src/Backend/AutopilotMonitor.Functions/Services/Analyze/AnalyzeOnEnrollmentEndHandler.cs` — reason branching, notify path, stats side-effects.
+- `src/Backend/AutopilotMonitor.Functions/Services/Analyze/AzureQueueAnalyzeOnEnrollmentEndProducer.cs` — 30s visibility delay rationale.
+- `src/Backend/AutopilotMonitor.Functions/Services/RuleEngine.cs` — existing-results dedupe, `TryMarkSessionFailedFromRuleAsync` KO path.
+- `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.cs` — sweep terminalization + analyze enqueue; inactivity-clock reset explains the never-terminal gap.
+- `rules/gather-rule-phase-scoping.md` (this bundle) — the on-device trigger precedent this design mirrors.
+- `rules/rule-authoring-surface.md` (this bundle) — where the new lints land (validate_rule + baked guide).

docs/rules/gather-rule-guardrails.md

@@ -7,14 +7,14 @@ description: >-
   guard rather than trusting rule.Target.
 resource: src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather
 tags: [gather-rules, security, guardrails, agent]
-timestamp: 2026-07-22
+timestamp: 2026-08-11
 ---
 
 # Concept
 
-A gather rule is authored by a **tenant administrator** through `POST /api/rules/gather` and executed by the agent as **SYSTEM** on an enrolling device. The backend does not validate `collectorType`, `target`, or `parameters` at all — it only enforces scope/emit-mode fields, a 1 MB body cap, and that the rule lands in the caller's own tenant partition. Everything that decides *what a rule may reach* is therefore enforced **on the agent**, in `GatherRuleGuards`.
+A gather rule is authored by a **tenant administrator** through `POST /api/rules/gather` and executed by the agent as **SYSTEM** on an enrolling device. The backend does not validate `collectorType`, `target`, or `parameters` at all — it only enforces scope/emit-mode fields, a 1 MB body cap, that the rule lands in the caller's own tenant partition, and that `Author` is stamped from the caller's JWT (create and PUT-upsert; true updates preserve the original author). Everything that decides *what a rule may reach* is therefore enforced **on the agent**, in `GatherRuleGuards`.
 
-This is the security boundary. The portal's `ValidationIndicator` is a convenience: it does not block submit, and the API is reachable directly.
+This is the security boundary. The portal's `ValidationIndicator` is a convenience — the API stays reachable directly and the backend stays validation-free — but since 2026-08 the portal additionally **gates enabling** on the same client-side validation: a custom rule whose target fails validation cannot be toggled on, is created `enabled=false`, and an edit that makes the target invalid force-disables the rule (`targetBlocked` in `app/gather-rules/types.ts`). An enabled rule with an invalid target shows a "Blocked on devices" badge. All of this is UX, not security — the agent guard remains the enforcement point.
 
 # Schema
 
@@ -27,7 +27,7 @@ item in `AutopilotMonitor.Agent.V2.Core.csproj`) and regenerated into the portal
 | --- | --- | --- |
 | `IsRegistryPathAllowed` | `registryPrefixes` | prefix, boundary `\` or end |
 | `IsFilePathAllowed` | `filePrefixes` | `Path.GetFullPath` first, then prefix + boundary |
-| `IsWmiQueryAllowed` | `wmiQueryPrefixes` | prefix, boundary whitespace or end |
+| `IsWmiQueryAllowed` | `wmiQueryPrefixes` | `SELECT <* \| property-list> FROM <class>`; class = case-insensitive equality against classes derived from the `SELECT * FROM <class>` entries, boundary whitespace or end (trailing `WHERE` allowed). Non-canonical entries (none today) fall back to literal prefix + boundary |
 | `IsCommandAllowed` | `allowedCommands` | **exact** match, trimmed — never prefix |
 | `IsEventLogChannelAllowed` | `eventLogChannels` | prefix, boundary `/` or end |
 
@@ -44,7 +44,12 @@ but the hard blocks must hold regardless of configuration:
   PowerShell channels (script-block logging routinely contains secrets in clear text).
 
 `rules/guardrails.json` mirrors the blocked lists (`blockedFilePrefixes`,
-`blockedEventLogChannels`) **for display only**. Enforcement is the C# constant.
+`blockedEventLogChannels`, `blockedCommandPatterns`, `maxCommandLength`) **for display
+and pre-flight only**. Enforcement is the C# constant; `GuardrailsParityTests` (agent
+test project) pins the JSON mirror to the constants so neither side can drift. The
+portal (`utils/guardValidation.ts`) and the MCP validator (`rule-validation.ts`) apply
+the mirrored hard blocks in the same order as the agent — before the unrestricted-mode
+early-return — so a rule the agent would refuse is never shown as "Allowed".
 
 # Examples
 
@@ -71,6 +76,15 @@ Two collectors were added to this contract on 2026-07-22 after shipping without
 remote config. The operator using it is already a local admin, so it relaxes the
 allowlist exactly the way unrestricted mode does — hard blocks still apply.
 
+**WMI property projections (2026-08):** `SELECT BatteryStatus FROM Win32_Battery` is
+allowed because `SELECT * FROM Win32_Battery` is — a projection exposes a strict subset
+of the allowed class. The matcher parses the query shape instead of literal-prefix
+matching; the allowed-class set is derived at load time from the existing
+`wmiQueryPrefixes` entries, so `rules/guardrails.json` needs no new key. The same
+algorithm is mirrored in the portal (`utils/guardValidation.ts`) and the MCP server
+(`rule-validation.ts`); agents older than the change still block projections with a
+`security_warning` until they self-update.
+
 # Citations
 
 * `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleGuards.cs`

docs/rules/gather-rule-phase-scoping.md

@@ -8,7 +8,7 @@ tags:
   - backend
   - gather-rules
   - config
-timestamp: 2026-07-20T00:00:00+02:00
+timestamp: 2026-08-04T00:00:00+02:00
 ---
 
 # Problem
@@ -64,6 +64,35 @@ enter-rule and an exit-rule on the same phase never cannibalise each other's slo
 * Old agents do not know the trigger value and simply never fire the rule (silent no-op) —
   which is why `phase_exit` needs no ConfigVersion bump: no new field is transported.
 
+# Which "phase" feeds the triggers — the emitted timeline, not raw signals
+
+The phase the executor sees is fed by `GatherRuleExecutorHost` from the **post-reduce
+`TimelineEventStream`**: `EventTimelineEmitter` publishes every emitted event's
+`(eventType, phase)` after the decision engine reduced the originating signal. Phase triggers
+therefore fire exactly when the UI timeline shows the phase — by construction.
+
+This replaced the original V2 wiring (`SignalIngress.SignalPosted`), which fires at enqueue
+time with the **raw** collector payload. The raw phase can run minutes ahead of the
+engine-declared one: in session `32312a32` (RealmJoin tenant) the Shell-Core ESP-exit
+synthesized `EspPhaseChanged(FinalizingSetup)` at 12:18, while the engine — holding the
+transition behind the RealmJoin completion gate until the first deployment resolved — declared
+`phase_transition(FinalizingSetup)` at 12:25. A `phase_change` rule on `FinalizingSetup`
+reading `HKLM\SOFTWARE\RealmJoin\Custom\BIOS` fired 7 minutes early and read the key before
+the RealmJoin package wrote it (`exists=false`).
+
+Consequences of the emitted-event feed:
+
+* `phase_change` / `phase_exit` / phase **scope** gates all follow the engine-reduced phase
+  (single feed, consistent with the portal's "collects once when the enrollment reaches …").
+* `on_event` now sees **every emitted event type**, including engine-emitted ones
+  (`enrollment_complete`, `phase_transition`, `realmjoin_resolved`, …) that never existed on
+  the raw signal stream — the documented "On Event with `enrollment_complete`" end-of-enrollment
+  pattern only works because of this. This restores V1 semantics (V1 fired triggers from every
+  emitted `EnrollmentEvent`).
+* Other hosts (`DeviceInfoHost`, `UserEspKeepAwakeHost`, `ProvisioningPackageHost`) still key
+  off the raw signal stream deliberately — their collections are about OS state at the raw
+  boundary (ESP exit, keep-awake), not about timeline agreement.
+
 # Scope semantics (agent, `GatherRuleExecutor`)
 
 * Scope applies to **all trigger types**:
@@ -130,7 +159,9 @@ enter-rule and an exit-rule on the same phase never cannibalise each other's slo
 # Citations
 
 * `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs` — scope gates, latch, canonical hash
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/Hosts/GatherRuleExecutorHost.cs` — timeline-event trigger feed
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/TimelineEventStream.cs` — post-reduce observer surface
 * `src/Backend/AutopilotMonitor.Functions/Functions/Rules/GatherRulesFunction.cs` — `ValidateScopeAndEmitMode`
 * `src/Backend/AutopilotMonitor.Functions/Services/GatherRuleService.cs` — partial-PUT merge, `ContentEquivalent`
 * `src/Shared/AutopilotMonitor.Shared/Models/Rules/GatherRule.cs` — field contracts
-* Tests: `GatherRuleExecutorPhaseScopeTests`, `GatherRuleExecutorEmitModeTests` (agent); `GatherRuleUpdatePartialMergeTests`, `GatherRuleScopeFieldsTests` (backend)
+* Tests: `GatherRuleExecutorPhaseScopeTests`, `GatherRuleExecutorEmitModeTests`, `GatherRuleExecutorHostTimelineFeedTests` (agent); `GatherRuleUpdatePartialMergeTests`, `GatherRuleScopeFieldsTests` (backend)

docs/rules/rule-authoring-surface.md

@@ -0,0 +1,152 @@
+---
+type: Concept
+title: Rule Authoring Surface — MCP Resources, validate_rule, and the Analyze Dry-Run
+description: >-
+  How customer AIs author gather/analyze rules against the real contract: the baked
+  authoring resources (guide, schemas, guardrails) generated by combine.js, the
+  MCP-local validate_rule pre-flight, and the side-effect-free backend dry-run that
+  traces a draft analyze rule against one session's events.
+resource: src/McpServer/autopilot-monitor-mcp/src/tools/rules.ts
+tags: [rules, mcp, analyze-rules, gather-rules, dry-run, authoring]
+timestamp: 2026-08-05
+---
+
+# Concept
+
+Customers author rules with an AI connected to the MCP server. Retrieval
+(`search_docs`) is deliberately NOT the knowledge source for authoring: chunked
+top-K retrieval can silently omit an operator, a guardrail prefix, or an enum,
+and the AI then produces a plausible-but-dead rule. The authoring surface is
+therefore **deterministic**: three `get_resource` entries carry the complete
+contract, a local validator rejects what production would reject or silently
+ignore, and a backend dry-run evaluates a draft against real session events with
+a full trace.
+
+The intended loop: draft → `validate_rule` → `test_analyze_rule` against a real
+session (one that should fire, one that should not) → iterate → create in the
+portal. The `author-rule` MCP prompt walks a client through exactly this order.
+
+# Schema
+
+## Resources (deterministic authoring context)
+
+| Resource | Content | Source |
+| --- | --- | --- |
+| `rule_authoring_guide` | Hand-written complete authoring knowledge: collector types, triggers, condition sources, operators, confidence model incl. the exact factor DSL, `{{token}}` interpolation order, guardrail matching semantics, pitfalls | `src/rule-authoring-guide.ts` |
+| `rule_schemas` | Both JSON Schemas (2020-12) verbatim | generated |
+| `rule_guardrails` | `rules/guardrails.json` verbatim | generated |
+
+Generation: `node rules/scripts/combine.js` bakes schemas + guardrails into
+`src/McpServer/autopilot-monitor-mcp/src/rule-authoring.generated.ts` (same
+pattern as the web's `utils/guardrails.generated.ts`; the tsconfig `rootDir` and
+the Docker build's exclusion of `rules/schema` rule out importing the JSON
+directly). Drift is closed twice: CI's `guardrails-in-sync` job re-runs
+combine.js and fails on any diff, and `rule-authoring-drift.test.ts` pins
+generated == repo source plus guide enums == schema enums.
+
+## validate_rule (MCP-local)
+
+`src/rule-validation.ts`, no backend call. Three layers:
+
+1. **Schema** — ajv (draft 2020-12) against the baked schemas, validating the
+   single-rule `$defs` entry directly (the top-level oneOf wrapper would double
+   every error).
+2. **Guardrails** — mirrors the AGENT's matching semantics from
+   `GatherRuleGuards.cs` (see [gather-rule-guardrails.md](gather-rule-guardrails.md)):
+   hive-stripped segment-bounded registry/file prefixes, whitespace-bounded WMI
+   prefixes, EXACT command matching, `/`-bounded event-log channels, and the
+   code-enforced hard blocks (`Security` etc. channels, `C:\Users`,
+   `C:\Windows\System32\config`).
+3. **Semantic lint** — schema-valid-but-dead rules: unreachable
+   confidenceThreshold, factor conditions outside the three parseable shapes
+   (`exists`, `count >= N`, `phase_duration > N`), unknown event types (warning;
+   `gather_*` softened to info), unanchored `not_regex` allow-lists,
+   unresolvable `{{token}}`s, trigger cross-fields, outputEventType
+   convention/collision checks.
+
+The validator is advisory pre-flight only — the agent re-enforces guardrails
+on-device and the backend re-validates structure. It must never be stricter
+than production.
+
+## POST /api/rules/analyze/dryrun (backend)
+
+`DryRunAnalyzeRuleFunction` → `RuleEngine.DryRunRuleAsync`. Body
+`{ sessionId, rule }` (draft `AnalyzeRule`, 1 MB cap). Policy tier
+`TenantAdminOrGlobalReader` — a POST by shape but a pure read in effect, so the
+read-only Global Reader is admitted; platform-scope callers reach any tenant's
+session via `FindSessionTenantIdAsync` (same pattern as `GetRuleResultsFunction`).
+
+`RuleEngine.DryRun.cs` is a partial-class trace twin of `EvaluateRule`: it
+shares the exact evaluators (`EvaluatePrecondition` / `EvaluateCondition` /
+`EvaluateConfidenceFactor`) but evaluates **all** conditions instead of breaking
+on the first failed required one — the full picture is the point of a dry run.
+Verdicts: `fired`, `skipped_by_precondition`, `required_condition_not_met`,
+`no_conditions_matched`, `below_confidence_threshold`, `no_events`. Each
+condition entry carries `matched`, the production evidence dictionary (or the
+evaluator's reason string) and `matchingEventCount` — how many session events
+even have that eventType, the first thing to check on an unexpected miss.
+
+Invariants, pinned by `RuleEngineDryRunTests`:
+
+* **Parity**: verdict `fired` ⇔ `EvaluateRule` produces a result, with identical
+  confidence and evidence keys. Factor evaluation stays sequential against the
+  accumulating `matchedConditions` (a factor can observe earlier `factor_*`
+  entries) — reordering would change results.
+* **Side-effect freedom**: exactly one strict event read; never a RuleResult
+  write, never `TryMarkSessionFailedFromRuleAsync`, never a notification.
+  `wouldMarkSessionAsFailed` is reported, not acted on.
+
+`test_analyze_rule` (MCP) wraps the endpoint and adds the interpolated
+explanation/remediation preview via the existing `interpolate-rule-template.ts`
+against the returned `matchedConditions`.
+
+## POST /api/rules/gather/test-pattern (backend)
+
+The logparser counterpart to the analyze dry-run, added after a field incident:
+a customer verified a logparser regex with a PHP tester and the agent's .NET
+engine matched differently. `TestLogPatternFunction` evaluates a pattern against
+pasted sample lines with the AGENT's exact matching semantics:
+
+* Regex construction identical to `LogParserCollector`: `Compiled`, 1 s timeout,
+  **no IgnoreCase** — logparser matching is case-sensitive (unlike analyze-rule
+  regex conditions, which run IgnoreCase).
+* `format` behaves exactly like the rule parameter: `cmtrace` (default) parses
+  each line via the shared `CmTraceLogParser` and matches against the parsed
+  MESSAGE only; `text` matches the raw line. First match per line
+  (`Regex.Match`), group `"0"` excluded, unsuccessful groups omitted — the
+  returned `groups` are exactly the event-data fields the device would emit.
+* Mirrors the agent's diagnostics: per-line outcomes
+  (`matched | no_match | parse_failed | regex_timeout`), the all-lines-parse-fail
+  hint ("set parameter format=text") verbatim, and a case-sensitivity note on
+  zero matches.
+* Pure compute on the request body — no tenant data touched. Same policy tier
+  as the dry-run (`TenantAdminOrGlobalReader`); caps: 200 lines, 8 KB/line,
+  1 MB body.
+
+Parity is structural, not duplicated: `CmTraceLogParser` moved from the agent
+(`Monitoring/Enrollment/Ime`) to **Shared** (`AutopilotMonitor.Shared.Logging`)
+so agent and backend run the SAME parsing implementation. Timestamp caveat:
+bias-less CMTrace lines parse with `AssumeLocal`, which on the backend is the
+server's timezone — the endpoint therefore reports match/parse results, never
+timestamps. `test_log_pattern` (MCP) wraps the endpoint; `validate_rule`
+additionally lints logparser parameters (missing/non-compiling pattern, unknown
+format value) and its `nextStep` routes logparser drafts to `test_log_pattern`.
+
+## What is deliberately absent
+
+* **No gather-rule remote execution** — gather rules run as SYSTEM on devices;
+  session dry-run is analyze-only. Logparser authors get the pattern tester
+  above; all gather authors get guardrail pre-flight plus the on-device debug
+  log ([gather-rule-debug-log](../agent/gather-rule-debug-log.md)).
+* **No rule write/deploy via MCP** — creating rules stays in the portal.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/TestLogPatternFunction.cs` — logparser pattern tester
+* `src/Shared/AutopilotMonitor.Shared/Logging/CmTraceLogParser.cs` — shared CMTrace parser (agent + backend)
+* `src/Backend/AutopilotMonitor.Functions/Services/RuleEngine.DryRun.cs` — trace twin + DTOs
+* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/DryRunAnalyzeRuleFunction.cs` — endpoint + draft validation
+* `src/McpServer/autopilot-monitor-mcp/src/rule-validation.ts` — validator
+* `src/McpServer/autopilot-monitor-mcp/src/tools/rules.ts` — validate_rule / test_analyze_rule
+* `src/McpServer/autopilot-monitor-mcp/src/rule-authoring-guide.ts` — guide resource
+* `rules/scripts/combine.js` — MCP module generation

docs/url-registry.md

@@ -21,7 +21,7 @@ literal appears nowhere else.
 | Component | Registry | Guard test |
 |---|---|---|
 | C# (Shared/Backend/Agent) | `AutopilotMonitor.Shared.Constants` (`*BaseUrl`) | `HardcodedUrlGuardTests` |
-| Web | `utils/config.ts` (`DOCS_URL`, `SITE_URL`, `PORTAL_URL`, `ENTRA_LOGIN_URL`, `API_URL_PROD`, `BLOB_URL_PROD`, `AGENT_DOWNLOAD_HOSTNAMES`) | `utils/__tests__/hardcodedUrls.guard.test.ts` |
+| Web | `utils/config.ts` (`DOCS_URL`, `SITE_URL`, `PORTAL_URL`, `BOOTSTRAP_GO_URL`, `ENTRA_LOGIN_URL`, `API_URL_PROD`, `BLOB_URL_PROD`, `AGENT_DOWNLOAD_HOSTNAMES`) | `utils/__tests__/hardcodedUrls.guard.test.ts` |
 | MCP | `src/config.ts` (`API_BASE_URL`, `ENTRA_LOGIN_BASE_URL`, `DOCS_BASE_URL`) | `src/__tests__/hardcoded-urls.guard.test.ts` |
 
 Derived registries build on these instead of repeating hosts:
@@ -76,6 +76,42 @@ Deliberately still on the legacy account: the `HealthCheckService` /
 `build-agent.yml` — they exist precisely to keep already-deployed customer
 bootstrap scripts working until the customer migration completes.
 
+# Bootstrap go-URL (2026-07-28)
+
+The OOBE bootstrap short-URL moved from `www.autopilotmonitor.com/go/{code}`
+(Next.js route, SSR) to **`go.autopilotmonitor.com/{code}`** — a Front Door
+custom domain whose `/*` route rewrites onto `/api/bootstrap/go/{code}` on the
+Function App (`GetBootstrapScriptFunction`). Registry entries:
+`Constants.BootstrapGoBaseUrl` (C#, the single producer via
+`CreateBootstrapSessionFunction`) and `BOOTSTRAP_GO_URL` (web, display-only in
+the sessions list); `go.autopilotmonitor.com` is on both guards' enforced-host
+lists. `CreateBootstrapSessionUrlShapeTests` pins the produced URL as an
+independent oracle — before this, no test guarded the bootstrap URL shape at
+all.
+
+Front Door route caching for `bootstrap-go` is DISABLED — same hazard class as
+the `/agent/*` route above, sharpened: the script body inlines the bearer
+token, so a cache hit would replay one requester's token to another.
+`NoStoreCacheMiddleware` additionally stamps `no-store` via the
+`/api/bootstrap/go/` prefix.
+
+Transition COMPLETED with the static-export PR (2026-07-29): the legacy
+Next.js `/go/[code]` route, `utils/bootstrapValidation.ts`, and
+`middleware.ts` are deleted — verified safe because the BootstrapSessions
+table held zero active sessions predating the URL cutover (all expired
+2026-03). The backend is now the only script producer;
+`OobeBootstrapScriptGeneratorTests`' golden file remains as the pin of the
+shipped template.
+
+Portal detail routes are query-string based since the same PR
+(`/sessions?id=…` etc., builders in `lib/routes.ts`, notification producer
+`Constants.PortalSessionUrl`). Legacy PATH-shaped links in sent
+Teams/Slack/webhook notifications are rewritten forever by SWA wildcard
+rewrites + `components/LegacyPathRedirect.tsx`; `staticwebapp.config.json`
+carries the production redirects/headers and is guarded by
+`utils/__tests__/swaConfig.guard.test.ts` (registry-backed hosts, no
+unsafe-eval, route order).
+
 # Citations
 
 - `src/Shared/AutopilotMonitor.Shared/Constants.cs` — C# registry

docs/versioning.md

@@ -1,7 +1,7 @@
 ---
 type: Concept
-title: Version Contract — Agent, Backend, MCP
-description: One version shape for all three shipping components, the ETag-CAS counter blob that mints build numbers, and the published manifests that make "what is deployed" checkable from outside.
+title: Version Contract — Agent, Backend, MCP, Web
+description: One version shape for all shipping components, the ETag-CAS counter blob that mints build numbers, and the published manifests that make "what is deployed" checkable from outside.
 resource: /.github/scripts/Request-BuildNumber.ps1
 tags:
   - build
@@ -13,9 +13,12 @@ timestamp: 2026-07-22T00:00:00+02:00
 
 # Version Contract
 
-Three components ship from this repository — the agent, the Functions backend and the
-MCP server. They share one version shape, one way of minting build numbers, and one
-manifest format, so that a version string means the same thing whoever emits it.
+Four components ship from this repository — the agent, the Functions backend, the
+MCP server and the web portal. They share one version shape, one way of minting build
+numbers, and one manifest format, so that a version string means the same thing
+whoever emits it. The web portal is the commit-only exception: a static export has no
+runtime that could report a `major.minor.build`, so it carries `commit` + `buildUtc`
+alone (no counter blob).
 
 ```
 version   = <major>.<minor>.<build>    major.minor curated by hand, build minted per build
@@ -28,6 +31,7 @@ buildUtc  = ISO-8601 build moment
 | Agent V2 | `VersionPrefix` in `AutopilotMonitor.Agent.V2.csproj` | `agent/buildcounter-v2.txt` | `agent/version.json` |
 | Backend | `VersionPrefix` in `AutopilotMonitor.Functions.csproj` | `versions/backend.txt` | `GET /api/health` |
 | MCP | `version` in `package.json` | `versions/mcp.txt` | `GET /health`, MCP handshake |
+| Web portal | — (commit-only) | — | `GET /version.json` on the portal host |
 
 # Schema
 
@@ -77,7 +81,12 @@ exception: `build.ps1` produces uploadable artifacts and reserves a real number
 ```
 
 The MCP manifest adds `docsCommit`, because for that component "which build" and "which
-documentation" are separate questions.
+documentation" are separate questions. `versions/web.json` carries `component`, `commit`,
+`deployedUtc` and `runId` (no `version`/`buildUtc` — the served `/version.json` holds the
+build moment). The portal's own stamp is generated into `public/version.json` by
+`scripts/generate-version.js` (prebuild) from `GITHUB_SHA`, served with
+`Cache-Control: no-store`, and `deploy-web.yml` polls it until the deployed commit
+matches the pushed SHA before publishing the manifest.
 
 Each is written **last and only after the deploy workflow has polled the component's
 health endpoint until it reports that exact version and commit**. A green deploy step
@@ -104,5 +113,6 @@ remain, being the customer-facing integrity contract.
 
 - `.github/scripts/Request-BuildNumber.ps1` — the CAS protocol
 - `.github/workflows/deploy-backend.yml`, `deploy-mcp.yml` — reserve, verify, publish
+- `.github/workflows/deploy-web.yml`, `src/Web/autopilot-monitor-web/scripts/generate-version.js` — web stamp, verify, publish
 - `.github/workflows/build-agent.yml`, `scripts/Deployment/build.ps1` — agent line
 - [Build Counter Blob](agent/build-counter-blob.md) — agent-specific consequences

docs/web/portal-navigation-prefetch.md

@@ -0,0 +1,126 @@
+---
+type: Concept
+title: Portal Navigation Prefetch & the SWA Runtime Bottleneck
+description: Why every navigation Link in the portal sets prefetch={false} — the App Router's viewport prefetch fires one RSC request per visible link, and the Static Web Apps SSR runtime queues them server-side into a multi-minute latency tail. Also records what the follow-up measurement showed about the Standard SKU and the keep-alive side effect.
+resource: src/Web/autopilot-monitor-web/components/GlobalSidebar.tsx
+tags:
+  - web
+  - performance
+  - nextjs
+  - static-web-apps
+  - observability
+timestamp: 2026-07-27T18:00:00+02:00
+---
+
+# Context
+
+The portal is a Next.js 15 App Router application hosted on Azure Static Web Apps. Every page under
+the authenticated shell is a client component behind `ProtectedRoute` that fetches its own data from
+the Function App (`autopilotmonitor-api-eu`) after mount. The RSC payload a route returns on
+navigation therefore carries no page data — only the shell.
+
+`GlobalSidebar` and `Navbar` render the full navigation on every page. With the App Router's default
+prefetch behaviour, each visible `<Link>` triggers a background `GET /<route>?_rsc=<hash>` as soon as
+it enters the viewport.
+
+# Mechanism
+
+Two properties combine into a portal-wide freeze:
+
+1. **Fan-out.** The navigation is fully rendered on each page load, so a single navigation issues one
+   RSC request per visible link — measured at ~10,400 requests over 14 days.
+2. **A heavy latency tail on the SSR runtime.** RSC responses are prerendered and edge-cached
+   (`x-nextjs-cache: HIT`, `s-maxage=31536000`), so the median is fast. On a cache miss or cold start
+   the Static Web Apps managed runtime queues them **server-side**, and the queue drains all at once.
+
+The navigation the user wants is then stuck behind that queue and the tab shows a loading spinner or a
+blank page until it drains. Nothing fails — the requests eventually return `200`, which is why the
+failure leaves no error trace anywhere.
+
+> **Correction (2026-07-28).** The original version of this document named a third property: that
+> `portal.autopilotmonitor.com` negotiates HTTP/1.1 and the prefetches exhaust the six-connection
+> browser cap. **That is wrong.** It came from `curl -w '%{http_version}'` on a Windows build of curl
+> whose Schannel backend has no HTTP/2 support, so it can only ever report `1.1`. ALPN says otherwise:
+> `openssl s_client -alpn h2,http/1.1` negotiates **h2** on the portal host, confirmed by a .NET
+> `HttpClient` request returning `HTTP/2.0`. There is no six-connection cap and connection starvation
+> was never the mechanism — the queue is server-side. Verify HTTP versions with `openssl s_client
+> -alpn` or `HttpClient`, never with this curl build.
+
+# Evidence
+
+Incident of 2026-07-27, 17:25–17:29 CEST. Browser-side dependencies during the freeze:
+
+| Request | Duration | Status |
+| --- | --- | --- |
+| `/admin/presence?_rsc=…` | 151,461 ms | 200 |
+| `/gather-rules?_rsc=…` | 52,283 ms | 200 |
+| `/progress?_rsc=…` | 37,878 ms | 200 |
+| `/analyze-rules?_rsc=…` | 37,559 ms | 200 |
+| `/audit?_rsc=…` | 37,539 ms | 200 |
+| Backend API, same window | 1,600–2,200 ms | 200 |
+
+The three ~37.5 s responses complete within 340 ms of each other — a queue draining, not independent
+slow requests. The corresponding `browserTimings` row for `/geographic-performance` reports
+`networkDuration` = 16 ms against `processingDuration` = 225,095 ms: the network delivered the
+document immediately and the browser then waited nearly four minutes for the `load` event.
+
+Fourteen-day distribution of RSC prefetches: n = 10,428, p50 = 91 ms, p95 = 896 ms, max = 234,230 ms,
+38 over 10 s, 21 over 30 s.
+
+# Outcome, measured 2026-07-28
+
+Two changes landed within half an hour of each other on 2026-07-27: the SWA plan went Free → Standard
+at 16:02:44 UTC, and `prefetch={false}` went live at 16:34:13 UTC. Twenty hours of production
+telemetry separate their effects.
+
+**The Standard plan produced no measurable latency gain.** Latency is governed almost entirely by the
+gap to the previous request — the SSR runtime cools down — so raw percentiles only measure the traffic
+mix. Stratified by that gap, the two eras are indistinguishable (p50, Free → Standard): `<10s`
+85 → 95 ms · `10-60s` 100 → 117 ms · `1-5min` 295 → 310 ms · `5-30min` 429 → 441 ms. Tail rates match
+too: Free ran 1.64 % over 2 s and 0.374 % over 10 s (n = 10,163); Standard produced 6 and 1 events at
+n = 258 against 4.2 and 1.0 expected. `browserTimings.totalDuration` by Mann-Whitney: n = 436 vs 48,
+z = −0.24, **p = 0.81**.
+
+**The prefetch fix is what removed the freezes** — worst `browserTimings.totalDuration` fell from
+225,277 ms to 4,856 ms, and the 30-second events stopped.
+
+**It also removed an accidental keep-alive.** The prefetch storm kept the SSR runtime warm: 85 % of
+requests used to arrive less than 10 s apart, now 46 % do. On an identical never-cacheable route
+(`/sessions/{id}`) the median rose from 87 ms to 211 ms and p90 from 465 ms to 1,480 ms. After 517
+minutes idle, one request took 11,441 ms and was abandoned (`resultCode 0`). The trade — minute-long
+freezes gone, ~150 ms added to a cold navigation — is worth it, but it is a trade.
+
+Do not benchmark this with a synthetic burst. Firing requests in quick succession warms the runtime
+and measures the best case: in a 25-round `curl --parallel-max 6` run, round 1 came in at p50 288 ms
+and rounds 4–25 at p50 113 ms.
+
+> **Endgame (2026-07-29).** The cold-start class was eliminated at the root: the portal became a
+> full static export (`output: 'export'`) — the SWA-managed SSR runtime no longer exists, so there
+> is nothing left to cool down. One escalation drove this: on 2026-07-28 a cold start exceeded the
+> SWA's 45-second function limit and the landing page served a hard "Backend call failure" 500.
+> The availability test that bridged the gap as a keep-alive stays as plain uptime monitoring.
+
+# Diagnosing this class of problem
+
+The backend Application Insights resource is the wrong place to look — a freeze appears there as an
+*absence* of requests, never as an error. Browser telemetry lives in a **separate** Application
+Insights resource addressed by `AUTOPILOT_MONITOR_WEB_APPINSIGHTS_ID`, which the MCP
+`query_backend_logs` tool does not reach. Query it through
+`.claude/commands/scripts/query-appinsights.sh` with that ID exported, and read `dependencies`
+(client-side fetches, including RSC prefetches) and `browserTimings` (the network/processing split of
+a document load).
+
+# Contract
+
+Navigation `<Link>` elements in `GlobalSidebar` and `Navbar` set `prefetch={false}`. The prefetched
+RSC payload buys nothing for these routes, so the only remaining cost of a click is the route's JS
+chunk, which the browser caches after first use.
+
+Do not remove the prop to "speed up navigation" without first re-measuring the tail in the web
+Application Insights resource — the prefetch is cheap only while the runtime is warm.
+
+# Citations
+
+* `src/Web/autopilot-monitor-web/components/GlobalSidebar.tsx` — nav link rendering, rationale comment
+* `src/Web/autopilot-monitor-web/components/Navbar.tsx` — top-bar and notification links
+* [SWA and Oryx node pinning](../architecture.md) — hosting model for the web app

infra/mcp-server.bicep

@@ -25,7 +25,7 @@
 //      az deployment group create \
 //        --resource-group <rg-name> \
 //        --template-file infra/mcp-server.bicep \
-//        --parameters apiUrl=https://autopilotmonitor-api.azurewebsites.net \
+//        --parameters apiUrl=https://autopilotmonitor-api-eu.azurewebsites.net \
 //                     entraClientSecret=<secret-value>
 //      This emits `containerAppUrl` as an output (e.g. https://autopilotmonitor-mcp.<env-suffix>.<region>.azurecontainerapps.io).
 //
@@ -60,8 +60,8 @@ param apiUrl string = 'https://autopilotmonitor-api-eu.azurewebsites.net'
 @description('Container image tag')
 param imageTag string = 'latest'
 
-@description('Entra ID app registration client_id used for the OAuth proxy. Public value (appears in JWT aud claim); not a secret.')
-param entraClientId string = '1a400946-62c1-4ab4-aa37-f730ac89704d'
+@description('Entra ID app registration client_id used for the OAuth proxy. Public value (appears in JWT aud claim); not a secret. Since the C4A8 app-reg move this is the NEW app (the old 1a400946-… app remains valid at the backend for legacy-homed tenants).')
+param entraClientId string = '886ab5e2-6144-442c-80cc-9b28e0667731'
 
 @secure()
 @description('Entra ID client secret for OAuth token exchange')
@@ -80,8 +80,8 @@ param mcpPublicUrl string = ''
 @description('Base64-encoded HMAC key (>=32 bytes after decode) for signing the OAuth proxy state. Naming and format match the backend\'s PaginationTokenSigningKey for consistency. Empty = generate per-instance random key on startup (acceptable for single-replica deployments since state has 10 min lifetime). Generate with PowerShell: [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))')
 param oAuthStateSigningKey string = ''
 
-@description('Enable structured tool-call logging to stderr (queryable via Container App Logs)')
-param toolLoggingEnabled bool = false
+@description('Enable structured tool-call logging to stderr (queryable via Container App Logs). Volume is one small JSON line per tool call - negligible at current usage.')
+param toolLoggingEnabled bool = true
 
 // --- Azure Container Registry ---
 

rules/analyze/ANALYZE-APP-001.json

@@ -5,8 +5,12 @@
   "description": "Detects when a Win32 app detection script fails or returns unexpected results.",
   "severity": "warning",
   "category": "apps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 60,
   "conditions": [
     {
@@ -34,5 +38,9 @@
       ]
     }
   ],
-  "tags": ["apps", "detection", "win32"]
+  "tags": [
+    "apps",
+    "detection",
+    "win32"
+  ]
 }

rules/analyze/ANALYZE-APP-002.json

@@ -5,8 +5,13 @@
   "description": "Detects app installation failures with specific exit codes or HRESULT error codes and suggests fixes.",
   "severity": "high",
   "category": "apps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:app_install_failed"
+  ],
   "baseConfidence": 80,
   "conditions": [
     {
@@ -36,5 +41,9 @@
       ]
     }
   ],
-  "tags": ["apps", "msi", "error-code"]
+  "tags": [
+    "apps",
+    "msi",
+    "error-code"
+  ]
 }

rules/analyze/ANALYZE-APP-003.json

@@ -6,6 +6,10 @@
   "severity": "high",
   "category": "apps",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 70,
   "conditions": [
     {
@@ -29,5 +33,9 @@
       ]
     }
   ],
-  "tags": ["apps", "dependency"]
+  "tags": [
+    "apps",
+    "dependency"
+  ],
+  "version": "1.1.0"
 }

rules/analyze/ANALYZE-APP-004.json

@@ -5,8 +5,13 @@
   "description": "Detects when disk space is critically low during enrollment, which can cause app installation failures. Confidence increases when app installations actually failed while disk space was low.",
   "severity": "critical",
   "category": "apps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:app_install_failed"
+  ],
   "baseConfidence": 75,
   "conditions": [
     {
@@ -36,8 +41,16 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "app_failed", "condition": "exists", "weight": 15 },
-    { "signal": "enrollment_failed", "condition": "exists", "weight": 10 }
+    {
+      "signal": "app_failed",
+      "condition": "exists",
+      "weight": 15
+    },
+    {
+      "signal": "enrollment_failed",
+      "condition": "exists",
+      "weight": 10
+    }
   ],
   "explanation": "Performance monitoring shows disk free space dropped below 5 GB during enrollment. This can cause app installation failures, especially for large Win32 apps.\n\nIf app installations failed in the same session while free space was low, treat storage exhaustion as the likely contributing cause — the confidence score of this finding is raised accordingly. Verify the individual app failures for their concrete error codes before concluding storage was the only cause.",
   "remediation": [
@@ -58,5 +71,9 @@
       ]
     }
   ],
-  "tags": ["apps", "disk-space", "critical"]
+  "tags": [
+    "apps",
+    "disk-space",
+    "critical"
+  ]
 }

rules/analyze/ANALYZE-APP-005.json

@@ -6,6 +6,10 @@
   "severity": "high",
   "category": "apps",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 70,
   "conditions": [
     {
@@ -29,5 +33,10 @@
       ]
     }
   ],
-  "tags": ["apps", "download", "timeout"]
+  "tags": [
+    "apps",
+    "download",
+    "timeout"
+  ],
+  "version": "1.1.0"
 }

rules/analyze/ANALYZE-APP-006.json

@@ -5,8 +5,12 @@
   "description": "Detects when the same app installation is attempted 3 or more times during one enrollment — a retry loop caused by unhonored reboot requests, repeated failures, or detection mismatches.",
   "severity": "high",
   "category": "apps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 70,
   "conditions": [
     {
@@ -31,5 +35,10 @@
       ]
     }
   ],
-  "tags": ["apps", "reboot", "retry", "loop"]
+  "tags": [
+    "apps",
+    "reboot",
+    "retry",
+    "loop"
+  ]
 }

rules/analyze/ANALYZE-APP-007.json

@@ -5,7 +5,13 @@
   "description": "Detects when the app tracking summary reports multiple failed app installations.",
   "severity": "high",
   "category": "apps",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:app_install_failed"
+  ],
   "baseConfidence": 75,
   "conditions": [
     {
@@ -16,10 +22,22 @@
       "operator": "gte",
       "value": "2",
       "required": true
+    },
+    {
+      "signal": "enrollment_failed",
+      "source": "event_type",
+      "eventType": "enrollment_failed",
+      "operator": "exists",
+      "value": "",
+      "required": false
     }
   ],
   "confidenceFactors": [
-    { "signal": "enrollment_failed", "condition": "exists", "weight": 15 }
+    {
+      "signal": "enrollment_failed",
+      "condition": "exists",
+      "weight": 15
+    }
   ],
   "explanation": "The app tracking summary reports 2 or more failed app installations during enrollment. This suggests a systemic issue rather than an isolated app failure.",
   "remediation": [
@@ -32,5 +50,9 @@
       ]
     }
   ],
-  "tags": ["apps", "summary", "multiple-failures"]
+  "tags": [
+    "apps",
+    "summary",
+    "multiple-failures"
+  ]
 }

rules/analyze/ANALYZE-APP-008.json

@@ -6,6 +6,10 @@
   "severity": "warning",
   "category": "apps",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 70,
   "conditions": [
     {
@@ -28,5 +32,11 @@
       ]
     }
   ],
-  "tags": ["apps", "performance", "slow-install", "warning"]
+  "tags": [
+    "apps",
+    "performance",
+    "slow-install",
+    "warning"
+  ],
+  "version": "1.1.0"
 }

rules/analyze/ANALYZE-APP-012.json

@@ -6,6 +6,10 @@
   "severity": "warning",
   "category": "apps",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "correlation",
   "baseConfidence": 80,
   "conditions": [
@@ -34,7 +38,17 @@
     }
   ],
   "relatedDocs": [
-    { "title": "Win32 app return codes in Intune", "url": "https://learn.microsoft.com/en-us/mem/intune/apps/apps-win32-app-management#step-4-return-codes" }
+    {
+      "title": "Win32 app return codes in Intune",
+      "url": "https://learn.microsoft.com/en-us/mem/intune/apps/apps-win32-app-management#step-4-return-codes"
+    }
   ],
-  "tags": ["apps", "enforcement", "exit-code", "unmapped", "resolved"]
+  "tags": [
+    "apps",
+    "enforcement",
+    "exit-code",
+    "unmapped",
+    "resolved"
+  ],
+  "version": "1.1.0"
 }

rules/analyze/ANALYZE-APP-013.json

@@ -5,8 +5,12 @@
   "description": "Detects when the Enrollment Status Page failed because Intune could not verify an app was installed (HRESULT 0x87D1041C). The installer ran but the detection rule did not match afterwards.",
   "severity": "critical",
   "category": "apps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 90,
   "preconditions": [
     {
@@ -69,8 +73,20 @@
     }
   ],
   "relatedDocs": [
-    { "title": "Microsoft Learn: Troubleshoot Windows Autopilot ESP error codes", "url": "https://learn.microsoft.com/en-us/autopilot/troubleshoot-tsg" },
-    { "title": "Win32 app detection rules in Intune", "url": "https://learn.microsoft.com/en-us/mem/intune/apps/apps-win32-add#step-4-detection-rules" }
+    {
+      "title": "Microsoft Learn: Troubleshoot Windows Autopilot ESP error codes",
+      "url": "https://learn.microsoft.com/en-us/autopilot/troubleshoot-tsg"
+    },
+    {
+      "title": "Win32 app detection rules in Intune",
+      "url": "https://learn.microsoft.com/en-us/mem/intune/apps/apps-win32-add#step-4-detection-rules"
+    }
   ],
-  "tags": ["apps", "detection", "esp", "0x87d1041c", "intune"]
+  "tags": [
+    "apps",
+    "detection",
+    "esp",
+    "0x87d1041c",
+    "intune"
+  ]
 }

rules/analyze/ANALYZE-APP-014.json

@@ -5,8 +5,12 @@
   "description": "Detects when the Enrollment Status Page failed on the Apps subcategory and the agent's AppX deployment log scan identified a suspected MSIX/Store package. Store/MSIX apps install outside the Win32 pipeline, so the regular per-app tracking sees nothing — this correlation names the likely culprit.",
   "severity": "warning",
   "category": "apps",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 75,
   "preconditions": [
     {
@@ -35,6 +39,51 @@
       "operator": "regex",
       "value": "^0x80073[cd]",
       "required": false
+    },
+    {
+      "signal": "appx_esp_category",
+      "source": "event_data",
+      "eventType": "esp_appx_failure_analysis",
+      "dataField": "espCategory",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "appx_esp_errorcode",
+      "source": "event_data",
+      "eventType": "esp_appx_failure_analysis",
+      "dataField": "espErrorCode",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "appx_top_candidate_package",
+      "source": "event_data",
+      "eventType": "esp_appx_failure_analysis",
+      "dataField": "topCandidatePackage",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "appx_candidate_count",
+      "source": "event_data",
+      "eventType": "esp_appx_failure_analysis",
+      "dataField": "candidateCount",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "appx_scan_confidence",
+      "source": "event_data",
+      "eventType": "esp_appx_failure_analysis",
+      "dataField": "confidence",
+      "operator": "exists",
+      "value": "",
+      "required": false
     }
   ],
   "explanation": "The ESP **{{espCategory}}/Apps** subcategory failed with HRESULT **{{espErrorCode}}** — an error from the AppX/MSIX deployment stack, i.e. a **Microsoft Store / MSIX app**, not a Win32 app. These apps install via the EnterpriseModernAppManagement CSP and never appear in the IME Win32 sidecar logs, which is why all tracked Win32/WinGet apps in this session can look green while ESP still reports an Apps failure.\n\nThe agent scanned the AppXDeploymentServer event log during the failure settle window and identified **{{topCandidatePackageName}}** (package `{{topCandidatePackage}}`) as the most likely culprit — its deployment error matches the ESP failure code ({{candidateCount}} candidate(s) total, confidence: {{confidence}}).\n\n**This is a correlation-based assessment, not a confirmed root cause** — validate against the AppXDeploymentServer/Operational event log on the device or in the diagnostics archive before acting.",
@@ -65,8 +114,21 @@
     }
   ],
   "relatedDocs": [
-    { "title": "Microsoft Learn: Troubleshoot Windows Autopilot ESP error codes", "url": "https://learn.microsoft.com/en-us/autopilot/troubleshoot-tsg" },
-    { "title": "Add Microsoft Store apps to Intune", "url": "https://learn.microsoft.com/en-us/mem/intune/apps/store-apps-microsoft" }
+    {
+      "title": "Microsoft Learn: Troubleshoot Windows Autopilot ESP error codes",
+      "url": "https://learn.microsoft.com/en-us/autopilot/troubleshoot-tsg"
+    },
+    {
+      "title": "Add Microsoft Store apps to Intune",
+      "url": "https://learn.microsoft.com/en-us/mem/intune/apps/store-apps-microsoft"
+    }
   ],
-  "tags": ["apps", "appx", "msix", "store", "esp", "0x80073cf9"]
+  "tags": [
+    "apps",
+    "appx",
+    "msix",
+    "store",
+    "esp",
+    "0x80073cf9"
+  ]
 }

rules/analyze/ANALYZE-APP-015.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-APP-015",
+  "title": "Required App Never Settled — ESP Completion Deferred",
+  "description": "The IME reported its user-session completion line, but at least one required app stayed pending — without ever failing or even starting to install — so the agent kept deferring the enrollment completion signal. Typically an assignment/requirement problem (requirement rules never met, dependency never satisfied, or the app needs a context that is not available during ESP, e.g. a VPN client waiting for user sign-in to a portal).",
+  "severity": "high",
+  "category": "apps",
+  "version": "1.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "trigger": "correlation",
+  "baseConfidence": 60,
+  "confidenceThreshold": 55,
+  "preconditions": [
+    {
+      "source": "event_data",
+      "eventType": "enrollment_complete",
+      "operator": "not_exists",
+      "description": "Suppress when the pending app eventually settled and the enrollment completed — a transient deferral is normal."
+    },
+    {
+      "source": "event_data",
+      "eventType": "enrollment_failed",
+      "operator": "not_exists",
+      "description": "Suppress when the session failed explicitly — the app/ESP failure rules already cover that path; this rule targets the never-finishing case."
+    }
+  ],
+  "conditions": [
+    {
+      "signal": "completion_deferred",
+      "source": "event_type",
+      "eventType": "agent_trace",
+      "dataField": "message",
+      "operator": "contains",
+      "value": "completion signal deferred",
+      "required": true
+    },
+    {
+      "signal": "apps_pending",
+      "source": "event_data",
+      "eventType": "app_tracking_summary",
+      "dataField": "pending",
+      "operator": "gte",
+      "value": "1",
+      "required": true
+    },
+    {
+      "signal": "pending_app_names",
+      "source": "event_data",
+      "eventType": "app_tracking_summary",
+      "dataField": "pendingNames",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    { "signal": "pending_app_names", "condition": "exists", "weight": 5 }
+  ],
+  "explanation": "The Intune Management Extension wrote its user-session completion line, but the agent observed `{{pending}}` required app(s) still pending (`{{pendingNames}}`) and therefore **deferred the enrollment completion signal** — repeatedly, if this happened across several logons or reboots.\n\nA pending app that never transitions to downloading/installing and never fails is almost always an **assignment or requirement problem**, not an install error:\n\n- requirement rules that are never met on this device (OS/architecture/registry/script checks),\n- an unsatisfied dependency or supersedence chain,\n- an app targeted as *required* for the user ESP that needs something unavailable during provisioning (e.g. a VPN client whose portal sign-in only happens after first logon),\n- user-targeted apps on a device where the user identity never fully registered (see the hybrid user-affinity rule if it also fired).",
+  "remediation": [
+    {
+      "title": "Identify and unblock the pending app",
+      "steps": [
+        "Check the app names listed in this finding's evidence (pendingNames) — these are the apps the ESP is waiting for.",
+        "In Intune, review the app's requirement rules and dependencies; test them on the device (IntuneManagementExtension.log logs each requirement evaluation).",
+        "Decide whether the app really must block the ESP: removing it from the ESP's 'blocking apps' list (or making it not-required during enrollment) unblocks completion immediately.",
+        "If the app is user-targeted on a hybrid-joined device, verify the user's Entra affinity first — without a signed-in Entra user, user-targeted policy never applies."
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Microsoft Learn: Enrollment Status Page — blocking apps",
+      "url": "https://learn.microsoft.com/en-us/intune/intune-service/enrollment/windows-enrollment-status"
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": ["apps", "esp", "completion", "assignment", "pending"]
+}

rules/analyze/ANALYZE-CORR-003.json

@@ -5,8 +5,13 @@
   "description": "Correlates an active proxy configuration with app content download failures (Delivery Optimization timeout or download error), suggesting the proxy is blocking or throttling Intune content delivery.",
   "severity": "high",
   "category": "apps",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:app_install_failed"
+  ],
   "trigger": "correlation",
   "baseConfidence": 60,
   "conditions": [
@@ -30,8 +35,16 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "app_install_failed", "condition": "count >= 2", "weight": 15 },
-    { "signal": "enrollment_failed", "condition": "count >= 1", "weight": 10 }
+    {
+      "signal": "app_install_failed",
+      "condition": "count >= 2",
+      "weight": 15
+    },
+    {
+      "signal": "enrollment_failed",
+      "condition": "count >= 1",
+      "weight": 10
+    }
   ],
   "confidenceThreshold": 50,
   "explanation": "A proxy (explicit or PAC-based) is configured on this device and app content downloads failed (Delivery Optimization timeout or download content error). Proxies can block or throttle downloads from *.delivery.mp.microsoft.com and other Intune CDN endpoints.\n\nThis is a common root cause when app downloads fail consistently on proxy-connected corporate networks. Note this rule only fires when the failure is download-related — generic app install errors behind a proxy do not trigger it.",
@@ -54,5 +67,12 @@
       ]
     }
   ],
-  "tags": ["correlation", "apps", "proxy", "network", "download", "root-cause"]
+  "tags": [
+    "correlation",
+    "apps",
+    "proxy",
+    "network",
+    "download",
+    "root-cause"
+  ]
 }

rules/analyze/ANALYZE-DEV-002.json

@@ -5,8 +5,12 @@
   "description": "Detects when memory usage stays above 90% across at least 3 performance snapshots during enrollment, indicating sustained memory pressure that can cause app installation failures or system instability.",
   "severity": "warning",
   "category": "device",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 55,
   "conditions": [
     {
@@ -38,8 +42,16 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "app_failed", "condition": "exists", "weight": 20 },
-    { "signal": "enrollment_failed", "condition": "exists", "weight": 15 }
+    {
+      "signal": "app_failed",
+      "condition": "exists",
+      "weight": 20
+    },
+    {
+      "signal": "enrollment_failed",
+      "condition": "exists",
+      "weight": 15
+    }
   ],
   "explanation": "Memory usage exceeded 90% in at least 3 performance snapshots during this enrollment — sustained pressure, not a single transient spike. Persistent high memory usage can cause app installation failures, system slowdowns, and ESP timeouts, especially on devices with 8 GB RAM installing several apps concurrently.",
   "remediation": [
@@ -53,5 +65,9 @@
       ]
     }
   ],
-  "tags": ["device", "memory", "performance"]
+  "tags": [
+    "device",
+    "memory",
+    "performance"
+  ]
 }

rules/analyze/ANALYZE-DEV-003.json

@@ -5,8 +5,12 @@
   "description": "Detects devices enrolling with an OS build that has reached end of support: Windows 11 22H2 (build 22621) or older, which includes every Windows 10 build. Maintenance note: raise the build cutoff to 22631 after Windows 11 23H2 reaches end of support on 2026-11-10.",
   "severity": "warning",
   "category": "device",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 90,
   "conditions": [
     {
@@ -52,5 +56,11 @@
       "url": "https://learn.microsoft.com/en-us/lifecycle/products/windows-11-home-and-pro"
     }
   ],
-  "tags": ["device", "os-version", "end-of-support", "windows-11", "windows-10"]
+  "tags": [
+    "device",
+    "os-version",
+    "end-of-support",
+    "windows-11",
+    "windows-10"
+  ]
 }

rules/analyze/ANALYZE-DEV-004.json

@@ -5,8 +5,13 @@
   "description": "Detects a Windows quality/cumulative update that FAILED to install during the OOBE / ESP enrollment window (WindowsUpdateClient EventID 20). A cumulative update failing mid-OOBE is a known cause of enrollment errors and is otherwise invisible in the Intune console.",
   "severity": "high",
   "category": "device",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:windows_update_failed"
+  ],
   "trigger": "single",
   "baseConfidence": 70,
   "confidenceThreshold": 60,
@@ -65,8 +70,16 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "enrollment_failed", "condition": "exists", "weight": 20 },
-    { "signal": "reboot_pending", "condition": "exists", "weight": 10 }
+    {
+      "signal": "enrollment_failed",
+      "condition": "exists",
+      "weight": 20
+    },
+    {
+      "signal": "reboot_pending",
+      "condition": "exists",
+      "weight": 10
+    }
   ],
   "explanation": "A Windows Update failed to install during enrollment: **{{updateTitle}}** (error {{hresult}} {{hresultSymbol}}). Windows can install quality/cumulative updates during OOBE (the \"Getting updates\" screen and the ESP \"Install Windows quality updates during OOBE\" option). When one of these fails mid-enrollment it can leave the device in an inconsistent state, force an unexpected reboot, or block the Enrollment Status Page — a failure mode that is otherwise only discoverable by deep manual digging on the device.",
   "remediation": [
@@ -87,5 +100,10 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["device", "windows-update", "oobe", "servicing"]
+  "tags": [
+    "device",
+    "windows-update",
+    "oobe",
+    "servicing"
+  ]
 }

rules/analyze/ANALYZE-DEV-005.json

@@ -5,8 +5,12 @@
   "description": "Informational: a Windows quality/cumulative update installed during the OOBE / ESP enrollment window (WindowsUpdateClient EventID 19). Surfaces updates applied mid-enrollment — useful context when correlating enrollment duration, reboots, or later issues with a specific KB.",
   "severity": "info",
   "category": "device",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 60,
   "confidenceThreshold": 50,
@@ -39,7 +43,11 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "reboot_pending", "condition": "exists", "weight": 15 }
+    {
+      "signal": "reboot_pending",
+      "condition": "exists",
+      "weight": 15
+    }
   ],
   "explanation": "One or more Windows updates installed during enrollment (e.g. **{{updateTitle}}**). This is normal when Windows Update runs during OOBE, but it extends enrollment time and can trigger a reboot mid-ESP. Track it when correlating enrollment duration or reboot count with a specific cumulative update, or when a device behaves differently after a particular KB landed during provisioning.",
   "remediation": [
@@ -53,5 +61,9 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["device", "windows-update", "oobe"]
+  "tags": [
+    "device",
+    "windows-update",
+    "oobe"
+  ]
 }

rules/analyze/ANALYZE-DEV-006.json

@@ -5,8 +5,12 @@
   "description": "Informational: the OS build (CurrentBuild.UBR) changed across a reboot during enrollment — an update was installed, regardless of which servicing path delivered it. Deterministic corroboration that works even when the Windows Update event channel shows nothing (registry comparison across restart cannot be lost to timing or logging-path differences).",
   "severity": "info",
   "category": "device",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 70,
   "confidenceThreshold": 50,
@@ -47,7 +51,11 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "wu_channel_blind", "condition": "exists", "weight": 10 }
+    {
+      "signal": "wu_channel_blind",
+      "condition": "exists",
+      "weight": 10
+    }
   ],
   "explanation": "The OS build changed from **{{previousBuild}}** to **{{currentBuild}}** across a reboot during enrollment — a Windows update was installed mid-provisioning. This is normal when quality updates run during OOBE, but it adds a reboot and extends enrollment time. If a windows_update_channel_census event is also present, the update installed via a servicing path the Windows Update watcher does not capture yet — its EventID histogram tells which IDs to enable.",
   "remediation": [
@@ -61,5 +69,10 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["device", "windows-update", "oobe", "reboot"]
+  "tags": [
+    "device",
+    "windows-update",
+    "oobe",
+    "reboot"
+  ]
 }

rules/analyze/ANALYZE-DEV-007.json

@@ -5,9 +5,13 @@
   "description": "The device's real-time clock deviates from NTP by more than two minutes. Microsoft documents that a clock off by several minutes causes TPM attestation errors (self-deploying/pre-provisioning) and ESP timeouts. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md.",
   "severity": "warning",
   "category": "device",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 55,
   "confidenceThreshold": 50,
@@ -55,5 +59,12 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["device", "ntp", "clock-skew", "tpm", "esp", "known-issue"]
+  "tags": [
+    "device",
+    "ntp",
+    "clock-skew",
+    "tpm",
+    "esp",
+    "known-issue"
+  ]
 }

rules/analyze/ANALYZE-ENRL-002.json

@@ -5,7 +5,7 @@
   "description": "Detects when the enrollment session was force-failed by the server-side inactivity timeout (no agent telemetry for the configured SessionTimeoutHours window) without ever completing or explicitly failing.",
   "severity": "high",
   "category": "enrollment",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "enabled": true,
   "baseConfidence": 80,
   "preconditions": [
@@ -30,9 +30,35 @@
       "operator": "exists",
       "value": "",
       "required": true
+    },
+    {
+      "signal": "timeoutHours",
+      "source": "event_data",
+      "eventType": "session_timeout",
+      "dataField": "timeoutHours",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "desktop_was_reached",
+      "source": "event_type",
+      "eventType": "desktop_arrived",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "all_tracked_apps_completed",
+      "source": "event_data",
+      "eventType": "app_tracking_summary",
+      "dataField": "isAllCompleted",
+      "operator": "equals",
+      "value": "true",
+      "required": false
     }
   ],
-  "explanation": "The enrollment session was force-failed by the server-side maintenance sweep after `{{timeoutHours}}` hour(s) of agent inactivity — the device stopped sending telemetry and never reported completion or an explicit failure.\n\nThis usually means the agent process died or the device went offline mid-enrollment (power off, network loss, bluescreen, reimage) rather than a clean enrollment failure. Because there is no terminal `enrollment_failed` event, the more specific app/ESP rules cannot pinpoint a cause — the evidence simply stops at the last event before the gap.",
+  "explanation": "The enrollment session was force-failed by the server-side maintenance sweep after `{{timeoutHours}}` hour(s) of agent inactivity — the device stopped sending telemetry and never reported completion or an explicit failure.\n\nThis usually means the agent process died or the device went offline mid-enrollment (power off, network loss, bluescreen, reimage) rather than a clean enrollment failure. Because there is no terminal `enrollment_failed` event, the more specific app/ESP rules cannot pinpoint a cause — the evidence simply stops at the last event before the gap.\n\n**If the evidence shows the user desktop was reached and all tracked apps completed**, the device most likely got all its content but the ESP never signaled completion — on hybrid-joined devices the usual culprit is the user session never establishing Entra affinity (Account Setup re-running on every logon). Check whether the hybrid user-affinity finding also fired for this session.",
   "remediation": [
     {
       "title": "Investigate the silent session",
@@ -43,6 +69,13 @@
         "If the device is reachable, collect the agent + IME logs and re-run enrollment, correlating with the timeout timestamp",
         "If many sessions time out in the same window, check for a tenant-wide network/connectivity issue or an Intune service incident"
       ]
+    },
+    {
+      "title": "Desktop reached and apps done, but no completion",
+      "steps": [
+        "Sign in as the affected user and run dsregcmd /status — 'SSO State: AzureAdPrt' must be YES; NO means the user never registered with Entra and the Account Setup ESP will loop",
+        "Verify Entra Connect syncs both the computer object (userCertificate) and the signing-in user, and that the user's UPN suffix is a verified Entra domain"
+      ]
     }
   ],
   "tags": ["enrollment", "timeout", "stalled"]

rules/analyze/ANALYZE-ENRL-003.json

@@ -5,9 +5,14 @@
   "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Observability: attestation precedes MDM enrollment, so in the normal deployment model (agent installed via IME after enrollment) these codes are rarely visible — the rule primarily serves bootstrap-token deployments. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).",
   "severity": "high",
   "category": "enrollment",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:modern_deployment_error"
+  ],
   "trigger": "single",
   "baseConfidence": 60,
   "confidenceThreshold": 55,
@@ -75,5 +80,12 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["enrollment", "tpm", "attestation", "self-deploying", "pre-provisioning", "known-issue"]
+  "tags": [
+    "enrollment",
+    "tpm",
+    "attestation",
+    "self-deploying",
+    "pre-provisioning",
+    "known-issue"
+  ]
 }

rules/analyze/ANALYZE-ENRL-004.json

@@ -5,9 +5,13 @@
   "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Observability: a blocked MDM enrollment normally means no agent gets installed at all (IME install happens after enrollment) — this rule can realistically only fire for bootstrap-token deployments (pre-MDM reporting) or mixed retry scenarios. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).",
   "severity": "high",
   "category": "enrollment",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 60,
   "confidenceThreshold": 55,
@@ -74,5 +78,11 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["enrollment", "mdm", "known-issue", "entra-id", "hybrid-join"]
+  "tags": [
+    "enrollment",
+    "mdm",
+    "known-issue",
+    "entra-id",
+    "hybrid-join"
+  ]
 }

rules/analyze/ANALYZE-ENRL-005.json

@@ -5,9 +5,13 @@
   "description": "A Microsoft Entra hybrid join Autopilot deployment hit error 0x80004005 — a documented build-dependent known issue, resolved by KB5065789 (25H2, build >= 26200.6725), KB5065426 (24H2, build >= 26100.6584), and KB5070312 (23H2, build >= 22631.6276). Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
   "severity": "high",
   "category": "enrollment",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "correlation",
   "baseConfidence": 25,
   "confidenceThreshold": 60,
@@ -59,10 +63,26 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "e_fail_esp_failure", "condition": "exists", "weight": 40 },
-    { "signal": "e_fail_esp_advisory", "condition": "exists", "weight": 35 },
-    { "signal": "e_fail_modern_deployment", "condition": "exists", "weight": 40 },
-    { "signal": "e_fail_error_detected", "condition": "exists", "weight": 35 }
+    {
+      "signal": "e_fail_esp_failure",
+      "condition": "exists",
+      "weight": 40
+    },
+    {
+      "signal": "e_fail_esp_advisory",
+      "condition": "exists",
+      "weight": 35
+    },
+    {
+      "signal": "e_fail_modern_deployment",
+      "condition": "exists",
+      "weight": 40
+    },
+    {
+      "signal": "e_fail_error_detected",
+      "condition": "exists",
+      "weight": 35
+    }
   ],
   "explanation": "This is a **Microsoft Entra hybrid join** deployment that hit error **0x80004005** — a documented, build-dependent Autopilot known issue where hybrid deployments time out.\n\nThe issue is fixed by Windows cumulative updates:\n\n- Windows 11 **25H2**: KB5065789 — fixed from build **26200.6725**\n- Windows 11 **24H2**: KB5065426 — fixed from build **26100.6584**\n- Windows 11 **23H2**: KB5070312 — fixed from build **22631.6276**\n\nCompare this session's OS build (see the Session Info card / os_info event) against the fixed-build threshold for its version. If the device booted with an older build, updating the deployment image (or installing quality updates during OOBE) resolves the timeout. Note that 0x80004005 is a generic failure code (E_FAIL) — if the build is already at or above the fixed threshold, investigate the Intune Connector for Active Directory and domain-controller connectivity instead.",
   "remediation": [
@@ -83,5 +103,11 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["enrollment", "hybrid-join", "known-issue", "windows-update", "esp"]
+  "tags": [
+    "enrollment",
+    "hybrid-join",
+    "known-issue",
+    "windows-update",
+    "esp"
+  ]
 }

rules/analyze/ANALYZE-ESP-001.json

@@ -5,8 +5,12 @@
   "description": "Detects when the DeviceSetup phase of the ESP took longer than 30 minutes, indicating a stuck or very slow blocking app. Confidence increases when the phase exceeds 60 minutes.",
   "severity": "high",
   "category": "esp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 50,
   "conditions": [
     {
@@ -20,8 +24,16 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "long_esp", "condition": "phase_duration > 1800", "weight": 40 },
-    { "signal": "very_long_esp", "condition": "phase_duration > 3600", "weight": 15 }
+    {
+      "signal": "long_esp",
+      "condition": "phase_duration > 1800",
+      "weight": 40
+    },
+    {
+      "signal": "very_long_esp",
+      "condition": "phase_duration > 3600",
+      "weight": 15
+    }
   ],
   "confidenceThreshold": 70,
   "explanation": "The ESP DeviceSetup phase took more than 30 minutes. This indicates a blocking app is stuck installing, downloading very slowly, or has entered a retry loop. A duration beyond 60 minutes raises the confidence further — at that point the enrollment is almost certainly held by a single stuck blocking item rather than ordinary slowness.",
@@ -35,5 +47,10 @@
       ]
     }
   ],
-  "tags": ["esp", "blocking", "timeout", "duration"]
+  "tags": [
+    "esp",
+    "blocking",
+    "timeout",
+    "duration"
+  ]
 }

rules/analyze/ANALYZE-ESP-002.json

@@ -5,9 +5,13 @@
   "description": "Detects when the Certificates subcategory of the Enrollment Status Page reported a failure, even if the enrollment later appears to have succeeded. Users can click 'Continue anyway' on an ESP error, which masks the underlying certificate provisioning failure — this rule surfaces the transition so it stays visible.",
   "severity": "high",
   "category": "esp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 80,
   "conditions": [
@@ -54,5 +58,10 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["esp", "certificates", "subcategory", "silent-failure"]
+  "tags": [
+    "esp",
+    "certificates",
+    "subcategory",
+    "silent-failure"
+  ]
 }

rules/analyze/ANALYZE-ESP-005.json

@@ -5,9 +5,13 @@
   "description": "Attributes an observed enrollment reboot to device-assigned MDM policies that Windows flagged as reboot-required. Fires ONLY when both facts are present in the session: at least one actually-observed reboot (system_reboot_detected) AND reboot-required policy flags (mdm_policy_reboot_required). Policy flags alone — e.g. from a user-policy sync during AccountSetup — force no reboot and stay advisory-silent.",
   "severity": "warning",
   "category": "esp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 70,
   "conditions": [
@@ -47,8 +51,16 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "multiple_reboot_uris", "condition": "exists", "weight": 10 },
-    { "signal": "omadm_reboot_flag_set", "condition": "exists", "weight": 15 }
+    {
+      "signal": "multiple_reboot_uris",
+      "condition": "exists",
+      "weight": 10
+    },
+    {
+      "signal": "omadm_reboot_flag_set",
+      "condition": "exists",
+      "weight": 15
+    }
   ],
   "confidenceThreshold": 70,
   "explanation": "This session **rebooted during enrollment**, and Windows flagged one or more device-assigned MDM policies as **reboot-required** — the classic cause of the coalesced mid-ESP restart and the unexpected **second sign-in screen** before AccountSetup.\n\nFirst reboot-forcing policy URI: `{{firstRebootUri}}`\n\nThe complete URI list is in the `mdm_policy_reboot_required` timeline event (`rebootUris`). Policies applied DURING ESP DeviceSetup are coalesced into one forced restart at the end of DeviceSetup; the same flags raised later (e.g. user-policy sync in AccountSetup) have no immediate effect — this advisory only fires when a reboot was actually observed.\n\nThis is expected OS behavior, not a failure — but it degrades the enrollment experience, confuses users, and is invisible in the Intune console.",
@@ -81,5 +93,12 @@
     }
   ],
   "markSessionAsFailedDefault": false,
-  "tags": ["esp", "reboot", "coalescing", "second-sign-in", "policy-attribution", "user-experience"]
+  "tags": [
+    "esp",
+    "reboot",
+    "coalescing",
+    "second-sign-in",
+    "policy-attribution",
+    "user-experience"
+  ]
 }

rules/analyze/ANALYZE-ESP-006.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-ESP-006",
+  "title": "ESP Failure Recovered After User Retry",
+  "description": "Detects the recovery story: the ESP reported a terminal failure (typically DeviceSetup/Apps), the user most likely pressed 'Try again' on the failure page, the failed step re-ran and completed successfully. The earlier failure did not stick — the enrollment continued past it.",
+  "severity": "info",
+  "category": "esp",
+  "version": "1.1.0",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
+  "baseConfidence": 85,
+  "conditions": [
+    {
+      "signal": "advisory",
+      "source": "event_type",
+      "eventType": "esp_failure_advisory",
+      "operator": "exists",
+      "value": "",
+      "required": true
+    },
+    {
+      "signal": "recovered",
+      "source": "event_type",
+      "eventType": "esp_failure_recovered",
+      "operator": "exists",
+      "value": "",
+      "required": true
+    },
+    {
+      "signal": "retry",
+      "source": "event_type",
+      "eventType": "esp_failure_retry_detected",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "category",
+      "source": "event_type",
+      "eventType": "esp_failure_recovered",
+      "dataField": "category",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "failedSubcategory",
+      "source": "event_type",
+      "eventType": "esp_failure_recovered",
+      "dataField": "failedSubcategory",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "likelyCulpritApps",
+      "source": "event_type",
+      "eventType": "esp_failure_advisory",
+      "dataField": "likelyCulpritApps",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    },
+    {
+      "signal": "minutesSinceFailure",
+      "source": "event_type",
+      "eventType": "esp_failure_recovered",
+      "dataField": "minutesSinceFailure",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    {
+      "signal": "retry",
+      "condition": "exists",
+      "weight": 10
+    },
+    {
+      "signal": "likelyCulpritApps",
+      "condition": "exists",
+      "weight": 5
+    }
+  ],
+  "explanation": "The Enrollment Status Page reported a **failure** in the `{{category}}` phase (`{{failedSubcategory}}` subcategory, most likely app(s): `{{likelyCulpritApps}}`) — and then **recovered**: the failed step left its failed state and completed successfully about `{{minutesSinceFailure}}` min later.\n\nThat pattern is consistent with the user pressing **'Try again'** on the ESP failure page (the profile allows failure-page actions; the agent cannot observe the click itself). The failure the user saw was real, but it did not stick — the ESP re-ran the step, it succeeded, and the enrollment continued.\n\nRead the session timeline as one arc: `esp_failure_advisory` (the failure, with the likely culprit app) → `esp_failure_retry_detected` (the retry) → `esp_failure_recovered` (the recovery). If this pattern repeats across devices for the same app, that app's install is flaky on first attempt — fix the app rather than the devices. Any literal `{{…}}` placeholder means that detail was not recorded for this session.",
+  "remediation": [
+    {
+      "title": "Make the first install attempt stick",
+      "steps": [
+        "Check the likely culprit app(s) (`{{likelyCulpritApps}}`) in Intune: an app that fails on the first ESP pass but succeeds on retry usually has a dependency/ordering or detection-timing problem.",
+        "If the app shows 'never started installing' in esp_failure_settle_started, verify its assignment and applicability rules — ESP counted it as required, but IME never processed it.",
+        "If the pattern repeats across the tenant, consider removing the app from the ESP blocking list until the first-attempt install is reliable — users are seeing an avoidable failure screen.",
+        "No device-side action is needed for this session: the failure recovered and the enrollment continued."
+      ]
+    }
+  ],
+  "tags": [
+    "esp",
+    "recovery",
+    "try-again",
+    "retry",
+    "continue-anyway",
+    "enrollment"
+  ]
+}

rules/analyze/ANALYZE-ID-001.json

@@ -7,7 +7,11 @@
   "category": "identity",
   "isCommunity": true,
   "enabled": false,
-  "version": "1.2.0",
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
+  "version": "1.3.0",
   "baseConfidence": 75,
   "conditions": [
     {
@@ -50,7 +54,12 @@
       ]
     }
   ],
-  "tags": ["identity", "certificates", "machine-store", "subject-check"],
+  "tags": [
+    "identity",
+    "certificates",
+    "machine-store",
+    "subject-check"
+  ],
   "templateVariables": [
     {
       "name": "cert_subject",

rules/analyze/ANALYZE-ID-002.json

@@ -5,9 +5,13 @@
   "description": "Detects when the LocalAdminAnalyzer flags unexpected local user accounts or profile directories on the device. This is a known Autopilot bypass technique where admin accounts are created before or during enrollment to gain persistent local admin access.",
   "severity": "high",
   "category": "identity",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 60,
   "conditions": [
@@ -81,5 +85,10 @@
     }
   ],
   "relatedDocs": [],
-  "tags": ["identity", "security", "local-admin", "bypass-detection"]
+  "tags": [
+    "identity",
+    "security",
+    "local-admin",
+    "bypass-detection"
+  ]
 }

rules/analyze/ANALYZE-ID-003.json

@@ -5,9 +5,13 @@
   "description": "Fires when the vulnerability correlation finds critical-severity CVEs or CISA KEV entries in installed software. This indicates the device has software with known, actively exploited vulnerabilities.",
   "severity": "critical",
   "category": "security",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "author": "Autopilot Monitor",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 90,
   "conditions": [
@@ -31,7 +35,11 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "kev_matches", "condition": "exists", "weight": 10 }
+    {
+      "signal": "kev_matches",
+      "condition": "exists",
+      "weight": 10
+    }
   ],
   "confidenceThreshold": 80,
   "explanation": "The device has installed software with critical vulnerabilities. Software with CVEs rated CRITICAL (CVSS >= 9.0) or listed in the CISA Known Exploited Vulnerabilities catalog was detected. These vulnerabilities are actively targeted by attackers and should be remediated immediately.",
@@ -64,5 +72,11 @@
       "url": "https://nvd.nist.gov/"
     }
   ],
-  "tags": ["vulnerability", "cve", "kev", "critical", "security"]
+  "tags": [
+    "vulnerability",
+    "cve",
+    "kev",
+    "critical",
+    "security"
+  ]
 }

rules/analyze/ANALYZE-ID-004.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-ID-004",
+  "title": "Hybrid Sign-In Never Establishes Entra User Affinity",
+  "description": "On a hybrid-joined device the real user reached the desktop, but the Autopilot provisioning placeholder stayed active in JoinInfo and the agent repeatedly reported the hybrid sign-in as overdue. The user session never establishes Entra user affinity (no PRT), so the Account Setup ESP re-runs on every logon and the enrollment never completes.",
+  "severity": "high",
+  "category": "identity",
+  "version": "1.2.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "trigger": "correlation",
+  "evaluateOn": ["enrollment_end", "on_event:hybrid_login_pending"],
+  "baseConfidence": 60,
+  "confidenceThreshold": 75,
+  "preconditions": [
+    {
+      "source": "event_data",
+      "eventType": "enrollment_complete",
+      "operator": "not_exists",
+      "description": "Suppress when the session eventually completed — a single overdue-login warning followed by a successful sign-in is normal hybrid latency, not a broken affinity."
+    }
+  ],
+  "conditions": [
+    {
+      "signal": "hybrid_login_overdue",
+      "source": "event_type",
+      "eventType": "hybrid_login_pending",
+      "operator": "exists",
+      "value": "",
+      "required": true
+    },
+    {
+      "signal": "user_desktop_reached",
+      "source": "event_type",
+      "eventType": "desktop_arrived",
+      "operator": "exists",
+      "value": "",
+      "required": true
+    },
+    {
+      "signal": "placeholder_still_active",
+      "source": "event_type",
+      "eventType": "aad_placeholder_user_detected",
+      "operator": "exists",
+      "value": "",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    { "signal": "hybrid_login_pending", "condition": "count >= 2", "weight": 20 },
+    { "signal": "hybrid_login_pending", "condition": "count >= 3", "weight": 10 },
+    { "signal": "aad_placeholder_user_detected", "condition": "count >= 3", "weight": 10 }
+  ],
+  "explanation": "A real user signed in and reached the desktop, but the device kept reporting the **Autopilot provisioning placeholder** as the active identity in JoinInfo and the hybrid sign-in as **overdue** — across multiple reboots. This means the signed-in user never established **Microsoft Entra user affinity** (no Primary Refresh Token), so:\n\n- the Account Setup ESP page re-appears on every logon,\n- user-targeted required apps and policies cannot settle,\n- the enrollment never reaches completion.\n\nAfter this many hours this is not normal Entra Connect sync latency — something is structurally preventing the user (or the computer object) from registering:\n\n- the computer object's `userCertificate` attribute is not syncing to Entra ID (sync scope / OU filtering),\n- the signing-in user is not synced, or their UPN does not match a verified Entra domain,\n- the device has no line of sight to a domain controller **at logon time**, so the hybrid PRT flow cannot finish,\n- time skew or a proxy blocking `login.microsoftonline.com` / `enterpriseregistration.windows.net` from the user context.\n\nA frequent variant: the user's **first sign-in happens without domain-controller reachability** — for example when a pre-logon VPN tunnel (GlobalProtect, Always On VPN, Zscaler ZPA) is not established yet at the logon screen. Windows falls back to cached credentials, the hybrid PRT flow silently never runs, and later reboots do not fix it — sessions in this state typically show repeated reboots and network flapping while the placeholder identity stays active.\n\nA visible side effect: **the Windows Hello for Business wizard never appears**, because Hello provisioning requires an Entra user token (PRT). Hello is a downstream symptom here, not the cause.",
+  "remediation": [
+    {
+      "title": "Verify user affinity on the device",
+      "steps": [
+        "Sign in as the affected user and run: dsregcmd /status — under 'SSO State' the value AzureAdPrt must be YES. NO means the user has no Entra token and this diagnosis is confirmed.",
+        "Also check 'Device State': AzureAdJoined = YES and DomainJoined = YES are expected for hybrid join.",
+        "Check Event Viewer: Applications and Services Logs > Microsoft > Windows > User Device Registration > Admin for PRT / registration errors (e.g. event 304/305/362).",
+        "Enable the gather rules 'Collect dsregcmd join status' so future sessions capture this state automatically."
+      ]
+    },
+    {
+      "title": "Fix the identity pipeline",
+      "steps": [
+        "Entra Connect: confirm BOTH the computer OU and the user OU are in the sync scope, and the computer object's userCertificate attribute is being exported.",
+        "Verify the user's UPN suffix is a verified domain in Entra ID (no .local / mismatched suffix).",
+        "Ensure domain-controller line of sight at logon from the provisioning network/VLAN (hybrid PRT requires a reachable DC).",
+        "Check proxy/firewall rules for login.microsoftonline.com, device.login.microsoftonline.com and enterpriseregistration.windows.net from the user context."
+      ]
+    },
+    {
+      "title": "Address VPN and Windows Hello dependencies",
+      "steps": [
+        "If a VPN is required to reach a domain controller, it must be established before or at the logon screen (machine tunnel / pre-logon tunnel). A user-context tunnel that starts after sign-in is too late for the hybrid PRT flow.",
+        "If you deploy Windows Hello for Business to hybrid-joined devices, use cloud Kerberos trust — it removes the on-premises certificate/key-trust dependencies that commonly stall Hello on hybrid devices.",
+        "If you do not use Windows Hello, disable it explicitly via a device-scoped Intune policy instead of leaving it unconfigured — the enrollment then resolves the Hello step deterministically instead of waiting for a wizard that never comes.",
+        "Avoid feature/quality updates mid-enrollment where possible — an OS update with forced reboots during enrollment aggravates this pattern. Consider a short Windows Update deferral covering the enrollment window.",
+        "For hybrid deployments, pre-provisioning (White Glove) materially shrinks the user-facing phase: the device phase runs on a known-good technician network, and the user phase reduces to sign-in, user ESP, and Hello."
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Autopilot Monitor: Hybrid join — stuck in Account Setup (no user affinity)",
+      "url": "https://docs.autopilotmonitor.com/troubleshooting/hybrid-join-stuck-in-account-setup"
+    },
+    {
+      "title": "Autopilot Monitor: Hybrid join — late device registration",
+      "url": "https://docs.autopilotmonitor.com/troubleshooting/hybrid-join-late-device-registration"
+    },
+    {
+      "title": "Microsoft Learn: Troubleshoot hybrid-joined devices",
+      "url": "https://learn.microsoft.com/en-us/entra/identity/devices/troubleshoot-hybrid-join-windows-current"
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": ["identity", "hybrid-join", "entra-id", "user-affinity", "esp"]
+}

rules/analyze/ANALYZE-OFFICE-001.json

@@ -5,8 +5,12 @@
   "description": "Detects when the Microsoft 365 Apps (Office Click-to-Run) background install did not reach completion. The V2 OfficeInstallDetector watches the C2R client directly (registry + process) and emits office_install_failed when the install scenario was abandoned (worker gone and streaming never finished) or a C2R failure code was observed. This catches Office failures that the Intune integrated app type hides, because IME reports the app done within 1-2 minutes while C2R keeps installing in the background.",
   "severity": "warning",
   "category": "apps",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 75,
   "conditions": [
     {
@@ -28,7 +32,11 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "error_code_present", "condition": "exists", "weight": 15 }
+    {
+      "signal": "error_code_present",
+      "condition": "exists",
+      "weight": 15
+    }
   ],
   "confidenceThreshold": 40,
   "explanation": "The Microsoft 365 Apps (Office Click-to-Run) install did not finish.\n\nThe OfficeInstallDetector watches the C2R client directly and reports the real background install lifecycle. The Intune \"integrated\" Microsoft 365 Apps app type only pushes the configuration XML and starts the C2R bootstrapper, so IME marks the app done within 1-2 minutes while C2R keeps streaming and laying down the product for several more minutes. This event means C2R activity ended (the OfficeC2RClient worker exited and the install scenario cleared) without the StreamingFinished flag being set, or a C2R failure code was observed.\n\nReview the office_install_failed event payload: `products`, `channel`, `phase`, `streamingFinished`, `errorCode` (best-effort — may be empty) and `durationSeconds`.",
@@ -44,5 +52,11 @@
       ]
     }
   ],
-  "tags": ["apps", "office", "microsoft-365-apps", "click-to-run", "install-failure"]
+  "tags": [
+    "apps",
+    "office",
+    "microsoft-365-apps",
+    "click-to-run",
+    "install-failure"
+  ]
 }

rules/analyze/ANALYZE-SEC-001.json

@@ -5,8 +5,12 @@
   "description": "Detects devices where the Windows UEFI CA 2023 certificate has not been deployed to the Secure Boot DB. The 2011 certificates expired in June 2026 — affected devices no longer receive Secure Boot security updates until the 2023 certificate is deployed. Since v3 the agent reads the firmware db/KEK variables directly: when the firmware itself confirms the 2023 certificate, the rule is suppressed even if the Windows servicing status has not caught up yet.",
   "severity": "warning",
   "category": "security",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 70,
   "preconditions": [
     {
@@ -83,10 +87,26 @@
     }
   ],
   "confidenceFactors": [
-    { "signal": "ca2023_notfound", "condition": "exists", "weight": 20 },
-    { "signal": "ca2023_error", "condition": "exists", "weight": 10 },
-    { "signal": "db_ca2023_firmware_missing", "condition": "exists", "weight": 20 },
-    { "signal": "kek_2023_missing", "condition": "exists", "weight": 10 }
+    {
+      "signal": "ca2023_notfound",
+      "condition": "exists",
+      "weight": 20
+    },
+    {
+      "signal": "ca2023_error",
+      "condition": "exists",
+      "weight": 10
+    },
+    {
+      "signal": "db_ca2023_firmware_missing",
+      "condition": "exists",
+      "weight": 20
+    },
+    {
+      "signal": "kek_2023_missing",
+      "condition": "exists",
+      "weight": 10
+    }
   ],
   "explanation": "This device has Secure Boot enabled but the **Windows UEFI CA 2023** certificate has not been deployed to the Secure Boot DB.\n\nThe original Windows UEFI CA 2011 certificates **expired on June 27, 2026 — this deadline has passed**. The automatic pre-expiry rollout window is over: this device no longer receives Secure Boot security updates (DB/DBX) and cannot trust 2023-signed boot managers until the 2023 certificate is deployed. Deploying it now requires active remediation (Windows servicing opt-in and, on some models, an OEM firmware update) rather than waiting for an automatic update.\n\nOn devices running a current agent this finding is verified against the firmware itself: the agent reads the UEFI `db` signature database directly, and this warning is automatically suppressed when the firmware already contains the 2023 certificate — regardless of the Windows servicing status below.\n\nCurrent UEFI CA 2023 servicing status: `{{uefiCA2023Status}}`",
   "remediation": [
@@ -112,5 +132,11 @@
       "url": "https://support.microsoft.com/en-us/topic/kb5036210"
     }
   ],
-  "tags": ["security", "secureboot", "certificate", "ca2023", "compliance"]
+  "tags": [
+    "security",
+    "secureboot",
+    "certificate",
+    "ca2023",
+    "compliance"
+  ]
 }

rules/analyze/ANALYZE-SEC-003.json

@@ -5,8 +5,12 @@
   "description": "Fires when the AutoLogon analyzer reports a DefaultPassword value present in Winlogon. A plaintext AutoLogon password stored in the registry is readable by any local administrator and is a credential exposure — more severe than AutoLogon alone (the Sysinternals Autologon tool deliberately avoids this by storing the secret in the LSA instead).",
   "severity": "high",
   "category": "security",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 90,
   "conditions": [
@@ -45,5 +49,11 @@
       "url": "https://learn.microsoft.com/en-us/sysinternals/downloads/autologon"
     }
   ],
-  "tags": ["security", "autologon", "winlogon", "credentials", "plaintext-password"]
+  "tags": [
+    "security",
+    "autologon",
+    "winlogon",
+    "credentials",
+    "plaintext-password"
+  ]
 }

rules/analyze/ANALYZE-SEC-004.json

@@ -5,8 +5,12 @@
   "description": "Optional kiosk allow-list for AutoLogon. Fires when AutoLogon is enabled for a default user that is NOT on your configured list of approved kiosk / shared-device accounts. Disabled until configured because a normal Autopilot enrollment leaves Windows' own ESP auto-logon for the enrolling user (AutoLogon enabled, a default user, no plaintext password) — so AutoLogon-enabled alone is not graded by default; only a plaintext DefaultPassword on disk (ANALYZE-SEC-003) is. Enable this rule with your expected kiosk account name(s) if you want to surface AutoLogon configured for any other user.",
   "severity": "warning",
   "category": "security",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "enabled": false,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "trigger": "single",
   "baseConfidence": 80,
   "conditions": [
@@ -55,7 +59,13 @@
       "url": "https://learn.microsoft.com/en-us/troubleshoot/windows-server/user-profiles-and-logon/turn-on-automatic-logon"
     }
   ],
-  "tags": ["security", "autologon", "winlogon", "kiosk", "allow-list"],
+  "tags": [
+    "security",
+    "autologon",
+    "winlogon",
+    "kiosk",
+    "allow-list"
+  ],
   "templateVariables": [
     {
       "name": "allowed_autologon_users",

rules/analyze/ANALYZE-SEC-005.json

@@ -5,8 +5,12 @@
   "description": "Detects provisioning packages (PPKG) that are not on the built-in allow-list. The agent emits one or more provisioning_package_scan events whose artifacts[] arrays list every PPKG (registry package, .ppkg file, or Recovery\\Customizations residue; a large set is split across several events). This rule iterates that array across all of them and fires for any artifact whose identity does not match the allow-list regex. The default allow-list covers the Windows OS-inbox packages (Cosa, Power.EnergyEstimationEngine, Power.Settings, SecureStart) plus common OEM factory-preload families (Intel PPM power profiles, AMD Power profiles, Lenovo ThinkPad power/battery packages, Microsoft Surface defaults and carrier packages) so clean factory devices stay quiet. OEM imaging leftovers (e.g. USMT.PPKG, InstallOrder.ini) and generically named packages deliberately still alert — on a pure-Autopilot device they are worth a look. To allow your own vendor/recovery packages, enable the template rule ANALYZE-SEC-006, extend its allow-list, then disable this rule.",
   "severity": "warning",
   "category": "security",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 80,
   "conditions": [
     {
@@ -34,5 +38,11 @@
       ]
     }
   ],
-  "tags": ["security", "provisioning-package", "ppkg", "allow-list", "tamper"]
+  "tags": [
+    "security",
+    "provisioning-package",
+    "ppkg",
+    "allow-list",
+    "tamper"
+  ]
 }

rules/analyze/ANALYZE-SEC-006.json

@@ -5,8 +5,12 @@
   "description": "Template version of ANALYZE-SEC-005 with a customizable allow-list. Iterates the provisioning_package_scan artifacts[] array and fires for any PPKG whose identity is not on YOUR allow-list regex. The placeholder ships with the same OS-inbox defaults as ANALYZE-SEC-005 — extend it with your own vendor/recovery packages. This rule is OFF by default: enable it, set your allow-list, then disable ANALYZE-SEC-005 so only packages outside your list alert.",
   "severity": "warning",
   "category": "security",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "enabled": false,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 80,
   "conditions": [
     {
@@ -41,7 +45,13 @@
       ]
     }
   ],
-  "tags": ["security", "provisioning-package", "ppkg", "allow-list", "template"],
+  "tags": [
+    "security",
+    "provisioning-package",
+    "ppkg",
+    "allow-list",
+    "template"
+  ],
   "templateVariables": [
     {
       "name": "allowed_packages",

rules/analyze/ANALYZE-SEC-007.json

@@ -5,8 +5,12 @@
   "description": "Fires when the provisioning-package scan hit a per-source collection cap (too many .ppkg files, registry packages, or Recovery\\Customizations residue files to capture them all). When that happens the allow-list rules (ANALYZE-SEC-005/006) could not evaluate every package, so a non-allow-listed package may have gone unseen. A device with that many provisioning packages is itself unusual and worth a manual look.",
   "severity": "warning",
   "category": "security",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
   "baseConfidence": 80,
   "conditions": [
     {
@@ -32,5 +36,11 @@
       ]
     }
   ],
-  "tags": ["security", "provisioning-package", "ppkg", "truncated", "coverage"]
+  "tags": [
+    "security",
+    "provisioning-package",
+    "ppkg",
+    "truncated",
+    "coverage"
+  ]
 }

rules/analyze/ANALYZE-SEC-008.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-SEC-008",
+  "title": "Secure Boot is disabled",
+  "description": "Detects devices enrolling with Secure Boot turned off. Secure Boot is a firmware-level protection against boot-time malware and is a prerequisite for several Windows security features (VBS/Credential Guard, device health attestation) and common Intune compliance policies. Devices that support Secure Boot but have it disabled should be flagged during enrollment. Legacy BIOS devices (no Secure Boot capability) are excluded — the agent marks those with a note field when the SecureBoot registry state key is absent.",
+  "severity": "warning",
+  "category": "security",
+  "version": "1.1.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
+  "trigger": "single",
+  "baseConfidence": 70,
+  "preconditions": [
+    {
+      "source": "event_data",
+      "eventType": "secureboot_status",
+      "dataField": "note",
+      "operator": "not_exists",
+      "value": "",
+      "description": "Skip when the agent could not find the SecureBoot state registry key (note field set) — that indicates a legacy BIOS / non-UEFI device where Secure Boot is unsupported rather than disabled, so a warning would not be actionable."
+    }
+  ],
+  "conditions": [
+    {
+      "signal": "secureboot_disabled",
+      "source": "event_data",
+      "eventType": "secureboot_status",
+      "dataField": "uefiSecureBootEnabled",
+      "operator": "equals",
+      "value": "false",
+      "required": true
+    },
+    {
+      "signal": "physical_device",
+      "source": "event_data",
+      "eventType": "hardware_spec",
+      "dataField": "isVirtualMachine",
+      "operator": "equals",
+      "value": "false",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    {
+      "signal": "physical_device",
+      "condition": "exists",
+      "weight": 20
+    }
+  ],
+  "confidenceThreshold": 60,
+  "explanation": "This device enrolled with **Secure Boot disabled**.\n\nThe firmware reports UEFI mode, but Secure Boot is turned off (`HKLM\\SYSTEM\\CurrentControlSet\\Control\\SecureBoot\\State\\UEFISecureBootEnabled = 0`). Without Secure Boot the boot chain is not verified, which:\n\n- Leaves the device exposed to bootkits and unsigned boot-time code\n- Blocks or weakens Virtualization-based Security (VBS), Credential Guard and Device Health Attestation\n- Typically makes the device **non-compliant** if an Intune compliance policy requires Secure Boot — Conditional Access may then block the user right after enrollment\n\nSecure Boot is usually disabled deliberately in firmware setup (e.g. for imaging, dual-boot or legacy CSM mode) and simply never re-enabled before the device was handed to Autopilot.",
+  "remediation": [
+    {
+      "title": "Enable Secure Boot in UEFI firmware",
+      "steps": [
+        "Reboot into the UEFI firmware setup (typically F2/F10/F12/Del during boot, or Shift+Restart -> Troubleshoot -> UEFI Firmware Settings)",
+        "Disable Legacy/CSM boot mode if it is active — Secure Boot requires native UEFI boot",
+        "Enable Secure Boot and ensure the Microsoft UEFI CA keys are selected (factory default key set)",
+        "Save, reboot and verify in Windows: msinfo32 -> 'Secure Boot State' = On, or PowerShell Confirm-SecureBootUEFI returns True",
+        "For Hyper-V test VMs: use a Generation 2 VM and enable Secure Boot in the VM's Security settings (template 'Microsoft Windows')"
+      ]
+    },
+    {
+      "title": "Check compliance impact",
+      "steps": [
+        "Review Intune compliance policies assigned to this device for a 'Require Secure Boot' setting",
+        "If the device stays non-compliant, Conditional Access policies may block sign-in — fix firmware settings before user handover"
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Microsoft Learn: Secure Boot",
+      "url": "https://learn.microsoft.com/en-us/windows-hardware/design/device-experiences/oem-secure-boot"
+    },
+    {
+      "title": "Microsoft Learn: Re-enable Secure Boot",
+      "url": "https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/disabling-secure-boot"
+    }
+  ],
+  "tags": [
+    "security",
+    "secureboot",
+    "firmware",
+    "uefi",
+    "compliance"
+  ]
+}

rules/dist/gather-rules.json

@@ -128,6 +128,27 @@
         "oobe"
       ]
     },
+    {
+      "ruleId": "GATHER-DEVICE-006",
+      "title": "Collect dsregcmd join status on overdue hybrid sign-in",
+      "description": "Runs dsregcmd /status the moment the agent reports a hybrid sign-in as overdue (hybrid_login_pending), capturing the Entra join and registration state at exactly the point where the problem is detected. Complements GATHER-DEVICE-001 (snapshot on entering Account Setup). Note: the agent runs as SYSTEM, so the output shows device join state — the per-user SSO/PRT state still requires running dsregcmd as the signed-in user.",
+      "category": "device",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": false,
+      "collectorType": "command_allowlisted",
+      "target": "dsregcmd /status",
+      "trigger": "on_event",
+      "triggerEventType": "hybrid_login_pending",
+      "outputEventType": "gather_dsregcmd_status",
+      "outputSeverity": "Info",
+      "tags": [
+        "device",
+        "entra",
+        "join",
+        "hybrid"
+      ]
+    },
     {
       "ruleId": "GATHER-ENROLL-001",
       "title": "MDM enrollment diagnostic events",

rules/dist/ime-log-patterns.json

@@ -4,12 +4,23 @@
     {
       "patternId": "HS-COMPLIANCE",
       "category": "always",
-      "pattern": "\\[HS\\] the (?<part>pre|post)-remdiation detection script compliance result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
+      "pattern": "\\[HS\\] the (?<part>pre|post)-rem(?:e)?diation detection script compliance result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
       "action": "healthScriptDetectionResult",
       "parameters": {
         "scriptType": "remediation"
       },
-      "description": "Early-signal fallback for health-script detection / post-detection results. Microsoft IME emits this line immediately after each detection script runs, ~30-90 seconds before the consolidated [HS] new result = JSON line is logged (which only fires after IME's batch-send to the Microsoft service). Short Autopilot enrollments often end inside that gap, so this pattern guarantees at least the compliance verdict is captured. The full data version arrives later via HS-NEW-RESULT and replaces this sparse entry through the UI dedupe (dataCompleteness scoring).",
+      "description": "Early-signal fallback for health-script detection / post-detection results. Microsoft IME emits this line immediately after each detection script runs, ~30-90 seconds before the consolidated [HS] new result = JSON line is logged (which only fires after IME's batch-send to the Microsoft service). Short Autopilot enrollments often end inside that gap, so this pattern guarantees at least the compliance verdict is captured. The full data version arrives later via HS-NEW-RESULT and replaces this sparse entry through the UI dedupe (dataCompleteness scoring). Tolerates both Microsoft's historical typo 'remdiation' and a future corrected 'remediation'. NOTE: IME 1.97 (Dec 2025) no longer emits the post- variant of this line; the post case is covered by HS-COMPLIANCE-POST.",
+      "enabled": true
+    },
+    {
+      "patternId": "HS-COMPLIANCE-POST",
+      "category": "always",
+      "pattern": "\\[HS\\] the (?<part>post) detection script result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
+      "action": "healthScriptDetectionResult",
+      "parameters": {
+        "scriptType": "remediation"
+      },
+      "description": "Post-remediation detection result, current wording. IME 1.97 (Dec 2025) replaced the old '[HS] the post-remdiation detection script compliance result for ...' line (still covered by HS-COMPLIANCE for older logs) with '[HS] the post detection script result for <guid> is <True|False>' (ScriptProcessorV2.cs:721). The literal word 'post' in the line is captured as the part group so the handler classifies it as the post-detection phase.",
       "enabled": true
     },
     {
@@ -139,6 +150,14 @@
       "description": "Captures the install attempt number for the current app. IME logs 'Execute retry 0' for the first attempt and increments on each retry. Reported as attempt+1 so retry 0 becomes AttemptNumber=1 (human-friendly: first attempt).",
       "enabled": true
     },
+    {
+      "patternId": "IME-CACHE-MISS",
+      "category": "always",
+      "pattern": "\\[Win32App\\] Content cache miss for app \\(id = {GUID}, name = (?<name>.*?)\\), start downloading",
+      "action": "updateName",
+      "description": "Captures 'Content cache miss for app (id = <guid>, name = <name>), start downloading...' (ContentManager.cs) as a secondary app-name source. Fires right before a real download begins, so it resolves names for exactly the apps that will produce download/install activity — a redundancy for IME-POLICIES-based naming after IME retired the old name-bearing processing lines.",
+      "enabled": true
+    },
     {
       "patternId": "IME-DECRYPT-FAILED",
       "category": "currentPhase",
@@ -150,9 +169,9 @@
     {
       "patternId": "IME-DETECTED-INSTALLED-1",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"DetectionState\"\":\\{\"\"OldValue\"\":null,\"\"NewValue\"\":\"\"Installed\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DetectionState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}Installed\"{1,2}",
       "action": "updateStateInstalled",
-      "description": "Detects when an app's detection state transitions to Installed (new ReportingManager format).",
+      "description": "Detects when an app's detection state transitions to Installed (new ReportingManager format). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
@@ -168,15 +187,15 @@
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] Detected app {GUID} ",
       "action": "updateStateInstalled",
-      "description": "Detects when an app is detected as installed (old log format).",
-      "enabled": true
+      "description": "Detects when an app is detected as installed (old log format). DISABLED 2026-08-17: the standalone 'Detected app <guid> ' line no longer exists in IME 1.97.107; this regex instead matched the 'Detected app ... and intent is to install, skip applicability check' line, colliding with IME-SKIP-INSTALL-DETECTED and firing updateStateInstalled and updateStateSkipped on the same physical line (see tasks/ime-v1-code-audit-2026-08-17.md).",
+      "enabled": false
     },
     {
       "patternId": "IME-DETECTION-RESULT",
       "category": "always",
-      "pattern": "\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: (?<id>{GUID}) resulted in action status: Success and detection state: (?<detection>Detected|NotDetected)",
+      "pattern": "\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: (?<id>{GUID}) resulted in action status: Success and detection state: (?<detection>DetectedDifferentVersion|NotDetected|Detected)",
       "action": "captureDetectionResult",
-      "description": "Captures the detection rule result after IME runs detection for an app. 'Detected' means the detection rule matched (app is installed), 'NotDetected' means it did not. Excludes [SimulatedDetectionActionHandler] which fires during applicability pre-checks.",
+      "description": "Captures the detection rule result after IME runs detection for an app. 'Detected' means the detection rule matched (app is installed), 'NotDetected' means it did not, 'DetectedDifferentVersion' means a different version was found (supersedence / WinGet version mismatch). DetectedDifferentVersion must come first in the alternation so the unanchored regex does not mis-capture its 'Detected' prefix. Excludes [SimulatedDetectionActionHandler] which fires during applicability pre-checks.",
       "enabled": true
     },
     {
@@ -217,9 +236,9 @@
     {
       "patternId": "IME-ENFORCEMENT-SUCCESS",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"EnforcementState\"\":\\{\"\"OldValue\"\":\"\"InProgressDownloadCompleted\"\",\"\"NewValue\"\":\"\"Success\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}\\w+\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}Success\"{1,2}",
       "action": "updateStateInstalled",
-      "description": "Detects when an app's enforcement state transitions from InProgressDownloadCompleted to Success.",
+      "description": "Detects when an app's enforcement state transitions to Success in an Execution state report delta. OldValue is deliberately unpinned: besides InProgressDownloadCompleted it can be Error (retry succeeding in a later check-in), InProgressPendingReboot (post-reboot completion) or null (first write) — the previously pinned InProgressDownloadCompleted missed those legitimate success paths (IME 1.97 audit 2026-08-17). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
@@ -236,9 +255,9 @@
     {
       "patternId": "IME-ERROR-DOWNLOAD",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Download state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"EnforcementState\"\":\\{\"\"OldValue\"\":\"\"InProgress\"\",\"\"NewValue\"\":\"\"ErrorDownloadingContent\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Download state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:\"{1,2}InProgress\"{1,2},\"{1,2}NewValue\"{1,2}:\"{1,2}ErrorDownloadingContent\"{1,2}",
       "action": "updateStateError",
-      "description": "Detects when an app's enforcement state transitions to ErrorDownloadingContent.",
+      "description": "Detects when an app's enforcement state transitions to ErrorDownloadingContent. Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
@@ -266,12 +285,12 @@
     {
       "patternId": "IME-ERROR-REPORT",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"EnforcementState\"\":\\{\"\"OldValue\"\":\"\"(?<from>\\w+)\"\",\"\"NewValue\"\":\"\"(?<to>\\w+)\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}(?<from>\\w+)\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}(?<to>\\w+)\"{1,2}",
       "action": "updateStateError",
       "parameters": {
         "checkTo": "true"
       },
-      "description": "Captures enforcement state transitions via ReportingManager. Only triggers error when 'to' value indicates an error state.",
+      "description": "Captures enforcement state transitions via ReportingManager. Only triggers error when 'to' value indicates an error state. OldValue may be the unquoted JSON literal null on the first-ever write of a reporting state — transitions straight from the initial state (e.g. first write directly to an error state) would otherwise be invisible (IME 1.97 audit 2026-08-17). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
@@ -293,6 +312,14 @@
       "description": "Detects when an app installer returned an exit code that has no mapping configured in Intune.",
       "enabled": true
     },
+    {
+      "patternId": "IME-ESP-APP-REGISTERED",
+      "category": "always",
+      "pattern": "\\[Win32App\\]\\[EspManager\\] In EspPhase: \\w+\\. App {GUID} has been registered.*?App name: (?<name>.*?)$",
+      "action": "updateName",
+      "description": "Captures the ESP tracked-app registration line ('App <guid> has been registered[ for user <id>]. App name: <name>', EspManager.cs) as an app-name source. Primary replacement for the retired IME-UPDATE-NAME-1/2/3 whose emitters were removed with IME's old V1/V2 processing pipeline; also documents exactly which apps IME registered for ESP tracking. Category 'always' so names resolve even before the first ApplicationPoller EspPhase line is seen.",
+      "enabled": true
+    },
     {
       "patternId": "IME-ESP-PHASE",
       "category": "always",
@@ -304,9 +331,9 @@
     {
       "patternId": "IME-ESP-TRACK-STATUS",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[EspManager\\] Updating ESP tracked install status from (?<from>\\w+) to (?<to>\\w+) for application {GUID}\\.",
+      "pattern": "\\[Win32App\\]\\[EspManager\\] Updating ESP tracked install status from (?<from>\\w+) to (?<to>\\w+) for application {GUID}",
       "action": "espTrackStatus",
-      "description": "Captures ESP tracked install status transitions (e.g., InProgress to Installed) for a specific app.",
+      "description": "Captures ESP tracked install status transitions (e.g., InProgress to Installed) for a specific app. No trailing anchor: IME 1.97 (Dec 2025) appends ' with name: <appName>.' after the GUID (EspManager.cs), which broke the previous '\\.' suffix. 'from' can be the literal string 'null' on first tracking.",
       "enabled": true
     },
     {
@@ -320,6 +347,33 @@
       "description": "Captures the installer exit code (lpExitCode) for the current app.",
       "enabled": true
     },
+    {
+      "patternId": "IME-EXITCODE-MAPPED-FAILED",
+      "category": "currentPhase",
+      "pattern": "\\[Win32App\\] lpExitCode is defined as Failed$",
+      "action": "updateStateError",
+      "parameters": {
+        "useCurrentApp": "true"
+      },
+      "description": "Marks the current app as failed when its exit code maps to Failed via the admin-defined return-code table ('[Win32App] lpExitCode is defined as <Failed|Success|SoftReboot|HardReboot|Retry>', Win32AppInstaller.cs). This is the NORMAL mapped-exit-code outcome; the previously matched 'Setting enforcementState as ... Error' line only fires on the rare no-mapping fallback path. The numeric exit code is captured separately by IME-EXITCODE, which precedes this line.",
+      "enabled": true
+    },
+    {
+      "patternId": "IME-GRS-CLEARED",
+      "category": "currentPhase",
+      "pattern": "\\[Win32App\\]\\[ExecutionActionHandler\\] Encountered early subgraph termination\\. Clearing GRS for app with id: {GUID} so it can be retried during the next check-in\\.",
+      "action": "updateStatePostponed",
+      "description": "IME aborted the app's subgraph before enforcement finished and cleared its GRS entry so the app retries on the next check-in (ExecutionActionHandler, AppWorkload.log). Maps to Postponed: the install did not complete this pass but is scheduled to run again - previously this looked like an unexplained gap. Wording verified in IME 1.97 and 1.104.",
+      "enabled": true
+    },
+    {
+      "patternId": "IME-GRS-SKIP",
+      "category": "currentPhase",
+      "pattern": "\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID} to (?:install|uninstall) is in GRS\\. The app will not be enforced\\.",
+      "action": "updateStatePostponed",
+      "description": "GRS (Global Retry Schedule) skip: the app failed recently and IME will not re-enforce it this check-in ('App with id: <guid> to install is in GRS. The app will not be enforced.', EnforcementActionProcessor / MixedEnforcementActionProcessor). THE canonical reason an app silently does nothing for up to 24h - previously invisible. Lives in AppActionProcessor.log, which the agent tails since the 2026-08-18 release; wording verified in IME 1.97 and 1.104.",
+      "enabled": true
+    },
     {
       "patternId": "IME-HRESULT",
       "category": "currentPhase",
@@ -377,25 +431,25 @@
     {
       "patternId": "IME-NOT-APPLICABLE-2",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Applicability state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"ApplicabilityState\"\":\\{\"\"OldValue\"\":null,\"\"NewValue\"\":\"\"ScriptRequirementRuleNotMet\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Applicability state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}ApplicabilityState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}ScriptRequirementRuleNotMet\"{1,2}",
       "action": "updateStateSkipped",
-      "description": "Detects when an app's applicability state is set to ScriptRequirementRuleNotMet (PowerShell requirement script returned false).",
+      "description": "Detects when an app's applicability state is set to ScriptRequirementRuleNotMet (PowerShell requirement script returned false). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
       "patternId": "IME-NOT-APPLICABLE-3",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"DesiredState\"\":\\{\"\"OldValue\"\":null,\"\"NewValue\"\":\"\"None\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DesiredState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}None\"{1,2}",
       "action": "updateStateSkipped",
-      "description": "Detects when an app's desired state is set to None (not targeted or not applicable).",
+      "description": "Detects when an app's desired state is set to None (not targeted or not applicable). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
       "patternId": "IME-NOT-APPLICABLE-4",
       "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"DesiredState\"\":\\{\"\"OldValue\"\":null,\"\"NewValue\"\":\"\"NotPresent\"\"",
+      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DesiredState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}NotPresent\"{1,2}",
       "action": "updateStateSkipped",
-      "description": "Detects when an app's desired state is set to NotPresent (targeted for uninstall or not required).",
+      "description": "Detects when an app's desired state is set to NotPresent (targeted for uninstall or not required). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
       "enabled": true
     },
     {
@@ -422,6 +476,17 @@
       "description": "Captures the JSON policies list discovered by IME, used to build the app inventory.",
       "enabled": true
     },
+    {
+      "patternId": "IME-RESTART-STOP-PROCESSING",
+      "category": "currentPhase",
+      "pattern": "\\[Win32App\\]\\[V3Processor\\] A restart is required to continue processing apps\\. Stop processing\\.",
+      "action": "updateStatePostponed",
+      "parameters": {
+        "useCurrentApp": "true"
+      },
+      "description": "Detects IME aborting app processing because an app requires a restart ('A restart is required to continue processing apps. Stop processing.', SideCarV3AppProcessor.cs). Postpones the current app: remaining apps do nothing until after the reboot, which previously looked like an unexplained stall mid-ESP.",
+      "enabled": true
+    },
     {
       "patternId": "IME-SESSION-CHANGE",
       "category": "always",
@@ -435,24 +500,24 @@
       "category": "always",
       "pattern": "\\[Win32App\\] ProcessAppWithDependencies starts for {GUID} with name",
       "action": "setCurrentApp",
-      "description": "Detects when IME begins processing an app with its dependency chain, setting it as the current app.",
-      "enabled": true
+      "description": "Detects when IME begins processing an app with its dependency chain, setting it as the current app. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-SET-CURRENT-2",
       "category": "always",
       "pattern": "\\[Win32App\\] ExecManager: processing targeted app.*?\\bid\\W+{GUID}",
       "action": "setCurrentApp",
-      "description": "Detects when the IME ExecManager starts processing a targeted app, setting it as current.",
-      "enabled": true
+      "description": "Detects when the IME ExecManager starts processing a targeted app, setting it as current. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-SET-CURRENT-3",
       "category": "always",
       "pattern": "\\[Win32App\\] ===Step=== Start to Present app {GUID}",
       "action": "setCurrentApp",
-      "description": "Detects the start of app presentation step in IME, setting the app as current.",
-      "enabled": true
+      "description": "Detects the start of app presentation step in IME, setting the app as current. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-SET-CURRENT-4",
@@ -478,24 +543,24 @@
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] (?=.*?\\bapplicability\\b)(?=.*?NotMet\\b).*?\\bapp\\W+{GUID}\\b",
       "action": "updateStateSkipped",
-      "description": "Detects when an app's applicability check returns NotMet (old log format with lookaheads).",
-      "enabled": true
+      "description": "Detects when an app's applicability check returns NotMet (old log format with lookaheads). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-SKIP-DEPENDENCY-DETECT",
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] app\\W+{GUID}\\b.*?\\bis a dependency\\b.*?\\bDetect Only mode\\b.*?\\bfinished processing",
       "action": "updateStateSkipped",
-      "description": "Detects when a dependency app in Detect Only mode finishes processing (no install needed).",
-      "enabled": true
+      "description": "Detects when a dependency app in Detect Only mode finishes processing (no install needed). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-SKIP-DETECTED",
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] Detected app {GUID}.*?skip next step",
       "action": "updateStateSkipped",
-      "description": "Detects when an already-detected app is skipped for further processing steps (old log format).",
-      "enabled": true
+      "description": "Detects when an already-detected app is skipped for further processing steps (old log format). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-SKIP-FILTERS",
@@ -529,8 +594,8 @@
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] NOT detected app {GUID}.*?skip un-installation",
       "action": "updateStateSkipped",
-      "description": "Detects when an app is not detected and uninstall is skipped (alternate old log format).",
-      "enabled": true
+      "description": "Detects when an app is not detected and uninstall is skipped (alternate old log format). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-STARTED",
@@ -540,6 +605,17 @@
       "description": "Detects when the Intune Management Extension (IME) agent starts up.",
       "enabled": true
     },
+    {
+      "patternId": "IME-STOP-SIGNAL",
+      "category": "currentPhase",
+      "pattern": "EMS Agent received stop signal",
+      "action": "updateStatePostponed",
+      "parameters": {
+        "useCurrentApp": "true"
+      },
+      "description": "Detects an IME service stop ('EMS Agent received stop signal', EmsAgentService.OnStop) — fired on manual restarts and agent-updater restarts, unlike the OS-shutdown-only 'shutdown signal' line matched by IME-SHUTDOWN. Postpones the current app installation, mirroring IME-SHUTDOWN semantics.",
+      "enabled": true
+    },
     {
       "patternId": "IME-SUBGRAPH",
       "category": "currentPhase",
@@ -548,6 +624,14 @@
       "description": "Detects when V3Processor starts a new subgraph, cancelling any stuck app and setting the new app as current.",
       "enabled": true
     },
+    {
+      "patternId": "IME-TOKEN-FAILURE",
+      "category": "always",
+      "pattern": "Failed to get AAD token\\..*?errorCode = (?<errorCode>.*?)$",
+      "action": "imeTokenFailure",
+      "description": "IME token acquisition failure ('Failed to get AAD token. len = N using client id ... and resource id ..., errorCode = N', IntuneTokenManager, IntuneManagementExtension.log). Complements IME-TOKEN-SUCCESS: an auth outage (WAM broken, conditional access, network) previously left every check-in silently doing nothing with no timeline evidence. errorCode can be empty when IME logged none; the agent dedups to one Warning per distinct code. Verified against IME 1.97 and 1.104 decompiled sources.",
+      "enabled": true
+    },
     {
       "patternId": "IME-TOKEN-SUCCESS",
       "category": "always",
@@ -564,24 +648,24 @@
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] ExecManager: processing targeted app.*?name\\W+(?<name>.*?)\\W+id\\W+{GUID}",
       "action": "updateName",
-      "description": "Captures the app name from ExecManager processing log (old format: name before id).",
-      "enabled": true
+      "description": "Captures the app name from ExecManager processing log (old format: name before id). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-UPDATE-NAME-2",
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] ProcessAppWithDependencies starts for {GUID} with name (?<name>.*?)$",
       "action": "updateName",
-      "description": "Captures the app name from ProcessAppWithDependencies log entry.",
-      "enabled": true
+      "description": "Captures the app name from ProcessAppWithDependencies log entry. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-UPDATE-NAME-3",
       "category": "currentPhase",
       "pattern": "\\[Win32App\\] Processing app \\(id={GUID}, name = (?<name>.*?)\\)",
       "action": "updateName",
-      "description": "Captures the app name from the Processing app log entry.",
-      "enabled": true
+      "description": "Captures the app name from the Processing app log entry. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
+      "enabled": false
     },
     {
       "patternId": "IME-USER-SESSION-COMPLETED",
@@ -607,6 +691,14 @@
       "description": "Captures the Win32 app ESP state (e.g., Installed, InProgress) for a specific app.",
       "enabled": true
     },
+    {
+      "patternId": "IME-WINGET-ERROR",
+      "category": "currentPhase",
+      "pattern": "\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID}.*?- Operation Phase = Error",
+      "action": "updateStateError",
+      "description": "Marks a WinGet (new Store) app as failed when its operation progress reports phase Error (WinGetOperationInstallPhase: Downloading/Installing/Queued/Finished/Error). Before this pattern only the Installing phase was matched, so WinGet failures never surfaced as app errors (IME 1.97 audit 2026-08-17).",
+      "enabled": true
+    },
     {
       "patternId": "IME-WINGET-INSTALLING-1",
       "category": "currentPhase",

rules/gather/GATHER-DEVICE-006.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "../schema/gather-rule.schema.json",
+  "ruleId": "GATHER-DEVICE-006",
+  "title": "Collect dsregcmd join status on overdue hybrid sign-in",
+  "description": "Runs dsregcmd /status the moment the agent reports a hybrid sign-in as overdue (hybrid_login_pending), capturing the Entra join and registration state at exactly the point where the problem is detected. Complements GATHER-DEVICE-001 (snapshot on entering Account Setup). Note: the agent runs as SYSTEM, so the output shows device join state — the per-user SSO/PRT state still requires running dsregcmd as the signed-in user.",
+  "category": "device",
+  "version": "1.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": false,
+  "collectorType": "command_allowlisted",
+  "target": "dsregcmd /status",
+  "trigger": "on_event",
+  "triggerEventType": "hybrid_login_pending",
+  "outputEventType": "gather_dsregcmd_status",
+  "outputSeverity": "Info",
+  "tags": ["device", "entra", "join", "hybrid"]
+}

rules/guardrails.json

@@ -43,7 +43,8 @@
       "prefixes": [
         "SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Setup",
         "SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\OOBE",
-        "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon"
+        "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon",
+        "SOFTWARE\\Microsoft\\Windows\\Autopilot"
       ]
     },
     {
@@ -249,6 +250,37 @@
     "C:\\Install\\Log"
   ],
   "blockedFilePrefixes": [
-    "C:\\Users"
+    "C:\\Users",
+    "C:\\Windows\\System32\\config"
+  ],
+  "blockedCommandPatterns": [
+    "Invoke-WebRequest",
+    "Invoke-RestMethod",
+    "Start-BitsTransfer",
+    "wget",
+    "curl",
+    "certutil -urlcache",
+    "New-LocalUser",
+    "Add-LocalGroupMember",
+    "net user",
+    "net localgroup",
+    "bcdedit",
+    "bcdboot",
+    "schtasks /create",
+    "Register-ScheduledTask",
+    "Remove-Item -Recurse",
+    "Format-Volume",
+    "Set-ExecutionPolicy"
+  ],
+  "maxCommandLength": 2000,
+  "blockedInterimTriggerEventTypes": [
+    "performance_snapshot",
+    "agent_metrics_snapshot",
+    "download_progress",
+    "network_state_change",
+    "network_connectivity_check",
+    "log_entry",
+    "agent_trace",
+    "stall_probe_check"
   ]
 }

rules/ime-log-patterns/HS-COMPLIANCE-POST.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../schema/ime-log-pattern.schema.json",
+  "patternId": "HS-COMPLIANCE-POST",
+  "category": "always",
+  "pattern": "\\[HS\\] the (?<part>post) detection script result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
+  "action": "healthScriptDetectionResult",
+  "parameters": { "scriptType": "remediation" },
+  "description": "Post-remediation detection result, current wording. IME 1.97 (Dec 2025) replaced the old '[HS] the post-remdiation detection script compliance result for ...' line (still covered by HS-COMPLIANCE for older logs) with '[HS] the post detection script result for <guid> is <True|False>' (ScriptProcessorV2.cs:721). The literal word 'post' in the line is captured as the part group so the handler classifies it as the post-detection phase.",
+  "enabled": true
+}

rules/ime-log-patterns/HS-COMPLIANCE.json

@@ -2,9 +2,9 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "HS-COMPLIANCE",
   "category": "always",
-  "pattern": "\\[HS\\] the (?<part>pre|post)-remdiation detection script compliance result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
+  "pattern": "\\[HS\\] the (?<part>pre|post)-rem(?:e)?diation detection script compliance result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
   "action": "healthScriptDetectionResult",
   "parameters": { "scriptType": "remediation" },
-  "description": "Early-signal fallback for health-script detection / post-detection results. Microsoft IME emits this line immediately after each detection script runs, ~30-90 seconds before the consolidated [HS] new result = JSON line is logged (which only fires after IME's batch-send to the Microsoft service). Short Autopilot enrollments often end inside that gap, so this pattern guarantees at least the compliance verdict is captured. The full data version arrives later via HS-NEW-RESULT and replaces this sparse entry through the UI dedupe (dataCompleteness scoring).",
+  "description": "Early-signal fallback for health-script detection / post-detection results. Microsoft IME emits this line immediately after each detection script runs, ~30-90 seconds before the consolidated [HS] new result = JSON line is logged (which only fires after IME's batch-send to the Microsoft service). Short Autopilot enrollments often end inside that gap, so this pattern guarantees at least the compliance verdict is captured. The full data version arrives later via HS-NEW-RESULT and replaces this sparse entry through the UI dedupe (dataCompleteness scoring). Tolerates both Microsoft's historical typo 'remdiation' and a future corrected 'remediation'. NOTE: IME 1.97 (Dec 2025) no longer emits the post- variant of this line; the post case is covered by HS-COMPLIANCE-POST.",
   "enabled": true
 }

rules/ime-log-patterns/IME-CACHE-MISS.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../schema/ime-log-pattern.schema.json",
+  "patternId": "IME-CACHE-MISS",
+  "category": "always",
+  "pattern": "\\[Win32App\\] Content cache miss for app \\(id = {GUID}, name = (?<name>.*?)\\), start downloading",
+  "action": "updateName",
+  "description": "Captures 'Content cache miss for app (id = <guid>, name = <name>), start downloading...' (ContentManager.cs) as a secondary app-name source. Fires right before a real download begins, so it resolves names for exactly the apps that will produce download/install activity — a redundancy for IME-POLICIES-based naming after IME retired the old name-bearing processing lines.",
+  "enabled": true
+}

rules/ime-log-patterns/IME-DETECTED-INSTALLED-1.json

@@ -2,8 +2,8 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "IME-DETECTED-INSTALLED-1",
   "category": "currentPhase",
-  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"DetectionState\"\":\\{\"\"OldValue\"\":null,\"\"NewValue\"\":\"\"Installed\"\"",
+  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DetectionState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}Installed\"{1,2}",
   "action": "updateStateInstalled",
-  "description": "Detects when an app's detection state transitions to Installed (new ReportingManager format).",
+  "description": "Detects when an app's detection state transitions to Installed (new ReportingManager format). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
   "enabled": true
 }

rules/ime-log-patterns/IME-DETECTED-OLD.json

@@ -4,6 +4,6 @@
   "category": "currentPhase",
   "pattern": "\\[Win32App\\] Detected app {GUID} ",
   "action": "updateStateInstalled",
-  "description": "Detects when an app is detected as installed (old log format).",
-  "enabled": true
+  "description": "Detects when an app is detected as installed (old log format). DISABLED 2026-08-17: the standalone 'Detected app <guid> ' line no longer exists in IME 1.97.107; this regex instead matched the 'Detected app ... and intent is to install, skip applicability check' line, colliding with IME-SKIP-INSTALL-DETECTED and firing updateStateInstalled and updateStateSkipped on the same physical line (see tasks/ime-v1-code-audit-2026-08-17.md).",
+  "enabled": false
 }

rules/ime-log-patterns/IME-DETECTION-RESULT.json

@@ -2,8 +2,8 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "IME-DETECTION-RESULT",
   "category": "always",
-  "pattern": "\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: (?<id>{GUID}) resulted in action status: Success and detection state: (?<detection>Detected|NotDetected)",
+  "pattern": "\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: (?<id>{GUID}) resulted in action status: Success and detection state: (?<detection>DetectedDifferentVersion|NotDetected|Detected)",
   "action": "captureDetectionResult",
-  "description": "Captures the detection rule result after IME runs detection for an app. 'Detected' means the detection rule matched (app is installed), 'NotDetected' means it did not. Excludes [SimulatedDetectionActionHandler] which fires during applicability pre-checks.",
+  "description": "Captures the detection rule result after IME runs detection for an app. 'Detected' means the detection rule matched (app is installed), 'NotDetected' means it did not, 'DetectedDifferentVersion' means a different version was found (supersedence / WinGet version mismatch). DetectedDifferentVersion must come first in the alternation so the unanchored regex does not mis-capture its 'Detected' prefix. Excludes [SimulatedDetectionActionHandler] which fires during applicability pre-checks.",
   "enabled": true
 }

rules/ime-log-patterns/IME-ENFORCEMENT-SUCCESS.json

@@ -2,8 +2,8 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "IME-ENFORCEMENT-SUCCESS",
   "category": "currentPhase",
-  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"EnforcementState\"\":\\{\"\"OldValue\"\":\"\"InProgressDownloadCompleted\"\",\"\"NewValue\"\":\"\"Success\"\"",
+  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}\\w+\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}Success\"{1,2}",
   "action": "updateStateInstalled",
-  "description": "Detects when an app's enforcement state transitions from InProgressDownloadCompleted to Success.",
+  "description": "Detects when an app's enforcement state transitions to Success in an Execution state report delta. OldValue is deliberately unpinned: besides InProgressDownloadCompleted it can be Error (retry succeeding in a later check-in), InProgressPendingReboot (post-reboot completion) or null (first write) — the previously pinned InProgressDownloadCompleted missed those legitimate success paths (IME 1.97 audit 2026-08-17). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
   "enabled": true
 }

rules/ime-log-patterns/IME-ERROR-DOWNLOAD.json

@@ -2,8 +2,8 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "IME-ERROR-DOWNLOAD",
   "category": "currentPhase",
-  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Download state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"EnforcementState\"\":\\{\"\"OldValue\"\":\"\"InProgress\"\",\"\"NewValue\"\":\"\"ErrorDownloadingContent\"\"",
+  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Download state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:\"{1,2}InProgress\"{1,2},\"{1,2}NewValue\"{1,2}:\"{1,2}ErrorDownloadingContent\"{1,2}",
   "action": "updateStateError",
-  "description": "Detects when an app's enforcement state transitions to ErrorDownloadingContent.",
+  "description": "Detects when an app's enforcement state transitions to ErrorDownloadingContent. Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
   "enabled": true
 }

rules/ime-log-patterns/IME-ERROR-REPORT.json

@@ -2,9 +2,11 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "IME-ERROR-REPORT",
   "category": "currentPhase",
-  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"\"EnforcementState\"\":\\{\"\"OldValue\"\":\"\"(?<from>\\w+)\"\",\"\"NewValue\"\":\"\"(?<to>\\w+)\"\"",
+  "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}(?<from>\\w+)\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}(?<to>\\w+)\"{1,2}",
   "action": "updateStateError",
-  "parameters": { "checkTo": "true" },
-  "description": "Captures enforcement state transitions via ReportingManager. Only triggers error when 'to' value indicates an error state.",
+  "parameters": {
+    "checkTo": "true"
+  },
+  "description": "Captures enforcement state transitions via ReportingManager. Only triggers error when 'to' value indicates an error state. OldValue may be the unquoted JSON literal null on the first-ever write of a reporting state — transitions straight from the initial state (e.g. first write directly to an error state) would otherwise be invisible (IME 1.97 audit 2026-08-17). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
   "enabled": true
 }

rules/ime-log-patterns/IME-ESP-APP-REGISTERED.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../schema/ime-log-pattern.schema.json",
+  "patternId": "IME-ESP-APP-REGISTERED",
+  "category": "always",
+  "pattern": "\\[Win32App\\]\\[EspManager\\] In EspPhase: \\w+\\. App {GUID} has been registered.*?App name: (?<name>.*?)$",
+  "action": "updateName",
+  "description": "Captures the ESP tracked-app registration line ('App <guid> has been registered[ for user <id>]. App name: <name>', EspManager.cs) as an app-name source. Primary replacement for the retired IME-UPDATE-NAME-1/2/3 whose emitters were removed with IME's old V1/V2 processing pipeline; also documents exactly which apps IME registered for ESP tracking. Category 'always' so names resolve even before the first ApplicationPoller EspPhase line is seen.",
+  "enabled": true
+}

rules/ime-log-patterns/IME-ESP-TRACK-STATUS.json

@@ -2,8 +2,8 @@
   "$schema": "../schema/ime-log-pattern.schema.json",
   "patternId": "IME-ESP-TRACK-STATUS",
   "category": "currentPhase",
-  "pattern": "\\[Win32App\\]\\[EspManager\\] Updating ESP tracked install status from (?<from>\\w+) to (?<to>\\w+) for application {GUID}\\.",
+  "pattern": "\\[Win32App\\]\\[EspManager\\] Updating ESP tracked install status from (?<from>\\w+) to (?<to>\\w+) for application {GUID}",
   "action": "espTrackStatus",
-  "description": "Captures ESP tracked install status transitions (e.g., InProgress to Installed) for a specific app.",
+  "description": "Captures ESP tracked install status transitions (e.g., InProgress to Installed) for a specific app. No trailing anchor: IME 1.97 (Dec 2025) appends ' with name: <appName>.' after the GUID (EspManager.cs), which broke the previous '\\.' suffix. 'from' can be the literal string 'null' on first tracking.",
   "enabled": true
 }

rules/ime-log-patterns/IME-EXITCODE-MAPPED-FAILED.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../schema/ime-log-pattern.schema.json",
+  "patternId": "IME-EXITCODE-MAPPED-FAILED",
+  "category": "currentPhase",
+  "pattern": "\\[Win32App\\] lpExitCode is defined as Failed$",
+  "action": "updateStateError",
+  "parameters": { "useCurrentApp": "true" },
+  "description": "Marks the current app as failed when its exit code maps to Failed via the admin-defined return-code table ('[Win32App] lpExitCode is defined as <Failed|Success|SoftReboot|HardReboot|Retry>', Win32AppInstaller.cs). This is the NORMAL mapped-exit-code outcome; the previously matched 'Setting enforcementState as ... Error' line only fires on the rare no-mapping fallback path. The numeric exit code is captured separately by IME-EXITCODE, which precedes this line.",
+  "enabled": true
+}

rules/ime-log-patterns/IME-GRS-CLEARED.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../schema/ime-log-pattern.schema.json",
+  "patternId": "IME-GRS-CLEARED",
+  "category": "currentPhase",
+  "pattern": "\\[Win32App\\]\\[ExecutionActionHandler\\] Encountered early subgraph termination\\. Clearing GRS for app with id: {GUID} so it can be retried during the next check-in\\.",
+  "action": "updateStatePostponed",
+  "description": "IME aborted the app's subgraph before enforcement finished and cleared its GRS entry so the app retries on the next check-in (ExecutionActionHandler, AppWorkload.log). Maps to Postponed: the install did not complete this pass but is scheduled to run again - previously this looked like an unexplained gap. Wording verified in IME 1.97 and 1.104.",
+  "enabled": true
+}