build: keep NuGet audit advisories as warnings in the warning freeze

A CVE published against an already-referenced package must not block an
unrelated hotfix deploy; advisories are handled by bumping the package.
WarningsNotAsErrors NU1901-NU1904 - everything else stays fatal.

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

.claude/CLAUDE.md

@@ -1,79 +1,37 @@
-## Workflow Orchestration
-# Agent Directives: Mechanical Overrides
+# Agent Directives
 
-You are operating within a constrained context window and strict system prompts. To produce production-grade code, you MUST adhere to these overrides:
+- **Plan first.** Enter plan mode for any non-trivial task (3+ steps or an architectural decision) and write the spec before building. If something goes sideways, stop and re-plan instead of pushing on.
+- **Use subagents liberally** for research, exploration, and parallel analysis — one focus each — to keep the main context clean.
+- **Verify before claiming done.** Run the tests, check the logs, show the evidence. Diff against `main` where behaviour could regress.
+- **Fix bugs autonomously.** Given a report, a failing test, or an error, resolve it — no hand-holding.
+- **Capture corrections.** After any correction from the user, record the pattern and a preventing rule in `tasks/lessons.md`; review it at session start.
+- Read files over 500 LOC in chunks. Never treat one grep as proof of absence.
 
+Codex reviews your output once you are done.
 
+## Code Quality
 
-### 1. Plan Mode Default
-- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
-- If something goes sideways, STOP and re-plan immediately — don't keep pushing
-- Use plan mode for specification steps, not just building
-- Write detailed specs upfront to reduce ambiguity
-
-### 2. Subagent Strategy
-- Use subagents liberally to keep main context window clean
-- Offload research, exploration, and parallel analysis to subagents
-- For complex problems, throw more compute at it via subagents
-- One tack per subagent for focused execution
-
-### 3. Self-Improvement Loop
-- After ANY correction from the user: update `tasks/lessons.md` with the pattern
-- Write rules for yourself that prevent the same mistake
-- Ruthlessly iterate on these lessons until mistake rate drops
-- Review lessons at session start for relevant project
-
-### 4. Verification Before Done
-- Never mark a task complete without proving it works
-- Diff behavior between main and your changes when relevant
-- Ask yourself: "Would a staff engineer approve this?"
-- Run tests, check logs, demonstrate correctness
-
-### 5. Demand Elegance (Balanced)
-- For non-trivial changes: pause and ask "is there a more elegant way?"
-- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
-- Skip this for simple, obvious fixes — don't over-engineer
-- Challenge your own work before presenting it
-
-### 6. Autonomous Bug Fixing
-- When given a bug report: just fix it. Don't ask for hand-holding
-- Point at logs, errors, failing tests — then resolve them
-- Zero context switching required from the user
-- Go fix failing CI tests without being told how
-
-
-
-### Tools Execution
-- Read any file over 500 LOC in chunks using offset and limit parameters.
-- Do not assume a single grep caught everything.
-
-### Code Quality
-- If architecture is flawed, state is duplicated, or patterns are inconsistent - propose and implement structural fixes. Ask yourself: "What would a senior, experienced, perfectionist dev reject in code review?" Fix all of it.
-
-
-Codex will review your output once you are done!
-
+- Simplicity first: minimal, targeted changes. No temporary fixes — find the root cause.
+- Where architecture is flawed, state is duplicated, or patterns are inconsistent, propose and implement the structural fix. Ask what a perfectionist reviewer would reject, and fix that too.
+- On non-trivial changes, ask whether there is a more elegant way before presenting. Skip it for simple fixes — don't over-engineer.
 
 ## Task Management
 
-1. **Plan First**: Write plan to `tasks/todo.md` with checkable items
-2. **Verify Plan**: Check in before starting implementation
-3. **Track Progress**: Mark items complete as you go
-4. **Explain Changes**: High-level summary at each step
-5. **Document Results**: Add review section to `tasks/todo.md`
-6. **Capture Lessons**: Update `tasks/lessons.md` after corrections
+Keep the plan in `tasks/todo.md` as checkable items, confirm it before implementing, tick items off as you go, and add a review section when done.
 
-## Core Principles
+## Customer-Facing Claims
 
-- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
-- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
-- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.
+`src/Web/autopilot-monitor-web/app/{about,terms,privacy}/page.tsx` and `autopilotmonitor-docs/trust/*` state facts customers and security reviewers rely on. They drift silently.
 
-## Technical Docs — OKF Knowledge Bundle (`docs/`)
+- Verify every claim against the code before writing it — never carry one forward because it was already on the page.
+- Update them in the same change as: runtime/framework versions, roles, notification providers, agent deployment or lifecycle, diagnostics payload, isolation/delegation model, retention caps, sub-processors, or any default governing what is collected.
+- Describe only what customers can actually use; operator-only infrastructure is not a feature.
+- Trust pages: durable phrasing over exact figures, and bump their "Last reviewed" date.
 
-`docs/` is an [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) knowledge bundle for contributor/AI-facing technical documentation (customer docs live in the separate autopilotmonitor-docs repo).
+## Technical Docs — OKF Bundle (`docs/`)
 
-- **Consume first**: start at `docs/index.md` for progressive disclosure before opening individual documents.
-- **When new durable technical knowledge emerges** (architecture decisions, flows, non-obvious mechanisms), capture it as an OKF concept document in `docs/` — markdown with YAML frontmatter: `type` (mandatory), plus `title`, `description`, `resource`, `tags`, `timestamp` (recommended).
-- **Maintain the bundle**: add every new document to `docs/index.md`, note changes in `docs/log.md` (grouped by ISO date). Use standard RELATIVE markdown links between docs — never the OKF `/`-prefixed bundle-absolute form (GitHub resolves those from the repo root and navigation breaks). `index.md` and `log.md` are reserved filenames.
-- Documents are English, structural markdown over prose (`# Schema`, `# Examples`, `# Citations` sections where applicable).
+Contributor/AI-facing docs (customer docs live in the `autopilotmonitor-docs` repo). Start at `docs/index.md` before opening individual files.
+
+- New durable knowledge (architecture decisions, flows, non-obvious mechanisms) → an OKF concept doc with YAML frontmatter: `type` (mandatory), plus `title`, `description`, `resource`, `tags`, `timestamp`.
+- Register it in `docs/index.md`, note the change in `docs/log.md` (ISO date). `index.md` and `log.md` are reserved names.
+- English, structural markdown (`# Schema`, `# Examples`, `# Citations`). Links between docs are RELATIVE — never `/`-prefixed, that breaks GitHub navigation.

.github/codeql/codeql-config.yml

@@ -0,0 +1,31 @@
+# CodeQL configuration.
+#
+# The default query suites stay active — this file only filters out two C# queries
+# that fire structurally on this codebase, where the flagged behavior is the feature,
+# not a defect:
+#
+#   cs/exposure-of-sensitive-information
+#     Audit and operational logs record WHO performed an action (actor UPN / email)
+#     and notification services deliver mail to a recipient address. Writing that
+#     identity to the log / notification IS the purpose of the field. Every such site
+#     is a legitimate, reviewed use — the query cannot distinguish it from a leak.
+#
+#   cs/cleartext-storage-of-sensitive-information
+#     The rate limiters and distress guard use the trusted client IP as their bucket
+#     key. The IP is an identifier for throttling, not a secret at rest; storing it in
+#     the in-memory / table rate-limit key is by design.
+#
+# Genuine one-off false positives from OTHER queries (e.g. an open-redirect the taint
+# model can't see is allow-listed, a rate-limited route it doesn't recognize) are
+# dismissed individually in the Security tab so those queries stay sharp — they are
+# NOT suppressed here.
+#
+# Log-injection (cs/log-forging) is deliberately NOT filtered: user-controlled values
+# are sanitized at the sink via Helpers/LogSanitizer, so the query stays useful for
+# catching a future unsanitized sink.
+
+query-filters:
+  - exclude:
+      id: cs/exposure-of-sensitive-information
+  - exclude:
+      id: cs/cleartext-storage-of-sensitive-information

.github/dependabot.yml

@@ -0,0 +1,47 @@
+version: 2
+
+updates:
+  - package-ecosystem: nuget
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      dotnet:
+        patterns: ['*']
+        update-types: [minor, patch]
+
+  - package-ecosystem: npm
+    directory: /src/Web/autopilot-monitor-web
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      web:
+        patterns: ['*']
+        update-types: [minor, patch]
+    # Major bumps are breaking and reviewed deliberately, not auto-PR'd.
+    # Security updates ignore this filter, so the Security tab stays clean.
+    ignore:
+      - dependency-name: '*'
+        update-types: ['version-update:semver-major']
+
+  - package-ecosystem: npm
+    directory: /src/McpServer/autopilot-monitor-mcp
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      mcp:
+        patterns: ['*']
+        update-types: [minor, patch]
+    # Major bumps are breaking and reviewed deliberately, not auto-PR'd.
+    # Security updates ignore this filter, so the Security tab stays clean.
+    ignore:
+      - dependency-name: '*'
+        update-types: ['version-update:semver-major']
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/scripts/Request-BuildNumber.ps1

@@ -0,0 +1,102 @@
+<#
+.SYNOPSIS
+    Reserves a monotone build number from a counter blob (ETag compare-and-swap).
+
+.DESCRIPTION
+    Single source of build numbers for every component that ships from this repo
+    (agent, backend, MCP). Each component owns one counter blob holding a plain
+    integer; this script reads it, writes value+1 back under If-Match, and returns
+    the reserved number.
+
+    Reserve-BEFORE-build: two concurrent builds can never mint the same number.
+    A failed build burns a number, which is harmless -- uniqueness matters,
+    density does not.
+
+    The blob is public-read; only the write needs the container SAS.
+
+    Why a counter and not the published version manifest: manifests are written
+    on publish, not on build (the agent writes version.json only for stable
+    releases), so two dev builds in a row would derive the same number and
+    overwrite each other's versioned artifact.
+
+.PARAMETER CounterUrl
+    Full URL of the counter blob, without SAS.
+
+.PARAMETER SasToken
+    Container SAS with create+write permission. A leading '?' is tolerated.
+
+.PARAMETER Override
+    Explicit build number instead of counter+1. If it is not greater than the
+    current counter the blob is left untouched (re-build of a number that was
+    already reserved). 0 = no override.
+
+.PARAMETER MaxAttempts
+    CAS retries before giving up.
+
+.OUTPUTS
+    [int] the reserved build number. Progress goes to the host, not the pipeline.
+
+.EXAMPLE
+    $n = ./Request-BuildNumber.ps1 -CounterUrl $url -SasToken $sas
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$CounterUrl,
+    [Parameter(Mandatory = $true)][string]$SasToken,
+    [int]$Override = 0,
+    [int]$MaxAttempts = 5
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Tolerate both secret formats ("sp=cw&..." and "?sp=cw&...").
+$writeUrl = $CounterUrl + '?' + $SasToken.TrimStart('?')
+
+function Get-HttpStatus {
+    param($ErrorRecord)
+    if ($ErrorRecord.Exception.PSObject.Properties['Response'] -and $ErrorRecord.Exception.Response) {
+        return [int]$ErrorRecord.Exception.Response.StatusCode
+    }
+    return 0
+}
+
+function Read-Counter {
+    try {
+        $resp = Invoke-WebRequest -Uri $CounterUrl -Method Get -UseBasicParsing
+    } catch {
+        if ((Get-HttpStatus $_) -eq 404) {
+            throw "Counter blob not found at $CounterUrl. Seed it once with the last used build number: PUT the plain integer with 'x-ms-blob-type: BlockBlob' and 'If-None-Match: *'. See docs/versioning.md."
+        }
+        throw
+    }
+    $raw = if ($resp.Content -is [byte[]]) { [System.Text.Encoding]::UTF8.GetString($resp.Content) } else { [string]$resp.Content }
+    # If-Match requires the quoted ETag form; PowerShell strips the quotes on read.
+    $etag = '"' + ([string]($resp.Headers['ETag'] | Select-Object -First 1)).Trim('"') + '"'
+    return [pscustomobject]@{ Value = [int]$raw.Trim(); ETag = $etag }
+}
+
+for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
+    $counter = Read-Counter
+
+    if ($Override -gt 0 -and $Override -le $counter.Value) {
+        Write-Host "  Build number $Override <= counter $($counter.Value) -- already reserved, counter blob unchanged"
+        return $Override
+    }
+    $target = if ($Override -gt 0) { $Override } else { $counter.Value + 1 }
+
+    try {
+        $headers = @{ 'x-ms-blob-type' = 'BlockBlob'; 'If-Match' = $counter.ETag }
+        Invoke-RestMethod -Uri $writeUrl -Method Put -Headers $headers -Body "$target" -ContentType 'text/plain' | Out-Null
+        Write-Host "  Reserved build number $target (CAS write ok, attempt $attempt)"
+        return $target
+    } catch {
+        if ((Get-HttpStatus $_) -eq 412) {
+            Write-Host "  CAS conflict on attempt $attempt (another build reserved concurrently) -- retrying"
+            Start-Sleep -Seconds ($attempt * 2)
+        } else {
+            throw
+        }
+    }
+}
+
+throw "Could not reserve a build number after $MaxAttempts CAS attempts"

.github/workflows/build-agent.yml

@@ -56,78 +56,27 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
 
       # SDK 10 = single build toolchain (parity with local build.ps1 / global.json).
       - name: Setup .NET
-        uses: actions/setup-dotnet@v5
+        uses: actions/setup-dotnet@v6
         with:
           dotnet-version: '10.0.x'
 
-      # Build numbers come from the shared counter blob (single source of truth for CI
-      # AND local build.ps1). Reserve-before-build with ETag-CAS: concurrent builds can
-      # never mint the same number; a failed build burns a number, which is harmless.
-      # The blob is public-read (like the rest of the container); writes need the SAS.
+      # Build numbers come from the shared counter blob -- one counter and one
+      # implementation for CI and the local build (.github/scripts/Request-BuildNumber.ps1).
+      # Reserve-before-build with ETag-CAS: concurrent builds can never mint the same
+      # number; a failed build burns a number, which is harmless.
       - name: Reserve build number (counter blob CAS)
         id: version
         shell: pwsh
         run: |
-          $counterBlob = "buildcounter-v$env:LINE_MAJOR.txt"
-          $counterUrl = "https://autopilotmonitoreu.blob.core.windows.net/agent/$counterBlob"
-          # Tolerate both secret formats ("sp=cw&..." and "?sp=cw&...") -- the URL below adds the '?'.
-          $sasToken = "${{ secrets.AZURE_BLOB_AGENT_SAS_TOKEN }}".TrimStart('?')
-          $override = "${{ inputs.build_number }}"
+          $override = 0
+          if ('${{ inputs.build_number }}' -ne '') { $override = [int]'${{ inputs.build_number }}' }
 
-          function Get-Counter {
-            try {
-              $resp = Invoke-WebRequest -Uri $counterUrl -Method Get
-              $raw = if ($resp.Content -is [byte[]]) { [System.Text.Encoding]::UTF8.GetString($resp.Content) } else { [string]$resp.Content }
-              # If-Match requires the quoted ETag form; pwsh strips the quotes on read.
-              $etag = '"' + ([string]($resp.Headers['ETag'] | Select-Object -First 1)).Trim('"') + '"'
-              return @{ Value = [int]$raw.Trim(); ETag = $etag }
-            } catch {
-              $status = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { 0 }
-              if ($status -eq 404) {
-                Write-Error "Counter blob '$counterBlob' not found. Seed it once with the last used build number (see docs/agent/build-counter-blob.md) -- do NOT seed from the repo's buildcounter.txt, it is a stale offline fallback."
-              }
-              throw
-            }
-          }
-
-          $buildNumber = $null
-          for ($attempt = 1; $attempt -le 5; $attempt++) {
-            $counter = Get-Counter
-            if ($override -ne '') {
-              $target = [int]$override
-              if ($target -le $counter.Value) {
-                # Re-build of an already-reserved number: counter stays monotonic, no write.
-                Write-Host "Manual build number $target <= counter $($counter.Value) -- counter blob unchanged"
-                $buildNumber = $target
-                break
-              }
-              Write-Host "Manual build number $target > counter $($counter.Value) -- advancing counter"
-            } else {
-              $target = $counter.Value + 1
-            }
-            try {
-              $headers = @{ 'x-ms-blob-type' = 'BlockBlob'; 'If-Match' = $counter.ETag }
-              Invoke-RestMethod -Uri "$counterUrl`?$sasToken" -Method Put -Headers $headers -Body "$target" -ContentType 'text/plain' | Out-Null
-              $buildNumber = $target
-              Write-Host "Reserved build number ${target} (CAS write ok, attempt $attempt)"
-              break
-            } catch {
-              $status = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { 0 }
-              if ($status -eq 412) {
-                Write-Host "CAS conflict on attempt $attempt (another build reserved concurrently) -- retrying"
-                Start-Sleep -Seconds ($attempt * 2)
-              } else {
-                throw
-              }
-            }
-          }
-          if ($null -eq $buildNumber) {
-            Write-Error "Could not reserve a build number after 5 CAS attempts"
-          }
+          $counterUrl = "https://autopilotmonitoreu.blob.core.windows.net/agent/buildcounter-v$($env:LINE_MAJOR).txt"
+          $buildNumber = & ./.github/scripts/Request-BuildNumber.ps1 -CounterUrl $counterUrl -SasToken '${{ secrets.AZURE_BLOB_AGENT_SAS_TOKEN }}' -Override $override
 
           $csproj = Get-Content $env:CSPROJ_PATH -Raw
           if ($csproj -match '<VersionPrefix>(\d+\.\d+)</VersionPrefix>') {
@@ -228,8 +177,13 @@ jobs:
             Write-Warning "Could not parse bootstrap `$ScriptVersion from $env:BOOTSTRAP_SOURCE"
           }
 
-          # Enrich the per-line manifest emitted by MSBuild (version-v2.json, read above)
+          # Enrich the per-line manifest emitted by MSBuild (version-v2.json, read above).
+          # commit/buildUtc are the same two fields the backend and MCP manifests carry —
+          # additive, and the bootstrap reads this file by field name, so older installers
+          # ignore them. sha256/bootstrapVersion stay: those are the customer contract.
           $manifest | Add-Member -NotePropertyName "sha256" -NotePropertyValue $sha256Hash -Force
+          $manifest | Add-Member -NotePropertyName "commit" -NotePropertyValue '${{ github.sha }}'.Substring(0, 7) -Force
+          $manifest | Add-Member -NotePropertyName "buildUtc" -NotePropertyValue ([DateTime]::UtcNow.ToString('o')) -Force
           if ($bootstrapVersion) {
             $manifest | Add-Member -NotePropertyName "bootstrapVersion" -NotePropertyValue $bootstrapVersion -Force
           }
@@ -240,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"'
 
@@ -277,7 +231,12 @@ jobs:
             param([string]$Local, [string]$BlobName, [string]$ContentType)
             $url = "$containerUrl/$BlobName`?$sasToken"
             $bytes = [System.IO.File]::ReadAllBytes($Local)
-            $headers = @{ "x-ms-blob-type" = "BlockBlob"; "Content-Type" = $ContentType }
+            # no-cache on EVERY blob: they all rotate in place (even the per-line ZIP is
+            # overwritten each build), and the download alias fronts them with Front Door.
+            # Route caching is disabled there, but a stale manifest paired with a fresh ZIP
+            # (independent cache entries) would fail the bootstrap SHA check -- this header
+            # keeps that class of bug impossible even if caching is ever re-enabled.
+            $headers = @{ "x-ms-blob-type" = "BlockBlob"; "Content-Type" = $ContentType; "x-ms-blob-cache-control" = "no-cache" }
             if ($ContentType -eq "application/zip") {
               $md5 = [System.Security.Cryptography.MD5]::Create()
               $headers["Content-MD5"] = [Convert]::ToBase64String($md5.ComputeHash($bytes))
@@ -311,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
@@ -352,13 +317,13 @@ jobs:
           subject-path: ${{ steps.artifact.outputs.versioned_zip_release }}
 
       - name: Upload build artifact
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: AutopilotMonitor-Agent-v${{ steps.version.outputs.version }}
           path: ${{ steps.artifact.outputs.versioned_zip_release }}
 
       - name: Upload version metadata
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: version-metadata
           path: ${{ env.MANIFEST_NAME }}

.github/workflows/ci.yml

@@ -0,0 +1,145 @@
+name: CI
+
+# Tests, typechecks and drift-checks every push to main and every pull request:
+# the .NET suites, the web and MCP suites, and a guard that the generated rule
+# files still match rules/guardrails.json.
+#
+# The deploy workflows build but never test, so this is the only place the suites
+# actually run. It does not gate anything — main is deliberately unprotected, so a
+# red run reports rather than blocks. Read the result and follow up.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  dotnet:
+    name: .NET tests (backend + agent)
+    # windows-latest is required: the agent test projects target net48.
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Restore
+        run: dotnet restore AutopilotMonitor.sln
+
+      - name: Build
+        run: dotnet build AutopilotMonitor.sln --configuration Release --no-restore
+
+      - name: Backend tests
+        run: dotnet test src/Backend/AutopilotMonitor.Functions.Tests --configuration Release --no-build --verbosity quiet
+
+      - name: Agent V2 Core tests
+        run: dotnet test src/Agent/AutopilotMonitor.Agent.V2.Core.Tests --configuration Release --no-build --verbosity quiet
+
+      - name: Decision Core tests
+        run: dotnet test src/Agent/AutopilotMonitor.DecisionCore.Tests --configuration Release --no-build --verbosity quiet
+
+      - name: Summary Dialog tests
+        run: dotnet test src/Agent/AutopilotMonitor.SummaryDialog.Tests --configuration Release --no-build --verbosity quiet
+
+  web:
+    name: Web (typecheck + tests)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: src/Web/autopilot-monitor-web
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          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
+
+  mcp:
+    name: MCP server tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: src/McpServer/autopilot-monitor-mcp
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: src/McpServer/autopilot-monitor-mcp/package-lock.json
+
+      - run: npm ci
+
+      - 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
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      - name: Regenerate
+        run: node rules/scripts/combine.js
+
+      - name: Fail if the generated files drifted
+        run: |
+          if ! git diff --quiet; then
+            echo "::error::Generated files are out of date. Run 'node rules/scripts/combine.js' and commit the result."
+            git diff --stat
+            exit 1
+          fi

.github/workflows/codeql.yml

@@ -0,0 +1,73 @@
+name: CodeQL
+
+# Documentation-only changes cannot affect what CodeQL analyzes (C# and
+# TypeScript), so they are filtered out rather than spending ~10 minutes to
+# re-report an unchanged result. A commit that touches docs AND code still runs:
+# GitHub skips only when EVERY changed path matches the filter.
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - '**/*.md'
+      - 'LICENSE'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - '**/*.md'
+      - 'LICENSE'
+  schedule:
+    # Weekly, so advisories published after a merge still surface. Deliberately
+    # unfiltered — it re-analyzes the whole tree regardless of what changed, which
+    # is also the backstop if the filters above ever skip too much.
+    - cron: '17 3 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze ${{ matrix.language }}
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # csharp needs the net48 agent projects to build, so Windows.
+          - language: csharp
+            runner: windows-latest
+            build-mode: manual
+          - language: javascript-typescript
+            runner: ubuntu-latest
+            build-mode: none
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-dotnet@v6
+        if: matrix.language == 'csharp'
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4.37.3
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          config-file: .github/codeql/codeql-config.yml
+
+      - name: Build
+        if: matrix.build-mode == 'manual'
+        run: dotnet build AutopilotMonitor.sln --configuration Release
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4.37.3
+        with:
+          category: /language:${{ matrix.language }}

.github/workflows/combine-rules.yml

@@ -22,11 +22,11 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v7
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install ajv-cli
         run: npm install -g ajv-cli ajv-formats

.github/workflows/deploy-backend.yml

@@ -7,13 +7,19 @@ permissions:
   id-token: write   # OIDC federated login (secret-less)
   contents: read
 
+env:
+  FUNCTION_APP: autopilotmonitor-api-eu
+  HEALTH_URL: https://autopilotmonitor-api-eu.azurewebsites.net/api/health
+  VERSIONS_CONTAINER: https://autopilotmonitoreu.blob.core.windows.net/versions
+  CSPROJ_PATH: src/Backend/AutopilotMonitor.Functions/AutopilotMonitor.Functions.csproj
+
 jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
     name: Build and Deploy Backend
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Login to Azure (OIDC)
         uses: azure/login@v3
@@ -23,21 +29,95 @@ jobs:
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 
       - name: Setup .NET 10
-        uses: actions/setup-dotnet@v5
+        uses: actions/setup-dotnet@v6
         with:
           dotnet-version: '10.0.x'
 
+      # Same counter mechanism as the agent line: reserve-before-build with ETag-CAS
+      # against a per-component counter blob. BuildTimestampUtc is pinned here rather
+      # than left to MSBuild's default so the published manifest and the value baked
+      # into the assembly (reported by /api/health) are the same instant.
+      - name: Reserve build number (counter blob CAS)
+        id: version
+        shell: pwsh
+        run: |
+          $buildNumber = & ./.github/scripts/Request-BuildNumber.ps1 -CounterUrl "${{ env.VERSIONS_CONTAINER }}/backend.txt" -SasToken '${{ secrets.AZURE_BLOB_VERSIONS_SAS_TOKEN }}'
+
+          $csproj = Get-Content ${{ env.CSPROJ_PATH }} -Raw
+          if ($csproj -notmatch '<VersionPrefix>(\d+\.\d+)</VersionPrefix>') {
+            throw "VersionPrefix not found in ${{ env.CSPROJ_PATH }}"
+          }
+          $version = "$($Matches[1]).$buildNumber"
+          $buildUtc = [DateTime]::UtcNow.ToString('o')
+          Write-Host "Backend version: $version (built $buildUtc)"
+
+          "build_number=$buildNumber" >> $env:GITHUB_OUTPUT
+          "version=$version" >> $env:GITHUB_OUTPUT
+          "build_utc=$buildUtc" >> $env:GITHUB_OUTPUT
+
       - name: Restore dependencies
-        run: dotnet restore src/Backend/AutopilotMonitor.Functions/AutopilotMonitor.Functions.csproj
+        run: dotnet restore ${{ env.CSPROJ_PATH }}
 
       - name: Build
-        run: dotnet build src/Backend/AutopilotMonitor.Functions/AutopilotMonitor.Functions.csproj --configuration Release --no-restore -p:SourceRevisionId=${{ github.sha }}
+        run: dotnet build ${{ env.CSPROJ_PATH }} --configuration Release --no-restore -p:SourceRevisionId=${{ github.sha }} -p:BuildNumber=${{ steps.version.outputs.build_number }} -p:BuildTimestampUtc=${{ steps.version.outputs.build_utc }}
 
       - name: Publish
-        run: dotnet publish src/Backend/AutopilotMonitor.Functions/AutopilotMonitor.Functions.csproj --configuration Release --output ./publish --no-build -p:SourceRevisionId=${{ github.sha }}
+        run: dotnet publish ${{ env.CSPROJ_PATH }} --configuration Release --output ./publish --no-build -p:SourceRevisionId=${{ github.sha }} -p:BuildNumber=${{ steps.version.outputs.build_number }} -p:BuildTimestampUtc=${{ steps.version.outputs.build_utc }}
 
       - name: Deploy to Azure Functions
         uses: Azure/functions-action@v1
         with:
-          app-name: autopilotmonitor-api-eu
+          app-name: ${{ env.FUNCTION_APP }}
           package: ./publish
+
+      # A green deploy step only means the package was accepted. This gate makes the
+      # workflow assert what is actually being served, so the manifest published below
+      # can be trusted as "this is live" rather than "this was uploaded".
+      # /api/health is IP rate-limited at 30/min; one poll per 10s stays well under.
+      - name: Verify deployed build is live
+        shell: pwsh
+        run: |
+          $expectedCommit = '${{ github.sha }}'.Substring(0, 7)
+          $expectedVersion = '${{ steps.version.outputs.version }}'
+          $deadline = [DateTime]::UtcNow.AddMinutes(3)
+          $attempt = 0
+
+          while ([DateTime]::UtcNow -lt $deadline) {
+            $attempt++
+            try {
+              $health = Invoke-RestMethod -Uri '${{ env.HEALTH_URL }}' -Method Get -TimeoutSec 30
+              if ($health.commitHash -eq $expectedCommit -and $health.version -eq $expectedVersion) {
+                Write-Host "Live after $attempt attempt(s): $($health.version) @ $($health.commitHash), built $($health.buildUtc)"
+                exit 0
+              }
+              Write-Host "Attempt ${attempt}: serving $($health.version) @ $($health.commitHash) -- waiting for $expectedVersion @ $expectedCommit"
+            } catch {
+              Write-Host "Attempt ${attempt}: /api/health not answering yet -- $($_.Exception.Message)"
+            }
+            Start-Sleep -Seconds 10
+          }
+
+          throw "Backend did not report $expectedVersion @ $expectedCommit within 3 minutes -- deployment not verified, version manifest NOT published"
+
+      # The manifest is the cross-component record of what is deployed where. It is
+      # written last and only on a verified deploy, so a difference between the
+      # manifest and /api/health means the running app drifted after the fact
+      # (rollback, stale instance) rather than a half-finished pipeline.
+      - name: Publish version manifest
+        shell: pwsh
+        run: |
+          $manifest = [ordered]@{
+            component   = 'backend'
+            version     = '${{ steps.version.outputs.version }}'
+            commit      = '${{ github.sha }}'.Substring(0, 7)
+            buildUtc    = '${{ steps.version.outputs.build_utc }}'
+            deployedUtc = [DateTime]::UtcNow.ToString('o')
+            runId       = '${{ github.run_id }}'
+          } | ConvertTo-Json
+
+          $sas = '${{ secrets.AZURE_BLOB_VERSIONS_SAS_TOKEN }}'.TrimStart('?')
+          $url = "${{ env.VERSIONS_CONTAINER }}/backend.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/backend.json"
+          Write-Host $manifest

.github/workflows/deploy-mcp.yml

@@ -12,6 +12,9 @@ env:
   CONTAINER_APP_NAME: autopilotmonitor-mcp
   RESOURCE_GROUP: ${{ secrets.AZURE_MCP_RESOURCE_GROUP }}
   IMAGE_TAG: ${{ github.sha }}
+  HEALTH_URL: https://mcp.autopilotmonitor.com/health
+  VERSIONS_CONTAINER: https://autopilotmonitoreu.blob.core.windows.net/versions
+  PACKAGE_JSON: src/McpServer/autopilot-monitor-mcp/package.json
 
 jobs:
   build-and-deploy:
@@ -19,7 +22,23 @@ jobs:
     name: Build and Deploy MCP Server
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
+
+      # The published customer documentation lives in its own PUBLIC repo and is
+      # baked into the image as the search_docs corpus (see the Dockerfile). No
+      # token is needed. Checking it out here rather than vendoring it keeps the
+      # docs single-sourced — but it also means EDITING THE DOCS DOES NOT UPDATE A
+      # RUNNING SERVER; this workflow must be re-run. /health reports the SHA
+      # captured below so that staleness is checkable.
+      - name: Check out documentation bundle
+        uses: actions/checkout@v7
+        with:
+          repository: autopilotmonitor/autopilotmonitor-docs
+          path: mcp-docs
+
+      - name: Resolve docs commit
+        id: docs
+        run: echo "sha=$(git -C mcp-docs rev-parse HEAD)" >> "$GITHUB_OUTPUT"
 
       - name: Login to Azure (OIDC)
         uses: azure/login@v3
@@ -28,6 +47,30 @@ jobs:
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 
+      # Same counter mechanism as agent and backend: reserve-before-build with
+      # ETag-CAS against the component's own counter blob. major.minor stays curated
+      # in package.json; only the build part is minted here.
+      - name: Reserve build number (counter blob CAS)
+        id: version
+        shell: pwsh
+        run: |
+          $buildNumber = & ./.github/scripts/Request-BuildNumber.ps1 -CounterUrl "${{ env.VERSIONS_CONTAINER }}/mcp.txt" -SasToken '${{ secrets.AZURE_BLOB_VERSIONS_SAS_TOKEN }}'
+
+          $pkgVersion = (Get-Content ${{ env.PACKAGE_JSON }} -Raw | ConvertFrom-Json).version
+          $prefix = ($pkgVersion -split '\.')[0..1] -join '.'
+          $version = "$prefix.$buildNumber"
+          $buildUtc = [DateTime]::UtcNow.ToString('o')
+          Write-Host "MCP version: $version (built $buildUtc)"
+
+          # 7 chars, matching what the backend's BackendBuildInfo reports — one commit
+          # shape across all components so the values can be compared as-is.
+          $shortSha = '${{ github.sha }}'.Substring(0, 7)
+
+          "build_number=$buildNumber" >> $env:GITHUB_OUTPUT
+          "version=$version" >> $env:GITHUB_OUTPUT
+          "build_utc=$buildUtc" >> $env:GITHUB_OUTPUT
+          "short_sha=$shortSha" >> $env:GITHUB_OUTPUT
+
       - name: Login to ACR
         run: az acr login --name ${{ env.ACR_NAME }}
 
@@ -35,6 +78,10 @@ jobs:
         run: |
           docker build \
             -f src/McpServer/autopilot-monitor-mcp/Dockerfile \
+            --build-arg DOCS_COMMIT=${{ steps.docs.outputs.sha }} \
+            --build-arg BUILD_NUMBER=${{ steps.version.outputs.build_number }} \
+            --build-arg BUILD_COMMIT=${{ steps.version.outputs.short_sha }} \
+            --build-arg BUILD_UTC=${{ steps.version.outputs.build_utc }} \
             -t ${{ env.ACR_NAME }}.azurecr.io/${{ env.CONTAINER_APP_NAME }}:${{ env.IMAGE_TAG }} \
             -t ${{ env.ACR_NAME }}.azurecr.io/${{ env.CONTAINER_APP_NAME }}:latest \
             .
@@ -46,3 +93,55 @@ jobs:
             --name ${{ env.CONTAINER_APP_NAME }} \
             --resource-group ${{ env.RESOURCE_GROUP }} \
             --image ${{ env.ACR_NAME }}.azurecr.io/${{ env.CONTAINER_APP_NAME }}:${{ env.IMAGE_TAG }}
+
+      # `az containerapp update` returns once the revision is provisioned, not once
+      # it serves traffic — and with minReplicas=0 the first request also pays a cold
+      # start. Polling /health until it reports THIS build is what makes the manifest
+      # below mean "live"; a full 5 minutes because the cold start alone is ~25s.
+      - name: Verify deployed build is live
+        shell: pwsh
+        run: |
+          $expectedCommit = '${{ steps.version.outputs.short_sha }}'
+          $expectedVersion = '${{ steps.version.outputs.version }}'
+          $deadline = [DateTime]::UtcNow.AddMinutes(5)
+          $attempt = 0
+
+          while ([DateTime]::UtcNow -lt $deadline) {
+            $attempt++
+            try {
+              $health = Invoke-RestMethod -Uri '${{ env.HEALTH_URL }}' -Method Get -TimeoutSec 60
+              if ($health.commit -eq $expectedCommit -and $health.version -eq $expectedVersion) {
+                Write-Host "Live after $attempt attempt(s): $($health.version) @ $($health.commit), docs $($health.docs.commit) ($($health.docs.chunks) chunks)"
+                exit 0
+              }
+              Write-Host "Attempt ${attempt}: serving $($health.version) @ $($health.commit) -- waiting for $expectedVersion @ $expectedCommit"
+            } catch {
+              Write-Host "Attempt ${attempt}: /health not answering yet -- $($_.Exception.Message)"
+            }
+            Start-Sleep -Seconds 15
+          }
+
+          throw "MCP did not report $expectedVersion @ $expectedCommit within 5 minutes -- deployment not verified, version manifest NOT published"
+
+      # Cross-component record of what is deployed where; written last and only on a
+      # verified deploy. docsCommit rides along because for this component "which
+      # build" and "which documentation" are two separate questions.
+      - name: Publish version manifest
+        shell: pwsh
+        run: |
+          $manifest = [ordered]@{
+            component   = 'mcp'
+            version     = '${{ steps.version.outputs.version }}'
+            commit      = '${{ steps.version.outputs.short_sha }}'
+            buildUtc    = '${{ steps.version.outputs.build_utc }}'
+            deployedUtc = [DateTime]::UtcNow.ToString('o')
+            runId       = '${{ github.run_id }}'
+            docsCommit  = '${{ steps.docs.outputs.sha }}'.Substring(0, 7)
+          } | ConvertTo-Json
+
+          $sas = '${{ secrets.AZURE_BLOB_VERSIONS_SAS_TOKEN }}'.TrimStart('?')
+          $url = "${{ env.VERSIONS_CONTAINER }}/mcp.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/mcp.json"
+          Write-Host $manifest

.github/workflows/deploy-web.yml

@@ -21,16 +21,28 @@ jobs:
     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@v5
+      - uses: actions/checkout@v7
         with:
           lfs: false
           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 }}
@@ -44,16 +56,24 @@ jobs:
           # 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 ######
 
   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/
@@ -117,8 +120,11 @@ scripts/Deployment/
 # Migration tooling (local only, vorerst) — cross-tenant storage/cert migration scripts
 scripts/Migration/
 
-# Infra (local only)
-infra/
+# Infra: tracked. The Bicep templates carry no credentials — every secret is a
+# @secure() parameter with an empty default, injected at deploy time, and image
+# pull runs on managed identity. Keep it that way: never commit a resolved secret
+# value or a *.parameters.json holding one.
+infra/*.parameters.json
 
 # M2 — local raw session fixtures before anonymization (plan §4 M2)
 tests/fixtures/enrollment-sessions-local/
@@ -145,3 +151,6 @@ 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/

.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%" />
@@ -34,7 +34,7 @@ For detailed information about the system architecture, components, and data flo
 
 ## Documentation
 
-Full documentation is available at **[autopilotmonitor.com/docs](https://www.autopilotmonitor.com/docs)**
+Full admin documentation is available at **[docs.autopilotmonitor.com](https://docs.autopilotmonitor.com)**
 
 ## License
 

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/build-counter-blob.md

@@ -22,26 +22,21 @@ attestation on top.
 
 # Schema
 
-- **Counter blob**: `https://autopilotmonitor.blob.core.windows.net/agent/buildcounter-v{LINE}.txt`
-  (per release line, analogous to `version-v{LINE}.json`). Content: the **last used**
-  build number as plain text. Public-read like the rest of the container (the number
-  is visible in `version-v{LINE}.json` anyway); writes require the container SAS.
-- **Protocol — reserve before build, ETag-CAS**:
-  1. Anonymous `GET` the blob, capture value `N` and the `ETag`.
-  2. `PUT N+1` with `If-Match: <etag>` (quoted form — pwsh strips the quotes on read,
-     they must be re-added or the request is rejected client-side).
-  3. `412 Precondition Failed` → another build reserved concurrently → re-read, retry
-     (5 attempts, linear backoff).
-  4. Build with `BUILD_NUMBER=N+1` in the environment. The csproj honors
-     `BUILD_NUMBER` and then skips its `PersistBuildCounter` target, so the repo file
-     is not touched.
-- **Failed builds burn a number.** That is intentional: uniqueness matters, density
-  does not. Reserve-before-build is what makes concurrent minting impossible.
+The reserve-before-build CAS protocol itself is shared with the backend and the MCP
+server and is documented once in [Version Contract](../versioning.md); the single
+implementation is `.github/scripts/Request-BuildNumber.ps1`. Agent-specific:
+
+- **Counter blob**: `https://autopilotmonitoreu.blob.core.windows.net/agent/buildcounter-v{LINE}.txt`
+  — one per release line, analogous to `version-v{LINE}.json`, and kept in the `agent`
+  container next to the artifacts it numbers rather than in `versions/`. Content: the
+  **last used** build number as plain text. Public-read like the rest of the container
+  (the number is visible in `version-v{LINE}.json` anyway); writes require the SAS.
+- The reserved number reaches the build as `BUILD_NUMBER` in the environment. The
+  csproj honors it and then skips its `PersistBuildCounter` target, so the repo file
+  is not touched.
 - **CI manual override** (`build_number` input): numbers `<=` counter are re-builds
   and leave the blob unchanged; numbers `>` counter advance it (monotonic guard).
-- **Seeding** (one-time per line): `PUT <last used number>` with `If-None-Match: *`
-  so an existing counter can never be clobbered. V2 was seeded with `1356` on
-  2026-07-17.
+- V2 was seeded with `1356` on 2026-07-17.
 
 # Consequences
 
@@ -62,7 +57,9 @@ attestation on top.
 
 # Citations
 
+- [Version Contract](../versioning.md) — the shared CAS protocol and manifest format
 - `.github/workflows/build-agent.yml` — "Reserve build number (counter blob CAS)" step
-- `scripts/Deployment/build.ps1` (gitignored, contains SAS) — `Request-BuildNumber`
+- `.github/scripts/Request-BuildNumber.ps1` — the shared implementation
+- `scripts/Deployment/build.ps1` (gitignored, contains SAS) — local build path
 - `src/Agent/AutopilotMonitor.Agent.V2/AutopilotMonitor.Agent.V2.csproj` —
   `BUILD_NUMBER` property + `PersistBuildCounter` target

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/decision-engine.md

@@ -137,8 +137,17 @@ false` and an arm holds), `EspExiting`, `ImeUserSessionCompleted`,
 advisory backstop. All routes converge on `CompleteThroughFinalizingOrDefer`:
 
 1. **Completion gates** (currently only the RealmJoin AND-gate): if RealmJoin was
-   detected and is neither resolved nor timed-out (hard 60-min timeout), completion is
-   *deferred* — the session stays in stage and emits `completion_waiting`.
+   detected and has no terminal outcome yet, completion is *deferred* — the session
+   stays in stage and emits `completion_waiting`. Three terminals open the gate:
+   `Resolved` (DeploymentPhase 110), `FirstDeploymentIncomplete` (phase left the
+   first-deployment window 100/101 for 200/210 without 110 — the RJ ESP was aborted,
+   typically by an interactive logon reclassifying the run as secondary-user; emits
+   the `realmjoin_first_deployment_incomplete` Warning, session 224b2087), and
+   `Timeout` (hard 60-min deadline). The abort rule reads the *persisted*
+   `RealmJoinFacts.LastDeploymentPhase` (updated by the typed `RealmJoinPhaseChanged`
+   signal), so it survives agent restarts — the `RealmJoinDetected` replay path
+   evaluates it too. A first observation of 210 does **not** release (RJ may have
+   completed before agent boot and deploy afterwards).
 2. `Finalizing` stage + ~5 s `FinalizingGrace` deadline.
 3. Grace fires → `Completed`, `EnrollmentComplete` outcome, `enrollment_complete`
    timeline event with full audit payload.

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/index.md

@@ -7,5 +7,6 @@ How the on-device agent works:
 * [Logs, Persistence & Crash Recovery](logs-and-persistence.md) - every persisted file and why it exists; signal log vs spool; snapshot/journal; the replay-based recovery flow and quarantine.
 * [Hello Wizard Un-Skip](hello-wizard-unskip.md) - why a single "WHfB disabled" policy read never decides completion: the HelloWizardStarted signal (prevention + cure) and the HelloTracker confirmation second read.
 * [Autopilot ZTD Diagnostics](autopilot-ztd-diagnostics.md) - Windows' own diagnostic surfaces for the profile-download flow: ModernDeployment event IDs (807/815/164/...), the Diagnostics\Autopilot registry key, deployment-service endpoints, and the known-issue error-code map.
+* [MDM Reboot Coalescing](mdm-reboot-coalescing.md) - attributing the mid-ESP coalesced reboot ("second sign-in") to the device-assigned policy URIs that forced it: aggregated 2800 observations (neutral, flush-time watermark) + ANALYZE-ESP-005 gated on an actually-observed reboot.
 
 Reading order for newcomers: overview → decision engine → persistence.

docs/agent/mdm-reboot-coalescing.md

@@ -0,0 +1,100 @@
+---
+type: Concept
+title: MDM Reboot Coalescing — attributing the mid-ESP reboot and second sign-in to policy URIs
+description: How the agent observes reboot-required MDM policy flags (DM-Enterprise EventID 2800, aggregated) and how ANALYZE-ESP-005 attributes an actually-observed enrollment reboot to them — including why the raw events stay neutral and why the Shell-Core RebootCoalescing match was removed.
+resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals
+tags:
+  - agent
+  - esp
+  - reboot
+  - policy-attribution
+  - second-sign-in
+timestamp: 2026-07-20T00:00:00+02:00
+---
+
+# MDM Reboot Coalescing
+
+Device-assigned MDM policies whose CSP URIs match the OS reboot-required catalog
+(`HKLM\SOFTWARE\Microsoft\Provisioning\SyncML\RebootRequiredURIs`) force a **coalesced
+reboot at the end of ESP DeviceSetup** — the user sees an unexpected restart and a
+**second sign-in screen** before AccountSetup. Invisible in the Intune console; most
+admins live with it, not knowing that reassigning the profiles to user groups removes the
+reboot entirely. Source research: Patch My PC,
+["Avoid the second sign-in screen after Autopilot"](https://patchmypc.com/blog/autopilot-unexpected-reboot-autopilot-second-login-screen/).
+
+The session already counts reboots (`system_reboot_detected` → `session.rebootCount`);
+this feature adds the **cause attribution**.
+
+# Verified signal facts (session b2e890c1, 2026-07-20)
+
+* **EventID 2800**, `Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider/Admin`,
+  one record per URI, verified description shape:
+  `The following URI has triggered a reboot: (./Device/Vendor/MSFT/Policy/Config/ServiceControlManager/SvchostProcessMitigation).`
+  Records arrive in sub-second bursts during policy sync.
+* **Timing semantics (the critical nuance)**: 2800 fires at EVERY policy sync. Only URIs
+  applied **during ESP DeviceSetup** are coalesced into the forced mid-ESP restart. In the
+  verified session the flags fired during AccountSetup (after DeviceSetup completed) —
+  **no reboot occurred**, and `omadmRebootRequiredFlag` read `false`. A detector that
+  claims "reboot incoming" on every 2800 is therefore wrong.
+* **Shell-Core 62407 "RebootCoalescing" — REMOVED as a signal.** The token appears in the
+  ROUTINE bootstrap marker on every enrollment:
+  `Name: 'CommercialOOBE_BootstrapStatusCategory_SubcategoryProcessing_Started', Value: '{"message":"BootstrapStatus: Starting subcategory DeviceSetup.RebootCoalescing...","errorCode":0}'`
+  — the ESP merely *processes* the RebootCoalescing subcategory (which checks whether a
+  reboot is needed). A substring match on it is a false positive by construction. If a
+  real coalesced-reboot record is ever captured on the E2E VM, a precise pattern can be
+  added then.
+
+# Detector — `MdmRebootPolicyTracker` (`MdmRebootPolicyWatcherHost`)
+
+Live `EventLogWatcher` on the DM-Enterprise Admin channel (EventID 2800) + startup
+backfill (default 60 min lookback). Records are **buffered and debounced (10 s)**, then
+flushed as **ONE aggregated `mdm_policy_reboot_required` event** per burst:
+
+* `Severity=Info`, neutral message ("Windows flagged N MDM policy URIs as
+  reboot-required: … (+N more)") — the raw event never claims a reboot.
+* `Data`: `rebootUris` (distinct, sorted, capped 20), `uriCount` (uncapped distinct),
+  `firstRebootUri` (record-time order, drives rule interpolation), `recordCount`,
+  `unparsedCount`/`sampleDescription` (extraction diagnostics), `backfilled` (all-backfill),
+  fail-soft `omadmRebootRequiredFlag` probe of
+  `HKLM\SOFTWARE\Microsoft\Provisioning\OMADM\SyncML\RebootRequired` (null = unknown).
+* `Timestamp` = earliest record time (backfilled bursts land at their historical instant);
+  `ImmediateUpload=true` (one event per burst is cheap, and a DeviceSetup burst precedes a
+  reboot that kills the agent).
+* **Watermark is persisted at FLUSH, not at claim** (`mdm-reboot-watermark.json`): if the
+  coalesced reboot kills the process before the debounced emit, nothing is marked — the
+  post-restart backfill re-reads and emits the burst. A flushed burst is never repeated.
+
+URI extraction: EventData values starting with `./` preferred, permissive regex over the
+description as fallback (trailing punctuation trimmed — the verified text wraps the URI in
+parens and ends with a period). Unparsed records still count into the aggregate.
+
+Config (internal steering only, no admin UI — agent-native collector, NOT an
+`IAgentAnalyzer`): `Collectors.MdmRebootPolicyWatcherEnabled` (default true),
+`Collectors.MdmRebootPolicyBackfillLookbackMinutes` (default 60). ConfigVersion 35.
+
+# Advisory — ANALYZE-ESP-005
+
+The reboot **claim** lives here, and only here. Required conditions (BOTH):
+
+1. `mdm_policy_reboot_required.firstRebootUri` exists (→ `{{firstRebootUri}}` interpolation)
+2. `system_reboot_detected` count ≥ 1 — **an actually-observed reboot**
+
+Policy flags alone (e.g. AccountSetup user-policy sync) stay advisory-silent. Optional
+confidence: `uriCount ≥ 2` (+10), `omadmRebootRequiredFlag == true` (+15) on base 70 /
+threshold 70. Remediation: map URIs to Intune profiles, reassign device → user groups (or
+exclude the Autopilot device group), or accept + communicate the restart.
+
+# Non-goals / invariants
+
+* Event type **deliberately distinct from `system_reboot_detected`** — the backend
+  RebootCount matches that string exactly in two places
+  (`EventIngestProcessor.Classification` + terminal recount); attribution must never
+  inflate the reboot count.
+* No session-level field / SessionInfoCard change in this iteration (follow-up candidate).
+* The `RebootRequiredURIs` catalog itself is not read; only the 2800 events (which carry
+  the actually-triggered URIs) are consumed.
+
+# Citations
+
+* [Patch My PC — Avoid the second sign-in screen after Autopilot](https://patchmypc.com/blog/autopilot-unexpected-reboot-autopilot-second-login-screen/)
+* [Microsoft Learn — Enrollment Status Page tracking](https://learn.microsoft.com/en-us/autopilot/enrollment-status)

docs/agent/secureboot-ca2023-detection.md

@@ -0,0 +1,100 @@
+---
+type: Concept
+title: Secure Boot CA-2023 Detection — firmware evidence vs. Windows servicing status
+description: Why ANALYZE-SEC-001 v3 reads the UEFI db/KEK variables directly (GetFirmwareEnvironmentVariableExW + SeSystemEnvironmentPrivilege) instead of trusting the SecureBoot\Servicing registry key, and how the one-sided uefiCa2023FirmwareConfirmed marker plus a not_exists precondition give absence-tolerant rule suppression across old and new agents.
+resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/UefiSecureBootCertReader.cs
+tags:
+  - agent
+  - secureboot
+  - ca2023
+  - analyze-rules
+  - backward-compatibility
+timestamp: 2026-07-23T00:00:00+02:00
+---
+
+# Secure Boot CA-2023 Detection
+
+## Schema
+
+Two independent evidence sources describe the Windows UEFI CA 2023 rollout state:
+
+1. **Servicing registry** (`HKLM\SYSTEM\CurrentControlSet\Control\SecureBoot\Servicing\UEFICA2023Status`)
+   — reflects whether the *Windows Update* rollout ran and self-verified. Lags reality:
+   devices whose firmware received the certificate another way (OEM factory image, WinCS
+   CLI, manual deployment) or where WU simply has not run yet show `unknown`/`notfound`.
+2. **Firmware itself** — the UEFI variables `db` (signature database, GUID
+   `{d719b2cb-3d3a-4596-a3bc-dad00e67656f}`) and `KEK` (GUID
+   `{8be4df61-93ca-11d2-aa0d-00e098032b8c}`). Authoritative. Certificate subject CNs are
+   ASCII bytes inside the DER signature lists, so a byte-substring search for
+   `Windows UEFI CA 2023` / `Microsoft Corporation KEK 2K CA 2023` decides presence —
+   the same check `Get-SecureBootUEFI` enables from PowerShell.
+
+`UefiSecureBootCertReader` (agent, `Monitoring/Interop`) reads both variables natively via
+`GetFirmwareEnvironmentVariableExW` — no PowerShell runspace during OOBE. The call needs
+`SeSystemEnvironmentPrivilege`: SYSTEM holds it default-disabled, so the reader enables it
+on the process token (`AdjustTokenPrivileges`) and restores the previous state afterwards.
+Fail-soft contract like `OobeStateReader`: never throws; failures map to status strings
+(`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`,
+`uefiKekHasMicrosoftKek2kCa2023`, …) — emitted only when the respective read succeeded —
+plus the marker below.
+
+## The one-sided marker (absence-tolerant suppression)
+
+Rule-engine constraints (pinned by `RuleEnginePreconditionTests`):
+
+* **Conditions** never match on an absent field (null guard) — new fields must stay
+  `required: false` or the rule dies for every old agent.
+* **Preconditions**: `not_exists` passes while the field is absent/empty and fails as soon
+  as the field is present with *any* value; comparison operators fail closed on absence.
+
+A two-sided boolean therefore cannot drive suppression: `not_exists` on
+`uefiDbHasWindowsUefiCa2023` would also suppress the rule when the field is present with
+`false`. Hence the **one-sided marker** `uefiCa2023FirmwareConfirmed = true`, emitted
+ONLY when the db read succeeded AND the 2023 certificate was found — never as `false`.
+ANALYZE-SEC-001 v3 adds a `not_exists` precondition on it:
+
+| Device state | Marker | Rule |
+|---|---|---|
+| Old agent (no firmware fields) | absent | evaluates exactly like v2 |
+| New agent, cert missing or firmware unreadable | absent | evaluates; optional conditions `uefiDbHasWindowsUefiCa2023=false` (+20) / `uefiKekHasMicrosoftKek2kCa2023=false` (+10) raise confidence |
+| New agent, firmware confirms cert | present | silently suppressed (the customer-reported false positive) |
+
+Because the marker exists nowhere until the new agent ships, the v3 rule is safe to seed
+**before** the agent rollout.
+
+## Examples
+
+Customer-equivalent verification from PowerShell (authoritative, matches the reader):
+
+```powershell
+[Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI -Name db).Bytes).Contains('Windows UEFI CA 2023')
+[Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI -Name KEK).Bytes).Contains('Microsoft Corporation KEK 2K CA 2023')
+```
+
+## Citations
+
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/UefiSecureBootCertReader.cs` — native reader
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/DeviceInfo/DeviceInfoCollector.NetworkAndSecurity.cs` — `CollectSecureBootStatus` / `AppendFirmwareCertFields`
+* `rules/analyze/ANALYZE-SEC-001.json` — v3.0.0 rule definition
+* `src/Backend/AutopilotMonitor.Functions.Tests/RuleEnginePreconditionTests.cs` — pinned precondition semantics + v3 mirror tests
+* Microsoft: [Act now — Secure Boot certificates expire June 2026](https://techcommunity.microsoft.com/blog/windows-itpro-blog/act-now-secure-boot-certificates-expire-in-june-2026/4426856)

docs/backend/business-timestamps.md

@@ -0,0 +1,95 @@
+---
+type: Concept
+title: Business Timestamps vs. the Azure Tables System Timestamp
+description: Why the system Timestamp is never authoritative, how the 2026-07-18 migration exposed that, and the OccurredUtc + RowKey-decode compensation (mappers, RowKey-range date filters, retention, backfill).
+resource: /src/Backend/AutopilotMonitor.Functions/Helpers/BusinessTimestamp.cs
+tags:
+  - backend
+  - table-storage
+  - audit-log
+  - ops-events
+  - events
+  - migration
+timestamp: 2026-07-20T00:00:00+02:00
+---
+
+# Problem
+
+Azure Table Storage's `Timestamp` is a **system property**: the server ignores any supplied
+value on write and stamps the row's *write* time; every row rewrite (storage-account
+migration, MERGE) resets it. Three tables nevertheless treated it as the business event
+time — writes like `["Timestamp"] = evt.Timestamp` were silent no-ops, unnoticed because
+write time ≈ event time in normal operation.
+
+The 2026-07-18 EU storage migration rewrote every row, so all migrated rows in
+**AuditLogs**, **OpsEvents**, and **Events** read as "2026-07-18 ~13:58 UTC": displays were
+wrong, date-window filters matched the wrong rows, and retention froze (nothing older than
+the migration moment) with a mass-delete cliff one retention period later.
+
+# Rule
+
+**The system Timestamp is never authoritative.** Every table that needs an event time
+stores it in the custom column `OccurredUtc` (`BusinessTimestamp.OccurredUtcColumn`).
+Custom columns are copied verbatim by `scripts/Migration/Copy-TableStorage.ps1`, so future
+migrations preserve chronology. Migration checklist: any table whose reads/filters depend
+on a timestamp must carry it as a custom column — audit this before every storage move.
+
+# Recovery sources per table
+
+The original time survives migrations inside the RowKey:
+
+| Table | RowKey scheme | Decodable |
+|---|---|---|
+| AuditLogs | `!{MaxTicks-ticks:D19}_{guid:N}` (since 2026-05-06) | Yes; legacy bare-GUID rows (pre-2026-05) are lost |
+| OpsEvents | `{MaxTicks-ticks:D19}` | Yes, all rows |
+| Events | `{ts:yyyyMMddHHmmssfff}_{seq:D10}` (sanitized agent time) | Yes, all rows (ms precision) |
+
+# Mechanism
+
+`BusinessTimestamp` (Functions/Helpers) is the single source of truth: RowKey decoders,
+the OData clause builders, and `GetUtcDateTime` (datetime columns materialize as
+`DateTimeOffset` *or* `DateTime` depending on payload shape — always read via this helper).
+
+1. **Read mappers** resolve `OccurredUtc` → RowKey decode → system Timestamp (last
+   resort; only audit legacy GUID rows end there). Resolvers:
+   `TableStorageService.ResolveAuditTimestamp`, `TableOpsEventRepository.ResolveTimestamp`,
+   `TableStorageService.ResolveEventTimestamp` (also used by
+   `GetEarliestSessionEventTimestampAsync`, which feeds StartedAt/Duration reconciliation —
+   a system-Timestamp read there would rewrite migrated sessions' derived fields).
+2. **Date-window filters and retention use RowKey ranges**, not property comparisons:
+   OData excludes rows missing a compared property (an `OccurredUtc` filter would drop
+   every not-yet-backfilled row), and RowKey ranges are index-backed. Boundary semantics
+   are tick-exact equivalents of the old `Timestamp ge/le` clauses.
+   **Trap:** audit legacy GUID RowKeys (hex first char) sort *after* all `!`-rows, so
+   every lower bound `RowKey ge '!…'` must be paired with `RowKey lt '"'`
+   (`AuditTimeEncodedUpperBound`) — without the guard, a retention sweep would delete all
+   legacy rows. Pinned by `BusinessTimestampFilterClauseTests`.
+3. **Writes** in all three tables now set `OccurredUtc`; the no-op `["Timestamp"]`
+   entries were removed.
+4. **Backfill** (`POST /api/maintenance/backfill-occurred-utc`, GlobalAdminOnly, dry-run
+   by default, `table=audit|ops`, batched via `maxRows`/`continuation`): MERGE that adds
+   only `OccurredUtc` decoded from the RowKey — deterministic and idempotent. **Events
+   rows are deliberately never backfilled** (read-path decode is sufficient; no bulk
+   mutation of enrollment evidence). Note: a MERGE resets the row's system Timestamp —
+   irrelevant once nothing depends on it.
+5. **Audit retention** runs two passes until ~2027-01: RowKey-range for `!`-rows plus a
+   `RowKey ge '0' and Timestamp lt …` pass that ages legacy GUID rows out via their frozen
+   migration-date system Timestamp (remove after 2027-03-01).
+
+# Consequences
+
+* Audit legacy GUID rows have "unknown date" semantics: excluded from date-filtered
+  views, shown with the (wrong but honest) 2026-07-18 fallback in unfiltered views.
+* Raw endpoints (`/api/raw/*`, `query_table`) intentionally keep showing the raw system
+  Timestamp — they are storage-state inspectors, not business views.
+* Event timestamps for pre-cutover rows resolve to the RowKey's sanitized agent time
+  (ms precision); `ReceivedAt` (server ingest time, rows since 2026-03-19) and
+  `OriginalTimestamp` (pre-clamp agent time, clamped rows only) remain separate fields.
+
+# Citations
+
+* `src/Backend/AutopilotMonitor.Functions/Helpers/BusinessTimestamp.cs` — decoders + clause builders
+* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.Maintenance.cs` — audit write/mapper/filters/retention
+* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableOpsEventRepository.cs` — ops write/mapper/filters/retention
+* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.Sessions.cs` — event writes, `ResolveEventTimestamp`, earliest-event read
+* `src/Backend/AutopilotMonitor.Functions/Services/OccurredUtcBackfillService.cs` + `Functions/Admin/BackfillOccurredUtcFunction.cs` — backfill

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/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/index.md

@@ -12,16 +12,46 @@ https://docs.autopilotmonitor.com (separate repository).
 # Architecture
 
 * [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.
 
 # 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.
+* [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 & Emit-on-Change](rules/gather-rule-phase-scoping.md) - Restricting gather rules to enrollment phases (activePhases / activeFromPhase sticky latch) and emitMode "on_change" result-dedup — the anti-spam pair for interval 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).
+
+# 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.
+* [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.
+
+# 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,13 +1,134 @@
 # Log
 
+## 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.
+
+* **Update**: `url-registry.md` — the first release after the alias migration surfaced Front Door caching as a correctness hazard: the alias served the previous `version.json` (`X-Cache: TCP_REMOTE_HIT`) after the origin had rotated, and since manifest and ZIP are independent cache entries, a stale manifest with a fresh ZIP fails the bootstrap SHA-256 check. Route caching on `/agent/*` is now disabled and every blob upload stamps `Cache-Control: no-cache` (CI `Send-Blob`, local `build.ps1`, `versions/*.json` manifests) — all agent-container blobs rotate in place, so nothing there is safely cacheable.
+
+* **Update**: `agent/decision-engine.md` — the RealmJoin completion gate has a third terminal, `FirstDeploymentIncomplete`. Session 224b2087 showed why: an interactive logon 17 s after DeploymentPhase 101 makes RealmJoin reclassify the run as a secondary-user deployment, whose branch writes 200/210 and never 110 — the gate stayed closed until the 60-min hard timeout although Hello and desktop were long resolved. `realmjoin_phase_changed` is now a typed `RealmJoinPhaseChanged` signal, so `RealmJoinFacts.LastDeploymentPhase` is persisted across agent restarts (this also fixes every `realmjoin_timeout` event claiming "last phase: 0"); a transition out of 100/101 into 200/210 releases the gate with the `realmjoin_first_deployment_incomplete` Warning, and the `RealmJoinDetected` replay path evaluates the same rule for restarts that swallow the transition. A first observation of 210 deliberately does not release — session 6f1959c0 started at 210 and only deployed afterwards.
+
+* **Creation**: Added `url-registry.md` — all well-known hosts (own subdomains, both blob accounts, API origin, Graph, Entra login) are now defined once per component (`Constants.cs`, web `utils/config.ts`, MCP `src/config.ts`) and referenced everywhere else; three guard tests fail the build on any literal outside the registries. Written because the EU cutover missed two hardcoded copies of the legacy blob host — `LatestVersionsService` (feeds the portal's version badge) and `ValidateBootstrapCodeFunction` — which kept working only through the fail-soft legacy mirror in `build-agent.yml`; those two plus the agent `SelfUpdater` now use the `download.autopilotmonitor.com` alias (verified serving all four artifacts first). The portal's bootstrap allow-list accepts alias AND legacy host during the transition, which imposes a deploy order: web before (or with) backend. The sweep also surfaced a fourth copy of the www/portal host pair in `middleware.ts` (now derived from the registry via `hostRouting.ts`) and a backend short-link built on the bare apex domain, which only worked through a registrar-level 301.
+
+## 2026-07-22
+
+* **Creation**: Added `versioning.md` — agent, backend and MCP now share one version shape (`<major>.<minor>.<build>` + 7-char commit + build timestamp) and one implementation of the build-number reservation (`.github/scripts/Request-BuildNumber.ps1`, previously copy-pasted between `build-agent.yml` and `build.ps1`). The backend had been pinned at a hand-written `1.0.0` since inception and now starts at `1.5.1000`; the MCP server's `package.json` version was bumped by hand and now starts at `1.5.300`, and it reports its own commit on `/health` instead of only the documentation bundle's. Both deploy workflows poll their health endpoint until it reports the build just deployed and publish `versions/<component>.json` only then, so a manifest that disagrees with the live endpoint means the instance drifted rather than the pipeline failing halfway. `agent/build-counter-blob.md` keeps the agent-specific parts and now points at the shared protocol; its counter URL was still the pre-cutover storage account.
+
+* **Creation**: Added `rules/gather-rule-guardrails.md` — the gather-rule allowlists are enforced only on the agent (the backend validates no `collectorType`, `target`, or `parameters`), so a collector that forgets to call its guard *is* the vulnerability. Written because two had: `LogParserCollector` read any path in `rule.Target`, bypassing even the `C:\Users` hard block that every other file collector honours, and `EventLogCollector` read any channel including `Security` — while the customer-facing documentation already promised both were allowlisted. Both now guard, with `logparser` checking the directory for wildcard targets (`Path.GetFullPath` throws on `*`) and re-checking each resolved path. Added an event-log channel allowlist (`eventLogChannels`) plus hard-blocked channels held in C# rather than JSON, so a parse error cannot lift them. Also fixed the command timeout, which was inert: `ReadToEnd()` blocks until the pipe closes, so `WaitForExit(30000)` was only reached after the process had already exited and a hung command pinned its worker forever — now read asynchronously and killed at the timeout.
+
+* **Update**: Added `.github/workflows/ci.yml` — the full suite (backend, agent V2 Core, DecisionCore, SummaryDialog, web, MCP) now runs on every pull request and every push to main, plus a job that fails if the generated guardrail files drift from `rules/guardrails.json`. Previously **no** workflow ran tests on a PR: the deploy workflows build without testing, and `build-agent.yml` tested only `DecisionCore.Tests` on manual dispatch — while `trust/security-faq.md` already told customers that automated tests run in CI. Added CodeQL (C# and TypeScript) and Dependabot (nuget, npm ×2, actions). Marked `OfficeBinaryWatcherTests` `[Collection("SerialThreading")]`: its bounded re-probe races the shared ThreadPool and failed once under full-suite load.
+
+## 2026-07-21
+
+* **Update**: `search_docs` and `search_knowledge` now state in their tool descriptions that queries must be in English. Both corpora and `all-MiniLM-L6-v2` are English-only, and the failure is total rather than gradual — a German question returns zero results, not weak ones. The caller is a language model, so translating the question before the call and answering in the user's language costs nothing; a multilingual embedding model would be the alternative but is much larger and would have to be measured against the eval harness first, since it changes English retrieval too.
+
+* **Update**: Added `scripts/eval-docs-search.ts`, an offline retrieval evaluation harness (2465 queries in three classes: chunk headings as a regression detector, rare identifiers, and hand-written questions as the reality anchor), and used it to close a third `search_docs` gap found during the live test. The keyword fallback only fired when semantic search returned *fewer* than `topK`; a pasted identifier like `WOW6432Node` instead returned three chunks at ~0.29 that did not contain the word while the one chunk that did was never considered. It now also fires on a weak semantic head (<0.35), letting exact matches take the front while keeping one semantic result. The threshold is measured, not guessed: 0.35 fixes 335 queries and breaks 0 (identifier recall 66.2% → 81.1%), while 0.40 fixes more but starts demoting hand-written questions. The measurement also resized the problem — identifier queries were only succeeding 66.2% of the time, so the reported case was one of roughly 750.
+
+* **Update**: Closed the two measured recall gaps in `search_docs` (`mcp/docs-corpus.md`). (1) **Token windows** — 87 of 324 chunks exceeded the model's 256-token context and 13% of all tokens never reached the ranking; a character budget cannot fix this (the corpus ranges 2.43–5.81 chars/token), so long text is now embedded as 250-token windows with 40 overlap and scored by its BEST window (`embeddings: number[][]`, max not mean). Token coverage 87% → 100%; "proxy configuration blocking app downloads" went from absent to 0.559 at rank 1; the ten reference queries kept byte-identical scores. Costs +31% vectors, index 2.63 → 3.12 MB. The rules corpus gained the same treatment (128 rules → 172 vectors). (2) **Keyword fallback** — when the semantic pass returns fewer than `topK`, results are topped up via literal `lexicalMatch` on distinctive query terms, requiring two matching terms for corroboration (one incidental substring match returned a page about LLM providers for a sourdough query). Fuzzy matching was measured and rejected: at a threshold low enough to surface "RealmJoin" it invents 5 hits for "SCEPman", which the corpus never mentions. Also sharpened the tool description with the measured context argument for preferring it over fetching the docs site.
+
+* **Creation**: Added `mcp/docs-corpus.md` (new `mcp/` section) — the MCP server gains `search_docs`, a third semantic corpus built from the published customer documentation repository (`autopilotmonitor-docs`, checked out into the Docker build context by the deploy workflow). Documents the h2/h3 + `<details>` chunking with breadcrumb prefixes, the two deliberate size exceptions (tables never split, unbroken changelog lists split at line level), the CRLF precondition (`.` does not match `\r` in JS — headings silently stop matching, which produced 286 wrong-but-plausible chunks before it was found), the optional `docs` section in `search-index.json` and its validation asymmetry, embedding rounding to 6 decimals, and the cross-repo coupling: a docs edit reaches clients only after an MCP redeploy, made checkable via `DOCS_COMMIT` on `/health`. Container resources raised to 0.5 vCPU / 1.0 GiB for the cold-start query-embedder load.
+
 ## 2026-07-20
 
+* **Update**: `rules/gather-rule-phase-scoping.md` — the gather-rule form now shows the phase-scope and emit-mode controls only where they can change behavior (`supportsPhaseScope` / `supportsEmitMode`), nulls hidden-control state out of the payload, and rejects a scope mode selected but left unfilled. Offering all three "when" controls unconditionally allowed combinations that could only suppress a one-shot rule, plus a silent no-op state.
+* **Update**: Extended `rules/gather-rule-phase-scoping.md` with the `phase_exit` trigger — the closing bookend to `phase_change`, for one-shot collection when a phase is LEFT (e.g. "state at the end of Account Setup"). Documents the evaluation-before-phase-advance rule (triggerPhase match and scope gate see the phase being left), firing into `Failed`, the disjoint `exit:` dedup key space, and why no ConfigVersion bump is needed (no new field — old agents simply never fire the rule).
+* **Update**: Reworked `agent/mdm-reboot-coalescing.md` after the first real enrollment (session b2e890c1): 2800 records are now **aggregated per burst** into ONE neutral Info event (`rebootUris[]`/`uriCount`/`firstRebootUri`; watermark persisted at flush so a pre-emit reboot kill loses nothing); the raw event no longer claims a reboot — ANALYZE-ESP-005 is gated on an actually-observed `system_reboot_detected`. **Removed** the Shell-Core `esp_reboot_coalescing` event entirely: the "RebootCoalescing" token appears in the routine `SubcategoryProcessing_Started` bootstrap marker on every enrollment (false positive by construction). Verified 2800 description shape recorded.
+* **Creation**: Added `agent/mdm-reboot-coalescing.md` — the agent now attributes the "unexpected mid-ESP reboot + second sign-in" pattern (PMPC research) to the device-assigned policy URIs that forced it: new `MdmRebootPolicyTracker` (DM-Enterprise EventID 2800, per-URI `mdm_policy_reboot_required` events, cross-restart RecordId watermark), a `RebootCoalescing` branch in `ShellCoreTracker` (`esp_reboot_coalescing`, backfill-emitting by design), and the `ANALYZE-ESP-005` advisory (reassign device → user groups). ConfigVersion 35; event types deliberately distinct from `system_reboot_detected` so RebootCount stays uninflated.
+
+* **Creation**: Added `backend/business-timestamps.md` (new `backend/` section) — the 2026-07-18 migration reset every row's system Timestamp, exposing that AuditLogs/OpsEvents/Events had (unknowingly) displayed and filtered on it all along; documents the `OccurredUtc` column, the RowKey decoders and RowKey-range date/retention clauses in `BusinessTimestamp`, the GUID-guard trap, the audit/ops backfill endpoint, and the "system Timestamp is never authoritative" migration rule.
 * **Creation**: Added `rules/gather-rule-phase-scoping.md` (new `rules/` section) — gather rules gain `activePhases` (run only during listed phases), `activeFromPhase` (sticky latch from a phase onwards, never via Failed) and `emitMode: "on_change"` (canonical-hash result dedup with `suppressedPolls` observability), ConfigVersion 34. Includes the prerequisite backend fix: the custom-rule toggle PUT no longer wipes the stored rule definition (partial-merge in `GatherRuleService.UpdateRuleAsync`).
 
 ## 2026-07-18
 
 * **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/docs-corpus.md

@@ -0,0 +1,305 @@
+---
+type: Concept
+title: MCP Docs Corpus — search_docs and the Cross-Repo Build Coupling
+description: How the published customer documentation becomes a third semantic search corpus in the MCP server — CRLF-safe heading chunking, build-time embedding, the corpus hash guard, and why editing the docs does not update a running server.
+resource: /src/McpServer/autopilot-monitor-mcp/src/docs-corpus.ts
+tags:
+  - mcp
+  - search
+  - embeddings
+  - documentation
+  - build
+timestamp: 2026-07-21T19:30:00+02:00
+---
+
+# Purpose
+
+The MCP server answers two different kinds of question, and they need two
+different corpora.
+
+* *"Why did this enrollment fail?"* → analysis rules, gather rules, IME log
+  patterns. That is `search_knowledge`, backed by `knowledge-base.ts`.
+* *"How do I deploy the agent?" / "Where is my data stored?"* → the published
+  customer documentation. That is `search_docs`, backed by `docs-corpus.ts`.
+
+They are deliberately **separate indexes**. Merged into one, they would compete
+for the same `topK` and dilute each other: a rules query would surface prose
+pages, and a product question would surface rule definitions.
+
+# Schema
+
+## Corpus source
+
+The corpus is the `autopilotmonitor-docs` repository — a public OKF bundle
+published at `docs.autopilotmonitor.com`. It is **not** vendored into this repo.
+The deploy workflow checks it out into `mcp-docs/` of the Docker build context;
+the Dockerfile copies it to `/app/docs` in both the build and the final stage
+(byte-identical, or the boot-time corpus hash rejects the precomputed index).
+
+`SUMMARY.md` and `log.md` are skipped as navigation scaffolding. `index.md` is
+kept — it is the documentation map and answers "what documentation exists" — but
+gets no `url`, because the bundle deliberately keeps it out of `SUMMARY.md` and
+GitBook therefore never renders it.
+
+## Chunking
+
+A whole page cannot be one document: `trust/security-faq.md` is 36 KB, while
+MiniLM-L6-v2 truncates at ~256 tokens. An un-chunked page would silently embed
+only its first paragraph.
+
+Chunks are cut at **h2/h3 headings**, which in this bundle are also the semantic
+boundaries — `security-faq.md` carries 37 h3s, one per question.
+`<details><summary>Q</summary>` blocks (used by `troubleshooting/faq.md`) are
+treated the same way, with the summary as the section title. Each chunk is
+prefixed with a `Page Title › Section › Subsection` breadcrumb so a hit lifted
+out of the middle of a page is self-describing to both the embedder and the
+reader.
+
+Two deliberate exceptions to the ~1500-character budget:
+
+* **Markdown tables are never split.** A table broken across chunks leaves
+  `| --- |` rows with no header — unreadable in a result and meaningless to
+  embed. Tables carry real answers here (the role matrix, the settings
+  reference), so an over-long table is allowed to exceed the budget.
+* **Unbroken lists split at line level.** The changelog pages are one bullet
+  list per release with no blank lines, so paragraph splitting cannot touch
+  them; left whole, everything past the model's window would be truncated away
+  and become unsearchable.
+
+Short sections are **kept**, not filtered. A one-line answer ("Is it free?" →
+"Yes, the Community plan is free") is often the most valuable hit, and the
+breadcrumb supplies the context the short body lacks. Only structural residue
+(under 25 alphanumeric characters) is dropped.
+
+## CRLF is a correctness precondition
+
+The docs repo is authored on Windows and ships CRLF. In JavaScript `.` does not
+match `\r`, so a pattern like `/^(#{2,3})\s+(.*)$/` matches **nothing** on a CRLF
+file: `(.*)` stops before the `\r` and `$` never reaches end-of-string.
+
+This was observed during development, and the failure mode is what makes it
+dangerous: no crash, no error — headings and frontmatter simply stop being
+recognized and every page silently degrades to unlabelled paragraph splits. The
+first working build produced 286 plausible-looking chunks that were almost all
+wrong; after normalizing, `security-faq.md` went from 29 blind splits to 46 real
+question sections.
+
+`normalizeNewlines()` runs before any parsing. Do not remove it, and do not
+"fix" a future parsing bug here by adding `\r?` to one pattern.
+
+## Token windows: why a chunk can hold several vectors
+
+Chunking at heading boundaries keeps sections coherent, but it does not bound the
+result by *tokens* — and it cannot. Measured on this corpus the ratio ranges from
+**2.43 to 5.81 characters per token**, a factor of 2.4, so no character budget maps
+reliably onto the model's 256-token window. A budget safe for the worst case
+(~620 characters) would shred prose and tables alike.
+
+Left alone, 87 of 324 chunks exceeded the window and **13% of all tokens never
+reached the ranking** — silently, since the tokenizer truncates without complaint.
+The effect was concrete: in `built-in-rules.md :: Apps` (734 tokens), the strings
+`ANALYZE-APP-013`, `ANALYZE-OFFICE-001`, `ANALYZE-CORR-003` and `Click-to-Run` all
+sit past the cutoff, so *"proxy configuration blocking app downloads"* did not
+retrieve that section at all.
+
+So the *chunk* stays whole and the *embedding* is split instead:
+`VectorSearchProvider.index()` cuts long text into 250-token windows with 40 tokens
+of overlap and embeds each. A document therefore carries `embeddings: number[][]`,
+and `search()` scores it by its **best** window.
+
+- **Max, not mean.** Averaging window vectors would blur a long section's several
+  topics into one mediocre direction — the same dilution that makes large context
+  windows worse than chunking. Max keeps a document findable by any one thing it
+  discusses.
+- **The tokenizer is a build-time dependency only.** `index()` runs during the
+  Docker build; production boots from precomputed vectors and never loads it. It is
+  also only the vocabulary, not the ONNX weights (~93 ms).
+- Cost: 324 chunks → 424 vectors (+31%), index 2.63 → 3.12 MB, and 424 instead of
+  324 dot products per query — still microseconds.
+- The rules corpus benefits too, unplanned: 128 rules now carry 172 vectors.
+
+Measured effect: token coverage 87% → **100%**, *"Office Click-to-Run install never
+finished"* 0.318 → **0.442**, *"proxy configuration blocking app downloads"* absent
+→ **0.559 at rank 1**. The ten reference queries kept byte-identical scores — their
+chunks are short, hence one window, hence the same vector as before.
+
+## Keyword fallback
+
+Semantic ranking alone leaves a gap: proper nouns embed poorly. `RealmJoin` occurs
+in 3 chunks yet scores under the threshold.
+
+Fuzzy matching is the wrong remedy, and the corpus says so. At a threshold low
+enough to surface `RealmJoin` (0.28), Fuse also returns 5 hits for `SCEPman` — a
+word this corpus contains **zero** times. Literal containment has neither problem.
+
+So when the semantic pass returns fewer than `topK`, `search_docs` tops the list up
+via `lexicalMatch`, the substring scan every provider already exposes:
+
+- Query terms are filtered to distinctive ones (≥4 characters, non-stopword, max 6).
+- A hit needs **corroboration**: at least two matching terms, unless the query has
+  only one. Without this rule, "how do I bake sourdough bread" matched a page about
+  LLM providers, because "bake" is a substring of "baked into the image".
+- Hits are **appended, never merged**: they carry no cosine similarity, so semantic
+  results keep the head of the list and keyword hits fill the tail, flagged
+  `matchType: "keyword"` with `keywordFallback` in the response.
+
+### Language
+
+The corpus and `all-MiniLM-L6-v2` are both English-only, and the failure is total
+rather than gradual: "wo werden meine Daten gespeichert" returns **zero** results,
+not weak ones, because the query vector lands nowhere near any English chunk.
+
+The fix is a sentence in the tool description telling the caller to query in English
+and answer in the user's language — the caller is a language model, so translating
+the question before the call costs nothing. A multilingual embedding model would
+handle it natively but is substantially larger and would need to be measured against
+`scripts/eval-docs-search.ts` first, since it changes English retrieval too.
+`search_knowledge` carries the same note for the same reason.
+
+### When it fires
+
+Two triggers, and the second one exists because the first was not enough:
+
+1. **Fewer than `topK` semantic hits** — the obvious case.
+2. **A weak semantic head** (best score below `WEAK_SEMANTIC_SCORE`, 0.35). Topping
+   up only a short list misses the more common failure: a pasted identifier like
+   `WOW6432Node` returns three chunks at ~0.29 that do not contain the word, while
+   the single chunk that does never gets considered. When nothing semantic is
+   convincing, exact matches take the front — keeping at least one semantic result,
+   so a weak-but-correct hit is never pushed out entirely.
+
+The threshold was chosen by measurement, not intuition. `scripts/eval-docs-search.ts`
+scores strategies over 2465 queries in three classes — every chunk heading
+(known-item, a regression detector), rare identifiers (the class this fallback
+serves), and hand-written questions (the reality anchor, not derived from the
+corpus):
+
+| strategy | known-item | literal | handwritten MRR | fixed | broken |
+| --- | --- | --- | --- | --- | --- |
+| append-only (previous) | 71.9% | 66.2% | 1.000 | — | — |
+| weak < 0.30 | 71.9% | 72.6% | 1.000 | 142 | 0 |
+| **weak < 0.35** | **73.7%** | **81.1%** | **1.000** | **335** | **0** |
+| weak < 0.40 | 76.3% | 88.2% | 0.944 | 502 | 3 |
+| weak < 0.45 | 77.2% | 93.0% | 0.889 | 613 | 5 |
+
+0.35 is strictly dominant: better in every class, worse in none. Higher thresholds
+keep repairing more identifier queries but start demoting hand-written questions —
+the class that most resembles real use — so the gain is not free past that point.
+
+The measurement also corrected the size of the problem: identifier queries were
+succeeding only 66.2% of the time, so `WOW6432Node` was not an outlier but one of
+roughly 750 such failures.
+
+## Build-time embedding
+
+Like the rules corpus, docs are embedded once at Docker build time by
+`precompute-embeddings.js <rulesDir> <outFile> [docsDir]`, into a third
+`PrecomputedSection` (`docs`) of `search-index.json`. The container never embeds
+a corpus at boot — only the incoming query.
+
+The `docs` section is **optional** in the file format, which is what makes a
+local checkout without the docs repo work: `validatePrecomputedIndex` skips it
+when the booting server loaded zero doc chunks. The asymmetry is intentional —
+if the server *has* a docs corpus and the file does *not*, that is staleness and
+is rejected like any other mismatch.
+
+Embeddings are rounded to 6 decimals on serialize. A float64 component
+serializes to ~20 characters of JSON, so 384 dims cost ~7.8 KB per vector;
+rounding roughly halves the index file, which is `JSON.parse`d on every
+scale-to-zero cold start. The induced L2 norm error (~1e-5 over 384 dims) sits
+two orders of magnitude inside `UNIT_NORM_EPSILON`.
+
+## Registration
+
+`search_docs` is registered for **every role**, unlike the platform tools: this
+is public documentation carrying no tenant data, and a tenant user asking "how do
+I deploy the agent" has as much business here as a Global Admin. It is skipped
+entirely when the corpus is empty, so a doc-less build advertises no broken tool.
+
+# Cold start
+
+`minReplicas: 0` means every idle period ends in a cold start someone waits through.
+Measured from outside: **24.5 s** to first byte after `ScaledToZero`, against **60 ms**
+warm.
+
+Where those seconds go could not be answered from outside the process. Log Analytics
+stamps every console line of one ingestion batch with the same time, so the boot
+sequence collapses to a single instant however it is queried. The server therefore
+times itself — `[boot +Nms]` marks from `process.uptime()`, which includes Node's own
+startup and module loading.
+
+Measured in production on a real cold start (31.5 s to first byte that time):
+
+```
++244ms  node started (startup + module loading)
++431ms  corpora read from disk         (+187ms)
++491ms  index read, validated, hydrated (+60ms  <- for 3.12 MB)
++504ms  listening
++677ms  query embedder warm            (background)
+```
+
+**The application accounts for half a second of it.** The other ~31 s — 98% — is
+Container Apps activation: KEDA reacting to the request, scheduling a pod, mounting
+the 236 MB image, starting the container. The container also boots *faster* than a
+development laptop (504 ms against 1273 ms), so nothing here is CPU-starved.
+
+Three conclusions, and two of them overturn assumptions this file previously stated:
+
+- **Index size is irrelevant to startup.** 3.12 MB hydrates in 60 ms. Growing the
+  corpus is effectively free, and the embedding rounding earns its keep on file size
+  alone, not on boot time.
+- **Raising the container to 0.5 vCPU was not justified by cold start.** The stated
+  reason was the embedding model load; prebaked, that is 173 ms and runs in the
+  background, where only the first *search* could ever wait on it. The extra vCPU may
+  still help concurrent requests, but the cold-start argument does not survive
+  measurement.
+- **The only real lever is `minReplicas: 1`**, which removes activation entirely at
+  roughly 7× the monthly free consumption grant. Shrinking the image would shave the
+  mount, but that is a fraction of platform time, not the bulk of it.
+
+# Cross-repo coupling
+
+**Editing the documentation does not update a running MCP server.** The corpus is
+baked into the image, so only re-running the *Deploy MCP Server* workflow picks
+up doc changes.
+
+That coupling is made checkable rather than memorable: the build passes the docs
+checkout SHA as `--build-arg DOCS_COMMIT`, and `/health` reports
+`docs: { commit, chunks, sections }`. Comparing that commit against
+`git rev-parse HEAD` in `autopilotmonitor-docs` answers "is the deployed
+documentation stale?" directly.
+
+Automatic redeploy on a docs push was considered and rejected: it would need a
+PAT secret in the docs repo and would turn every typo fix into a container
+deployment.
+
+# Examples
+
+Retrieval measured against the real bundle (323 chunks, all-MiniLM-L6-v2):
+
+```
+"where is my data stored"            → 0.566  troubleshooting/faq.md :: General › Where is my data stored?
+"how do I deploy the agent with Intune" → 0.819  troubleshooting/faq.md :: Setup & Agent › How do I deploy the agent?
+"which roles exist and what can they do" → 0.500  trust/security-faq.md :: Identity and Access › What roles exist?
+"how do I set up Teams notifications"    → 0.592  reference/settings.md  :: Tenant › Notifications
+"what firewall URLs do I need to allow"  → 0.374  reference/network-endpoints.md :: (intro)
+```
+
+The 0.25 `minScore` default is tuned to that observed band — short keyword
+queries on all-MiniLM score low, and a relevant-but-marginal hit lands around
+0.34.
+
+# Citations
+
+* `/src/McpServer/autopilot-monitor-mcp/src/docs-corpus.ts` — loader, frontmatter
+  parser, chunker
+* `/src/McpServer/autopilot-monitor-mcp/src/tools/search.ts` — `search_docs`
+  registration
+* `/src/McpServer/autopilot-monitor-mcp/src/precomputed-index.ts` — `docs`
+  section and its validation asymmetry
+* `/src/McpServer/autopilot-monitor-mcp/Dockerfile` — `mcp-docs/` copy,
+  `DOCS_COMMIT`
+* `/.github/workflows/deploy-mcp.yml` — docs checkout and SHA capture
+* `/src/McpServer/autopilot-monitor-mcp/scripts/eval-docs-search.ts` — retrieval
+  evaluation harness; run it before changing anything about ranking
+* [MCP OAuth Flow](../mcp-oauth-flow.md) — the other MCP concept document

docs/mcp/tool-telemetry.md

@@ -0,0 +1,81 @@
+---
+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), `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/gather-rule-guardrails.md

@@ -0,0 +1,95 @@
+---
+type: Concept
+title: Gather Rule Guardrails
+description: >-
+  How gather-rule collectors are fenced in — the allowlists in rules/guardrails.json,
+  the hard blocks that survive unrestricted mode, and why every collector must call a
+  guard rather than trusting rule.Target.
+resource: src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather
+tags: [gather-rules, security, guardrails, agent]
+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, 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 — 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
+
+Allowlists come from `rules/guardrails.json`, embedded into the agent assembly as
+`AutopilotMonitor.Agent.V2.Core.Resources.guardrails.json` (see the `EmbeddedResource`
+item in `AutopilotMonitor.Agent.V2.Core.csproj`) and regenerated into the portal's
+`utils/guardrails.generated.ts` by `node rules/scripts/combine.js`.
+
+| Guard | Source list | Match rule |
+| --- | --- | --- |
+| `IsRegistryPathAllowed` | `registryPrefixes` | prefix, boundary `\` or end |
+| `IsFilePathAllowed` | `filePrefixes` | `Path.GetFullPath` first, then prefix + boundary |
+| `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 |
+
+**Hard blocks live in code, not in the JSON**, so a parse error cannot lift them — on a
+parse failure the allowlists fall back to empty and everything is blocked (fail-closed),
+but the hard blocks must hold regardless of configuration:
+
+* `BlockedUsersPrefix` (`C:\Users`) and `AdditionalHardBlockedPathPrefixes`
+  (`C:\Windows\System32\config`) — exception only for `%LOGGED_ON_USER_PROFILE%`
+  under `AppData\Local` / `AppData\Roaming`.
+* `HardBlockedCommandPatterns` — download, user/group creation, boot config,
+  persistence, destructive operations; plus `MaxCommandLength`.
+* `HardBlockedEventLogChannels` — `Security` (audit trail of user behaviour) and the
+  PowerShell channels (script-block logging routinely contains secrets in clear text).
+
+`rules/guardrails.json` mirrors the blocked lists (`blockedFilePrefixes`,
+`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
+
+Every collector must call its guard and return `context.EmitSecurityWarning(...)` on
+refusal — that emits the `security_warning` event that makes a block visible in the
+timeline instead of failing silently.
+
+```csharp
+// FileCollector / JsonCollector / XmlCollector
+if (!GatherRuleGuards.IsFilePathAllowed(filePath, context.UnrestrictedMode, userProfilePath))
+    return context.EmitSecurityWarning(rule, "file", filePath);
+```
+
+Two collectors were added to this contract on 2026-07-22 after shipping without it:
+
+* **`LogParserCollector`** read any path in `rule.Target`, bypassing even the `C:\Users`
+  hard block. It cannot guard `rule.Target` directly — a wildcard filename makes
+  `Path.GetFullPath` throw — so it guards **the directory** when the filename contains
+  `*`/`?`, and re-guards **each resolved path** after wildcard expansion (a junction can
+  surface a file the directory check did not cover).
+* **`EventLogCollector`** read any channel, including `Security`.
+
+`ImeLogPathOverride` comes only from the local `--ime-log-path` CLI flag, never from
+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`
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleContext.cs` — `EmitSecurityWarning`
+* `src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleCollectorGuardTests.cs`
+* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/GatherRulesFunction.cs` — what the backend does *not* validate
+* `rules/guardrails.json`, `rules/scripts/combine.js`
+* Customer-facing counterpart: `autopilotmonitor-docs/rules/gather-rules.md` (§ Security guardrails)

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

@@ -1,14 +1,14 @@
 ---
 type: Concept
-title: Gather Rule Phase Scoping & Emit-on-Change
-description: How gather rules are restricted to enrollment phases (activePhases / activeFromPhase) and how emitMode "on_change" suppresses repeated identical results — the anti-spam pair for interval rules.
+title: Gather Rule Phase Scoping, One-Shot Triggers & Emit-on-Change
+description: How gather rules are restricted to enrollment phases (activePhases / activeFromPhase), collect once at a phase boundary (phase_change / phase_exit), and how emitMode "on_change" suppresses repeated identical results.
 resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs
 tags:
   - agent
   - backend
   - gather-rules
   - config
-timestamp: 2026-07-20T00:00:00+02:00
+timestamp: 2026-08-04T00:00:00+02:00
 ---
 
 # Problem
@@ -35,6 +35,64 @@ Backend validation (`GatherRulesFunction.ValidateScopeAndEmitMode`) rejects `Unk
 numeric tokens, unknown emit modes, and both scope fields set at once (400). The agent
 defensively prefers `activePhases` if both arrive anyway.
 
+# One-shot collection at phase boundaries
+
+Scoping answers "while *may* this rule run". The trigger answers "when does it fire". For
+one-shot collection the two phase triggers are the bookends of a phase:
+
+| Trigger | Fires |
+|---|---|
+| `phase_change` | Once when `triggerPhase` is **entered** (dedup key `{ruleId}\|{phase}`). |
+| `phase_exit` | Once when `triggerPhase` is **left** (dedup key `exit:{ruleId}\|{phase}`). |
+
+Empty `triggerPhase` means every transition. Both keys live in the same
+`_phaseRulesExecuted` set; the `exit:` prefix keeps the two key spaces disjoint, so an
+enter-rule and an exit-rule on the same phase never cannibalise each other's slot.
+
+`phase_exit` semantics that are easy to get wrong:
+
+* It is evaluated **before** `_currentPhase` advances, so both the `triggerPhase` match and
+  the phase-scope gate see the phase being **left**. A rule scoped to `DeviceSetup` therefore
+  still fires on its own exit, even though the phase being entered is outside that scope.
+* A transition into `Failed` **does** fire the exit rules of the failing phase — capturing
+  state at the failure boundary is the point.
+* Exit of `Unknown` never fires (nothing was entered yet), and a repeated identical phase
+  signal is not a transition.
+* An exit rule on `Complete` only fires if something transitions *away* from Complete. For
+  "at the end of enrollment", use `phase_change` on `Complete` or `on_event` with
+  `enrollment_complete`.
+* 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**:
@@ -78,6 +136,16 @@ defensively prefers `activePhases` if both arrive anyway.
   `always`. The scope UI is a three-way mode (always / during phases / from phase) backed by
   a canonical `GATHER_PHASES` list — the same list replaced the free-text `triggerPhase`
   input, whose placeholder used to suggest invalid tokens.
+* **Controls are shown only where they change behavior** (`supportsPhaseScope` /
+  `supportsEmitMode` in `types.ts`). Offering all three "when" controls unconditionally
+  produced meaningless combinations — a scope on a `phase_change` rule naming a concrete
+  phase can only ever suppress the single firing, and `on_change` has no second result to
+  compare against. Hidden controls are nulled by `buildScopeFields` so state from an earlier
+  trigger choice cannot leak into the payload, and `validateScopeSelection` rejects a scope
+  mode that was selected but left unfilled (which previously serialised to null and silently
+  ran the rule everywhere while the form still read "From a phase onwards").
+  Startup is the deliberate exception: a scope there defers the one-shot rather than
+  suppressing it, so the scope control stays while emit mode is hidden.
 * The custom-rule toggle PUT (`{enabled, isBuiltIn, isCommunity}`) previously full-replaced
   the stored rule and wiped Title/Target/Trigger — `GatherRuleService.UpdateRuleAsync` now
   merges toggle-style partials (empty Title/CollectorType/Target) into the existing row and
@@ -91,7 +159,9 @@ defensively prefers `activePhases` if both arrive anyway.
 # 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

@@ -0,0 +1,121 @@
+---
+type: Concept
+title: URL Registry — One Place per Component, Guard-Enforced
+description: Every well-known own or Microsoft host lives in exactly one registry file per component (Constants.cs, utils/config.ts, src/config.ts); guard tests fail the build on any literal outside them. Includes the agent-download host migration to the download alias.
+resource: /src/Shared/AutopilotMonitor.Shared/Constants.cs
+tags:
+  - architecture
+  - urls
+  - ci
+  - convention
+timestamp: 2026-07-23T00:00:00+02:00
+---
+
+# URL Registry
+
+Every well-known base URL — own hosts (portal, www, docs, download alias, MCP,
+API, both blob accounts) and Microsoft hosts (Graph, Entra login) — is defined
+in exactly one registry file per component. Code references the constant; the
+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`, `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:
+`lib/hostRouting.ts` computes `PUBLIC_HOST`/`PORTAL_HOST`/`APEX_HOST` from the
+URL constants, and `middleware.ts` imports from it.
+
+# Schema
+
+The guards scan non-test source for the enforced host list and fail with
+file:line on any occurrence outside the registry. Comment lines are ignored
+(docs may cite URLs). Test files are excluded on purpose: a literal in a test
+is an independent oracle — `ValidateBootstrapCodeResponseShapeTests` spells the
+full agent download URL out so a registry change must be acknowledged in two
+places, backend and portal allow-list, consciously.
+
+Why enforced rather than agreed: the registry existed before (both
+`Constants.AgentBlobBaseUrl` and the MCP `config.ts` header document earlier
+drift), yet the EU cutover still missed two literal copies of the blob host —
+`LatestVersionsService` and `ValidateBootstrapCodeFunction` kept reading the
+legacy account, silently kept alive only by the fail-soft legacy mirror in
+`build-agent.yml`. A convention that is not checked decays; these guards make
+the next stray literal a red build instead of a production surprise.
+
+# Agent-download host migration (2026-07-23)
+
+The two legacy readers above plus the agent's `SelfUpdater` now use
+`Constants.AgentDownloadBaseUrl` (`download.autopilotmonitor.com/agent`, Front
+Door in front of the current blob origin — verified serving `version.json`,
+`version-v2.json` and both ZIPs before the switch). The portal's
+`bootstrapValidation.ts` allow-lists BOTH the alias and the legacy blob host
+(`AGENT_DOWNLOAD_HOSTNAMES`) because bootstrap scripts already deployed in
+customer Intune tenants still carry legacy URLs.
+
+Deploy-order constraint: the web allow-list must be live BEFORE (or with) the
+backend that serves alias URLs — an old portal build rejects the alias host and
+the bootstrap flow dies client-side. Remove the legacy hostname from the
+allow-list only after the legacy account is torn down.
+
+**Front Door caching is a correctness hazard here, not a staleness nuisance.**
+The first release after the migration exposed it: the alias kept serving the
+previous `version.json` (`X-Cache: TCP_REMOTE_HIT`) while the origin was already
+updated — and because manifest and ZIP are independent cache entries, a stale
+manifest paired with a fresh ZIP fails the bootstrap's SHA-256 check. Two
+defenses, both in place since 2026-07-23: route caching on `/agent/*` is
+DISABLED, and every blob upload (CI `Send-Blob`, local `build.ps1`, the
+`versions/*.json` manifests) stamps `Cache-Control: no-cache` — all these blobs
+rotate in place, even the per-line ZIP. If caching is ever re-enabled, the
+headers keep the mismatch class impossible.
+
+Deliberately still on the legacy account: the `HealthCheckService` /
+`MaintenanceService` legacy-keepalive probes and the fail-soft mirror in
+`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
+- `src/Web/autopilot-monitor-web/utils/config.ts` — web registry
+- `src/McpServer/autopilot-monitor-mcp/src/config.ts` — MCP registry
+- `src/Backend/AutopilotMonitor.Functions.Tests/HardcodedUrlGuardTests.cs`
+- [Version Contract](versioning.md) — the release pipeline this migration protects

docs/versioning.md

@@ -0,0 +1,108 @@
+---
+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.
+resource: /.github/scripts/Request-BuildNumber.ps1
+tags:
+  - build
+  - ci
+  - release
+  - versioning
+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.
+
+```
+version   = <major>.<minor>.<build>    major.minor curated by hand, build minted per build
+commit    = 7-char short SHA of this repo
+buildUtc  = ISO-8601 build moment
+```
+
+| Component | major.minor from | Counter blob | Reported by |
+|---|---|---|---|
+| 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 |
+
+# Schema
+
+## Build numbers — reserve before build, ETag-CAS
+
+`.github/scripts/Request-BuildNumber.ps1` is the only implementation; the CI
+workflows and the local `build.ps1` all call it.
+
+1. Anonymous `GET` on the counter blob → value `N` and `ETag`. The blob holds the
+   **last used** number as plain text and is public-read; only the write needs the
+   container SAS.
+2. `PUT N+1` with `If-Match: <etag>`. The quoted ETag form is required — PowerShell
+   strips the quotes on read, and an unquoted `If-Match` is rejected client-side.
+3. `412 Precondition Failed` → a concurrent build reserved first → re-read and retry
+   (5 attempts, linear backoff).
+4. Build with the reserved number.
+
+Reserving *before* the build is what makes concurrent minting impossible. **A failed
+build burns a number** — deliberate: uniqueness matters, density does not.
+
+Why a counter and not the published manifest: manifests are written on publish, not on
+build. The agent writes `version.json` only for stable releases, so deriving the next
+number from it would hand two consecutive dev builds the same number and let the second
+overwrite the first's artifact. A state-free scheme such as `git rev-list --count HEAD`
+fails for the same reason — two builds of one commit collide.
+
+**Seeding** (once per component): `PUT <last used number>` with `If-None-Match: *`, so
+an existing counter can never be clobbered. Agent V2 was seeded with `1356` on
+2026-07-17; `versions/backend.txt` with `999` and `versions/mcp.txt` with `299` on
+2026-07-22.
+
+## Local builds
+
+No counter is reached, the build number stays `0`, and the commit is empty or
+`unknown`. A `1.5.0` with no commit hash on `/api/health` is therefore a developer
+machine, not a release — the fallback is the signal, not a defect. The agent is the
+exception: `build.ps1` produces uploadable artifacts and reserves a real number unless
+`-SkipUpload` is passed.
+
+## Manifests
+
+`versions/backend.json` and `versions/mcp.json` (public-read) record what is deployed:
+
+```json
+{ "component": "backend", "version": "1.5.1000", "commit": "abc1234",
+  "buildUtc": "…", "deployedUtc": "…", "runId": "…" }
+```
+
+The MCP manifest adds `docsCommit`, because for that component "which build" and "which
+documentation" are separate questions.
+
+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
+alone means the package was accepted, not that it is being served. Consequently a
+manifest that disagrees with the live endpoint means the running instance drifted after
+the fact (rollback, stale revision) rather than a half-finished pipeline.
+
+The agent keeps its own manifest at `agent/version.json` — the bootstrap derives that
+URL from the download URL and verifies the ZIP against its `sha256`, so it cannot move.
+It carries the same `commit` and `buildUtc` fields; `sha256` and `bootstrapVersion`
+remain, being the customer-facing integrity contract.
+
+# Consequences
+
+- Bumping `major.minor` is a human decision, made in the component's own file
+  (`VersionPrefix`, or `version` in `package.json`). Nothing bumps it automatically.
+- A new component joins by seeding a counter blob and calling the same script; no new
+  mechanism.
+- The counter blobs and manifests live in the `versions` container on
+  `autopilotmonitoreu` (writes via `AZURE_BLOB_VERSIONS_SAS_TOKEN`). The agent's
+  counter stays in the `agent` container next to the artifacts it numbers.
+
+# Citations
+
+- `.github/scripts/Request-BuildNumber.ps1` — the CAS protocol
+- `.github/workflows/deploy-backend.yml`, `deploy-mcp.yml` — reserve, 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

@@ -0,0 +1,268 @@
+// Autopilot-Monitor MCP Server — Azure Container App Infrastructure
+//
+// Reconciled against the live deployment on 2026-07-21 (rg-autopilotmonitor-prd-gwc,
+// Germany West Central). The template had drifted behind two changes made directly
+// in Azure: the EU cutover (registry/API renamed) and the ACR hardening (admin user
+// disabled, image pull moved to the app's system-assigned identity).
+//
+// !! BEFORE RE-DEPLOYING THIS TEMPLATE, READ THIS !!
+// The live app carries an ingress custom-domain binding for mcp.autopilotmonitor.com
+// (SNI-enabled, with a managed certificate). Custom domains are NOT modelled below,
+// because the certificate is bound out-of-band. A full template deployment would
+// therefore REMOVE that binding and take the public MCP endpoint offline.
+// For routine changes (CPU/memory, env vars, image) prefer the surgical CLI form:
+//   az containerapp update -n autopilotmonitor-mcp -g rg-autopilotmonitor-prd-gwc --cpu 0.5 --memory 1.0Gi
+// Treat this file as the documented desired state and as a rebuild-from-scratch
+// recipe — not as a routinely-applied deployment.
+//
+// On a FROM-SCRATCH deploy the AcrPull assignment below is created only after the
+// Container App exists (it needs the app's principalId), so the very first revision
+// can fail to pull its image. Re-run the deployment, or restart the revision, once
+// the role assignment has propagated. This does not affect updates to a live app.
+//
+// Deploy (two-stage; required to set the OAuth public URL safely):
+//   1. First deploy without mcpPublicUrl:
+//      az deployment group create \
+//        --resource-group <rg-name> \
+//        --template-file infra/mcp-server.bicep \
+//        --parameters apiUrl=https://autopilotmonitor-api.azurewebsites.net \
+//                     entraClientSecret=<secret-value>
+//      This emits `containerAppUrl` as an output (e.g. https://autopilotmonitor-mcp.<env-suffix>.<region>.azurecontainerapps.io).
+//
+//   2. Re-deploy with that URL pinned, so the OAuth proxy never trusts caller-
+//      supplied X-Forwarded-Host / Host headers when building issuer / WWW-
+//      Authenticate / redirect_uri metadata:
+//        --parameters mcpPublicUrl=<containerAppUrl from step 1>
+//
+//   When mcpPublicUrl is set, the MCP server uses it verbatim and ignores any
+//   forwarded-headers from the request. Without it, the server logs a startup
+//   warning and falls back to header-derived URLs (acceptable for local dev,
+//   not for production).
+
+@description('Azure region for all resources')
+param location string = resourceGroup().location
+
+@description('Name of the Container App')
+param containerAppName string = 'autopilotmonitor-mcp'
+
+@description('Name of the Container App Environment')
+param environmentName string = 'autopilotmonitor-env'
+
+@description('Name of the Log Analytics Workspace (dedicated for Container Apps)')
+param logAnalyticsName string = 'autopilotmonitor-container-logs'
+
+@description('Name of the Azure Container Registry')
+param acrName string = 'autopilotmonitoreuacr'
+
+@description('Backend API URL')
+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. 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')
+param entraClientSecret string = ''
+
+@description('Comma-separated allowlist of redirect_uri hosts for the OAuth proxy. Loopback is always allowed. Empty = built-in default (Anthropic, OpenAI, Google).')
+param mcpAllowedRedirectHosts string = ''
+
+@description('Public URL of the MCP server, used verbatim for OAuth issuer / WWW-Authenticate / redirect metadata. REQUIRED in production: the container refuses to boot without it (host-spoofing defense — see config.ts). Set on the second deploy with the value of the containerAppUrl output from the first deploy. The stage-1 deploy is safe because minReplicas=0 means no container runs until this is pinned. Empty falls back to X-Forwarded-Host headers only outside production (NODE_ENV != production).')
+param mcpPublicUrl string = ''
+
+@secure()
+// NOTE: avoid characters outside cp1252 here (this one used to say a Unicode
+// >=). `az bicep build --stdout` writes through the Windows console codec and
+// dies with a UnicodeEncodeError on anything it cannot map. Em dashes are fine.
+@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). Volume is one small JSON line per tool call - negligible at current usage.')
+param toolLoggingEnabled bool = true
+
+// --- Azure Container Registry ---
+
+// Admin user is DISABLED: a registry-wide username/password pair is a static,
+// non-rotating credential that would also have to live in a Container App secret.
+// The app pulls with its system-assigned identity + AcrPull instead (see below).
+resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
+  name: acrName
+  location: location
+  sku: {
+    name: 'Basic'
+  }
+  properties: {
+    adminUserEnabled: false
+  }
+}
+
+// AcrPull for the Container App's system-assigned identity — this is what replaces
+// the admin credentials. Without it the app cannot pull its own image.
+//
+// NOTE: this assignment exists on the live registry but could not be enumerated
+// during reconciliation (the CLI session lacks Microsoft.Authorization read), so it
+// is reproduced here from the documented pattern rather than read back from Azure.
+// Verify with:
+//   az role assignment list --scope <acr-id> --assignee <containerApp principalId>
+var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d'
+
+resource acrPull 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  scope: acr
+  name: guid(acr.id, containerAppName, acrPullRoleId)
+  properties: {
+    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId)
+    principalId: containerApp.identity.principalId
+    principalType: 'ServicePrincipal'
+  }
+}
+
+// --- Log Analytics Workspace (required by Container App Environment) ---
+
+resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
+  name: logAnalyticsName
+  location: location
+  properties: {
+    sku: {
+      name: 'PerGB2018'
+    }
+    retentionInDays: 30
+  }
+}
+
+// --- Container App Environment ---
+
+resource environment 'Microsoft.App/managedEnvironments@2024-03-01' = {
+  name: environmentName
+  location: location
+  properties: {
+    appLogsConfiguration: {
+      destination: 'log-analytics'
+      logAnalyticsConfiguration: {
+        customerId: logAnalytics.properties.customerId
+        sharedKey: logAnalytics.listKeys().primarySharedKey
+      }
+    }
+  }
+}
+
+// --- Container App ---
+
+resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
+  name: containerAppName
+  location: location
+  // System-assigned identity: the credential the app uses to pull from the ACR
+  // (see the AcrPull assignment above). Replaces the former admin-user secret.
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    managedEnvironmentId: environment.id
+    configuration: {
+      ingress: {
+        external: true
+        targetPort: 8080
+        transport: 'auto'
+        allowInsecure: false
+      }
+      // 'system' = pull with the app's system-assigned identity. No username, no
+      // password secret — nothing to rotate and nothing to leak from the app config.
+      registries: [
+        {
+          server: acr.properties.loginServer
+          identity: 'system'
+        }
+      ]
+      secrets: [
+        {
+          name: 'entra-client-secret'
+          value: entraClientSecret
+        }
+        {
+          name: 'oauth-state-signing-key'
+          value: oAuthStateSigningKey
+        }
+      ]
+      activeRevisionsMode: 'Single'
+    }
+    template: {
+      containers: [
+        {
+          name: 'mcp-server'
+          image: '${acr.properties.loginServer}/${containerAppName}:${imageTag}'
+          // 0.5 vCPU, but NOT for the reason originally given. It was raised from
+          // 0.25 to shorten the scale-to-zero cold start, on the assumption that
+          // loading the ONNX embedding model dominated it. Measurement disproved
+          // that: the app boots in 504 ms in production (see the [boot] marks in
+          // the container log and docs/mcp/docs-corpus.md), of which the prebaked
+          // embedder is 173 ms in the background. Of a 31 s cold start, ~98% is
+          // Container Apps activation — pod scheduling, image mount, container
+          // start — which no CPU setting touches.
+          //
+          // It stays at 0.5 because it plausibly helps CONCURRENT requests
+          // (maxReplicas is 1, so one replica serves up to 10 in-flight calls) and
+          // because at scale-to-zero the container bills only while active, making
+          // the difference negligible. If cold start ever needs to actually go
+          // away, the only lever is minReplicas: 1. Container Apps accepts fixed
+          // CPU/memory pairs, so memory moves with the CPU.
+          resources: {
+            cpu: json('0.5')
+            memory: '1.0Gi'
+          }
+          env: [
+            { name: 'AUTOPILOT_API_URL', value: apiUrl }
+            { name: 'PORT', value: '8080' }
+            { name: 'AUTOPILOT_ENTRA_CLIENT_ID', value: entraClientId }
+            { name: 'AUTOPILOT_ENTRA_CLIENT_SECRET', secretRef: 'entra-client-secret' }
+            { name: 'MCP_ALLOWED_REDIRECT_HOSTS', value: mcpAllowedRedirectHosts }
+            { name: 'MCP_PUBLIC_URL', value: mcpPublicUrl }
+            { name: 'OAuthStateSigningKey', secretRef: 'oauth-state-signing-key' }
+            { name: 'MCP_TOOL_LOGGING', value: toolLoggingEnabled ? 'true' : 'false' }
+          ]
+          probes: [
+            {
+              type: 'Liveness'
+              httpGet: {
+                path: '/health'
+                port: 8080
+              }
+              periodSeconds: 30
+              initialDelaySeconds: 10
+            }
+            {
+              type: 'Readiness'
+              httpGet: {
+                path: '/health'
+                port: 8080
+              }
+              periodSeconds: 10
+              initialDelaySeconds: 5
+            }
+          ]
+        }
+      ]
+      scale: {
+        minReplicas: 0
+        maxReplicas: 1
+        rules: [
+          {
+            name: 'http-scaler'
+            http: {
+              metadata: {
+                concurrentRequests: '10'
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+
+// --- Outputs ---
+
+output containerAppUrl string = 'https://${containerApp.properties.configuration.ingress.fqdn}'
+output mcpEndpoint string = 'https://${containerApp.properties.configuration.ingress.fqdn}/mcp'
+output acrLoginServer string = acr.properties.loginServer

rules/analyze/ANALYZE-ESP-005.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-ESP-005",
+  "title": "MDM Policy Forced a Mid-ESP Reboot (Second Sign-In)",
+  "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",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "trigger": "single",
+  "baseConfidence": 70,
+  "conditions": [
+    {
+      "signal": "reboot_forcing_policy_uri",
+      "source": "event_data",
+      "eventType": "mdm_policy_reboot_required",
+      "dataField": "firstRebootUri",
+      "operator": "exists",
+      "required": true
+    },
+    {
+      "signal": "reboot_observed",
+      "source": "event_count",
+      "eventType": "system_reboot_detected",
+      "operator": "count_gte",
+      "value": "1",
+      "required": true
+    },
+    {
+      "signal": "multiple_reboot_uris",
+      "source": "event_data",
+      "eventType": "mdm_policy_reboot_required",
+      "dataField": "uriCount",
+      "operator": "gte",
+      "value": "2",
+      "required": false
+    },
+    {
+      "signal": "omadm_reboot_flag_set",
+      "source": "event_data",
+      "eventType": "mdm_policy_reboot_required",
+      "dataField": "omadmRebootRequiredFlag",
+      "operator": "equals",
+      "value": "true",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    { "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.",
+  "remediation": [
+    {
+      "title": "Reassign the reboot-forcing policies to user groups",
+      "steps": [
+        "Open the `mdm_policy_reboot_required` timeline event and note the CSP URIs in `rebootUris` (e.g. `./Device/Vendor/MSFT/...`)",
+        "Map each URI to its Intune profile (Settings Catalog / configuration profile) — the URI path names the CSP area",
+        "Reassign those profiles from device groups to user groups so they apply during/after AccountSetup instead of DeviceSetup",
+        "Alternatively, exclude the Autopilot device group from the profile and deliver the setting post-enrollment"
+      ]
+    },
+    {
+      "title": "Or accept the reboot and set expectations",
+      "steps": [
+        "If the policy must be device-assigned (e.g. a security baseline), keep it and document the expected mid-ESP restart",
+        "Communicate to users that a restart and second sign-in during provisioning is expected for these deployments"
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Patch My PC: Avoid the second sign-in screen after Autopilot",
+      "url": "https://patchmypc.com/blog/autopilot-unexpected-reboot-autopilot-second-login-screen/"
+    },
+    {
+      "title": "Microsoft Learn: Enrollment Status Page tracking",
+      "url": "https://learn.microsoft.com/en-us/autopilot/enrollment-status"
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": ["esp", "reboot", "coalescing", "second-sign-in", "policy-attribution", "user-experience"]
+}

rules/analyze/ANALYZE-ESP-006.json

@@ -0,0 +1,90 @@
+{
+  "$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.0.0",
+  "enabled": true,
+  "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-SEC-001.json

@@ -2,10 +2,10 @@
   "$schema": "../schema/analyze-rule.schema.json",
   "ruleId": "ANALYZE-SEC-001",
   "title": "Secure Boot UEFI CA 2023 certificate not deployed",
-  "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.",
+  "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": "2.0.0",
+  "version": "3.0.0",
   "enabled": true,
   "baseConfidence": 70,
   "preconditions": [
@@ -16,6 +16,14 @@
       "operator": "equals",
       "value": "false",
       "description": "Skip on virtual machines — Secure Boot DB is host-controlled (Hyper-V/VMware/etc), the inside-the-VM UEFICA2023Status registry value is not the right indicator and not actionable for the VM admin."
+    },
+    {
+      "source": "event_data",
+      "eventType": "secureboot_status",
+      "dataField": "uefiCa2023FirmwareConfirmed",
+      "operator": "not_exists",
+      "value": "",
+      "description": "Skip when the firmware db itself confirms the Windows UEFI CA 2023 certificate — the marker is only emitted on positive firmware confirmation, so old agents (field absent) and unconfirmed devices keep evaluating the rule. The servicing registry status lags behind actual firmware state (OEM factory image, WinCS, manual deployment, or WU simply not run yet)."
     }
   ],
   "conditions": [
@@ -54,13 +62,33 @@
       "operator": "exists",
       "value": "",
       "required": false
+    },
+    {
+      "signal": "db_ca2023_firmware_missing",
+      "source": "event_data",
+      "eventType": "secureboot_status",
+      "dataField": "uefiDbHasWindowsUefiCa2023",
+      "operator": "equals",
+      "value": "false",
+      "required": false
+    },
+    {
+      "signal": "kek_2023_missing",
+      "source": "event_data",
+      "eventType": "secureboot_status",
+      "dataField": "uefiKekHasMicrosoftKek2kCa2023",
+      "operator": "equals",
+      "value": "false",
+      "required": false
     }
   ],
   "confidenceFactors": [
     { "signal": "ca2023_notfound", "condition": "exists", "weight": 20 },
-    { "signal": "ca2023_error", "condition": "exists", "weight": 10 }
+    { "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\nCurrent UEFI CA 2023 status: `{{uefiCA2023Status}}`",
+  "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": [
     {
       "title": "Deploy UEFI CA 2023 certificate now",
@@ -69,7 +97,7 @@
         "Use Intune policy to enable Secure Boot DB update (Windows UEFI CA 2023)",
         "Check with the device OEM whether a firmware update is required for the DB update to apply on this model",
         "Alternatively, use the WinCS CLI tool from Microsoft for manual deployment",
-        "Verify deployment: check registry HKLM\\SYSTEM\\CurrentControlSet\\Control\\SecureBoot\\Servicing\\UEFICA2023Status = 'Updated'",
+        "Verify deployment against the firmware directly: [Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI -Name db).Bytes).Contains('Windows UEFI CA 2023') — this is authoritative; the registry value HKLM\\SYSTEM\\CurrentControlSet\\Control\\SecureBoot\\Servicing\\UEFICA2023Status = 'Updated' only reflects the Windows Update rollout",
         "After DB update: ensure the boot manager is updated to a 2023-signed version via monthly cumulative update"
       ]
     }

rules/analyze/ANALYZE-SEC-008.json

@@ -0,0 +1,78 @@
+{
+  "$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.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "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/analyze-rules.json

@@ -1785,6 +1785,209 @@
         "enrollment"
       ]
     },
+    {
+      "ruleId": "ANALYZE-ESP-005",
+      "title": "MDM Policy Forced a Mid-ESP Reboot (Second Sign-In)",
+      "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",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "trigger": "single",
+      "baseConfidence": 70,
+      "conditions": [
+        {
+          "signal": "reboot_forcing_policy_uri",
+          "source": "event_data",
+          "eventType": "mdm_policy_reboot_required",
+          "dataField": "firstRebootUri",
+          "operator": "exists",
+          "required": true
+        },
+        {
+          "signal": "reboot_observed",
+          "source": "event_count",
+          "eventType": "system_reboot_detected",
+          "operator": "count_gte",
+          "value": "1",
+          "required": true
+        },
+        {
+          "signal": "multiple_reboot_uris",
+          "source": "event_data",
+          "eventType": "mdm_policy_reboot_required",
+          "dataField": "uriCount",
+          "operator": "gte",
+          "value": "2",
+          "required": false
+        },
+        {
+          "signal": "omadm_reboot_flag_set",
+          "source": "event_data",
+          "eventType": "mdm_policy_reboot_required",
+          "dataField": "omadmRebootRequiredFlag",
+          "operator": "equals",
+          "value": "true",
+          "required": false
+        }
+      ],
+      "confidenceFactors": [
+        {
+          "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.",
+      "remediation": [
+        {
+          "title": "Reassign the reboot-forcing policies to user groups",
+          "steps": [
+            "Open the `mdm_policy_reboot_required` timeline event and note the CSP URIs in `rebootUris` (e.g. `./Device/Vendor/MSFT/...`)",
+            "Map each URI to its Intune profile (Settings Catalog / configuration profile) — the URI path names the CSP area",
+            "Reassign those profiles from device groups to user groups so they apply during/after AccountSetup instead of DeviceSetup",
+            "Alternatively, exclude the Autopilot device group from the profile and deliver the setting post-enrollment"
+          ]
+        },
+        {
+          "title": "Or accept the reboot and set expectations",
+          "steps": [
+            "If the policy must be device-assigned (e.g. a security baseline), keep it and document the expected mid-ESP restart",
+            "Communicate to users that a restart and second sign-in during provisioning is expected for these deployments"
+          ]
+        }
+      ],
+      "relatedDocs": [
+        {
+          "title": "Patch My PC: Avoid the second sign-in screen after Autopilot",
+          "url": "https://patchmypc.com/blog/autopilot-unexpected-reboot-autopilot-second-login-screen/"
+        },
+        {
+          "title": "Microsoft Learn: Enrollment Status Page tracking",
+          "url": "https://learn.microsoft.com/en-us/autopilot/enrollment-status"
+        }
+      ],
+      "markSessionAsFailedDefault": false,
+      "tags": [
+        "esp",
+        "reboot",
+        "coalescing",
+        "second-sign-in",
+        "policy-attribution",
+        "user-experience"
+      ]
+    },
+    {
+      "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.0.0",
+      "enabled": true,
+      "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"
+      ]
+    },
     {
       "ruleId": "ANALYZE-ID-001",
       "title": "Expected Machine Certificate Not Found",
@@ -2079,10 +2282,10 @@
     {
       "ruleId": "ANALYZE-SEC-001",
       "title": "Secure Boot UEFI CA 2023 certificate not deployed",
-      "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.",
+      "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": "2.0.0",
+      "version": "3.0.0",
       "enabled": true,
       "baseConfidence": 70,
       "preconditions": [
@@ -2093,6 +2296,14 @@
           "operator": "equals",
           "value": "false",
           "description": "Skip on virtual machines — Secure Boot DB is host-controlled (Hyper-V/VMware/etc), the inside-the-VM UEFICA2023Status registry value is not the right indicator and not actionable for the VM admin."
+        },
+        {
+          "source": "event_data",
+          "eventType": "secureboot_status",
+          "dataField": "uefiCa2023FirmwareConfirmed",
+          "operator": "not_exists",
+          "value": "",
+          "description": "Skip when the firmware db itself confirms the Windows UEFI CA 2023 certificate — the marker is only emitted on positive firmware confirmation, so old agents (field absent) and unconfirmed devices keep evaluating the rule. The servicing registry status lags behind actual firmware state (OEM factory image, WinCS, manual deployment, or WU simply not run yet)."
         }
       ],
       "conditions": [
@@ -2131,6 +2342,24 @@
           "operator": "exists",
           "value": "",
           "required": false
+        },
+        {
+          "signal": "db_ca2023_firmware_missing",
+          "source": "event_data",
+          "eventType": "secureboot_status",
+          "dataField": "uefiDbHasWindowsUefiCa2023",
+          "operator": "equals",
+          "value": "false",
+          "required": false
+        },
+        {
+          "signal": "kek_2023_missing",
+          "source": "event_data",
+          "eventType": "secureboot_status",
+          "dataField": "uefiKekHasMicrosoftKek2kCa2023",
+          "operator": "equals",
+          "value": "false",
+          "required": false
         }
       ],
       "confidenceFactors": [
@@ -2143,9 +2372,19 @@
           "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\nCurrent UEFI CA 2023 status: `{{uefiCA2023Status}}`",
+      "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": [
         {
           "title": "Deploy UEFI CA 2023 certificate now",
@@ -2154,7 +2393,7 @@
             "Use Intune policy to enable Secure Boot DB update (Windows UEFI CA 2023)",
             "Check with the device OEM whether a firmware update is required for the DB update to apply on this model",
             "Alternatively, use the WinCS CLI tool from Microsoft for manual deployment",
-            "Verify deployment: check registry HKLM\\SYSTEM\\CurrentControlSet\\Control\\SecureBoot\\Servicing\\UEFICA2023Status = 'Updated'",
+            "Verify deployment against the firmware directly: [Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI -Name db).Bytes).Contains('Windows UEFI CA 2023') — this is authoritative; the registry value HKLM\\SYSTEM\\CurrentControlSet\\Control\\SecureBoot\\Servicing\\UEFICA2023Status = 'Updated' only reflects the Windows Update rollout",
             "After DB update: ensure the boot manager is updated to a 2023-signed version via monthly cumulative update"
           ]
         }
@@ -2448,6 +2687,93 @@
         "truncated",
         "coverage"
       ]
+    },
+    {
+      "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.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "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/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"
       ]
     },
     {
@@ -109,6 +110,79 @@
     "SELECT * FROM Win32_LogicalDisk",
     "SELECT * FROM SoftwareLicensingProduct"
   ],
+  "eventLogChannels": [
+    {
+      "category": "Core Windows logs",
+      "channels": [
+        "Application",
+        "System",
+        "Setup",
+        "Microsoft-Windows-Kernel-Boot",
+        "Microsoft-Windows-Diagnostics-Performance"
+      ]
+    },
+    {
+      "category": "MDM / Enrollment",
+      "channels": [
+        "Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider",
+        "Microsoft-Windows-ModernDeployment-Diagnostics-Provider",
+        "Microsoft-Windows-Provisioning-Diagnostics-Provider",
+        "Microsoft-Windows-AAD",
+        "Microsoft-Windows-User Device Registration"
+      ]
+    },
+    {
+      "category": "ESP / Shell / Apps",
+      "channels": [
+        "Microsoft-Windows-Shell-Core",
+        "Microsoft-Windows-AppXDeployment",
+        "Microsoft-Windows-AppXDeploymentServer",
+        "Microsoft-Windows-AppReadiness",
+        "Microsoft-Windows-Store"
+      ]
+    },
+    {
+      "category": "Security posture / Crypto",
+      "channels": [
+        "Microsoft-Windows-BitLocker-API",
+        "Microsoft-Windows-BitLocker-DrivePreparationTool",
+        "Microsoft-Windows-TPM-WMI",
+        "Microsoft-Windows-CertificateServicesClient-Lifecycle-System"
+      ]
+    },
+    {
+      "category": "Update / Servicing",
+      "channels": [
+        "Microsoft-Windows-WindowsUpdateClient"
+      ]
+    },
+    {
+      "category": "Logon / Session",
+      "channels": [
+        "Microsoft-Windows-Winlogon",
+        "Microsoft-Windows-User Profile Service",
+        "Microsoft-Windows-GroupPolicy",
+        "Microsoft-Windows-TaskScheduler"
+      ]
+    },
+    {
+      "category": "Network",
+      "channels": [
+        "Microsoft-Windows-NetworkProfile",
+        "Microsoft-Windows-Dhcp-Client",
+        "Microsoft-Windows-DNS-Client",
+        "Microsoft-Windows-NCSI",
+        "Microsoft-Windows-WLAN-AutoConfig",
+        "Microsoft-Windows-Time-Service"
+      ]
+    }
+  ],
+  "blockedEventLogChannels": [
+    "Security",
+    "Microsoft-Windows-PowerShell",
+    "Windows PowerShell",
+    "Microsoft-Windows-Sysmon"
+  ],
   "allowedCommands": [
     {
       "category": "TPM and Security",
@@ -176,6 +250,27 @@
     "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
 }

rules/schema/gather-rule.schema.json

@@ -67,7 +67,7 @@
         "collectorType": {
           "type": "string",
           "description": "Type of data collection.",
-          "enum": ["registry", "eventlog", "wmi", "file", "command_allowlisted", "logparser"]
+          "enum": ["registry", "eventlog", "wmi", "file", "json", "xml", "command_allowlisted", "logparser"]
         },
         "target": {
           "type": "string",
@@ -80,8 +80,8 @@
         },
         "trigger": {
           "type": "string",
-          "description": "When to collect data.",
-          "enum": ["startup", "phase_change", "interval", "on_event"]
+          "description": "When to collect data. \"phase_change\" fires once when triggerPhase is entered, \"phase_exit\" once when it is left.",
+          "enum": ["startup", "phase_change", "phase_exit", "interval", "on_event"]
         },
         "intervalSeconds": {
           "type": "integer",
@@ -90,7 +90,7 @@
         },
         "triggerPhase": {
           "type": "string",
-          "description": "Phase to trigger on (only used when trigger = \"phase_change\")."
+          "description": "Phase to trigger on (used when trigger = \"phase_change\" or \"phase_exit\"). Empty = every phase transition."
         },
         "triggerEventType": {
           "type": "string",

rules/scripts/combine.js

@@ -91,6 +91,7 @@ if (fs.existsSync(guardrailsPath)) {
   // Flatten categorized lists for validation
   const flatRegistryPrefixes = guardrails.registryPrefixes.flatMap((g) => g.prefixes);
   const flatCommands = guardrails.allowedCommands.flatMap((g) => g.commands);
+  const flatEventLogChannels = guardrails.eventLogChannels.flatMap((g) => g.channels);
 
   const ts = `/**
  * AUTO-GENERATED from rules/guardrails.json — DO NOT EDIT.
@@ -114,6 +115,10 @@ export const COMMAND_CATEGORIES: readonly GuardrailCategory[] = [
 ${categorizedArray(guardrails.allowedCommands, 'commands')}
 ];
 
+export const EVENT_LOG_CHANNEL_CATEGORIES: readonly GuardrailCategory[] = [
+${categorizedArray(guardrails.eventLogChannels, 'channels')}
+];
+
 // ---------------------------------------------------------------------------
 // Flat arrays (for validation logic)
 // ---------------------------------------------------------------------------
@@ -141,10 +146,66 @@ ${flatArray(guardrails.diagnosticsPathPrefixes)}
 export const BLOCKED_FILE_PREFIXES: readonly string[] = [
 ${flatArray(guardrails.blockedFilePrefixes)}
 ];
+
+export const ALLOWED_EVENT_LOG_CHANNELS: readonly string[] = [
+${flatArray(flatEventLogChannels)}
+];
+
+export const BLOCKED_EVENT_LOG_CHANNELS: readonly string[] = [
+${flatArray(guardrails.blockedEventLogChannels)}
+];
+
+export const BLOCKED_COMMAND_PATTERNS: readonly string[] = [
+${flatArray(guardrails.blockedCommandPatterns)}
+];
+
+export const MAX_COMMAND_LENGTH = ${guardrails.maxCommandLength};
 `;
 
   fs.writeFileSync(guardrailsOutput, ts, 'utf8');
-  console.log(`guardrails.generated.ts: ${flatRegistryPrefixes.length} registry, ${flatCommands.length} commands, ${guardrails.filePrefixes.length} file prefixes`);
+  console.log(`guardrails.generated.ts: ${flatRegistryPrefixes.length} registry, ${flatCommands.length} commands, ${guardrails.filePrefixes.length} file prefixes, ${flatEventLogChannels.length} event log channels`);
 } else {
   console.warn('guardrails.json not found — skipping guardrails generation');
 }
+
+// ── MCP rule-authoring module generation ────────────────────────────────────
+// The MCP server exposes the rule schemas + guardrails as get_resource content
+// so a customer's AI can author rules against the real contract instead of
+// retrieval fragments. The server's tsconfig (rootDir: src, no resolveJsonModule)
+// and the Docker build (rules/schema not copied) rule out importing the JSON
+// directly — so we bake it into a TS module, exactly like the web mirror above.
+// CI's guardrails-in-sync job re-runs this script and fails on any diff, which
+// makes drift between rules/* and this generated module impossible to merge.
+
+const mcpAuthoringOutput = path.resolve(
+  rulesRoot, '..', 'src', 'McpServer', 'autopilot-monitor-mcp', 'src', 'rule-authoring.generated.ts'
+);
+
+{
+  const guardrails = JSON.parse(fs.readFileSync(guardrailsPath, 'utf8'));
+  const gatherSchema = JSON.parse(fs.readFileSync(path.join(rulesRoot, 'schema', 'gather-rule.schema.json'), 'utf8'));
+  const analyzeSchema = JSON.parse(fs.readFileSync(path.join(rulesRoot, 'schema', 'analyze-rule.schema.json'), 'utf8'));
+
+  const ts = `/**
+ * AUTO-GENERATED from rules/guardrails.json + rules/schema/*.schema.json — DO NOT EDIT.
+ * Run: node rules/scripts/combine.js
+ *
+ * Consumed by the MCP server's rule-authoring surface (get_resource +
+ * validate_rule): the JSON Schemas are the validation contract, the guardrails
+ * are the agent-side collection allowlists. Single source of truth is rules/;
+ * the CI guardrails-in-sync job guards this file against drift.
+ */
+
+/** JSON Schema (2020-12) for gather rules — rules/schema/gather-rule.schema.json verbatim. */
+export const GATHER_RULE_SCHEMA: Record<string, unknown> = ${JSON.stringify(gatherSchema, null, 2)};
+
+/** JSON Schema (2020-12) for analyze rules — rules/schema/analyze-rule.schema.json verbatim. */
+export const ANALYZE_RULE_SCHEMA: Record<string, unknown> = ${JSON.stringify(analyzeSchema, null, 2)};
+
+/** Gather-rule collection guardrails — rules/guardrails.json verbatim. */
+export const RULE_GUARDRAILS = ${JSON.stringify(guardrails, null, 2)} as const;
+`;
+
+  fs.writeFileSync(mcpAuthoringOutput, ts, 'utf8');
+  console.log('rule-authoring.generated.ts: schemas + guardrails baked for MCP server');
+}

scripts/Bootstrap/Install-AutopilotMonitor-dev.ps1

@@ -1,362 +0,0 @@
-<#
-.SYNOPSIS
-    Bootstrap script to deploy and start the Autopilot Monitor agent. (DEV)
-
-.DESCRIPTION
-    Designed to be deployed via Intune as a PowerShell Script during Autopilot.
-    Runs very early in the enrollment process (first Intune action) and:
-      1. Runs pre-flight guards to skip productive devices and ghost re-installs.
-         An OOBE-relax exemption allows install when a single freshly-created profile
-         appears DURING OOBE (the "Windows Backup for Organizations" restore case).
-      2. Downloads the monitoring agent ZIP from Azure Blob Storage
-      3. Verifies integrity via SHA-256 hash from the version manifest (mandatory)
-      4. Extracts the agent into %ProgramData%\AutopilotMonitor\Agent
-      5. Runs the agent in --install mode (registers Scheduled Task, spawns the runtime)
-      6. Verifies the runtime process actually launched
-    Agent self-destructs when enrollment completes.
-
-    OOBE-relax flow (guards 2+3): a real user profile (or a real LastLoggedOnUser)
-    normally means "productive -> skip". Windows Backup for Organizations breaks that
-    by restoring settings and creating ONE profile while still in OOBE. We relax guards
-    2+3 ONLY when all three positives hold, and nothing else:
-      (a) the OS positively reports OOBE InProgress (Test-OobeInProgress), AND
-      (b) there is exactly ONE real user profile, AND
-      (c) that profile was created within $OobeProfileMaxAgeMinutes minutes.
-    Any miss keeps the original skip (SKIP-safe: we never install on uncertainty).
-
-.PARAMETER AgentDownloadUrl
-    URL to download the agent ZIP from. Defaults to the production blob; override only
-    for parallel lab/dev assignments that point at a separate pre-release ZIP.
-
-.PARAMETER VersionJsonName
-    Filename of the integrity manifest in the same blob container as the agent ZIP.
-    Defaults to "version.json"; override only for parallel lab/dev manifests.
-
-.PARAMETER MaxBootstrapWindowHours
-    Maximum device uptime (hours) within which the bootstrap is still considered
-    valid. Devices booted more than this many hours ago are skipped because we no
-    longer trust their OOBE state. Default: 12.
-
-.PARAMETER OobeProfileMaxAgeMinutes
-    Maximum age (minutes) of the single profile that may appear during OOBE for the
-    OOBE-relax exemption to apply. The restore->bootstrap gap is always minutes; an
-    older profile is treated as a productive device. Default: 15.
-
-.NOTES
-    - Agent is temporary and auto-removes after enrollment.
-    - All files live under C:\ProgramData\AutopilotMonitor (easy cleanup).
-    - One registry key remains after removal: HKLM\SOFTWARE\AutopilotMonitor\Deployed
-      (prevents ghost re-installs on re-Autopilot of the same device).
-    - Scheduled Task survives reboots during enrollment.
-    - OOBE detection uses Windows.System.Profile.SystemSetupInfo.OutOfBoxExperienceState.
-      Requires Windows 10, version 1809 (introduced in 10.0.17763.0). Older builds lack
-      the class -> Test-OobeInProgress returns $false -> original (skip) behaviour. Docs:
-      https://learn.microsoft.com/en-us/uwp/api/windows.system.profile.systemsetupinfo
-    - This script MUST remain pure ASCII (no Unicode/UTF-8 special chars).
-      PowerShell 5.1 (IME) reads scripts without BOM as ANSI, corrupting multi-byte chars.
-
-.CHANGELOG
-    2026-06-25  v2.1  OOBE-relax: detect genuine OOBE via WinRT
-                      SystemSetupInfo.OutOfBoxExperienceState and exempt guards 2+3 when a
-                      single freshly-created profile appears in OOBE (Windows Backup for
-                      Organizations). SKIP-safe when the API is absent (< 1809).
-                      Removed legacy Content-MD5 fallback; SHA-256 manifest verification is
-                      now mandatory (no hash -> bootstrap aborts, no unverified install).
-    2026-05-09  v2.0  Generic bootstrap: agent owns its own defaults (e.g. 600 s
-                      TenantId-wait), so the script only calls `--install` plain.
-                      Hardened post-install with a 10 s runtime-process verify.
-    2026-04-09  v1.1  Introduced explicit script version, logged on startup.
-    2026-03-31        Replaced OS age + MDM pre-flight checks with multi-signal guard
-                      (registry deployment marker, WMI/filesystem user profile, last
-                      logged-on user, 12 h bootstrap window).
-    2026-03-30        Fixed non-ASCII characters that broke parsing under PowerShell 5.1.
-    2026-03-29        Hardened integrity check: SHA-256 verification via version.json.
-    2026-02-13        Simplified bootstrapper, introduced --install parameter for agent.
-    2026-02-12        Robust download with integrity check (Content-MD5), boot time support,
-                      pre-flight check to skip if agent already installed.
-    2026-02-05        Initial version.
-#>
-
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory = $false)]
-    [string]$AgentDownloadUrl = "https://autopilotmonitor.blob.core.windows.net/agent/AutopilotMonitor-Agent.zip",
-
-    [Parameter(Mandatory = $false)]
-    [string]$VersionJsonName = "version.json",
-
-    [Parameter(Mandatory = $false)]
-    [int]$MaxBootstrapWindowHours = 12,
-
-    [Parameter(Mandatory = $false)]
-    [int]$OobeProfileMaxAgeMinutes = 15
-)
-
-# Script version (bump on meaningful changes; see .CHANGELOG above)
-$ScriptVersion = "2.1"
-
-# Configuration - Everything in ProgramData for easy cleanup
-$AgentBasePath = "$env:ProgramData\AutopilotMonitor"
-$AgentBinPath = "$AgentBasePath\Agent"
-$AgentLogPath = "$AgentBasePath\Logs"
-$LogFile = "$AgentLogPath\bootstrap_agent.log"
-
-New-Item -Path $AgentBasePath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-New-Item -Path $AgentBinPath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-New-Item -Path $AgentLogPath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-
-function Write-Log {
-    param([string]$Message)
-    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
-    $logMessage = "[$timestamp] $Message"
-    Write-Output $logMessage
-    Add-Content -Path $LogFile -Value $logMessage -ErrorAction SilentlyContinue
-}
-
-# Positive OOBE check via the documented WinRT API
-# Windows.System.Profile.SystemSetupInfo.OutOfBoxExperienceState.
-# Returns $true ONLY when the OS reports InProgress. Any other state (Completed/NotStarted),
-# an older OS without the class (< Win10 1809 / 10.0.17763.0), or any error returns $false
-# -> SKIP-safe (we never relax a guard on uncertainty).
-# Docs: https://learn.microsoft.com/en-us/uwp/api/windows.system.profile.systemsetupinfo
-function Test-OobeInProgress {
-    try {
-        $null = [Windows.System.Profile.SystemSetupInfo, Windows.System.Profile, ContentType = WindowsRuntime]
-        return ([Windows.System.Profile.SystemSetupInfo]::OutOfBoxExperienceState).ToString() -eq 'InProgress'
-    }
-    catch {
-        return $false
-    }
-}
-
-try {
-    Write-Log "===== Autopilot Monitor Bootstrap Started ====="
-    Write-Log "Bootstrap script version: v$ScriptVersion"
-
-    # Guard 1: Agent was already deployed on this device (registry marker survives self-destruct)
-    $deployed = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\AutopilotMonitor' -Name 'Deployed' -ErrorAction SilentlyContinue).Deployed
-    if ($deployed) {
-        Write-Log "SKIP: Agent was previously deployed at $deployed."
-        exit 0
-    }
-
-    # Collect real (non-special) user profiles as full paths (WMI Special flag + filesystem).
-    $excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users|WDAGUtilityAccount)$'
-
-    # NOTE: the outer @() is required. Without it the trailing Where/Select pipeline
-    # unwraps a single result back to a scalar string, so $profilePaths[0] would index
-    # into the string and return its first char ('C') instead of the full path.
-    $profilePaths = @(
-        @(
-            try {
-                Get-CimInstance Win32_UserProfile -ErrorAction Stop |
-                    Where-Object { -not $_.Special -and $_.LocalPath -like 'C:\Users\*' } |
-                    ForEach-Object { $_.LocalPath }
-            } catch { Write-Log "INFO: WMI profile query failed, continuing with filesystem check." }
-
-            (Get-ChildItem 'C:\Users' -Directory -ErrorAction SilentlyContinue).FullName
-        ) | Where-Object { $_ -and (Split-Path $_ -Leaf) -notmatch $excludePattern } |
-            Select-Object -Unique
-    )
-
-    # OOBE-relax: the ONLY exemption to guards 2+3. Matches exactly the Windows Backup for
-    # Organizations restore (one user signs in + restores DURING OOBE). All three must hold:
-    #   OOBE InProgress  AND  exactly one profile  AND  that profile created < N minutes ago.
-    $oobeRelax = $false
-    $oobeInProgress = Test-OobeInProgress
-    if ($profilePaths.Count -eq 1 -and $oobeInProgress) {
-        try {
-            $created = (Get-Item -LiteralPath $profilePaths[0] -Force -ErrorAction Stop).CreationTimeUtc
-            $ageMin = ((Get-Date).ToUniversalTime() - $created).TotalMinutes
-            if ($ageMin -ge 0 -and $ageMin -lt $OobeProfileMaxAgeMinutes) {
-                $oobeRelax = $true
-                Write-Log ("OOBE-relax active: OOBE InProgress + single profile created {0:N1}min ago (< {1}min). Guards 2+3 relaxed (Windows Backup restore case)." -f $ageMin, $OobeProfileMaxAgeMinutes)
-            } else {
-                Write-Log ("OOBE-relax NOT applied: OOBE InProgress + single profile '{0}', but profile created {1:N1}min ago (created {2:u}) is outside the [0, {3})min window." -f (Split-Path $profilePaths[0] -Leaf), $ageMin, $created, $OobeProfileMaxAgeMinutes)
-            }
-        } catch { Write-Log "INFO: profile age check failed; OOBE-relax not applied. $($_.Exception.Message)" }
-    } elseif ($profilePaths.Count -eq 1 -and -not $oobeInProgress) {
-        Write-Log "OOBE-relax NOT applied: single profile present but OutOfBoxExperienceState != InProgress (OOBE already finished / not detectable)."
-    } elseif ($profilePaths.Count -gt 1) {
-        Write-Log ("OOBE-relax NOT applied: {0} real profiles present (relax requires exactly one)." -f $profilePaths.Count)
-    }
-
-    # Guard 2: No real user profile should exist yet (primary productive-device guard),
-    # unless the OOBE-relax signature holds.
-    if ($profilePaths.Count -gt 0 -and -not $oobeRelax) {
-        $details = (($profilePaths | ForEach-Object {
-            $leaf = Split-Path $_ -Leaf
-            try {
-                $c = (Get-Item -LiteralPath $_ -Force -ErrorAction Stop).CreationTimeUtc
-                "{0} (created {1:u}, {2:N1}min ago)" -f $leaf, $c, ((Get-Date).ToUniversalTime() - $c).TotalMinutes
-            } catch { "$leaf (age unknown)" }
-        }) | Select-Object -First 3) -join '; '
-        Write-Log "SKIP: Real user profile(s) found ($details). OOBE InProgress=$oobeInProgress. Device appears productive."
-        exit 0
-    }
-
-    # Guard 3: LastLoggedOnUser - during Device ESP no real user has logged on yet
-    # (same OOBE-relax exemption: the restoring user signs in during OOBE).
-    $lastLoggedOnUser = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI' -Name 'LastLoggedOnUser' -EA SilentlyContinue).LastLoggedOnUser
-    if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and -not $oobeRelax) {
-        Write-Log "SKIP: LastLoggedOnUser found ($lastLoggedOnUser). Device appears productive."
-        exit 0
-    }
-
-    # Guard 4: Bootstrap window check - device uptime must be within accepted OOBE window.
-    # Sleep/standby does not reset uptime, only real boot/restart does.
-    $lastBoot = (Get-CimInstance Win32_OperatingSystem).LastBootUpTime
-    $uptimeHours = ((Get-Date) - $lastBoot).TotalHours
-    Write-Log "Device uptime: $([int]$uptimeHours)h (last boot: $lastBoot)"
-    if ($uptimeHours -gt $MaxBootstrapWindowHours) {
-        Write-Log "SKIP: Device uptime is $([int]$uptimeHours)h. OOBE state is older than accepted bootstrap window of ${MaxBootstrapWindowHours}h."
-        exit 0
-    }
-
-    # Guard 5: Is the agent already installed? (leftover from previous run)
-    if (Test-Path $AgentBinPath) {
-        $existingAgent = Get-ChildItem -Path $AgentBinPath -Filter "AutopilotMonitor.Agent.exe" -ErrorAction SilentlyContinue
-        if ($existingAgent) {
-            Write-Log "SKIP: Agent already installed at $($existingAgent.FullName)."
-            exit 0
-        }
-    }
-
-    Write-Log "Pre-flight checks passed -- no prior deployment, no productive-device signals, within bootstrap window (oobeRelax=$oobeRelax)"
-
-    # Download and extract agent binaries
-    $agentExePath = Join-Path $AgentBinPath "AutopilotMonitor.Agent.exe"
-
-    if (Test-Path $agentExePath) {
-        Write-Log "Agent already installed at $agentExePath"
-    }
-    else {
-        Write-Log "Downloading agent from $AgentDownloadUrl..."
-
-        try {
-            # Derive manifest URL from the agent download URL (same blob container)
-            $versionJsonUrl = $AgentDownloadUrl -replace '[^/]+$', $VersionJsonName
-            $expectedSha256 = $null
-            $manifestAttempts = 3
-            $manifestDelays = @(1, 2)   # short backoff between attempts; do not block enrollment
-
-            for ($attempt = 1; $attempt -le $manifestAttempts; $attempt++) {
-                try {
-                    Write-Log "Fetching $VersionJsonName (attempt ${attempt}/${manifestAttempts}) from $versionJsonUrl for integrity verification..."
-                    $versionJsonResponse = Invoke-RestMethod -Uri $versionJsonUrl -UseBasicParsing -TimeoutSec 5 -ErrorAction Stop
-                    if ($versionJsonResponse.sha256) {
-                        $expectedSha256 = $versionJsonResponse.sha256.ToLowerInvariant()
-                        Write-Log "SHA-256 hash from manifest: $expectedSha256 (version: $($versionJsonResponse.version))"
-                    } else {
-                        Write-Log "WARNING: Manifest has no sha256 field - integrity cannot be verified."
-                    }
-                    break   # manifest reached (with or without hash); retrying would not help
-                }
-                catch {
-                    Write-Log "WARNING: Could not fetch integrity manifest (attempt $attempt): $($_.Exception.Message)"
-                    if ($attempt -lt $manifestAttempts) {
-                        Start-Sleep -Seconds $manifestDelays[$attempt - 1]
-                    }
-                }
-            }
-
-            $zipPath = Join-Path $env:TEMP "AutopilotMonitor-Agent.zip"
-            $maxDownloadAttempts = 3
-            $downloadAttempt = 0
-
-            do {
-                $downloadAttempt++
-                try {
-                    Write-Log "Download attempt ${downloadAttempt}/${maxDownloadAttempts}"
-                    Invoke-WebRequest `
-                        -Uri $AgentDownloadUrl `
-                        -OutFile $zipPath `
-                        -UseBasicParsing `
-                        -TimeoutSec 30 `
-                        -ErrorAction Stop
-                    Write-Log "Downloaded agent to $zipPath"
-                    break
-                }
-                catch {
-                    if ($downloadAttempt -ge $maxDownloadAttempts) {
-                        throw
-                    }
-
-                    $retryDelaysInSeconds = @(2, 4, 8)
-                    $retryDelaySeconds = $retryDelaysInSeconds[$downloadAttempt - 1]
-                    Write-Log "Download failed (attempt $downloadAttempt): $($_.Exception.Message). Retrying in ${retryDelaySeconds}s..."
-                    Start-Sleep -Seconds $retryDelaySeconds
-                }
-            } while ($downloadAttempt -lt $maxDownloadAttempts)
-
-            # SHA-256 from the version manifest is the only accepted integrity proof.
-            # No hash -> refuse to install an unverified ZIP (SKIP-safe security posture).
-            if (-not $expectedSha256) {
-                throw "No SHA-256 hash available from manifest - refusing to install unverified agent ZIP."
-            }
-            $actualSha256 = (Get-FileHash $zipPath -Algorithm SHA256).Hash.ToLowerInvariant()
-            Write-Log "Validating SHA-256 hash against manifest"
-            if ($actualSha256 -ne $expectedSha256) {
-                throw "SHA-256 integrity check FAILED. Expected='$expectedSha256', Actual='$actualSha256'. Download may be tampered or corrupted."
-            }
-            Write-Log "SHA-256 integrity check passed"
-
-            Expand-Archive -Path $zipPath -DestinationPath $AgentBinPath -Force
-            Write-Log "Extracted agent to $AgentBinPath"
-
-            Remove-Item $zipPath -Force -ErrorAction SilentlyContinue
-            Write-Log "Cleaned up temporary files"
-
-            if (-not (Test-Path $agentExePath)) {
-                throw "Agent executable not found after extraction at $agentExePath"
-            }
-
-            Write-Log "Agent installation completed successfully"
-        }
-        catch {
-            Write-Log "ERROR downloading/extracting agent: $($_.Exception.Message)"
-            throw
-        }
-    }
-
-    Write-Log "Calling agent install mode (--install)..."
-    & $agentExePath --install
-    $installExitCode = $LASTEXITCODE
-    if ($installExitCode -ne 0) {
-        throw "Agent install failed with exit code $installExitCode"
-    }
-    Write-Log "Agent install mode completed successfully"
-
-    $runtimeProcessName = 'AutopilotMonitor.Agent'
-    $verifyTimeoutSec = 10
-    $verifyDeadline = (Get-Date).AddSeconds($verifyTimeoutSec)
-    $runtimeProc = $null
-    while ((Get-Date) -lt $verifyDeadline) {
-        $runtimeProc = Get-Process -Name $runtimeProcessName -ErrorAction SilentlyContinue | Select-Object -First 1
-        if ($null -ne $runtimeProc) { break }
-        Start-Sleep -Milliseconds 500
-    }
-    if ($null -ne $runtimeProc) {
-        $startedUtc = 'unavailable'
-        try { $startedUtc = $runtimeProc.StartTime.ToUniversalTime().ToString('o') } catch { }
-        Write-Log ("Runtime process verified: name={0}.exe pid={1} startedUtc={2}" -f $runtimeProcessName, $runtimeProc.Id, $startedUtc)
-    } else {
-        Write-Log ("WARNING: Runtime process verification FAILED. Agent --install reported success but no '{0}.exe' process appeared within {1}s. Likely silent block (AV/EDR, AppLocker/WDAC) of the runtime launch. Agent should still come up at next boot via the BootTrigger task. Check Event Viewer > Microsoft > Windows > TaskScheduler/Operational and AV/EDR logs for '{0}.exe'." -f $runtimeProcessName, $verifyTimeoutSec)
-    }
-
-    Write-Log "===== Bootstrap Completed Successfully ====="
-
-    exit 0
-}
-catch {
-    Write-Log "===== Bootstrap FAILED ====="
-    Write-Log "ERROR: $($_.Exception.Message)"
-    Write-Log "Stack trace: $($_.ScriptStackTrace)"
-    Write-Log "Please check log file: $LogFile"
-
-    $errMsg = "AutopilotMonitor bootstrap failed: $($_.Exception.Message)"
-    if ($errMsg.Length -gt 2048) { $errMsg = $errMsg.Substring(0, 1045) + '...' }
-    [Console]::Error.WriteLine($errMsg)
-
-    exit 1
-}

scripts/Bootstrap/Install-AutopilotMonitor.Tests.ps1

@@ -0,0 +1,307 @@
+# Pester tests (Pester 5+) for the bootstrap guard/relax logic in
+# Install-AutopilotMonitor.ps1.
+#
+# The script under test is dot-sourced; its entry guard prevents the bootstrap
+# from executing, so loading it here is side-effect free. External state (WMI,
+# registry, filesystem, WinRT) is mocked; profile directories are real folders
+# under Pester's $TestDrive with a manipulated CreationTimeUtc.
+#
+# Run under Windows PowerShell 5.1 to match the IME runtime:
+#   powershell.exe -NoProfile -Command "& { $c = New-PesterConfiguration; $c.Run.Path = 'scripts\Bootstrap'; $c.Output.Verbosity = 'Detailed'; Invoke-Pester -Configuration $c }"
+#
+# This file MUST remain pure ASCII (PS 5.1 reads BOM-less files as ANSI).
+
+BeforeAll {
+    . (Join-Path $PSScriptRoot 'Install-AutopilotMonitor.ps1')
+
+    function New-FakeProfile {
+        param([string]$Name, [double]$AgeMinutes)
+        $p = Join-Path $TestDrive $Name
+        New-Item -ItemType Directory -Path $p -Force | Out-Null
+        (Get-Item $p).CreationTimeUtc = (Get-Date).ToUniversalTime().AddMinutes(-$AgeMinutes)
+        return $p
+    }
+}
+
+Describe 'Test-IsCloudPc' {
+    # Local WMI on a Cloud PC is generic ('Virtual Machine'), so detection rests on
+    # the Windows365 registry key AND the CloudManagedDesktopExtension service
+    # (both required).
+    BeforeEach {
+        Mock Write-Log { }
+        Mock Get-CimInstance { [pscustomobject]@{ Manufacturer = 'Microsoft Corporation'; Model = 'Virtual Machine' } }
+    }
+
+    It 'detects a Cloud PC when both markers are present' {
+        Mock Test-Path { $true } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\Microsoft\Windows365' }
+        Mock Get-Service { [pscustomobject]@{ Name = 'CloudManagedDesktopExtension'; Status = 'Running' } }
+        Test-IsCloudPc | Should -BeTrue
+    }
+
+    It 'does not detect with the registry key alone (e.g. W365-Boot physical client)' {
+        Mock Test-Path { $true } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\Microsoft\Windows365' }
+        Mock Get-Service { $null }
+        Test-IsCloudPc | Should -BeFalse
+    }
+
+    It 'does not detect with the service alone' {
+        Mock Test-Path { $false } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\Microsoft\Windows365' }
+        Mock Get-Service { [pscustomobject]@{ Name = 'CloudManagedDesktopExtension'; Status = 'Running' } }
+        Test-IsCloudPc | Should -BeFalse
+    }
+
+    It 'does not detect a plain device (no markers)' {
+        Mock Test-Path { $false } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\Microsoft\Windows365' }
+        Mock Get-Service { $null }
+        Test-IsCloudPc | Should -BeFalse
+    }
+
+    It 'still evaluates markers when the WMI identity query fails' {
+        Mock Get-CimInstance { throw 'RPC server unavailable' }
+        Mock Test-Path { $true } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\Microsoft\Windows365' }
+        Mock Get-Service { [pscustomobject]@{ Name = 'CloudManagedDesktopExtension'; Status = 'Running' } }
+        Test-IsCloudPc | Should -BeTrue
+    }
+}
+
+Describe 'Get-OobeState' {
+    It 'returns a non-empty state string and never throws' {
+        Get-OobeState | Should -Not -BeNullOrEmpty
+    }
+}
+
+Describe 'Get-RealUserProfilePaths' {
+    BeforeEach {
+        Mock Write-Log { }
+    }
+
+    It 'merges WMI and filesystem views, drops special/system profiles, dedupes' {
+        Mock Get-CimInstance {
+            @(
+                [pscustomobject]@{ Special = $false; LocalPath = 'C:\Users\UserOne' }
+                [pscustomobject]@{ Special = $true; LocalPath = 'C:\Users\systemprofile' }
+                [pscustomobject]@{ Special = $false; LocalPath = 'D:\Profiles\Elsewhere' }
+            )
+        }
+        Mock Get-ChildItem {
+            @(
+                [pscustomobject]@{ FullName = 'C:\Users\UserOne' }
+                [pscustomobject]@{ FullName = 'C:\Users\Public' }
+                [pscustomobject]@{ FullName = 'C:\Users\defaultuser0' }
+                [pscustomobject]@{ FullName = 'C:\Users\WDAGUtilityAccount' }
+            )
+        }
+        $result = @(Get-RealUserProfilePaths)
+        $result | Should -Be @('C:\Users\UserOne')
+    }
+
+    It 'falls back to the filesystem view when the WMI query fails' {
+        Mock Get-CimInstance { throw 'WMI broken' }
+        Mock Get-ChildItem {
+            @(
+                [pscustomobject]@{ FullName = 'C:\Users\SomeUser' }
+                [pscustomobject]@{ FullName = 'C:\Users\Default' }
+            )
+        }
+        $result = @(Get-RealUserProfilePaths)
+        $result | Should -Be @('C:\Users\SomeUser')
+    }
+
+    It 'returns an empty result when only special/system profiles exist' {
+        Mock Get-CimInstance { @() }
+        Mock Get-ChildItem {
+            @(
+                [pscustomobject]@{ FullName = 'C:\Users\Public' }
+                [pscustomobject]@{ FullName = 'C:\Users\defaultuser1' }
+            )
+        }
+        @(Get-RealUserProfilePaths).Count | Should -Be 0
+    }
+}
+
+Describe 'Get-RelaxDecision' {
+    BeforeEach {
+        Mock Write-Log { }
+        # Defaults: physical device, OOBE long done. Individual tests override.
+        Mock Get-OobeState { 'Completed' }
+        Mock Test-IsCloudPc { $false }
+    }
+
+    Context 'Windows 365 Cloud PC' {
+        BeforeEach {
+            Mock Test-IsCloudPc { $true }
+        }
+
+        It 'relaxes for a single fresh profile although OOBE is Completed (first connect)' {
+            $p = New-FakeProfile 'CloudPcUser' 0.6
+            $d = Get-RelaxDecision -ProfilePaths @($p) -OobeProfileMaxAgeMinutes 15
+            $d.Active | Should -BeTrue
+            $d.IsCloudPc | Should -BeTrue
+        }
+
+        It 'does not relax for an old profile (productive Cloud PC)' {
+            $p = New-FakeProfile 'CloudPcUser' 30
+            (Get-RelaxDecision -ProfilePaths @($p) -OobeProfileMaxAgeMinutes 15).Active | Should -BeFalse
+        }
+
+        It 'does not relax for two profiles' {
+            $p1 = New-FakeProfile 'UserA' 2
+            $p2 = New-FakeProfile 'UserB' 400
+            (Get-RelaxDecision -ProfilePaths @($p1, $p2) -OobeProfileMaxAgeMinutes 15).Active | Should -BeFalse
+        }
+
+        It 'relaxes even when the WinRT OOBE API is unavailable (old build)' {
+            Mock Get-OobeState { 'Unavailable' }
+            $p = New-FakeProfile 'CpcUser' 1
+            (Get-RelaxDecision -ProfilePaths @($p) -OobeProfileMaxAgeMinutes 15).Active | Should -BeTrue
+        }
+
+        It 'does not relax for a profile with a future creation time (clock skew)' {
+            $p = New-FakeProfile 'SkewUser' -10
+            (Get-RelaxDecision -ProfilePaths @($p) -OobeProfileMaxAgeMinutes 15).Active | Should -BeFalse
+        }
+    }
+
+    Context 'OOBE InProgress (Windows Backup for Organizations)' {
+        It 'relaxes for a single fresh profile during OOBE' {
+            Mock Get-OobeState { 'InProgress' }
+            $p = New-FakeProfile 'RestoreUser' 3
+            $d = Get-RelaxDecision -ProfilePaths @($p) -OobeProfileMaxAgeMinutes 15
+            $d.Active | Should -BeTrue
+        }
+    }
+
+    Context 'no trigger' {
+        It 'does not relax on a physical device with a fresh profile and OOBE Completed' {
+            $p = New-FakeProfile 'SomeUser' 2
+            (Get-RelaxDecision -ProfilePaths @($p) -OobeProfileMaxAgeMinutes 15).Active | Should -BeFalse
+        }
+
+        It 'stays inactive with no profiles at all' {
+            (Get-RelaxDecision -ProfilePaths @() -OobeProfileMaxAgeMinutes 15).Active | Should -BeFalse
+        }
+    }
+}
+
+Describe 'Get-BootstrapDecision' {
+    BeforeEach {
+        Mock Write-Log { }
+        # Baseline: clean device during Device ESP -- no marker, no profiles, no
+        # logged-on user, 1h uptime, agent not installed. Tests override selectively.
+        Mock Get-ItemProperty { $null }
+        Mock Get-RealUserProfilePaths { @() }
+        Mock Get-OobeState { 'Completed' }
+        Mock Test-IsCloudPc { $false }
+        Mock Get-CimInstance { [pscustomobject]@{ LastBootUpTime = (Get-Date).AddHours(-1) } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+        $script:cleanAgentBin = Join-Path $TestDrive 'AgentBin'
+    }
+
+    It 'installs on a clean ESP device' {
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeTrue
+        $d.ReasonCode | Should -BeNullOrEmpty
+        $d.RelaxActive | Should -BeFalse
+    }
+
+    It 'skips when the Deployed marker exists (guard 1)' {
+        Mock Get-ItemProperty { [pscustomobject]@{ Deployed = '2026-08-01T10:00:00Z' } } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\AutopilotMonitor' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'AlreadyDeployed'
+    }
+
+    It 'skips a productive device with an old profile (guard 2)' {
+        $script:fakeProfile = New-FakeProfile 'OldUser' 5000
+        Mock Get-RealUserProfilePaths { @($script:fakeProfile) }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'ProfilesFound'
+    }
+
+    It 'installs on a freshly provisioned Cloud PC with one fresh profile' {
+        $script:fakeProfile = New-FakeProfile 'CloudPcUser' 0.6
+        Mock Get-RealUserProfilePaths { @($script:fakeProfile) }
+        Mock Test-IsCloudPc { $true }
+        # First-connect user is already visible in LogonUI on W365 -- must not block either.
+        Mock Get-ItemProperty { [pscustomobject]@{ LastLoggedOnUser = 'AzureAD\CloudPcUser' } } -ParameterFilter { $Path -like '*LogonUI*' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeTrue
+        $d.RelaxActive | Should -BeTrue
+    }
+
+    It 'skips when a real user has logged on and no relax applies (guard 3)' {
+        Mock Get-ItemProperty { [pscustomobject]@{ LastLoggedOnUser = 'AzureAD\SomeUser' } } -ParameterFilter { $Path -like '*LogonUI*' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'LastLoggedOnUser'
+    }
+
+    It 'does not skip for the defaultuser0 OOBE account (guard 3)' {
+        Mock Get-ItemProperty { [pscustomobject]@{ LastLoggedOnUser = 'defaultuser0' } } -ParameterFilter { $Path -like '*LogonUI*' }
+        (Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin).Install | Should -BeTrue
+    }
+
+    It 'skips when uptime exceeds the bootstrap window (guard 4)' {
+        Mock Get-CimInstance { [pscustomobject]@{ LastBootUpTime = (Get-Date).AddHours(-20) } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'UptimeExceeded'
+    }
+
+    It 'installs on a Cloud PC despite uptime over the window when the relax is active (guard 4 exemption)' {
+        # W365 reality: provisioned days ago, running headless ever since; the user's
+        # first connect just created the profile. Uptime is meaningless here.
+        $script:fakeProfile = New-FakeProfile 'FirstConnectUser' 0.6
+        Mock Get-RealUserProfilePaths { @($script:fakeProfile) }
+        Mock Test-IsCloudPc { $true }
+        Mock Get-CimInstance { [pscustomobject]@{ LastBootUpTime = (Get-Date).AddHours(-90) } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeTrue
+        $d.RelaxActive | Should -BeTrue
+    }
+
+    It 'still skips an over-uptime Cloud PC when the relax is NOT active (no fresh profile)' {
+        Mock Test-IsCloudPc { $true }
+        Mock Get-CimInstance { [pscustomobject]@{ LastBootUpTime = (Get-Date).AddHours(-90) } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'UptimeExceeded'
+    }
+
+    It 'keeps guard 4 for the OOBE-restore relax (physical device, uptime is meaningful)' {
+        $script:fakeProfile = New-FakeProfile 'RestoreUser' 3
+        Mock Get-RealUserProfilePaths { @($script:fakeProfile) }
+        Mock Get-OobeState { 'InProgress' }
+        Mock Get-CimInstance { [pscustomobject]@{ LastBootUpTime = (Get-Date).AddHours(-20) } } -ParameterFilter { $ClassName -eq 'Win32_OperatingSystem' }
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $script:cleanAgentBin
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'UptimeExceeded'
+    }
+
+    It 'skips when the agent binary is already present (guard 5)' {
+        $binPath = Join-Path $TestDrive 'AgentBinExisting'
+        New-Item -ItemType Directory -Path $binPath -Force | Out-Null
+        Set-Content -Path (Join-Path $binPath 'AutopilotMonitor.Agent.exe') -Value 'stub'
+        $d = Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath $binPath
+        $d.Install | Should -BeFalse
+        $d.ReasonCode | Should -Be 'AgentPresent'
+    }
+}
+
+Describe 'logging purity' {
+    # Regression guard: Write-Log runs inside functions that RETURN decision
+    # objects. If it ever emits to the output stream again (Write-Output), the
+    # log lines leak into the return values and turn them into arrays. This
+    # test deliberately does NOT mock Write-Log.
+    It 'Get-BootstrapDecision returns exactly one object with real logging' {
+        Mock Get-ItemProperty { [pscustomobject]@{ Deployed = '2026-08-01T10:00:00Z' } } -ParameterFilter { $Path -eq 'HKLM:\SOFTWARE\AutopilotMonitor' }
+        # Plain local assignment: PowerShell's dynamic scoping makes Write-Log
+        # (called from Get-BootstrapDecision) resolve this $LogFile instead of
+        # the ProgramData path defined by the dot-sourced script.
+        $LogFile = Join-Path $TestDrive 'bootstrap_test.log'
+        $d = @(Get-BootstrapDecision -MaxBootstrapWindowHours 12 -OobeProfileMaxAgeMinutes 15 -AgentBinPath (Join-Path $TestDrive 'NoAgent'))
+        $d.Count | Should -Be 1
+        $d[0].ReasonCode | Should -Be 'AlreadyDeployed'
+        Get-Content $LogFile -Raw | Should -Match 'SKIP: Agent was previously deployed'
+    }
+}

scripts/Bootstrap/Install-AutopilotMonitor.ps1

@@ -5,18 +5,42 @@
 .DESCRIPTION
     Designed to be deployed via Intune as a PowerShell Script during Autopilot.
     Runs very early in the enrollment process (first Intune action) and:
-      1. Runs five pre-flight guards to skip productive devices and ghost re-installs
+      1. Runs pre-flight guards to skip productive devices and ghost re-installs.
+         A relax exemption allows install when a single freshly-created profile
+         appears DURING OOBE (Windows Backup for Organizations restore) or on a
+         freshly provisioned Windows 365 Cloud PC.
       2. Downloads the monitoring agent ZIP from Azure Blob Storage
-      3. Verifies integrity via SHA-256 hash from the version manifest
-         (legacy fallback: Content-MD5 header from the blob response)
+      3. Verifies integrity via SHA-256 hash from the version manifest (mandatory)
       4. Extracts the agent into %ProgramData%\AutopilotMonitor\Agent
       5. Runs the agent in --install mode (registers Scheduled Task, spawns the runtime)
       6. Verifies the runtime process actually launched
     Agent self-destructs when enrollment completes.
 
+    Relax flow (guards 2+3): a real user profile (or a real LastLoggedOnUser)
+    normally means "productive -> skip". Two legitimate flows break that assumption:
+
+    (1) Windows Backup for Organizations: one user signs in + restores DURING OOBE.
+        Trigger: the OS positively reports OOBE InProgress.
+
+    (2) Windows 365 Cloud PC: W365 provisions headless -- OOBE and Intune enrollment
+        complete before any user ever connects, so OOBE is never InProgress when
+        this script runs. The assigned user's profile is created at first connect,
+        typically seconds before Intune pulls this script. Trigger: the device
+        positively identifies as a Cloud PC via TWO local markers (both required):
+        the HKLM\SOFTWARE\Microsoft\Windows365 registry key AND the
+        CloudManagedDesktopExtension service.
+
+    Either trigger relaxes guards 2+3 ONLY when additionally:
+      (a) there is exactly ONE real user profile, AND
+      (b) that profile was created within $OobeProfileMaxAgeMinutes minutes.
+    The Cloud PC trigger additionally exempts guard 4 (uptime window) -- see
+    .PARAMETER MaxBootstrapWindowHours. Any miss keeps the original skip
+    (SKIP-safe: we never install on uncertainty). On productive devices the
+    profile is old, so (b) keeps skipping correctly.
+
 .PARAMETER AgentDownloadUrl
-    URL to download the agent ZIP from. Defaults to the production blob; override only
-    for parallel lab/dev assignments that point at a separate pre-release ZIP.
+    URL to download the agent ZIP from. Defaults to the production download endpoint;
+    override only for parallel lab/dev assignments that point at a separate pre-release ZIP.
 
 .PARAMETER VersionJsonName
     Filename of the integrity manifest in the same blob container as the agent ZIP.
@@ -26,6 +50,14 @@
     Maximum device uptime (hours) within which the bootstrap is still considered
     valid. Devices booted more than this many hours ago are skipped because we no
     longer trust their OOBE state. Default: 12.
+    Not applied while the Cloud PC relax is active: a Cloud PC runs headless for
+    days between provisioning and the user's first connect, so the fresh-profile
+    window (OobeProfileMaxAgeMinutes) is the time anchor there, not boot uptime.
+
+.PARAMETER OobeProfileMaxAgeMinutes
+    Maximum age (minutes) of the single profile that may appear for the relax
+    exemption to apply. The restore/first-connect -> bootstrap gap is always
+    minutes; an older profile is treated as a productive device. Default: 15.
 
 .NOTES
     - Agent is temporary and auto-removes after enrollment.
@@ -33,10 +65,36 @@
     - One registry key remains after removal: HKLM\SOFTWARE\AutopilotMonitor\Deployed
       (prevents ghost re-installs on re-Autopilot of the same device).
     - Scheduled Task survives reboots during enrollment.
+    - OOBE detection uses Windows.System.Profile.SystemSetupInfo.OutOfBoxExperienceState.
+      Requires Windows 10, version 1809 (introduced in 10.0.17763.0). Older builds lack
+      the class -> state reads as 'Unavailable' -> original (skip) behaviour. Docs:
+      https://learn.microsoft.com/en-us/uwp/api/windows.system.profile.systemsetupinfo
+    - Guard/relax logic lives in functions; the script only executes when run
+      directly. Dot-sourcing it (as the Pester suite in
+      Install-AutopilotMonitor.Tests.ps1 does) loads the functions without side effects.
     - This script MUST remain pure ASCII (no Unicode/UTF-8 special chars).
       PowerShell 5.1 (IME) reads scripts without BOM as ANSI, corrupting multi-byte chars.
 
 .CHANGELOG
+    2026-08-08  v2.3  Windows 365 Cloud PC support: a positively identified Cloud PC
+                      (Windows365 registry key AND CloudManagedDesktopExtension
+                      service) now triggers the guard 2+3 relax alongside OOBE
+                      InProgress; the single-fresh-profile conditions are unchanged
+                      and guard 4 (uptime window) is exempted for Cloud PCs.
+                      Raw OOBE state and Cloud PC marker states are now logged.
+                      Guard/relax logic refactored into functions with a dot-source
+                      entry guard so the Pester suite can test it without executing
+                      the bootstrap; behaviour when run directly is unchanged.
+    2026-07-20  v2.2  Switched default download endpoint from the legacy blob
+                      (autopilotmonitor.blob.core.windows.net) to the Front Door alias
+                      https://download.autopilotmonitor.com/agent/ (route /agent/*).
+                      version.json is still derived from the same container.
+    2026-06-25  v2.1  OOBE-relax: detect genuine OOBE via WinRT
+                      SystemSetupInfo.OutOfBoxExperienceState and exempt guards 2+3 when a
+                      single freshly-created profile appears in OOBE (Windows Backup for
+                      Organizations). SKIP-safe when the API is absent (< 1809).
+                      Removed legacy Content-MD5 fallback; SHA-256 manifest verification is
+                      now mandatory (no hash -> bootstrap aborts, no unverified install).
     2026-05-09  v2.0  Generic bootstrap: agent owns its own defaults (e.g. 600 s
                       TenantId-wait), so the script only calls `--install` plain.
                       Hardened post-install with a 10 s runtime-process verify.
@@ -55,17 +113,20 @@
 [CmdletBinding()]
 param(
     [Parameter(Mandatory = $false)]
-    [string]$AgentDownloadUrl = "https://autopilotmonitor.blob.core.windows.net/agent/AutopilotMonitor-Agent.zip",
+    [string]$AgentDownloadUrl = "https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip",
 
     [Parameter(Mandatory = $false)]
     [string]$VersionJsonName = "version.json",
 
     [Parameter(Mandatory = $false)]
-    [int]$MaxBootstrapWindowHours = 12
+    [int]$MaxBootstrapWindowHours = 12,
+
+    [Parameter(Mandatory = $false)]
+    [int]$OobeProfileMaxAgeMinutes = 15
 )
 
 # Script version (bump on meaningful changes; see .CHANGELOG above)
-$ScriptVersion = "2.0"
+$ScriptVersion = "2.3"
 
 # Configuration - Everything in ProgramData for easy cleanup
 $AgentBasePath = "$env:ProgramData\AutopilotMonitor"
@@ -73,88 +134,185 @@ $AgentBinPath = "$AgentBasePath\Agent"
 $AgentLogPath = "$AgentBasePath\Logs"
 $LogFile = "$AgentLogPath\bootstrap_agent.log"
 
-New-Item -Path $AgentBasePath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-New-Item -Path $AgentBinPath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-New-Item -Path $AgentLogPath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
-
+# Write-Host (NOT Write-Output): log calls happen inside functions that return
+# decision objects; Write-Output would leak every log line into those return values.
 function Write-Log {
     param([string]$Message)
     $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
     $logMessage = "[$timestamp] $Message"
-    Write-Output $logMessage
+    Write-Host $logMessage
     Add-Content -Path $LogFile -Value $logMessage -ErrorAction SilentlyContinue
 }
 
-function Get-FileMd5Base64 {
-    param(
-        [Parameter(Mandatory = $true)]
-        [string]$Path
-    )
-
-    $md5 = [System.Security.Cryptography.MD5]::Create()
+# Raw OOBE state via the documented WinRT API
+# Windows.System.Profile.SystemSetupInfo.OutOfBoxExperienceState.
+# Returns the state string (InProgress/Completed/NotStarted). An older OS without the
+# class (< Win10 1809 / 10.0.17763.0) or any error returns 'Unavailable'
+# -> SKIP-safe (we never relax a guard on uncertainty).
+function Get-OobeState {
     try {
-        $stream = [System.IO.File]::OpenRead($Path)
-        try {
-            $hashBytes = $md5.ComputeHash($stream)
-        }
-        finally {
-            $stream.Dispose()
-        }
-
-        return [Convert]::ToBase64String($hashBytes)
+        $null = [Windows.System.Profile.SystemSetupInfo, Windows.System.Profile, ContentType = WindowsRuntime]
+        return ([Windows.System.Profile.SystemSetupInfo]::OutOfBoxExperienceState).ToString()
     }
-    finally {
-        $md5.Dispose()
+    catch {
+        return 'Unavailable'
     }
 }
 
-try {
-    Write-Log "===== Autopilot Monitor Bootstrap Started ====="
-    Write-Log "Bootstrap script version: v$ScriptVersion"
+# Positive Windows 365 Cloud PC detection. Local WMI/SMBIOS on a Cloud PC only
+# reports the generic Manufacturer='Microsoft Corporation' / Model='Virtual Machine',
+# so identification uses two W365-specific markers instead. BOTH are required (AND):
+# each alone has look-alikes (e.g. W365 Boot physical clients, other managed-desktop
+# agents). Identity and marker states are logged for diagnosis; any error returns
+# $false (SKIP-safe).
+function Test-IsCloudPc {
+    try {
+        $cs = Get-CimInstance Win32_ComputerSystem -ErrorAction Stop
+        Write-Log "Computer identity: Manufacturer='$($cs.Manufacturer)' Model='$($cs.Model)'."
+    }
+    catch { Write-Log "INFO: computer identity query failed: $($_.Exception.Message)" }
+
+    try {
+        $regMarker = Test-Path 'HKLM:\SOFTWARE\Microsoft\Windows365'
+        $svcMarker = $null -ne (Get-Service -Name 'CloudManagedDesktopExtension' -ErrorAction SilentlyContinue)
+        Write-Log "Cloud PC markers: Windows365 registry key=$regMarker; CloudManagedDesktopExtension service=$svcMarker."
+        return ($regMarker -and $svcMarker)
+    }
+    catch {
+        Write-Log "INFO: Cloud PC marker check failed: $($_.Exception.Message)"
+        return $false
+    }
+}
+
+# Collects real (non-special) user profiles as full paths (WMI Special flag + filesystem).
+# NOTE: callers MUST wrap the result in @(...). PowerShell unrolls function output, so an
+# empty result returns $null and a single path returns a scalar string, whose [0] indexer
+# would yield its first char ('C') instead of the full path.
+function Get-RealUserProfilePaths {
+    $excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users|WDAGUtilityAccount)$'
+    @(
+        try {
+            Get-CimInstance Win32_UserProfile -ErrorAction Stop |
+                Where-Object { -not $_.Special -and $_.LocalPath -like 'C:\Users\*' } |
+                ForEach-Object { $_.LocalPath }
+        } catch { Write-Log "INFO: WMI profile query failed, continuing with filesystem check." }
+
+        (Get-ChildItem 'C:\Users' -Directory -ErrorAction SilentlyContinue).FullName
+    ) | Where-Object { $_ -and (Split-Path $_ -Leaf) -notmatch $excludePattern } |
+        Select-Object -Unique
+}
+
+# Relax: the ONLY exemption to guards 2+3. Two triggers (see .DESCRIPTION):
+#   (1) OOBE InProgress          -> Windows Backup for Organizations restore
+#   (2) Cloud PC identity        -> Windows 365 (headless OOBE, profile at first connect)
+# Either trigger additionally requires: exactly one real profile AND that profile
+# created < $OobeProfileMaxAgeMinutes minutes ago. Any miss keeps the original skip.
+# Returns an object with: Active (bool), OobeState (string), IsCloudPc (bool).
+function Get-RelaxDecision {
+    param(
+        [string[]]$ProfilePaths,
+        [int]$OobeProfileMaxAgeMinutes
+    )
+    if ($null -eq $ProfilePaths) { $ProfilePaths = @() }
+
+    $relaxActive = $false
+    $oobeState = Get-OobeState
+    $oobeInProgress = ($oobeState -eq 'InProgress')
+    $isCloudPc = Test-IsCloudPc
+    if ($isCloudPc) {
+        Write-Log "Cloud PC detected (OOBE state: $oobeState)."
+    }
+
+    $relaxTrigger = $null
+    if ($oobeInProgress) {
+        $relaxTrigger = "OOBE InProgress (Windows Backup restore case)"
+    } elseif ($isCloudPc) {
+        $relaxTrigger = "Cloud PC (headless provisioning, OOBE state: $oobeState)"
+    }
+
+    if ($ProfilePaths.Count -eq 1 -and $relaxTrigger) {
+        try {
+            $created = (Get-Item -LiteralPath $ProfilePaths[0] -Force -ErrorAction Stop).CreationTimeUtc
+            $ageMin = ((Get-Date).ToUniversalTime() - $created).TotalMinutes
+            if ($ageMin -ge 0 -and $ageMin -lt $OobeProfileMaxAgeMinutes) {
+                $relaxActive = $true
+                Write-Log ("Relax active: {0} + single profile created {1:N1}min ago (< {2}min). Guards 2+3 relaxed." -f $relaxTrigger, $ageMin, $OobeProfileMaxAgeMinutes)
+            } else {
+                Write-Log ("Relax NOT applied: {0} + single profile '{1}', but profile created {2:N1}min ago (created {3:u}) is outside the [0, {4})min window." -f $relaxTrigger, (Split-Path $ProfilePaths[0] -Leaf), $ageMin, $created, $OobeProfileMaxAgeMinutes)
+            }
+        } catch { Write-Log "INFO: profile age check failed; relax not applied. $($_.Exception.Message)" }
+    } elseif ($ProfilePaths.Count -eq 1) {
+        Write-Log "Relax NOT applied: single profile present but neither OOBE InProgress nor Cloud PC (OOBE state: $oobeState)."
+    } elseif ($ProfilePaths.Count -gt 1) {
+        Write-Log ("Relax NOT applied: {0} real profiles present (relax requires exactly one). OOBE state: {1}; CloudPC: {2}." -f $ProfilePaths.Count, $oobeState, $isCloudPc)
+    }
+
+    return [pscustomobject]@{
+        Active    = $relaxActive
+        OobeState = $oobeState
+        IsCloudPc = $isCloudPc
+    }
+}
+
+# Runs pre-flight guards 1-5 and returns the install decision WITHOUT side effects
+# beyond logging. Returns an object with:
+#   Install (bool), ReasonCode (null | AlreadyDeployed | ProfilesFound |
+#   LastLoggedOnUser | UptimeExceeded | AgentPresent), RelaxActive (bool).
+function Get-BootstrapDecision {
+    param(
+        [int]$MaxBootstrapWindowHours,
+        [int]$OobeProfileMaxAgeMinutes,
+        [string]$AgentBinPath
+    )
 
     # Guard 1: Agent was already deployed on this device (registry marker survives self-destruct)
     $deployed = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\AutopilotMonitor' -Name 'Deployed' -ErrorAction SilentlyContinue).Deployed
     if ($deployed) {
         Write-Log "SKIP: Agent was previously deployed at $deployed."
-        exit 0
+        return [pscustomobject]@{ Install = $false; ReasonCode = 'AlreadyDeployed'; RelaxActive = $false }
     }
 
-    # Guard 2: No real user profile should exist yet (primary productive-device guard).
-    # Combines WMI (Win32_UserProfile.Special flag) and filesystem for maximum reliability.
-    $excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users)$'
+    # The @() wrap is required, see NOTE on Get-RealUserProfilePaths.
+    $profilePaths = @(Get-RealUserProfilePaths)
+    $relax = Get-RelaxDecision -ProfilePaths $profilePaths -OobeProfileMaxAgeMinutes $OobeProfileMaxAgeMinutes
 
-    $profileNames = @(
-        try {
-            Get-CimInstance Win32_UserProfile -ErrorAction Stop |
-                Where-Object { -not $_.Special -and $_.LocalPath -like 'C:\Users\*' } |
-                ForEach-Object { Split-Path $_.LocalPath -Leaf }
-        } catch { Write-Log "INFO: WMI profile query failed, continuing with filesystem check." }
-
-        (Get-ChildItem 'C:\Users' -Directory -ErrorAction SilentlyContinue).Name
-    ) | Where-Object { $_ -and $_ -notmatch $excludePattern } |
-        Select-Object -Unique
-
-    if ($profileNames) {
-        $names = ($profileNames | Select-Object -First 3) -join ', '
-        Write-Log "SKIP: Real user profile(s) found ($names). Device appears productive."
-        exit 0
+    # Guard 2: No real user profile should exist yet (primary productive-device guard),
+    # unless the relax signature holds.
+    if ($profilePaths.Count -gt 0 -and -not $relax.Active) {
+        $details = (($profilePaths | ForEach-Object {
+            $leaf = Split-Path $_ -Leaf
+            try {
+                $c = (Get-Item -LiteralPath $_ -Force -ErrorAction Stop).CreationTimeUtc
+                "{0} (created {1:u}, {2:N1}min ago)" -f $leaf, $c, ((Get-Date).ToUniversalTime() - $c).TotalMinutes
+            } catch { "$leaf (age unknown)" }
+        }) | Select-Object -First 3) -join '; '
+        Write-Log "SKIP: Real user profile(s) found ($details). OOBE state: $($relax.OobeState). CloudPC: $($relax.IsCloudPc). Device appears productive."
+        return [pscustomobject]@{ Install = $false; ReasonCode = 'ProfilesFound'; RelaxActive = $false }
     }
 
-    # Guard 3: LastLoggedOnUser - during Device ESP no real user has logged on yet.
+    # Guard 3: LastLoggedOnUser - during Device ESP no real user has logged on yet
+    # (same relax exemption: the restoring/first-connect user signs in legitimately).
     $lastLoggedOnUser = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI' -Name 'LastLoggedOnUser' -EA SilentlyContinue).LastLoggedOnUser
-    if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*') {
+    if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and -not $relax.Active) {
         Write-Log "SKIP: LastLoggedOnUser found ($lastLoggedOnUser). Device appears productive."
-        exit 0
+        return [pscustomobject]@{ Install = $false; ReasonCode = 'LastLoggedOnUser'; RelaxActive = $false }
     }
 
     # Guard 4: Bootstrap window check - device uptime must be within accepted OOBE window.
     # Sleep/standby does not reset uptime, only real boot/restart does.
+    # Exempted while the Cloud PC relax is active: a Cloud PC runs headless from
+    # provisioning until the user's first connect (often days), so boot uptime says
+    # nothing there -- the fresh-profile window of the relax is the time anchor.
     $lastBoot = (Get-CimInstance Win32_OperatingSystem).LastBootUpTime
     $uptimeHours = ((Get-Date) - $lastBoot).TotalHours
     Write-Log "Device uptime: $([int]$uptimeHours)h (last boot: $lastBoot)"
     if ($uptimeHours -gt $MaxBootstrapWindowHours) {
-        Write-Log "SKIP: Device uptime is $([int]$uptimeHours)h. OOBE state is older than accepted bootstrap window of ${MaxBootstrapWindowHours}h."
-        exit 0
+        if ($relax.Active -and $relax.IsCloudPc) {
+            Write-Log "Uptime $([int]$uptimeHours)h exceeds the ${MaxBootstrapWindowHours}h window, but the Cloud PC relax is active (fresh first-connect profile is the time anchor). Continuing."
+        } else {
+            Write-Log "SKIP: Device uptime is $([int]$uptimeHours)h. OOBE state is older than accepted bootstrap window of ${MaxBootstrapWindowHours}h."
+            return [pscustomobject]@{ Install = $false; ReasonCode = 'UptimeExceeded'; RelaxActive = $relax.Active }
+        }
     }
 
     # Guard 5: Is the agent already installed? (leftover from previous run)
@@ -162,151 +320,175 @@ try {
         $existingAgent = Get-ChildItem -Path $AgentBinPath -Filter "AutopilotMonitor.Agent.exe" -ErrorAction SilentlyContinue
         if ($existingAgent) {
             Write-Log "SKIP: Agent already installed at $($existingAgent.FullName)."
-            exit 0
+            return [pscustomobject]@{ Install = $false; ReasonCode = 'AgentPresent'; RelaxActive = $relax.Active }
         }
     }
 
-    Write-Log "Pre-flight checks passed -- no prior deployment, no real user profiles, no logged-on user, within bootstrap window"
+    return [pscustomobject]@{ Install = $true; ReasonCode = $null; RelaxActive = $relax.Active }
+}
 
-    # Download and extract agent binaries
-    $agentExePath = Join-Path $AgentBinPath "AutopilotMonitor.Agent.exe"
+# Main bootstrap flow. Only invoked when the script is run directly (see entry guard
+# at the bottom); never on dot-source.
+function Invoke-Bootstrap {
+    try {
+        New-Item -Path $AgentBasePath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
+        New-Item -Path $AgentBinPath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
+        New-Item -Path $AgentLogPath -ItemType Directory -Force -ErrorAction SilentlyContinue | Out-Null
 
-    if (Test-Path $agentExePath) {
-        Write-Log "Agent already installed at $agentExePath"
-    }
-    else {
-        Write-Log "Downloading agent from $AgentDownloadUrl..."
+        Write-Log "===== Autopilot Monitor Bootstrap Started ====="
+        Write-Log "Bootstrap script version: v$ScriptVersion"
 
-        try {
-            # Derive manifest URL from the agent download URL (same blob container)
-            $versionJsonUrl = $AgentDownloadUrl -replace '[^/]+$', $VersionJsonName
-            $expectedSha256 = $null
+        $decision = Get-BootstrapDecision -MaxBootstrapWindowHours $MaxBootstrapWindowHours -OobeProfileMaxAgeMinutes $OobeProfileMaxAgeMinutes -AgentBinPath $AgentBinPath
+        if (-not $decision.Install) {
+            exit 0
+        }
+
+        Write-Log "Pre-flight checks passed -- no prior deployment, no productive-device signals, within bootstrap window (relaxActive=$($decision.RelaxActive))"
+
+        # Download and extract agent binaries
+        $agentExePath = Join-Path $AgentBinPath "AutopilotMonitor.Agent.exe"
+
+        if (Test-Path $agentExePath) {
+            Write-Log "Agent already installed at $agentExePath"
+        }
+        else {
+            Write-Log "Downloading agent from $AgentDownloadUrl..."
 
             try {
-                Write-Log "Fetching $VersionJsonName from $versionJsonUrl for integrity verification..."
-                $versionJsonResponse = Invoke-RestMethod -Uri $versionJsonUrl -UseBasicParsing -TimeoutSec 5 -ErrorAction Stop
-                if ($versionJsonResponse.sha256) {
-                    $expectedSha256 = $versionJsonResponse.sha256.ToLowerInvariant()
-                    Write-Log "SHA-256 hash from manifest: $expectedSha256 (version: $($versionJsonResponse.version))"
-                } else {
-                    Write-Log "Manifest has no sha256 field - falling back to legacy MD5 check (older build)"
-                }
-            }
-            catch {
-                Write-Log "WARNING: Could not fetch manifest - falling back to legacy MD5 check: $($_.Exception.Message)"
-            }
+                # Derive manifest URL from the agent download URL (same blob container)
+                $versionJsonUrl = $AgentDownloadUrl -replace '[^/]+$', $VersionJsonName
+                $expectedSha256 = $null
+                $manifestAttempts = 3
+                $manifestDelays = @(1, 2)   # short backoff between attempts; do not block enrollment
 
-            $zipPath = Join-Path $env:TEMP "AutopilotMonitor-Agent.zip"
-            $maxDownloadAttempts = 3
-            $downloadAttempt = 0
-            $downloadResponse = $null
-
-            do {
-                $downloadAttempt++
-                try {
-                    Write-Log "Download attempt ${downloadAttempt}/${maxDownloadAttempts}"
-                    $downloadResponse = Invoke-WebRequest `
-                        -Uri $AgentDownloadUrl `
-                        -OutFile $zipPath `
-                        -UseBasicParsing `
-                        -TimeoutSec 30 `
-                        -ErrorAction Stop `
-                        -PassThru
-                    Write-Log "Downloaded agent to $zipPath"
-                    break
-                }
-                catch {
-                    if ($downloadAttempt -ge $maxDownloadAttempts) {
-                        throw
+                for ($attempt = 1; $attempt -le $manifestAttempts; $attempt++) {
+                    try {
+                        Write-Log "Fetching $VersionJsonName (attempt ${attempt}/${manifestAttempts}) from $versionJsonUrl for integrity verification..."
+                        $versionJsonResponse = Invoke-RestMethod -Uri $versionJsonUrl -UseBasicParsing -TimeoutSec 5 -ErrorAction Stop
+                        if ($versionJsonResponse.sha256) {
+                            $expectedSha256 = $versionJsonResponse.sha256.ToLowerInvariant()
+                            Write-Log "SHA-256 hash from manifest: $expectedSha256 (version: $($versionJsonResponse.version))"
+                        } else {
+                            Write-Log "WARNING: Manifest has no sha256 field - integrity cannot be verified."
+                        }
+                        break   # manifest reached (with or without hash); retrying would not help
+                    }
+                    catch {
+                        Write-Log "WARNING: Could not fetch integrity manifest (attempt $attempt): $($_.Exception.Message)"
+                        if ($attempt -lt $manifestAttempts) {
+                            Start-Sleep -Seconds $manifestDelays[$attempt - 1]
+                        }
                     }
-
-                    $retryDelaysInSeconds = @(2, 4, 8)
-                    $retryDelaySeconds = $retryDelaysInSeconds[$downloadAttempt - 1]
-                    Write-Log "Download failed (attempt $downloadAttempt): $($_.Exception.Message). Retrying in ${retryDelaySeconds}s..."
-                    Start-Sleep -Seconds $retryDelaySeconds
                 }
-            } while ($downloadAttempt -lt $maxDownloadAttempts)
 
-            if ($expectedSha256) {
+                $zipPath = Join-Path $env:TEMP "AutopilotMonitor-Agent.zip"
+                $maxDownloadAttempts = 3
+                $downloadAttempt = 0
+
+                do {
+                    $downloadAttempt++
+                    try {
+                        Write-Log "Download attempt ${downloadAttempt}/${maxDownloadAttempts}"
+                        $downloadStopwatch = [System.Diagnostics.Stopwatch]::StartNew()
+                        Invoke-WebRequest `
+                            -Uri $AgentDownloadUrl `
+                            -OutFile $zipPath `
+                            -UseBasicParsing `
+                            -TimeoutSec 30 `
+                            -ErrorAction Stop
+                        $downloadStopwatch.Stop()
+                        $downloadSeconds = [math]::Round($downloadStopwatch.Elapsed.TotalSeconds, 1)
+                        Write-Log "Downloaded agent to $zipPath (took ${downloadSeconds}s)"
+                        break
+                    }
+                    catch {
+                        if ($downloadAttempt -ge $maxDownloadAttempts) {
+                            throw
+                        }
+
+                        $retryDelaysInSeconds = @(2, 4, 8)
+                        $retryDelaySeconds = $retryDelaysInSeconds[$downloadAttempt - 1]
+                        Write-Log "Download failed (attempt $downloadAttempt): $($_.Exception.Message). Retrying in ${retryDelaySeconds}s..."
+                        Start-Sleep -Seconds $retryDelaySeconds
+                    }
+                } while ($downloadAttempt -lt $maxDownloadAttempts)
+
+                # SHA-256 from the version manifest is the only accepted integrity proof.
+                # No hash -> refuse to install an unverified ZIP (SKIP-safe security posture).
+                if (-not $expectedSha256) {
+                    throw "No SHA-256 hash available from manifest - refusing to install unverified agent ZIP."
+                }
                 $actualSha256 = (Get-FileHash $zipPath -Algorithm SHA256).Hash.ToLowerInvariant()
                 Write-Log "Validating SHA-256 hash against manifest"
                 if ($actualSha256 -ne $expectedSha256) {
                     throw "SHA-256 integrity check FAILED. Expected='$expectedSha256', Actual='$actualSha256'. Download may be tampered or corrupted."
                 }
                 Write-Log "SHA-256 integrity check passed"
-            }
-            else {
-                $expectedMd5Header = $downloadResponse.Headers["Content-MD5"]
-                $expectedMd5 = if ($expectedMd5Header -is [System.Array]) { "$($expectedMd5Header[0])".Trim() } else { "$expectedMd5Header".Trim() }
-                if ($expectedMd5 -notmatch '\S') {
-                    Write-Log "WARNING: No SHA-256 and no Content-MD5 header - skipping integrity validation"
-                }
-                else {
-                    $actualMd5 = Get-FileMd5Base64 -Path $zipPath
-                    Write-Log "Validating Content-MD5 header against downloaded ZIP"
-                    if ($actualMd5 -ne $expectedMd5) {
-                        throw "MD5 integrity check failed. Expected (Content-MD5)='$expectedMd5', Actual='$actualMd5'"
-                    }
-                    Write-Log "MD5 integrity check passed"
+
+                Expand-Archive -Path $zipPath -DestinationPath $AgentBinPath -Force
+                Write-Log "Extracted agent to $AgentBinPath"
+
+                Remove-Item $zipPath -Force -ErrorAction SilentlyContinue
+                Write-Log "Cleaned up temporary files"
+
+                if (-not (Test-Path $agentExePath)) {
+                    throw "Agent executable not found after extraction at $agentExePath"
                 }
+
+                Write-Log "Agent installation completed successfully"
             }
-
-            Expand-Archive -Path $zipPath -DestinationPath $AgentBinPath -Force
-            Write-Log "Extracted agent to $AgentBinPath"
-
-            Remove-Item $zipPath -Force -ErrorAction SilentlyContinue
-            Write-Log "Cleaned up temporary files"
-
-            if (-not (Test-Path $agentExePath)) {
-                throw "Agent executable not found after extraction at $agentExePath"
+            catch {
+                Write-Log "ERROR downloading/extracting agent: $($_.Exception.Message)"
+                throw
             }
-
-            Write-Log "Agent installation completed successfully"
         }
-        catch {
-            Write-Log "ERROR downloading/extracting agent: $($_.Exception.Message)"
-            throw
+
+        Write-Log "Calling agent install mode (--install)..."
+        & $agentExePath --install
+        $installExitCode = $LASTEXITCODE
+        if ($installExitCode -ne 0) {
+            throw "Agent install failed with exit code $installExitCode"
         }
-    }
+        Write-Log "Agent install mode completed successfully"
 
-    Write-Log "Calling agent install mode (--install)..."
-    & $agentExePath --install
-    $installExitCode = $LASTEXITCODE
-    if ($installExitCode -ne 0) {
-        throw "Agent install failed with exit code $installExitCode"
-    }
-    Write-Log "Agent install mode completed successfully"
+        $runtimeProcessName = 'AutopilotMonitor.Agent'
+        $verifyTimeoutSec = 10
+        $verifyDeadline = (Get-Date).AddSeconds($verifyTimeoutSec)
+        $runtimeProc = $null
+        while ((Get-Date) -lt $verifyDeadline) {
+            $runtimeProc = Get-Process -Name $runtimeProcessName -ErrorAction SilentlyContinue | Select-Object -First 1
+            if ($null -ne $runtimeProc) { break }
+            Start-Sleep -Milliseconds 500
+        }
+        if ($null -ne $runtimeProc) {
+            $startedUtc = 'unavailable'
+            try { $startedUtc = $runtimeProc.StartTime.ToUniversalTime().ToString('o') } catch { }
+            Write-Log ("Runtime process verified: name={0}.exe pid={1} startedUtc={2}" -f $runtimeProcessName, $runtimeProc.Id, $startedUtc)
+        } else {
+            Write-Log ("WARNING: Runtime process verification FAILED. Agent --install reported success but no '{0}.exe' process appeared within {1}s. Likely silent block (AV/EDR, AppLocker/WDAC) of the runtime launch. Agent should still come up at next boot via the BootTrigger task. Check Event Viewer > Microsoft > Windows > TaskScheduler/Operational and AV/EDR logs for '{0}.exe'." -f $runtimeProcessName, $verifyTimeoutSec)
+        }
 
-    $runtimeProcessName = 'AutopilotMonitor.Agent'
-    $verifyTimeoutSec = 10
-    $verifyDeadline = (Get-Date).AddSeconds($verifyTimeoutSec)
-    $runtimeProc = $null
-    while ((Get-Date) -lt $verifyDeadline) {
-        $runtimeProc = Get-Process -Name $runtimeProcessName -ErrorAction SilentlyContinue | Select-Object -First 1
-        if ($null -ne $runtimeProc) { break }
-        Start-Sleep -Milliseconds 500
-    }
-    if ($null -ne $runtimeProc) {
-        $startedUtc = 'unavailable'
-        try { $startedUtc = $runtimeProc.StartTime.ToUniversalTime().ToString('o') } catch { }
-        Write-Log ("Runtime process verified: name={0}.exe pid={1} startedUtc={2}" -f $runtimeProcessName, $runtimeProc.Id, $startedUtc)
-    } else {
-        Write-Log ("WARNING: Runtime process verification FAILED. Agent --install reported success but no '{0}.exe' process appeared within {1}s. Likely silent block (AV/EDR, AppLocker/WDAC) of the runtime launch. Agent should still come up at next boot via the BootTrigger task. Check Event Viewer > Microsoft > Windows > TaskScheduler/Operational and AV/EDR logs for '{0}.exe'." -f $runtimeProcessName, $verifyTimeoutSec)
-    }
+        Write-Log "===== Bootstrap Completed Successfully ====="
 
-    Write-Log "===== Bootstrap Completed Successfully ====="
+        exit 0
+    }
+    catch {
+        Write-Log "===== Bootstrap FAILED ====="
+        Write-Log "ERROR: $($_.Exception.Message)"
+        Write-Log "Stack trace: $($_.ScriptStackTrace)"
+        Write-Log "Please check log file: $LogFile"
 
-    exit 0
+        $errMsg = "AutopilotMonitor bootstrap failed: $($_.Exception.Message)"
+        if ($errMsg.Length -gt 2048) { $errMsg = $errMsg.Substring(0, 1045) + '...' }
+        [Console]::Error.WriteLine($errMsg)
+
+        exit 1
+    }
 }
-catch {
-    Write-Log "===== Bootstrap FAILED ====="
-    Write-Log "ERROR: $($_.Exception.Message)"
-    Write-Log "Stack trace: $($_.ScriptStackTrace)"
-    Write-Log "Please check log file: $LogFile"
 
-    $errMsg = "AutopilotMonitor bootstrap failed: $($_.Exception.Message)"
-    if ($errMsg.Length -gt 2048) { $errMsg = $errMsg.Substring(0, 1045) + '...' }
-    [Console]::Error.WriteLine($errMsg)
-
-    exit 1
+# Entry guard: execute only when run as a script (IME, console). Dot-sourcing
+# (". .\Install-AutopilotMonitor.ps1", as the Pester suite does) only loads
+# the functions above and MUST stay side-effect free.
+if ($MyInvocation.InvocationName -ne '.') {
+    Invoke-Bootstrap
 }

scripts/Bootstrap/Test-ShouldBootstrapAgent-dev.ps1

@@ -1,213 +0,0 @@
-# Autopilot Monitor Bootstrap Guard Test (DEV)
-# Dry-run only: does not exit, does not install, only reports what WOULD happen.
-# Mirrors Install-AutopilotMonitor-dev.ps1 incl. the OOBE-relax exemption for the
-# "Windows Backup for Organizations" restore case (guards 2+3).
-
-param(
-    [string]$AgentBinPath = 'C:\ProgramData\AutopilotMonitor\Agent',
-    [int]$OobeProfileMaxAgeMinutes = 15
-)
-
-$ErrorActionPreference = 'SilentlyContinue'
-
-function Write-Step {
-    param(
-        [string]$Status,
-        [string]$Message
-    )
-
-    $prefix = switch ($Status) {
-        'PASS' { '[PASS]' }
-        'SKIP' { '[SKIP]' }
-        'WARN' { '[WARN]' }
-        'INFO' { '[INFO]' }
-        default { '[....]' }
-    }
-
-    Write-Host "$prefix $Message"
-}
-
-function Get-RegistryValueSafe {
-    param(
-        [string]$Path,
-        [string]$Name
-    )
-
-    try {
-        return (Get-ItemProperty -Path $Path -Name $Name -ErrorAction Stop).$Name
-    }
-    catch {
-        return $null
-    }
-}
-
-# Positive OOBE check via WinRT Windows.System.Profile.SystemSetupInfo.OutOfBoxExperienceState.
-# Requires Windows 10, version 1809 (10.0.17763.0). Older builds / errors -> $false (SKIP-safe).
-# Docs: https://learn.microsoft.com/en-us/uwp/api/windows.system.profile.systemsetupinfo
-function Test-OobeInProgress {
-    try {
-        $null = [Windows.System.Profile.SystemSetupInfo, Windows.System.Profile, ContentType = WindowsRuntime]
-        return ([Windows.System.Profile.SystemSetupInfo]::OutOfBoxExperienceState).ToString() -eq 'InProgress'
-    }
-    catch {
-        return $false
-    }
-}
-
-$AgentExePath = Join-Path $AgentBinPath 'AutopilotMonitor.Agent.exe'
-$MaxBootstrapWindowHours = 12
-
-$wouldInstall = $true
-$reasons = New-Object System.Collections.Generic.List[string]
-
-Write-Host ''
-Write-Host '=== Autopilot Monitor Bootstrap Guard Test (Dry Run, DEV) ==='
-Write-Host ''
-
-# Guard 1: Agent was already deployed on this device (survives self-destruct)
-$deployed = Get-RegistryValueSafe -Path 'HKLM:\SOFTWARE\AutopilotMonitor' -Name 'Deployed'
-if ($deployed) {
-    Write-Step -Status 'SKIP' -Message "Guard 1: Agent was previously deployed at '$deployed'."
-    $wouldInstall = $false
-    $reasons.Add("Previously deployed marker exists: $deployed")
-} else {
-    Write-Step -Status 'PASS' -Message 'Guard 1: No previous deployment marker found.'
-}
-
-# Collect real (non-special) user profiles as full paths (combined WMI/filesystem view).
-$excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users|WDAGUtilityAccount)$'
-$wmiProfileQueryFailed = $false
-
-# NOTE: the outer @() is required. Without it the trailing Where/Select pipeline
-# unwraps a single result back to a scalar string, so $profilePaths[0] would index
-# into the string and return its first char ('C') instead of the full path.
-$profilePaths = @(
-    @(
-        try {
-            Get-CimInstance Win32_UserProfile -ErrorAction Stop |
-                Where-Object { -not $_.Special -and $_.LocalPath -like 'C:\Users\*' } |
-                ForEach-Object { $_.LocalPath }
-        }
-        catch {
-            $wmiProfileQueryFailed = $true
-        }
-
-        (Get-ChildItem 'C:\Users' -Directory -ErrorAction SilentlyContinue).FullName
-    ) |
-    Where-Object { $_ -and (Split-Path $_ -Leaf) -notmatch $excludePattern } |
-    Select-Object -Unique
-)
-
-if ($wmiProfileQueryFailed) {
-    Write-Step -Status 'WARN' -Message 'Profiles: WMI query failed, filesystem check still applied.'
-}
-
-$profileNames = $profilePaths | ForEach-Object { Split-Path $_ -Leaf }
-
-# OOBE-relax: the ONLY exemption to guards 2+3. Matches exactly the Windows Backup for
-# Organizations restore: OOBE InProgress AND exactly one profile AND that profile fresh.
-$oobeInProgress = Test-OobeInProgress
-$profileAgeMin = $null
-$oobeRelax = $false
-if ($profilePaths.Count -eq 1) {
-    try {
-        $created = (Get-Item -LiteralPath $profilePaths[0] -Force -ErrorAction Stop).CreationTimeUtc
-        $profileAgeMin = [math]::Round(((Get-Date).ToUniversalTime() - $created).TotalMinutes, 1)
-    } catch { }
-    if ($oobeInProgress -and $null -ne $profileAgeMin -and $profileAgeMin -ge 0 -and $profileAgeMin -lt $OobeProfileMaxAgeMinutes) {
-        $oobeRelax = $true
-    }
-}
-
-Write-Step -Status 'INFO' -Message "OOBE: OutOfBoxExperienceState InProgress = $oobeInProgress ; profileCount = $($profilePaths.Count) ; singleProfileAgeMin = $profileAgeMin ; OOBE-relax = $oobeRelax"
-
-# Guard 2: No real user profile should exist yet (unless OOBE-relax holds)
-if ($profilePaths.Count -gt 0 -and -not $oobeRelax) {
-    $names = ($profileNames | Select-Object -First 3) -join ', '
-    Write-Step -Status 'SKIP' -Message "Guard 2: Real user profile(s) found ($names). Device appears productive."
-    $wouldInstall = $false
-    $reasons.Add("Real user profile(s) found: $names")
-} elseif ($profilePaths.Count -gt 0 -and $oobeRelax) {
-    $names = ($profileNames | Select-Object -First 3) -join ', '
-    Write-Step -Status 'PASS' -Message "Guard 2: Profile ($names) present but OOBE-relax active (single fresh profile in OOBE) -- not blocking."
-} else {
-    Write-Step -Status 'PASS' -Message 'Guard 2: No real user profiles found (combined WMI/filesystem view).'
-}
-
-# Guard 3: LastLoggedOnUser (unless OOBE-relax holds)
-$lastLoggedOnUser = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI' -Name 'LastLoggedOnUser' -EA SilentlyContinue).LastLoggedOnUser
-if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and -not $oobeRelax) {
-    Write-Step -Status 'SKIP' -Message "Guard 3: LastLoggedOnUser found ($lastLoggedOnUser). Device appears productive."
-    $wouldInstall = $false
-    $reasons.Add("LastLoggedOnUser found: $lastLoggedOnUser")
-} elseif ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and $oobeRelax) {
-    Write-Step -Status 'PASS' -Message "Guard 3: LastLoggedOnUser ($lastLoggedOnUser) present but OOBE-relax active -- not blocking."
-} else {
-    Write-Step -Status 'PASS' -Message "Guard 3: No real LastLoggedOnUser (value: '$lastLoggedOnUser')."
-}
-
-# Guard 4: Bootstrap window check (sleep/standby does NOT reset uptime, only real boot does)
-$lastBoot = $null
-$uptimeHours = $null
-
-try {
-    $lastBoot = (Get-CimInstance Win32_OperatingSystem -ErrorAction Stop).LastBootUpTime
-    $uptimeHours = ((Get-Date) - $lastBoot).TotalHours
-
-    if ($uptimeHours -gt $MaxBootstrapWindowHours) {
-        Write-Step -Status 'SKIP' -Message "Guard 4: Device uptime is $([int]$uptimeHours)h. Older than accepted bootstrap window of ${MaxBootstrapWindowHours}h."
-        $wouldInstall = $false
-        $reasons.Add("Uptime exceeds bootstrap window: $([int]$uptimeHours)h > ${MaxBootstrapWindowHours}h")
-    } else {
-        Write-Step -Status 'PASS' -Message "Guard 4: Device uptime is $([int]$uptimeHours)h and within bootstrap window of ${MaxBootstrapWindowHours}h."
-    }
-}
-catch {
-    Write-Step -Status 'WARN' -Message 'Guard 4: Could not determine LastBootUpTime / uptime.'
-}
-
-# Guard 5: Agent binary already present
-if (Test-Path $AgentExePath) {
-    Write-Step -Status 'SKIP' -Message "Guard 5: Agent already installed at '$AgentExePath'."
-    $wouldInstall = $false
-    $reasons.Add("Agent binary already present: $AgentExePath")
-} else {
-    Write-Step -Status 'PASS' -Message "Guard 5: Agent binary not present at '$AgentExePath'."
-}
-
-Write-Host ''
-Write-Host '=== Result ==='
-Write-Host ''
-
-if ($wouldInstall) {
-    Write-Host '[DECISION] WOULD INSTALL agent on this device.'
-} else {
-    Write-Host '[DECISION] WOULD SKIP agent installation on this device.'
-}
-
-Write-Host ''
-Write-Host '=== Summary ==='
-
-if ($reasons.Count -eq 0) {
-    Write-Host 'No blocking reasons found.'
-} else {
-    foreach ($reason in $reasons) {
-        Write-Host " - $reason"
-    }
-}
-
-Write-Host ''
-Write-Host '=== Raw Values ==='
-Write-Host "Deployed marker           : $deployed"
-Write-Host "DetectedProfileNames      : $($profileNames -join ', ')"
-Write-Host "ProfileCount              : $($profilePaths.Count)"
-Write-Host "OobeInProgress (WinRT)    : $oobeInProgress"
-Write-Host "SingleProfileAgeMinutes   : $profileAgeMin"
-Write-Host "OobeProfileMaxAgeMinutes  : $OobeProfileMaxAgeMinutes"
-Write-Host "OobeRelaxActive           : $oobeRelax"
-Write-Host "LastLoggedOnUser          : $lastLoggedOnUser"
-Write-Host "MaxBootstrapWindowHours   : $MaxBootstrapWindowHours"
-Write-Host "LastBootUpTime            : $lastBoot"
-Write-Host "UptimeHours               : $([string]$uptimeHours)"
-Write-Host "AgentExePath              : $AgentExePath"
-Write-Host ''

scripts/Bootstrap/Test-ShouldBootstrapAgent.ps1

@@ -1,8 +1,13 @@
 # Autopilot Monitor Bootstrap Guard Test
 # Dry-run only: does not exit, does not install, only reports what WOULD happen.
+# Mirrors Install-AutopilotMonitor.ps1 (v2.3) incl. the relax exemption for
+# guards 2+3, triggered by "Windows Backup for Organizations" (OOBE InProgress)
+# or a positively identified Windows 365 Cloud PC, and the guard 4 (uptime)
+# exemption while the Cloud PC relax is active.
 
 param(
-    [string]$AgentBinPath = 'C:\ProgramData\AutopilotMonitor\Agent'
+    [string]$AgentBinPath = 'C:\ProgramData\AutopilotMonitor\Agent',
+    [int]$OobeProfileMaxAgeMinutes = 15
 )
 
 $ErrorActionPreference = 'SilentlyContinue'
@@ -38,6 +43,25 @@ function Get-RegistryValueSafe {
     }
 }
 
+# Positive OOBE check via WinRT Windows.System.Profile.SystemSetupInfo.OutOfBoxExperienceState.
+# Requires Windows 10, version 1809 (10.0.17763.0). Older builds / errors -> $false (SKIP-safe).
+# Docs: https://learn.microsoft.com/en-us/uwp/api/windows.system.profile.systemsetupinfo
+function Test-OobeInProgress {
+    try {
+        $null = [Windows.System.Profile.SystemSetupInfo, Windows.System.Profile, ContentType = WindowsRuntime]
+        return ([Windows.System.Profile.SystemSetupInfo]::OutOfBoxExperienceState).ToString() -eq 'InProgress'
+    }
+    catch {
+        return $false
+    }
+}
+
+# Positive Windows 365 Cloud PC detection: two local markers, BOTH required (AND),
+# because each alone has look-alikes. Mirrors Test-IsCloudPc in the bootstrapper.
+$cloudPcRegMarker = Test-Path 'HKLM:\SOFTWARE\Microsoft\Windows365'
+$cloudPcSvcMarker = $null -ne (Get-Service -Name 'CloudManagedDesktopExtension' -ErrorAction SilentlyContinue)
+$isCloudPc = ($cloudPcRegMarker -and $cloudPcSvcMarker)
+
 $AgentExePath = Join-Path $AgentBinPath 'AutopilotMonitor.Agent.exe'
 $MaxBootstrapWindowHours = 12
 
@@ -58,63 +82,82 @@ if ($deployed) {
     Write-Step -Status 'PASS' -Message 'Guard 1: No previous deployment marker found.'
 }
 
-# Guard 2: No real user profile should exist yet (primary productive-device guard)
-# NOTE: OOBEInProgress is NOT used -- it is unreliable (observed =0 during active enrollment).
-$excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users)$'
+# Collect real (non-special) user profiles as full paths (combined WMI/filesystem view).
+$excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users|WDAGUtilityAccount)$'
 $wmiProfileQueryFailed = $false
 
-$profileNames = @(
-    # WMI/CIM view -- Special flag reliably excludes SYSTEM/LocalService/NetworkService
-    try {
-        Get-CimInstance Win32_UserProfile -ErrorAction Stop |
-            Where-Object {
-                -not $_.Special -and
-                $_.LocalPath -like 'C:\Users\*'
-            } |
-            ForEach-Object {
-                Split-Path $_.LocalPath -Leaf
-            }
-    }
-    catch {
-        $wmiProfileQueryFailed = $true
-    }
+# NOTE: the outer @() is required. Without it the trailing Where/Select pipeline
+# unwraps a single result back to a scalar string, so $profilePaths[0] would index
+# into the string and return its first char ('C') instead of the full path.
+$profilePaths = @(
+    @(
+        try {
+            Get-CimInstance Win32_UserProfile -ErrorAction Stop |
+                Where-Object { -not $_.Special -and $_.LocalPath -like 'C:\Users\*' } |
+                ForEach-Object { $_.LocalPath }
+        }
+        catch {
+            $wmiProfileQueryFailed = $true
+        }
 
-    # Filesystem view -- catches profiles WMI might miss
-    (Get-ChildItem 'C:\Users' -Directory -ErrorAction SilentlyContinue).Name
-) |
-Where-Object {
-    $_ -and $_ -notmatch $excludePattern
-} |
-Select-Object -Unique
+        (Get-ChildItem 'C:\Users' -Directory -ErrorAction SilentlyContinue).FullName
+    ) |
+    Where-Object { $_ -and (Split-Path $_ -Leaf) -notmatch $excludePattern } |
+    Select-Object -Unique
+)
 
 if ($wmiProfileQueryFailed) {
-    Write-Step -Status 'WARN' -Message 'Guard 2: WMI profile query failed, filesystem check still applied.'
+    Write-Step -Status 'WARN' -Message 'Profiles: WMI query failed, filesystem check still applied.'
 }
 
-if ($profileNames) {
+$profileNames = $profilePaths | ForEach-Object { Split-Path $_ -Leaf }
+
+# Relax: the ONLY exemption to guards 2+3. Two triggers -- OOBE InProgress (Windows
+# Backup for Organizations restore) or Cloud PC identity (headless provisioning,
+# profile at first connect). Either additionally requires exactly one fresh profile.
+$oobeInProgress = Test-OobeInProgress
+$profileAgeMin = $null
+$oobeRelax = $false
+if ($profilePaths.Count -eq 1) {
+    try {
+        $created = (Get-Item -LiteralPath $profilePaths[0] -Force -ErrorAction Stop).CreationTimeUtc
+        $profileAgeMin = [math]::Round(((Get-Date).ToUniversalTime() - $created).TotalMinutes, 1)
+    } catch { }
+    if (($oobeInProgress -or $isCloudPc) -and $null -ne $profileAgeMin -and $profileAgeMin -ge 0 -and $profileAgeMin -lt $OobeProfileMaxAgeMinutes) {
+        $oobeRelax = $true
+    }
+}
+
+Write-Step -Status 'INFO' -Message "Cloud PC markers: Windows365 registry key = $cloudPcRegMarker ; CloudManagedDesktopExtension service = $cloudPcSvcMarker ; IsCloudPc = $isCloudPc"
+Write-Step -Status 'INFO' -Message "OOBE: OutOfBoxExperienceState InProgress = $oobeInProgress ; profileCount = $($profilePaths.Count) ; singleProfileAgeMin = $profileAgeMin ; relax = $oobeRelax"
+
+# Guard 2: No real user profile should exist yet (unless OOBE-relax holds)
+if ($profilePaths.Count -gt 0 -and -not $oobeRelax) {
     $names = ($profileNames | Select-Object -First 3) -join ', '
     Write-Step -Status 'SKIP' -Message "Guard 2: Real user profile(s) found ($names). Device appears productive."
     $wouldInstall = $false
     $reasons.Add("Real user profile(s) found: $names")
+} elseif ($profilePaths.Count -gt 0 -and $oobeRelax) {
+    $names = ($profileNames | Select-Object -First 3) -join ', '
+    $trigger = if ($oobeInProgress) { 'OOBE InProgress' } else { 'Cloud PC' }
+    Write-Step -Status 'PASS' -Message "Guard 2: Profile ($names) present but relax active ($trigger + single fresh profile) -- not blocking."
 } else {
     Write-Step -Status 'PASS' -Message 'Guard 2: No real user profiles found (combined WMI/filesystem view).'
 }
 
-# Guard 3: LastLoggedOnUser -- during Device ESP no real user has logged on yet
+# Guard 3: LastLoggedOnUser (unless OOBE-relax holds)
 $lastLoggedOnUser = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\LogonUI' -Name 'LastLoggedOnUser' -EA SilentlyContinue).LastLoggedOnUser
-if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*') {
+if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and -not $oobeRelax) {
     Write-Step -Status 'SKIP' -Message "Guard 3: LastLoggedOnUser found ($lastLoggedOnUser). Device appears productive."
     $wouldInstall = $false
     $reasons.Add("LastLoggedOnUser found: $lastLoggedOnUser")
+} elseif ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and $oobeRelax) {
+    Write-Step -Status 'PASS' -Message "Guard 3: LastLoggedOnUser ($lastLoggedOnUser) present but relax active -- not blocking."
 } else {
     Write-Step -Status 'PASS' -Message "Guard 3: No real LastLoggedOnUser (value: '$lastLoggedOnUser')."
 }
 
-# Guard 4: Bootstrap window check
-# NOT "how long may enrollment take" -- agent handles that internally (6h emergency break).
-# This is "how old can the OOBE state be before I no longer trust it for initial install".
-# 12h bootstrap window vs 6h agent emergency break = consistent layered approach.
-# Sleep/standby does NOT reset uptime -- only real boot/restart does.
+# Guard 4: Bootstrap window check (sleep/standby does NOT reset uptime, only real boot does)
 $lastBoot = $null
 $uptimeHours = $null
 
@@ -123,9 +166,15 @@ try {
     $uptimeHours = ((Get-Date) - $lastBoot).TotalHours
 
     if ($uptimeHours -gt $MaxBootstrapWindowHours) {
-        Write-Step -Status 'SKIP' -Message "Guard 4: Device uptime is $([int]$uptimeHours)h. Older than accepted bootstrap window of ${MaxBootstrapWindowHours}h."
-        $wouldInstall = $false
-        $reasons.Add("Uptime exceeds bootstrap window: $([int]$uptimeHours)h > ${MaxBootstrapWindowHours}h")
+        if ($oobeRelax -and $isCloudPc) {
+            # Cloud PCs run headless for days before the user's first connect; the
+            # fresh-profile window is the time anchor there, not boot uptime.
+            Write-Step -Status 'PASS' -Message "Guard 4: Device uptime is $([int]$uptimeHours)h (over ${MaxBootstrapWindowHours}h), but the Cloud PC relax is active -- not blocking."
+        } else {
+            Write-Step -Status 'SKIP' -Message "Guard 4: Device uptime is $([int]$uptimeHours)h. Older than accepted bootstrap window of ${MaxBootstrapWindowHours}h."
+            $wouldInstall = $false
+            $reasons.Add("Uptime exceeds bootstrap window: $([int]$uptimeHours)h > ${MaxBootstrapWindowHours}h")
+        }
     } else {
         Write-Step -Status 'PASS' -Message "Guard 4: Device uptime is $([int]$uptimeHours)h and within bootstrap window of ${MaxBootstrapWindowHours}h."
     }
@@ -134,7 +183,7 @@ catch {
     Write-Step -Status 'WARN' -Message 'Guard 4: Could not determine LastBootUpTime / uptime.'
 }
 
-# Guard 4: Agent binary already present
+# Guard 5: Agent binary already present
 if (Test-Path $AgentExePath) {
     Write-Step -Status 'SKIP' -Message "Guard 5: Agent already installed at '$AgentExePath'."
     $wouldInstall = $false
@@ -168,6 +217,14 @@ Write-Host ''
 Write-Host '=== Raw Values ==='
 Write-Host "Deployed marker           : $deployed"
 Write-Host "DetectedProfileNames      : $($profileNames -join ', ')"
+Write-Host "ProfileCount              : $($profilePaths.Count)"
+Write-Host "OobeInProgress (WinRT)    : $oobeInProgress"
+Write-Host "CloudPcRegistryMarker     : $cloudPcRegMarker"
+Write-Host "CloudPcServiceMarker      : $cloudPcSvcMarker"
+Write-Host "IsCloudPc                 : $isCloudPc"
+Write-Host "SingleProfileAgeMinutes   : $profileAgeMin"
+Write-Host "OobeProfileMaxAgeMinutes  : $OobeProfileMaxAgeMinutes"
+Write-Host "RelaxActive               : $oobeRelax"
 Write-Host "LastLoggedOnUser          : $lastLoggedOnUser"
 Write-Host "MaxBootstrapWindowHours   : $MaxBootstrapWindowHours"
 Write-Host "LastBootUpTime            : $lastBoot"

scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1

@@ -23,7 +23,11 @@
     One or more high-level feature identifiers. The script translates each to the underlying
     Graph permissions. Use this when you don't want to know permission strings.
     Available features:
-      - ScriptDisplayNames -> DeviceManagementScripts.Read.All
+      - ScriptDisplayNames     -> DeviceManagementScripts.Read.All
+      - W365CloudPcValidation  -> CloudPC.Read.All
+        (validates Windows 365 Cloud PCs against the tenant's Cloud PC inventory --
+         Cloud PCs are never Autopilot-registered, so this enables agent monitoring
+         of Cloud PC first-connect enrollment)
 
 .PARAMETER Permissions
     Microsoft Graph application permission names to grant directly. Use when the admin UI
@@ -76,7 +80,7 @@ param(
     [string]$ClientId,
 
     [Parameter(Mandatory = $true, ParameterSetName = 'ByFeatures')]
-    [ValidateSet('ScriptDisplayNames')]
+    [ValidateSet('ScriptDisplayNames', 'W365CloudPcValidation')]
     [string[]]$Features,
 
     [Parameter(Mandatory = $true, ParameterSetName = 'ByPermissions')]
@@ -97,7 +101,8 @@ $ErrorActionPreference = 'Stop'
 # ---- Feature -> Graph permission catalog -----------------------------------
 # Keep in lock-step with src/Shared/AutopilotMonitor.Shared/Models/Graph/GraphFeatureCatalog.cs
 $FeatureCatalog = @{
-    'ScriptDisplayNames' = @('DeviceManagementScripts.Read.All')
+    'ScriptDisplayNames'    = @('DeviceManagementScripts.Read.All')
+    'W365CloudPcValidation' = @('CloudPC.Read.All')
 }
 
 # Translate Features -> Permissions when caller used the high-level form.

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Configuration/EndpointMigrationTests.cs

@@ -15,7 +15,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
         private const string CurrentUrl = "https://autopilotmonitor-api-eu.azurewebsites.net";
         private const string TargetUrl = "https://autopilotmonitor-api-us.azurewebsites.net";
 
-        private static AgentConfigResponse Config(string migrateUrl) =>
+        private static AgentConfigResponse Config(string? migrateUrl) =>
             new AgentConfigResponse { MigrateToApiBaseUrl = migrateUrl };
 
         [Fact]

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Configuration/RemoteConfigMergerTests.cs

@@ -285,6 +285,54 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
             Assert.Equal(@"C:\Temp\custom-ime.log", agent.ImeMatchLogPath);
         }
 
+        [Fact]
+        public void Merge_maps_enable_gather_rule_debug_log_true_to_default_path()
+        {
+            var agent = NewAgentConfig();
+            agent.GatherRuleDebugLogPath = null;
+
+            var remote = FullRemote();
+            remote.EnableGatherRuleDebugLog = true;
+
+            RemoteConfigMerger.Merge(agent, remote);
+
+            Assert.False(string.IsNullOrEmpty(agent.GatherRuleDebugLogPath));
+            Assert.Equal(
+                Environment.ExpandEnvironmentVariables(Constants.GatherRuleDebugLogPath),
+                agent.GatherRuleDebugLogPath);
+        }
+
+        [Fact]
+        public void Merge_maps_enable_gather_rule_debug_log_false_clears_path()
+        {
+            var agent = NewAgentConfig();
+            agent.GatherRuleDebugLogPath = Environment.ExpandEnvironmentVariables(Constants.GatherRuleDebugLogPath);
+
+            var remote = FullRemote();
+            remote.EnableGatherRuleDebugLog = false;
+
+            RemoteConfigMerger.Merge(agent, remote);
+
+            Assert.Null(agent.GatherRuleDebugLogPath);
+        }
+
+        [Fact]
+        public void Merge_preserves_custom_gather_rule_debug_log_path_when_remote_disables()
+        {
+            // A dev-time --gather-debug-log <custom> override seeds a non-default path on the
+            // AgentConfiguration. When the tenant remote flips EnableGatherRuleDebugLog off we
+            // keep the custom path rather than clobbering a deliberate dev override.
+            var agent = NewAgentConfig();
+            agent.GatherRuleDebugLogPath = @"C:\Temp\custom-gather.log";
+
+            var remote = FullRemote();
+            remote.EnableGatherRuleDebugLog = false;
+
+            RemoteConfigMerger.Merge(agent, remote);
+
+            Assert.Equal(@"C:\Temp\custom-gather.log", agent.GatherRuleDebugLogPath);
+        }
+
         // ============================================================= Null / partial tolerance
 
         [Fact]

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Configuration/RemoteConfigServiceCacheHardeningTests.cs

@@ -70,6 +70,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
             // Read the file the production code actually wrote and deserialize with the same lib.
             var raw = File.ReadAllText(_cachePath);
             var persisted = JsonConvert.DeserializeObject<AgentConfigResponse>(raw);
+            Assert.NotNull(persisted);
 
             Assert.False(persisted.UnrestrictedMode);
             Assert.False(persisted.AllowAgentDowngrade);

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Configuration/RemoteConfigServiceRetryTests.cs

@@ -193,7 +193,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
                     case BackendBehaviour.AlwaysAuthFailure401:
                         throw new BackendAuthException("Unauthorized", 401);
                     case BackendBehaviour.AlwaysReturnNull:
-                        return Task.FromResult<AgentConfigResponse>(null);
+                        return Task.FromResult<AgentConfigResponse>(null!);
                     default:
                         throw new InvalidOperationException("unknown behaviour");
                 }
@@ -204,9 +204,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
 
             // In-memory + per-instance cache so a prior test's successful fetch can't
             // bleed into a later test that expects UsedDefaults.
-            private AgentConfigResponse _cached;
+            private AgentConfigResponse? _cached;
             protected override void CacheConfig(AgentConfigResponse config) { _cached = config; }
-            protected override AgentConfigResponse LoadCachedConfig() => _cached;
+            protected override AgentConfigResponse LoadCachedConfig() => _cached!;
         }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/DeviceInfo/DeviceInfoCollectorEspRefreshTests.cs

@@ -0,0 +1,157 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Agent.V2.Core.Persistence;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Agent.V2.Core.Tests.Orchestration;
+using AutopilotMonitor.DecisionCore.Engine;
+using AutopilotMonitor.DecisionCore.Signals;
+using Xunit;
+using SharedEventTypes = AutopilotMonitor.Shared.Constants.EventTypes;
+using DeviceInfoCollector = AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo.DeviceInfoCollector;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.DeviceInfo
+{
+    /// <summary>
+    /// Audit Q2 — <see cref="DeviceInfoCollector.RefreshEspConfiguration"/>
+    /// re-reads the ESP blocking lists and re-emits <c>esp_config_detected</c> exactly when the
+    /// payload changed: the registry lists grow progressively (one timestamped subkey per CSP
+    /// status write) and the user-scope lists appear only after sign-in, so the early emissions
+    /// are structurally partial. The StartupEventGate keeps an unchanged re-read silent.
+    /// Probe overrides are static slots → serialized with the other probe-driven suites.
+    /// </summary>
+    [Collection("SerialThreading")]
+    public sealed class DeviceInfoCollectorEspRefreshTests
+    {
+        private static readonly DateTime T0 = new DateTime(2026, 7, 27, 10, 0, 0, DateTimeKind.Utc);
+
+        private const string DeviceApp1 = "11111111-1111-1111-1111-111111111111";
+        private const string DeviceApp2 = "22222222-2222-2222-2222-222222222222";
+        private const string UserApp1 = "33333333-3333-3333-3333-333333333333";
+
+        private static EspTrackingInfoSnapshot Snapshot(string[] deviceApps, string[] userApps)
+        {
+            var all = deviceApps.Concat(userApps).Distinct().ToArray();
+            return new EspTrackingInfoSnapshot(
+                msiProductCodes: Array.Empty<string>(),
+                modernAppPfns: Array.Empty<string>(),
+                win32AppIds: all,
+                userWin32AppIds: userApps,
+                msiCount: 0,
+                modernCount: 0,
+                win32Count: all.Length);
+        }
+
+        private static IReadOnlyList<FakeSignalIngressSink.PostedSignal> EspConfigEvents(FakeSignalIngressSink ingress) =>
+            ingress.Posted
+                .Where(p => p.Kind == DecisionSignalKind.InformationalEvent
+                            && p.Payload != null
+                            && p.Payload.TryGetValue(SignalPayloadKeys.EventType, out var et)
+                            && et == SharedEventTypes.EspConfigDetected)
+                .ToList();
+
+        private static IReadOnlyList<string> TypedList(FakeSignalIngressSink.PostedSignal signal, string key)
+        {
+            var data = Assert.IsAssignableFrom<IReadOnlyDictionary<string, object>>(signal.TypedPayload);
+            return Assert.IsAssignableFrom<IReadOnlyList<string>>(data[key]);
+        }
+
+        [Fact]
+        public void Refresh_reemits_when_lists_grew_and_stays_silent_when_unchanged()
+        {
+            using var tmp = new TempDirectory();
+            var logger = new AgentLogger(tmp.Path, AgentLogLevel.Info);
+            var ingress = new FakeSignalIngressSink();
+            var clock = new VirtualClock(T0);
+            var collector = new DeviceInfoCollector(
+                "session-1", "tenant-1",
+                new InformationalEventPost(ingress, clock), logger,
+                signalIngress: null, clock: clock,
+                startupGate: new StartupEventGate(tmp.Path, logger));
+
+            using var skip = new EspSkipConfigurationProbe.ScopedFullOverride(
+                _ => new EspFirstSyncSnapshot(
+                    skipUser: false, skipDevice: false,
+                    blockInStatusPage: null, syncFailureTimeoutMinutes: null));
+
+            // Early read (agent start / DeviceSetup detection): partial device list, empty user list.
+            using (new EspTrackingInfoProbe.ScopedOverride(_ => Snapshot(new[] { DeviceApp1 }, Array.Empty<string>())))
+            {
+                collector.CollectEspConfiguration();
+            }
+            var afterEarly = EspConfigEvents(ingress);
+            Assert.Single(afterEarly);
+            Assert.Empty(TypedList(afterEarly[0], "espTrackedUserWin32AppIds"));
+
+            // Apps sub-phase opened: the device list grew and sign-in populated the user list.
+            using (new EspTrackingInfoProbe.ScopedOverride(_ => Snapshot(new[] { DeviceApp1, DeviceApp2 }, new[] { UserApp1 })))
+            {
+                collector.RefreshEspConfiguration(DeviceInfoHost.EspConfigTriggerAppsUser);
+            }
+            var afterGrowth = EspConfigEvents(ingress);
+            Assert.Equal(2, afterGrowth.Count);
+            Assert.Contains(DeviceApp2, TypedList(afterGrowth[1], "espTrackedWin32AppIds"));
+            Assert.Equal(new[] { UserApp1 }, TypedList(afterGrowth[1], "espTrackedUserWin32AppIds"));
+
+            // A later trigger with an UNCHANGED registry state re-reads but emits nothing —
+            // the StartupEventGate suppresses the identical payload.
+            using (new EspTrackingInfoProbe.ScopedOverride(_ => Snapshot(new[] { DeviceApp1, DeviceApp2 }, new[] { UserApp1 })))
+            {
+                collector.RefreshEspConfiguration(DeviceInfoHost.EspConfigTriggerAccountSetup);
+            }
+            Assert.Equal(2, EspConfigEvents(ingress).Count);
+        }
+
+        [Fact]
+        public async Task Concurrent_refreshes_never_emit_an_older_snapshot_after_a_newer_one()
+        {
+            // Codex review: the refresh triggers each run on their own Task.Run — without the
+            // collector-side lock, two collects can interleave read-before-emit and the LATER
+            // emission carries the OLDER (smaller) list. The backend keeps the latest
+            // list-bearing emission as positive evidence, so that would silently shrink it.
+            // The probe returns a strictly growing list per read; with the read→emit critical
+            // section, emission order must equal read order — sizes strictly ascending.
+            using var tmp = new TempDirectory();
+            var logger = new AgentLogger(tmp.Path, AgentLogLevel.Info);
+            var ingress = new FakeSignalIngressSink();
+            var clock = new VirtualClock(T0);
+            var collector = new DeviceInfoCollector(
+                "session-1", "tenant-1",
+                new InformationalEventPost(ingress, clock), logger,
+                signalIngress: null, clock: clock,
+                startupGate: new StartupEventGate(tmp.Path, logger));
+
+            using var skip = new EspSkipConfigurationProbe.ScopedFullOverride(
+                _ => new EspFirstSyncSnapshot(
+                    skipUser: false, skipDevice: false,
+                    blockInStatusPage: null, syncFailureTimeoutMinutes: null));
+
+            var readCounter = 0;
+            using var tracking = new EspTrackingInfoProbe.ScopedOverride(_ =>
+            {
+                var n = Interlocked.Increment(ref readCounter);
+                var ids = Enumerable.Range(1, n)
+                    .Select(i => $"{i:d8}-1111-2222-3333-444444444444")
+                    .ToArray();
+                return Snapshot(ids, Array.Empty<string>());
+            });
+
+            var tasks = Enumerable.Range(0, 12)
+                .Select(i => Task.Run(() => collector.RefreshEspConfiguration($"stress-{i}")))
+                .ToArray();
+            await Task.WhenAll(tasks);
+
+            var sizes = EspConfigEvents(ingress)
+                .Select(e => TypedList(e, "espTrackedWin32AppIds").Count)
+                .ToList();
+            // Every refresh saw a strictly larger list (gate never suppresses) and each
+            // read→emit is atomic, so the emission sequence is exactly 1..12.
+            Assert.Equal(Enumerable.Range(1, 12), sizes);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Harness/ImeLogTrackerAdapterFixture.cs

@@ -39,6 +39,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Harness
                 logFolder: Tmp.Path,
                 patterns: new List<ImeLogPattern>(),
                 logger: Logger);
+            // Mirror ImeLogHost wiring: the historic-replay guard judges staleness against the
+            // (virtual) agent clock so tests stay deterministic.
+            Tracker.UtcNowProvider = () => Clock.UtcNow;
         }
 
         public IReadOnlyList<FakeSignalIngressSink.PostedSignal> DecisionSignals(DecisionSignalKind kind) =>

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Integration/ShellCoreToEngineEspExitingTests.cs

@@ -51,7 +51,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Integration
                 logger: logger,
                 helloTracker: null);
 
-            EspExitedEventArgs captured = null;
+            EspExitedEventArgs? captured = null;
             tracker.EspExited += (_, args) => captured = args;
 
             // Source time IS in the past relative to the clock — verify the tracker carries the

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Logging/AgentLoggerTests.cs

@@ -94,6 +94,21 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Logging
             Assert.Equal("older-002\n", File.ReadAllText(Path.Combine(tmp.Path, TodayBaseName + "_002.log")));
         }
 
+        [Fact]
+        public void Log_transliterates_typographic_punctuation_to_ascii()
+        {
+            using var tmp = new TempDirectory();
+            var logger = new AgentLogger(tmp.Path, AgentLogLevel.Info, maxFileSizeBytes: 1024L * 1024);
+
+            // The log file is UTF-8 without BOM; cp1252-guessing viewers (Outlook web
+            // preview) render em dashes as mojibake. Our own punctuation must come out
+            // as plain ASCII, while genuine non-ASCII payload stays untouched.
+            logger.Info("check failed \u2014 range 1\u20132 \u2192 done\u2026 \u2018a\u2019 \u201Cb\u201D nb\u00A0sp f\u00FCr M\u00FCller");
+
+            var text = File.ReadAllText(Path.Combine(tmp.Path, TodayBaseName + ".log"));
+            Assert.Contains("check failed - range 1-2 -> done... 'a' \"b\" nb sp f\u00FCr M\u00FCller", text);
+        }
+
         [Fact]
         public void Log_swallows_io_errors_silently()
         {

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Analyzers/LocalAdminAnalyzerTests.cs

@@ -0,0 +1,71 @@
+#nullable enable
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Analyzers;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Analyzers
+{
+    /// <summary>
+    /// LocalAdminAnalyzer.MatchesAllowedEntry — the allowed-list matching contract.
+    /// Entries without wildcard characters match exactly (case-insensitive); entries
+    /// containing * or ? are glob patterns with the same semantics as the hardware
+    /// whitelist. The same matcher is applied to local accounts and profile folders.
+    /// </summary>
+    public sealed class LocalAdminAnalyzerTests
+    {
+        // -------------------------------------------------------------- literal entries
+
+        [Theory]
+        [InlineData("SupportAdmin", "SupportAdmin")]
+        [InlineData("supportadmin", "SupportAdmin")]
+        [InlineData("SUPPORTADMIN", "supportadmin")]
+        public void Literal_entry_matches_exactly_case_insensitive(string name, string entry)
+        {
+            Assert.True(LocalAdminAnalyzer.MatchesAllowedEntry(name, entry));
+        }
+
+        [Theory]
+        [InlineData("SupportAdmin2", "SupportAdmin")]
+        [InlineData("SupportAdmin", "SupportAdmin2")]
+        [InlineData("Support", "SupportAdmin")]
+        public void Literal_entry_does_not_substring_match(string name, string entry)
+        {
+            Assert.False(LocalAdminAnalyzer.MatchesAllowedEntry(name, entry));
+        }
+
+        // -------------------------------------------------------------- glob patterns
+
+        [Theory]
+        [InlineData("adm-12345", "adm-*")]
+        [InlineData("adm-", "adm-*")]
+        [InlineData("ADM-9F3B2C", "adm-*")]
+        [InlineData("lapsAdmin01", "lapsAdmin??")]
+        [InlineData("svc-backup-01", "svc-*-01")]
+        public void Wildcard_entry_matches_glob(string name, string entry)
+        {
+            Assert.True(LocalAdminAnalyzer.MatchesAllowedEntry(name, entry));
+        }
+
+        [Theory]
+        [InlineData("administrator2", "adm-*")]   // no literal "adm-" prefix
+        [InlineData("xadm-123", "adm-*")]          // pattern is anchored at start
+        [InlineData("lapsAdmin1", "lapsAdmin??")]  // ? is exactly one char
+        [InlineData("adm.123", "adm-*")]           // "-" is literal, not a regex class
+        public void Wildcard_entry_does_not_overmatch(string name, string entry)
+        {
+            Assert.False(LocalAdminAnalyzer.MatchesAllowedEntry(name, entry));
+        }
+
+        [Fact]
+        public void Regex_metacharacters_in_entry_are_treated_literally()
+        {
+            // "adm.123" as an entry has no wildcard chars → exact match only,
+            // the dot must not act as a regex any-char.
+            Assert.True(LocalAdminAnalyzer.MatchesAllowedEntry("adm.123", "adm.123"));
+            Assert.False(LocalAdminAnalyzer.MatchesAllowedEntry("admX123", "adm.123"));
+
+            // Mixed: wildcard present, remaining metacharacters stay literal.
+            Assert.True(LocalAdminAnalyzer.MatchesAllowedEntry("adm.123", "adm.*"));
+            Assert.False(LocalAdminAnalyzer.MatchesAllowedEntry("admX123", "adm.*"));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/DesktopArrivalDetectorTests.cs

@@ -405,5 +405,144 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring
             var started = trace.Events.Find(e => e.EventType == SharedEventTypes.DesktopDetectorStarted);
             Assert.Equal(0, started.Data["noCandidateThresholdMinutes"]);
         }
+
+        // ============================================================================
+        // OOBE-state flip (oobe_state_completed) — observational one-shot on the poll
+        // ============================================================================
+        // The WinRT OutOfBoxExperienceState flip in_progress->completed is an owner-
+        // independent desktop corroboration for DAD-starved sessions (4d5a0b78 class).
+        // Tests drive polls synchronously via PollOnceForTest after Stop() so the real
+        // timer cannot race, and pin the owner seams to an excluded user so a real
+        // explorer.exe on the test machine can never set _desktopArrived (which would
+        // short-circuit PollForDesktop before the flip check).
+
+        private static DesktopArrivalDetector BuildFlipDetector(TempDirectory tmp, TraceCapture trace, System.Func<string> oobeProvider)
+        {
+            var detector = new DesktopArrivalDetector(new AgentLogger(tmp.Path, AgentLogLevel.Info), noCandidateTimeoutMinutes: 0)
+            {
+                OnTraceEvent = trace.Sink,
+                OobeStateProvider = oobeProvider,
+                SessionOwnerResolver = _ => "SYSTEM",
+                ProcessOwnerResolver = _ => "SYSTEM",
+            };
+            return detector;
+        }
+
+        /// <summary>Returns the queued states in order, then repeats the last one forever.</summary>
+        private static System.Func<string> StateQueue(params string[] states)
+        {
+            var queue = new Queue<string>(states);
+            var last = states[states.Length - 1];
+            return () => queue.Count > 0 ? queue.Dequeue() : last;
+        }
+
+        [Fact]
+        public void OobeFlip_emits_exactly_once_with_payload()
+        {
+            using var tmp = new TempDirectory();
+            var trace = new TraceCapture();
+            // Baseline sample happens synchronously inside Start()/ArmTimer.
+            using var detector = BuildFlipDetector(tmp, trace, StateQueue("in_progress", "completed"));
+
+            detector.Start();
+            detector.Stop();
+            detector.PollOnceForTest(); // reads "completed" -> flip
+            detector.PollOnceForTest(); // still "completed" -> no second emit
+
+            Assert.Equal(1, trace.CountOf(SharedEventTypes.OobeStateCompleted));
+            var flip = trace.Events.Find(e => e.EventType == SharedEventTypes.OobeStateCompleted);
+            Assert.Equal("in_progress", flip.Data["previousState"]);
+            Assert.True(flip.Data.ContainsKey("pollCount"));
+            Assert.True(flip.Data.ContainsKey("minutesSinceStart"));
+            Assert.False((bool)flip.Data["desktopArrived"]);
+            Assert.True(flip.Data.ContainsKey("wmiErrorCount"));
+            Assert.True(flip.Data.ContainsKey("wtsErrorCount"));
+        }
+
+        [Fact]
+        public void OobeFlip_does_not_emit_when_state_is_already_completed()
+        {
+            using var tmp = new TempDirectory();
+            var trace = new TraceCapture();
+            using var detector = BuildFlipDetector(tmp, trace, StateQueue("completed"));
+
+            detector.Start();
+            detector.Stop();
+            detector.PollOnceForTest();
+            detector.PollOnceForTest();
+
+            // Productive machines read "completed" from the very first sample — the flip
+            // event must never fire there (the agent_started field already records the state).
+            Assert.Equal(0, trace.CountOf(SharedEventTypes.OobeStateCompleted));
+        }
+
+        [Fact]
+        public void OobeFlip_does_not_emit_when_in_progress_was_never_seen()
+        {
+            using var tmp = new TempDirectory();
+            var trace = new TraceCapture();
+            using var detector = BuildFlipDetector(tmp, trace, StateQueue("unavailable", "completed"));
+
+            detector.Start();
+            detector.Stop();
+            detector.PollOnceForTest();
+
+            // Old builds without the WinRT contract report "unavailable"; a later
+            // "completed" without a positively observed "in_progress" is not a flip.
+            Assert.Equal(0, trace.CountOf(SharedEventTypes.OobeStateCompleted));
+        }
+
+        [Fact]
+        public void OobeFlip_survives_transient_unavailable_between_polls()
+        {
+            using var tmp = new TempDirectory();
+            var trace = new TraceCapture();
+            using var detector = BuildFlipDetector(tmp, trace, StateQueue("in_progress", "unavailable", "completed"));
+
+            detector.Start();
+            detector.Stop();
+            detector.PollOnceForTest(); // transient reflection failure — must NOT clear the baseline
+            detector.PollOnceForTest(); // "completed" -> flip still detected
+
+            Assert.Equal(1, trace.CountOf(SharedEventTypes.OobeStateCompleted));
+        }
+
+        [Fact]
+        public void OobeFlip_provider_throwing_never_emits_and_never_pollutes_wmi_error_count()
+        {
+            using var tmp = new TempDirectory();
+            var trace = new TraceCapture();
+            using var detector = BuildFlipDetector(tmp, trace, () => throw new System.InvalidOperationException("boom"));
+
+            detector.Start(); // baseline sample throws -> swallowed
+            detector.Stop();
+            detector.PollOnceForTest();
+            detector.PollOnceForTest();
+
+            Assert.Equal(0, trace.CountOf(SharedEventTypes.OobeStateCompleted));
+            // The flip check has its own try/catch — a throw must not fall into
+            // PollForDesktop's outer catch, which increments the WMI error counter the
+            // session-4d5a0b78 liveness diagnostics rely on. first_poll carries that counter.
+            var firstPoll = trace.Events.Find(e => e.EventType == SharedEventTypes.DesktopDetectorFirstPoll);
+            Assert.Equal(0, firstPoll.Data["wmiErrorCount"]);
+        }
+
+        [Fact]
+        public void OobeFlip_one_shot_flag_survives_ResetForRealUserSwitch()
+        {
+            using var tmp = new TempDirectory();
+            var trace = new TraceCapture();
+            using var detector = BuildFlipDetector(tmp, trace,
+                StateQueue("in_progress", "completed", "in_progress", "completed"));
+
+            detector.Start();
+            detector.Stop();
+            detector.PollOnceForTest(); // flip #1
+            detector.ResetForRealUserSwitch(); // re-arms + re-samples baseline ("in_progress")
+            detector.Stop();
+            detector.PollOnceForTest(); // "completed" again — must NOT re-emit
+
+            Assert.Equal(1, trace.CountOf(SharedEventTypes.OobeStateCompleted));
+        }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleCollectorGuardTests.cs

@@ -0,0 +1,460 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Shared;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
+{
+    /// <summary>
+    /// Allowlist enforcement for the two collectors that used to bypass it:
+    /// <see cref="LogParserCollector"/> read any path the rule named — including
+    /// C:\Users, whose hard block every other file collector honours — and
+    /// <see cref="EventLogCollector"/> read any channel, including Security.
+    /// A tenant admin can author both through the rules API, so the agent is the
+    /// only place this can be enforced.
+    /// </summary>
+    public sealed class GatherRuleCollectorGuardTests : IDisposable
+    {
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly List<EnrollmentEvent> _events = new List<EnrollmentEvent>();
+
+        // %TEMP% itself lives under C:\Users, which is hard-blocked — the positive
+        // cases need a directory the guard can actually admit, so they run beside
+        // the test assembly instead.
+        private readonly string _outsideUsers = Path.Combine(
+            AppContext.BaseDirectory, "guard-tests-" + Guid.NewGuid().ToString("N"));
+
+        public GatherRuleCollectorGuardTests() => Directory.CreateDirectory(_outsideUsers);
+
+        public void Dispose()
+        {
+            _tmp.Dispose();
+            try { Directory.Delete(_outsideUsers, recursive: true); } catch { /* best effort */ }
+        }
+
+        private GatherRuleContext Context(bool unrestricted = false, string? imeLogPathOverride = null)
+            => new GatherRuleContext(
+                new AgentLogger(_tmp.Path, AgentLogLevel.Info),
+                "sess", "tenant",
+                evt => _events.Add(evt),
+                imeLogPathOverride,
+                new LogFilePositionTracker())
+            {
+                UnrestrictedMode = unrestricted
+            };
+
+        private static GatherRule Rule(string collectorType, string target,
+            Dictionary<string, string>? parameters = null) => new GatherRule
+            {
+                RuleId = "GATHER-GUARD-TEST",
+                Title = "guard test",
+                CollectorType = collectorType,
+                Target = target,
+                // Match the model default (empty, never null) so the collectors see the
+                // same shape a deserialized rule without parameters gives them.
+                Parameters = parameters ?? new Dictionary<string, string>(),
+                Trigger = "startup",
+                OutputEventType = "guard_test",
+            };
+
+        private EnrollmentEvent SingleSecurityWarning()
+            => Assert.Single(_events, e => e.EventType == Constants.EventTypes.SecurityWarning);
+
+        // -------------------------------------------------------------------
+        // Event log channel allowlist
+        // -------------------------------------------------------------------
+
+        [Theory]
+        [InlineData("System")]
+        [InlineData("Application")]
+        [InlineData("Setup")]
+        [InlineData("Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider/Admin")]
+        [InlineData("Microsoft-Windows-AAD/Operational")]
+        [InlineData("Microsoft-Windows-Shell-Core/Operational")]
+        public void EventLogChannel_OnAllowlist_IsAllowed(string channel)
+            => Assert.True(GatherRuleGuards.IsEventLogChannelAllowed(channel));
+
+        [Theory]
+        [InlineData("Security")]
+        [InlineData("Microsoft-Windows-PowerShell/Operational")]
+        [InlineData("Windows PowerShell")]
+        [InlineData("Microsoft-Windows-Sysmon/Operational")]
+        public void EventLogChannel_HardBlocked_StaysBlockedEvenUnrestricted(string channel)
+        {
+            Assert.False(GatherRuleGuards.IsEventLogChannelAllowed(channel));
+            Assert.False(GatherRuleGuards.IsEventLogChannelAllowed(channel, unrestrictedMode: true));
+        }
+
+        [Theory]
+        [InlineData("Microsoft-Windows-AADSomethingElse/Operational")] // prefix spoofing
+        [InlineData("Microsoft-Windows-TerminalServices-LocalSessionManager/Operational")]
+        [InlineData("")]
+        public void EventLogChannel_OffAllowlist_IsBlocked(string channel)
+            => Assert.False(GatherRuleGuards.IsEventLogChannelAllowed(channel));
+
+        [Fact]
+        public void EventLogChannel_Null_IsBlocked()
+            => Assert.False(GatherRuleGuards.IsEventLogChannelAllowed(null));
+
+        [Fact]
+        public void EventLogChannel_OffAllowlist_IsAllowedInUnrestrictedMode()
+            => Assert.True(GatherRuleGuards.IsEventLogChannelAllowed(
+                "Microsoft-Windows-TerminalServices-LocalSessionManager/Operational",
+                unrestrictedMode: true));
+
+        [Fact]
+        public void EventLogCollector_SecurityChannel_EmitsSecurityWarningAndReturnsNoData()
+        {
+            var result = new EventLogCollector().Execute(Rule("eventlog", "Security"), Context());
+
+            Assert.Empty(result);
+            var warning = SingleSecurityWarning();
+            Assert.Equal(true, warning.Data["blocked"]);
+            Assert.Equal("Security", warning.Data["target"]);
+        }
+
+        [Fact]
+        public void EventLogCollector_SecurityChannel_StaysBlockedInUnrestrictedMode()
+        {
+            var result = new EventLogCollector().Execute(
+                Rule("eventlog", "Security"), Context(unrestricted: true));
+
+            Assert.Empty(result);
+            SingleSecurityWarning();
+        }
+
+        // -------------------------------------------------------------------
+        // Log parser file allowlist
+        // -------------------------------------------------------------------
+
+        private static Dictionary<string, string> TextPattern() => new Dictionary<string, string>
+        {
+            ["pattern"] = "(?<line>.+)",
+            ["format"] = "text",
+            ["trackPosition"] = "false",
+        };
+
+        [Fact]
+        public void LogParser_UserProfilePath_IsBlockedAndEmitsSecurityWarning()
+        {
+            const string target = @"C:\Users\Public\Documents\secret.txt";
+
+            var result = new LogParserCollector().Execute(
+                Rule("logparser", target, TextPattern()), Context());
+
+            Assert.Null(result);
+            var warning = SingleSecurityWarning();
+            Assert.Equal(target, warning.Data["target"]);
+            Assert.DoesNotContain(_events, e => e.EventType == "guard_test");
+        }
+
+        [Fact]
+        public void LogParser_UserProfilePath_StaysBlockedInUnrestrictedMode()
+        {
+            // C:\Users is a hard block — unrestricted mode must not lift it.
+            new LogParserCollector().Execute(
+                Rule("logparser", @"C:\Users\Public\Documents\secret.txt", TextPattern()),
+                Context(unrestricted: true));
+
+            SingleSecurityWarning();
+        }
+
+        [Fact]
+        public void LogParser_OffAllowlistPath_IsBlockedEvenWhenFileExists()
+        {
+            var path = _tmp.File("evidence.log");
+            File.WriteAllText(path, "line one\nline two\n");
+
+            var result = new LogParserCollector().Execute(
+                Rule("logparser", path, TextPattern()), Context());
+
+            Assert.Null(result);
+            SingleSecurityWarning();
+            Assert.DoesNotContain(_events, e => e.EventType == "guard_test");
+        }
+
+        [Fact]
+        public void LogParser_WildcardTarget_IsBlockedByItsDirectory()
+        {
+            // Path.GetFullPath rejects '*', so the guard has to check the directory.
+            File.WriteAllText(_tmp.File("evidence.log"), "line one\n");
+
+            new LogParserCollector().Execute(
+                Rule("logparser", Path.Combine(_tmp.Path, "*.log"), TextPattern()), Context());
+
+            SingleSecurityWarning();
+            Assert.DoesNotContain(_events, e => e.EventType == "guard_test");
+        }
+
+        [Fact]
+        public void LogParser_UnrestrictedMode_ReadsPathOffTheAllowlist()
+        {
+            var path = Path.Combine(_outsideUsers, "evidence.log");
+            File.WriteAllText(path, "line one\nline two\n");
+
+            new LogParserCollector().Execute(
+                Rule("logparser", path, TextPattern()), Context(unrestricted: true));
+
+            Assert.DoesNotContain(_events, e => e.EventType == Constants.EventTypes.SecurityWarning);
+            Assert.Equal(2, _events.Count(e => e.EventType == "guard_test"));
+        }
+
+        [Fact]
+        public void LogParser_LocalImeLogPathOverride_RelaxesTheAllowlist()
+        {
+            // --ime-log-path is a local CLI flag, never remote config: the operator
+            // using it is already a local admin, so it relaxes the allowlist the way
+            // unrestricted mode does.
+            File.WriteAllText(Path.Combine(_outsideUsers, "AppWorkload.log"), "line one\n");
+
+            new LogParserCollector().Execute(
+                Rule("logparser", @"C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\AppWorkload.log",
+                    TextPattern()),
+                Context(imeLogPathOverride: _outsideUsers));
+
+            Assert.DoesNotContain(_events, e => e.EventType == Constants.EventTypes.SecurityWarning);
+            Assert.Single(_events, e => e.EventType == "guard_test");
+        }
+
+        // -------------------------------------------------------------------
+        // Command execution
+        // -------------------------------------------------------------------
+
+        [Fact]
+        public void Command_OffAllowlist_IsBlockedAndNeverRuns()
+        {
+            var result = new CommandCollector().Execute(
+                Rule("command_allowlisted", "Get-Content C:\\Windows\\System32\\config\\SAM"), Context());
+
+            Assert.Equal(true, result["blocked"]);
+            Assert.False(result.ContainsKey("output"));
+            SingleSecurityWarning();
+        }
+
+        [Fact]
+        public void Command_HardBlockedPattern_StaysBlockedInUnrestrictedMode()
+        {
+            var result = new CommandCollector().Execute(
+                Rule("command_allowlisted", "Invoke-WebRequest https://example.invalid/x"),
+                Context(unrestricted: true));
+
+            Assert.Equal(true, result["blocked"]);
+            SingleSecurityWarning();
+        }
+
+        [Fact]
+        public void Command_ThatHangs_IsKilledAtTheTimeoutRatherThanPinningTheWorker()
+        {
+            // Regression: reading stdout synchronously blocked until the pipe closed,
+            // so WaitForExit's timeout was never reached and a hung command pinned the
+            // worker indefinitely. Unrestricted mode is needed to run an ad-hoc command.
+            var sw = System.Diagnostics.Stopwatch.StartNew();
+            var result = new CommandCollector().Execute(
+                Rule("command_allowlisted", "Start-Sleep -Seconds 120"), Context(unrestricted: true));
+            sw.Stop();
+
+            Assert.Equal(true, result["timed_out"]);
+            Assert.Equal(-1, result["exit_code"]);
+            // The 30s timeout plus drain margin — nowhere near the command's 120s.
+            Assert.True(sw.Elapsed < TimeSpan.FromSeconds(60),
+                $"expected the hung command to be killed at the timeout; took {sw.Elapsed}");
+        }
+
+        // -------------------------------------------------------------------
+        // Every remaining collector actually calls its guard
+        //
+        // The guard functions have their own unit tests, but those prove nothing about
+        // whether a collector consults them before touching the registry, WMI or disk.
+        // These drive the collectors themselves: each blocked target must come back empty,
+        // emit exactly one security_warning naming the target, and produce no rule output.
+        // -------------------------------------------------------------------
+
+        private void AssertBlocked(Dictionary<string, object> result, string target)
+        {
+            Assert.Empty(result);
+            var warning = SingleSecurityWarning();
+            Assert.Equal(true, warning.Data["blocked"]);
+            Assert.Equal(target, warning.Data["target"]);
+            Assert.DoesNotContain(_events, e => e.EventType == "guard_test");
+        }
+
+        [Theory]
+        [InlineData(@"SAM\SAM\Domains\Account\Users")]
+        [InlineData(@"SECURITY\Policy\Secrets")]
+        [InlineData(@"HKLM\SOFTWARE\Microsoft\EnrollmentsSomethingElse")]  // prefix spoofing
+        [InlineData(@"HKLM\SOFTWARE\Microsoft\Windows\AutopilotSomethingElse")]  // sibling spoof of the Autopilot prefix
+        public void RegistryCollector_OffAllowlistPath_IsBlockedBeforeTheHiveIsOpened(string target)
+            => AssertBlocked(new RegistryCollector().Execute(Rule("registry", target), Context()), target);
+
+        // Session 5d735290: the EnrollmentStatusTracking subtree (ESP policy providers / tracking
+        // state) is allow-listed so tenants can build gather rules on the co-management stall
+        // signature the esp_policy_provider_stalled detector reports (e.g. not_exists on the
+        // Sidecar provider key).
+        [Theory]
+        [InlineData(@"SOFTWARE\Microsoft\Windows\Autopilot")]
+        [InlineData(@"SOFTWARE\Microsoft\Windows\Autopilot\EnrollmentStatusTracking\Device\Setup\Apps\PolicyProviders\Sidecar")]
+        public void RegistryGuard_AutopilotEnrollmentTrackingSubtree_IsAllowed(string subPath)
+            => Assert.True(GatherRuleGuards.IsRegistryPathAllowed(subPath));
+
+        [Theory]
+        [InlineData("SELECT * FROM Win32_UserAccount")]
+        [InlineData("SELECT * FROM Win32_ShadowCopy")]
+        [InlineData("SELECT * FROM Win32_OperatingSystemExtra")]          // prefix spoofing
+        [InlineData("SELECT Name FROM Win32_Process")]                    // projection of a disallowed class
+        [InlineData("SELECT BatteryStatus FROM Win32_BatteryX")]          // class spoofing via projection
+        public void WmiCollector_OffAllowlistQuery_IsBlockedBeforeTheQueryRuns(string query)
+            => AssertBlocked(new WmiCollector().Execute(Rule("wmi", query), Context()), query);
+
+        // -------------------------------------------------------------------
+        // WMI query matcher: "SELECT <* | property-list> FROM <allowed class>"
+        //
+        // Guard-level (no WMI touched): a property projection of an allowed class
+        // exposes a strict subset of the already-allowed SELECT *, so it is admitted.
+        // -------------------------------------------------------------------
+
+        [Theory]
+        [InlineData("SELECT * FROM Win32_Battery")]                                       // legacy form unchanged
+        [InlineData("SELECT * FROM Win32_BIOS WHERE PrimaryBIOS = TRUE")]                 // legacy + WHERE
+        [InlineData("SELECT BatteryStatus FROM Win32_Battery")]
+        [InlineData("SELECT BatteryStatus, EstimatedChargeRemaining FROM Win32_Battery")]
+        [InlineData("select batterystatus from win32_battery")]                           // case-insensitive
+        [InlineData("SELECT\tBatteryStatus\tFROM\tWin32_Battery")]                        // tabs as separators
+        [InlineData("  SELECT BatteryStatus FROM Win32_Battery  ")]                       // surrounding whitespace
+        [InlineData("SELECT BatteryStatus,EstimatedChargeRemaining FROM Win32_Battery")]  // no space after comma
+        [InlineData("SELECT Status FROM Win32_Battery WHERE BatteryStatus = 1")]          // projection + WHERE
+        public void WmiGuard_ProjectionOfAllowedClass_IsAllowed(string query)
+            => Assert.True(GatherRuleGuards.IsWmiQueryAllowed(query));
+
+        [Theory]
+        [InlineData("SELECT Name FROM Win32_Process")]                    // class not on the allowlist
+        [InlineData("SELECT BatteryStatus FROM Win32_BatteryX")]          // class spoofing
+        [InlineData("SELECT * FROM Win32_BatteryX")]
+        [InlineData("SELECT *, Name FROM Win32_BIOS")]                    // star mixed into a property list
+        [InlineData("SELECT FROM Win32_BIOS")]                            // empty property list
+        [InlineData("SELECT BatteryStatus FROM")]                         // missing class
+        [InlineData("SELECT BatteryStatus FROM Win32_Battery;DROP")]      // non-whitespace boundary after class
+        [InlineData("SELECT BatteryStatus, FROM Win32_Battery")]          // trailing comma
+        [InlineData("")]
+        public void WmiGuard_MalformedOrDisallowedQuery_IsBlocked(string query)
+            => Assert.False(GatherRuleGuards.IsWmiQueryAllowed(query));
+
+        [Fact]
+        public void WmiGuard_NullQuery_IsBlocked()
+            => Assert.False(GatherRuleGuards.IsWmiQueryAllowed(null));
+
+        [Fact]
+        public void WmiGuard_UnrestrictedMode_AllowsAnyQuery()
+            => Assert.True(GatherRuleGuards.IsWmiQueryAllowed("SELECT Name FROM Win32_Process", unrestrictedMode: true));
+
+        [Fact]
+        public void JsonCollector_UserProfilePath_IsBlockedBeforeTheFileIsOpened()
+        {
+            const string target = @"C:\Users\Public\Documents\secrets.json";
+            AssertBlocked(
+                new JsonCollector().Execute(
+                    Rule("json", target, new Dictionary<string, string> { ["jsonpath"] = "$.token" }),
+                    Context()),
+                target);
+        }
+
+        [Fact]
+        public void XmlCollector_UserProfilePath_IsBlockedBeforeTheFileIsOpened()
+        {
+            const string target = @"C:\Users\Public\Documents\secrets.xml";
+            AssertBlocked(
+                new XmlCollector().Execute(
+                    Rule("xml", target, new Dictionary<string, string> { ["xpath"] = "//token" }),
+                    Context()),
+                target);
+        }
+
+        [Fact]
+        public void FileCollector_UserProfilePath_IsBlockedBeforeTheFileIsOpened()
+        {
+            const string target = @"C:\Users\Public\Documents\secrets.txt";
+            AssertBlocked(new FileCollector().Execute(Rule("file", target), Context()), target);
+        }
+
+        [Fact]
+        public void JsonCollector_AllowedPath_ReadsTheFile()
+        {
+            // Counterpart to the blocked cases: proves the guard is a gate, not a wall —
+            // the collector does reach the file once the path is admitted.
+            var path = Path.Combine(_outsideUsers, "inventory.json");
+            File.WriteAllText(path, "{ \"agent\": { \"version\": \"2.4.0\" } }");
+
+            var result = new JsonCollector().Execute(
+                Rule("json", path, new Dictionary<string, string> { ["jsonpath"] = "$.agent.version" }),
+                Context(unrestricted: true));
+
+            Assert.DoesNotContain(_events, e => e.EventType == Constants.EventTypes.SecurityWarning);
+            Assert.Contains("2.4.0", string.Join(",", result.Values));
+        }
+
+        // -------------------------------------------------------------------
+        // Path traversal
+        // -------------------------------------------------------------------
+
+        [Fact]
+        public void FilePath_TraversalOutOfAnAllowedPrefix_IsBlocked()
+        {
+            // The raw string starts with an allowed prefix, so a naive StartsWith check would
+            // admit it. Path.GetFullPath runs FIRST, so the allowlist sees C:\Secret.txt.
+            const string traversal =
+                @"C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\..\..\..\..\Secret.txt";
+
+            Assert.Equal(@"C:\Secret.txt", Path.GetFullPath(traversal));
+            Assert.False(GatherRuleGuards.IsFilePathAllowed(traversal));
+        }
+
+        [Fact]
+        public void FilePath_TraversalIntoTheUsersHardBlock_StaysBlockedEvenUnrestricted()
+        {
+            // Unrestricted mode lifts the allowlist but never the C:\Users privacy block —
+            // and it must not be reachable by spelling the path with '..' either.
+            const string traversal =
+                @"C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\..\..\..\..\Users\Public\ntuser.dat";
+
+            Assert.StartsWith(@"C:\Users\", Path.GetFullPath(traversal), StringComparison.OrdinalIgnoreCase);
+            Assert.False(GatherRuleGuards.IsFilePathAllowed(traversal));
+            Assert.False(GatherRuleGuards.IsFilePathAllowed(traversal, unrestrictedMode: true));
+        }
+
+        [Fact]
+        public void FilePath_TraversalIntoTheConfigHiveDirectory_StaysBlockedEvenUnrestricted()
+        {
+            const string traversal = @"C:\Windows\Logs\..\System32\config\SAM";
+
+            Assert.False(GatherRuleGuards.IsFilePathAllowed(traversal));
+            Assert.False(GatherRuleGuards.IsFilePathAllowed(traversal, unrestrictedMode: true));
+        }
+
+        [Fact]
+        public void FileCollector_TraversalTarget_IsBlockedAndReported()
+        {
+            const string traversal =
+                @"C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\..\..\..\..\Users\Public\ntuser.dat";
+
+            AssertBlocked(new FileCollector().Execute(Rule("file", traversal), Context()), traversal);
+        }
+
+        [Fact]
+        public void LogParser_ImeLogPathOverride_StillHonoursTheUsersHardBlock()
+        {
+            new LogParserCollector().Execute(
+                Rule("logparser", @"C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\AppWorkload.log",
+                    TextPattern()),
+                Context(imeLogPathOverride: @"C:\Users\Public\Documents"));
+
+            SingleSecurityWarning();
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleDebugLogTests.cs

@@ -0,0 +1,104 @@
+using System;
+using System.IO;
+using System.Linq;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
+{
+    /// <summary>
+    /// Writer unit tests for <see cref="GatherRuleDebugLog"/>: line format, lazy directory
+    /// creation, size-cap rotation, and the null-writer no-op path on the context.
+    /// </summary>
+    public sealed class GatherRuleDebugLogTests : IDisposable
+    {
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly AgentLogger _logger;
+
+        public GatherRuleDebugLogTests()
+        {
+            _logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+        }
+
+        public void Dispose() => _tmp.Dispose();
+
+        private string LogPath => Path.Combine(_tmp.Path, "sub", "gather_rules_debug.log");
+
+        [Fact]
+        public void Write_produces_pipe_delimited_line_and_creates_directory_lazily()
+        {
+            var log = new GatherRuleDebugLog(LogPath, _logger);
+            Assert.False(File.Exists(LogPath)); // lazy — nothing until the first write
+
+            log.Write("RULE-1", GatherRuleDebugLog.StageScope, "skipped: out of scope");
+
+            var lines = File.ReadAllLines(LogPath);
+            Assert.Equal(2, lines.Length); // header + entry
+            Assert.Contains("| - | config | -- gather rule debug log started --", lines[0]);
+            var parts = lines[1].Split(new[] { " | " }, StringSplitOptions.None);
+            Assert.Equal(4, parts.Length);
+            Assert.Equal("RULE-1", parts[1]);
+            Assert.Equal("scope", parts[2]);
+            Assert.Equal("skipped: out of scope", parts[3]);
+        }
+
+        [Fact]
+        public void Write_flattens_newlines_except_for_error_stage()
+        {
+            var log = new GatherRuleDebugLog(LogPath, _logger);
+            log.Write("RULE-1", GatherRuleDebugLog.StageCollector, "line1\r\nline2");
+            log.Write("RULE-1", GatherRuleDebugLog.StageError, "boom\r\n   at Frame()");
+
+            var content = File.ReadAllText(LogPath);
+            Assert.Contains("line1 line2", content);
+            Assert.Contains("   at Frame()", content); // error stage keeps the stack multi-line
+        }
+
+        [Fact]
+        public void Write_null_ruleId_renders_dash()
+        {
+            var log = new GatherRuleDebugLog(LogPath, _logger);
+            log.Write(null, GatherRuleDebugLog.StageConfig, "no rules delivered");
+
+            Assert.Contains(" | - | config | no rules delivered", File.ReadAllText(LogPath));
+        }
+
+        [Fact]
+        public void Write_rotates_once_when_file_exceeds_cap()
+        {
+            var log = new GatherRuleDebugLog(LogPath, _logger, maxBytes: 512);
+            for (int i = 0; i < 20; i++)
+                log.Write("RULE-1", GatherRuleDebugLog.StageExec, new string('x', 100));
+
+            var oldPath = Path.Combine(Path.GetDirectoryName(LogPath), "gather_rules_debug.old.log");
+            Assert.True(File.Exists(oldPath), "expected one .old rotation generation");
+            Assert.True(File.Exists(LogPath));
+            Assert.Contains("-- rotated", File.ReadAllText(LogPath) + File.ReadAllText(oldPath));
+            // Never more than one .old generation
+            Assert.Single(Directory.GetFiles(Path.GetDirectoryName(LogPath), "*.old.log"));
+        }
+
+        [Fact]
+        public void WriteStandalone_writes_single_config_line()
+        {
+            GatherRuleDebugLog.WriteStandalone(LogPath, "no gather rules delivered by backend — nothing to execute", _logger);
+
+            var lines = File.ReadAllLines(LogPath);
+            Assert.Contains(lines, l => l.Contains("no gather rules delivered by backend"));
+        }
+
+        [Fact]
+        public void Context_DebugLog_is_noop_without_writer()
+        {
+            var context = new GatherRuleContext(
+                _logger, "sess", "tenant", _ => { }, null, new LogFilePositionTracker());
+
+            context.DebugLog("RULE-1", GatherRuleDebugLog.StageScope, "should not throw, should not write");
+
+            Assert.False(File.Exists(LogPath));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleExecutorDebugLogTests.cs

@@ -0,0 +1,174 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
+{
+    /// <summary>
+    /// Debug-trace coverage of <see cref="GatherRuleExecutor"/> (EnableGatherRuleDebugLog):
+    /// every "silently produced nothing" outcome must leave an explanatory line in the trace
+    /// file — registration summary, missing interval, scope skips, on_change suppression,
+    /// empty collector results.
+    /// </summary>
+    [Collection("SerialThreading")] // startup rules execute on the shared ThreadPool
+    public sealed class GatherRuleExecutorDebugLogTests : IDisposable
+    {
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly GatherRuleExecutor _executor;
+        private readonly string _debugLogPath;
+
+        private const string AbsentPath =
+            "HKLM\\SOFTWARE\\AutopilotMonitorTests\\DefinitelyAbsent_7e3a1f4b-0000-0000-0000-000000000000";
+
+        public GatherRuleExecutorDebugLogTests()
+        {
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            _debugLogPath = Path.Combine(_tmp.Path, "gather_rules_debug.log");
+            _executor = new GatherRuleExecutor(
+                "sess", "tenant", _ => { }, logger,
+                debugLogPath: _debugLogPath)
+            {
+                UnrestrictedMode = true
+            };
+        }
+
+        public void Dispose()
+        {
+            _executor.Dispose();
+            _tmp.Dispose();
+        }
+
+        private string TraceContent() => File.Exists(_debugLogPath) ? File.ReadAllText(_debugLogPath) : string.Empty;
+
+        private static GatherRule Rule(string id, Action<GatherRule>? mutate = null)
+        {
+            var rule = new GatherRule
+            {
+                RuleId = id,
+                Title = id,
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "startup",
+                OutputEventType = "gather_test",
+                Enabled = true,
+            };
+            mutate?.Invoke(rule);
+            return rule;
+        }
+
+        [Fact]
+        public void UpdateRules_writes_registration_summary_per_rule()
+        {
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                Rule("GATHER-REG-001", r => { r.Trigger = "interval"; r.IntervalSeconds = 3600; r.EmitMode = "on_change"; }),
+                Rule("GATHER-REG-002", r => r.Enabled = false),
+            });
+            _executor.WaitForStartupRules(30);
+
+            var trace = TraceContent();
+            Assert.Contains("GATHER-REG-001 | config | registered: trigger=interval, collector=registry", trace);
+            Assert.Contains("emitMode=on_change", trace);
+            Assert.Contains("interval=3600s", trace);
+            Assert.Contains("GATHER-REG-002 | config | rule disabled — will never run", trace);
+            Assert.Contains("interval timer scheduled every 3600s (first run after one full interval", trace);
+        }
+
+        [Fact]
+        public void UpdateRules_flags_interval_rule_without_intervalSeconds()
+        {
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                Rule("GATHER-NOINT-001", r => { r.Trigger = "interval"; r.IntervalSeconds = null; }),
+            });
+
+            Assert.Contains("GATHER-NOINT-001 | error | trigger=interval but intervalSeconds is missing — rule will NEVER run",
+                TraceContent());
+        }
+
+        [Fact]
+        public void ScopedRule_skip_traces_unknown_phase_reason()
+        {
+            var rule = Rule("GATHER-SCOPE-001", r => { r.Trigger = "interval"; r.IntervalSeconds = 3600; r.ActivePhases = new List<string> { "DeviceSetup" }; });
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            // Synchronous internal check mirrors the timer-tick gate; the reason must name Unknown.
+            string reason;
+            Assert.False(_executor.IsRuleInScope(rule, out reason));
+            Assert.Contains("currentPhase=Unknown", reason);
+        }
+
+        [Fact]
+        public void ScopedStartupRule_deferral_is_traced()
+        {
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                Rule("GATHER-DEFER-001", r => r.ActivePhases = new List<string> { "DeviceSetup" }),
+            });
+
+            Assert.Contains("GATHER-DEFER-001 | scope | startup rule deferred — currentPhase=Unknown", TraceContent());
+        }
+
+        [Fact]
+        public void OnChange_suppression_and_reemission_are_traced()
+        {
+            var rule = Rule("GATHER-OC-001", r => { r.Trigger = "interval"; r.IntervalSeconds = 3600; r.EmitMode = "on_change"; });
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            string hashPrefix;
+            int streak;
+            var first = new Dictionary<string, object> { ["exists"] = false };
+            Assert.True(_executor.ShouldEmitOnChange(rule, first, out hashPrefix, out streak));
+            Assert.Equal(0, streak);
+            Assert.False(string.IsNullOrEmpty(hashPrefix));
+
+            Assert.False(_executor.ShouldEmitOnChange(rule, new Dictionary<string, object> { ["exists"] = false }, out hashPrefix, out streak));
+            Assert.Equal(1, streak);
+            Assert.False(_executor.ShouldEmitOnChange(rule, new Dictionary<string, object> { ["exists"] = false }, out hashPrefix, out streak));
+            Assert.Equal(2, streak);
+
+            var changed = new Dictionary<string, object> { ["exists"] = true };
+            Assert.True(_executor.ShouldEmitOnChange(rule, changed, out hashPrefix, out streak));
+            Assert.Equal(2, streak); // the streak that just ended
+            Assert.Equal(2, changed["suppressedPolls"]);
+        }
+
+        [Fact]
+        public void PhaseChange_writes_transition_line()
+        {
+            _executor.UpdateRules(new List<GatherRule> { Rule("GATHER-PHASE-001") });
+            _executor.WaitForStartupRules(30);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup); // repeat — no extra line
+
+            var trace = TraceContent();
+            Assert.Contains("- | phase | phase change: Unknown -> DeviceSetup (first phase signal", trace);
+            Assert.Contains("- | phase | phase change: DeviceSetup -> AccountSetup", trace);
+            // A repeated signal for the same phase must not produce a second transition line.
+            var marker = "phase change: DeviceSetup -> AccountSetup";
+            Assert.Equal(trace.IndexOf(marker), trace.LastIndexOf(marker));
+        }
+
+        [Fact]
+        public void EmptyCollectorResult_is_traced_via_startup_execution()
+        {
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                Rule("GATHER-EMPTY-001", r => r.Parameters = new Dictionary<string, string> { ["emitOnlyIfExists"] = "true" }),
+            });
+            Assert.True(_executor.WaitForStartupRules(30));
+
+            var trace = TraceContent();
+            Assert.Contains("GATHER-EMPTY-001 | exec | executing: collector=registry", trace);
+            Assert.Contains("GATHER-EMPTY-001 | collector | registry key/value not found", trace);
+            Assert.Contains("GATHER-EMPTY-001 | collector | collector returned EMPTY result — nothing emitted", trace);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleExecutorEmitModeTests.cs

@@ -192,7 +192,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
                 GatherRuleExecutor.ComputeCanonicalHash(new Dictionary<string, object> { ["v"] = "1" }),
                 GatherRuleExecutor.ComputeCanonicalHash(new Dictionary<string, object> { ["v"] = 1 }));
             Assert.NotEqual(
-                GatherRuleExecutor.ComputeCanonicalHash(new Dictionary<string, object> { ["v"] = null }),
+                GatherRuleExecutor.ComputeCanonicalHash(new Dictionary<string, object> { ["v"] = null! }),
                 GatherRuleExecutor.ComputeCanonicalHash(new Dictionary<string, object> { ["v"] = "<null>" }));
         }
 

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleExecutorPhaseExitTests.cs

@@ -0,0 +1,246 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Threading;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
+{
+    /// <summary>
+    /// The <c>phase_exit</c> trigger: a one-shot collection when a phase is LEFT — the closing
+    /// bookend to <c>phase_change</c> (which fires on ENTER). The distinguishing invariant is that
+    /// both the TriggerPhase match and the phase-scope gate must evaluate against the phase being
+    /// left, i.e. before the executor's current-phase state moves forward.
+    /// Rules use the absent-registry-path pattern so no real system state is touched.
+    /// </summary>
+    [Collection("SerialThreading")] // rules execute on the shared ThreadPool
+    public sealed class GatherRuleExecutorPhaseExitTests : IDisposable
+    {
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly List<EnrollmentEvent> _events = new List<EnrollmentEvent>();
+        private readonly object _eventsGate = new object();
+        private readonly GatherRuleExecutor _executor;
+
+        private const string AbsentPath =
+            "HKLM\\SOFTWARE\\AutopilotMonitorTests\\DefinitelyAbsent_9c4d2a7f-0000-0000-0000-000000000000";
+
+        public GatherRuleExecutorPhaseExitTests()
+        {
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            _executor = new GatherRuleExecutor(
+                "sess", "tenant",
+                evt => { lock (_eventsGate) _events.Add(evt); },
+                logger)
+            {
+                UnrestrictedMode = true
+            };
+        }
+
+        public void Dispose()
+        {
+            _executor.Dispose();
+            _tmp.Dispose();
+        }
+
+        private int EventCount { get { lock (_eventsGate) return _events.Count; } }
+
+        private bool WaitForEventCount(int count, int timeoutMs = 10000)
+        {
+            var sw = Stopwatch.StartNew();
+            while (sw.ElapsedMilliseconds < timeoutMs)
+            {
+                if (EventCount >= count) return true;
+                Thread.Sleep(25);
+            }
+            return EventCount >= count;
+        }
+
+        private static GatherRule ExitRule(
+            string id, string triggerPhase, List<string>? activePhases = null, string? fromPhase = null)
+            => new GatherRule
+            {
+                RuleId = id,
+                Title = id,
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "phase_exit",
+                TriggerPhase = triggerPhase,
+                OutputEventType = "gather_test",
+                Enabled = true,
+                ActivePhases = activePhases,
+                ActiveFromPhase = fromPhase,
+            };
+
+        [Fact]
+        public void FiresOnceWhenTheNamedPhaseIsLeft_NotWhenItIsEntered()
+        {
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-001", "AccountSetup") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+
+            // Entering AccountSetup must NOT fire an exit rule.
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+
+            // Leaving it does.
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+            Assert.True(WaitForEventCount(1));
+        }
+
+        [Fact]
+        public void DoesNotRefireWhenThePhaseIsLeftTwice()
+        {
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-002", "AccountSetup") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+            Assert.True(WaitForEventCount(1));
+
+            // A phase can be re-entered (ESP re-reporting); the one-shot slot stays consumed.
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+            Thread.Sleep(400);
+            Assert.Equal(1, EventCount);
+        }
+
+        [Fact]
+        public void EmptyTriggerPhase_FiresOnEveryExit()
+        {
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-003", "") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup); // exit of Unknown — must NOT fire
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup); // exit of DeviceSetup
+            Assert.True(WaitForEventCount(1));
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);     // exit of AccountSetup
+            Assert.True(WaitForEventCount(2));
+        }
+
+        [Fact]
+        public void NeverFiresOnExitOfUnknown()
+        {
+            // Before the first phase signal there is no phase to leave.
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-004", "") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.Start);
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+        }
+
+        [Fact]
+        public void RepeatedSamePhaseSignal_IsNotAnExit()
+        {
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-005", "") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup); // same phase — no transition
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+        }
+
+        [Fact]
+        public void FiresOnTransitionIntoFailed_CapturingStateAtTheFailurePoint()
+        {
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-006", "AccountSetup") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.Failed);
+
+            Assert.True(WaitForEventCount(1), "leaving a phase into Failed must still snapshot it");
+        }
+
+        [Fact]
+        public void FiresOnExitOfCompleteOnly_WhenCompleteIsActuallyLeft()
+        {
+            // "End of enrollment" is better served by phase_change on Complete / on_event; an exit
+            // rule on Complete only fires if a later transition happens at all.
+            _executor.UpdateRules(new List<GatherRule> { ExitRule("GATHER-PX-007", "Complete") });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.FinalizingSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.Complete);
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+        }
+
+        [Fact]
+        public void ScopeGate_EvaluatesAgainstThePhaseBeingLeft()
+        {
+            // Scope = only during DeviceSetup. Leaving DeviceSetup must fire (the rule is still in
+            // scope at that instant) even though the NEW phase is outside the scope.
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                ExitRule("GATHER-PX-010", "DeviceSetup", activePhases: new List<string> { "DeviceSetup" })
+            });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+
+            Assert.True(WaitForEventCount(1),
+                "the scope gate must see the phase being left, not the one being entered");
+        }
+
+        [Fact]
+        public void OutOfScopeExit_DoesNotFire_AndDoesNotConsumeTheOneShotSlot()
+        {
+            // Scope = only during AccountSetup; the rule exits DeviceSetup while out of scope.
+            var rule = ExitRule("GATHER-PX-011", "", activePhases: new List<string> { "AccountSetup" });
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup); // exit of DeviceSetup: out of scope
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);     // exit of AccountSetup: in scope
+            Assert.True(WaitForEventCount(1));
+        }
+
+        [Fact]
+        public void ExitAndChangeRulesForTheSamePhase_BothFireIndependently()
+        {
+            // The dedup key spaces must not collide: same ruleId shape, same phase, different trigger.
+            var enter = new GatherRule
+            {
+                RuleId = "GATHER-PX-020",
+                Title = "enter",
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "phase_change",
+                TriggerPhase = "AccountSetup",
+                OutputEventType = "gather_test",
+                Enabled = true,
+            };
+            var exit = ExitRule("GATHER-PX-021", "AccountSetup");
+            _executor.UpdateRules(new List<GatherRule> { enter, exit });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.True(WaitForEventCount(1)); // enter fired
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+            Assert.True(WaitForEventCount(2)); // exit fired
+        }
+
+        [Fact]
+        public void ExitRuleWithEmitOnChange_StillEmitsItsFirstResult()
+        {
+            var rule = ExitRule("GATHER-PX-030", "AccountSetup");
+            rule.EmitMode = "on_change";
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+
+            Assert.True(WaitForEventCount(1));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleExecutorPhaseScopeTests.cs

@@ -63,7 +63,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
 
         /// <summary>Interval rule with a 1h period — the timer never ticks within a test run,
         /// so these rules exist purely for synchronous scope-matrix assertions.</summary>
-        private static GatherRule ScopeProbeRule(string id, List<string> activePhases = null, string fromPhase = null)
+        private static GatherRule ScopeProbeRule(string id, List<string>? activePhases = null, string? fromPhase = null)
             => new GatherRule
             {
                 RuleId = id,
@@ -78,7 +78,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
                 ActiveFromPhase = fromPhase,
             };
 
-        private static GatherRule StartupRule(string id, List<string> activePhases = null, string fromPhase = null)
+        private static GatherRule StartupRule(string id, List<string>? activePhases = null, string? fromPhase = null)
             => new GatherRule
             {
                 RuleId = id,

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/LogParserCollectorDebugLogTests.cs

@@ -0,0 +1,169 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
+{
+    /// <summary>
+    /// Debug-trace coverage of <see cref="LogParserCollector"/>: the classic
+    /// "rule delivers nothing" cases must be explained in the trace — zero matches,
+    /// position-tracker skips, and plain-text logs parsed in the default cmtrace mode.
+    /// </summary>
+    public sealed class LogParserCollectorDebugLogTests : IDisposable
+    {
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly List<EnrollmentEvent> _events = new List<EnrollmentEvent>();
+        private readonly GatherRuleContext _context;
+        private readonly string _debugLogPath;
+
+        // %TEMP% lives under C:\Users (hard-blocked) — parse targets sit beside the
+        // test assembly instead, admitted via UnrestrictedMode.
+        private readonly string _outsideUsers = Path.Combine(
+            AppContext.BaseDirectory, "gather-debug-tests-" + Guid.NewGuid().ToString("N"));
+
+        public LogParserCollectorDebugLogTests()
+        {
+            Directory.CreateDirectory(_outsideUsers);
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            _debugLogPath = Path.Combine(_tmp.Path, "gather_rules_debug.log");
+            _context = new GatherRuleContext(
+                logger, "sess", "tenant",
+                evt => _events.Add(evt),
+                null,
+                new LogFilePositionTracker(),
+                new GatherRuleDebugLog(_debugLogPath, logger))
+            {
+                UnrestrictedMode = true
+            };
+        }
+
+        public void Dispose()
+        {
+            _tmp.Dispose();
+            try { Directory.Delete(_outsideUsers, recursive: true); } catch { /* best effort */ }
+        }
+
+        private string TraceContent() => File.Exists(_debugLogPath) ? File.ReadAllText(_debugLogPath) : string.Empty;
+
+        private static GatherRule Rule(string target, string pattern, string? format = null) => new GatherRule
+        {
+            RuleId = "GATHER-LP-DEBUG",
+            Title = "logparser debug test",
+            CollectorType = "logparser",
+            Target = target,
+            Parameters = format == null
+                ? new Dictionary<string, string> { ["pattern"] = pattern }
+                : new Dictionary<string, string> { ["pattern"] = pattern, ["format"] = format },
+            Trigger = "startup",
+            OutputEventType = "logparser_debug_test",
+        };
+
+        [Fact]
+        public void ZeroMatches_writes_per_file_outcome_line()
+        {
+            var path = Path.Combine(_outsideUsers, "app.log");
+            File.WriteAllText(path, "nothing interesting\nstill nothing\n");
+
+            new LogParserCollector().Execute(Rule(path, "WILL_NEVER_MATCH_[0-9]+", format: "text"), _context);
+
+            Assert.Empty(_events);
+            var trace = TraceContent();
+            Assert.Contains("app.log: read 2 lines", trace);
+            Assert.Contains("matched 0", trace);
+            Assert.Contains("mode=text", trace);
+        }
+
+        [Fact]
+        public void SecondRun_without_new_content_traces_position_skip()
+        {
+            var path = Path.Combine(_outsideUsers, "twice.log");
+            File.WriteAllText(path, "one line\n");
+            var rule = Rule(path, "one", format: "text");
+
+            var collector = new LogParserCollector();
+            collector.Execute(rule, _context);   // reads the file, advances the position
+            collector.Execute(rule, _context);   // nothing new
+
+            Assert.Contains("twice.log: no new content (position", TraceContent());
+        }
+
+        [Fact]
+        public void PlainTextFile_in_default_cmtrace_mode_gets_format_hint()
+        {
+            var path = Path.Combine(_outsideUsers, "plain.log");
+            File.WriteAllText(path, "plain line one\nplain line two\n");
+
+            new LogParserCollector().Execute(Rule(path, "plain"), _context); // default = cmtrace mode
+
+            Assert.Empty(_events);
+            var trace = TraceContent();
+            Assert.Contains("parseFailures=2", trace);
+            Assert.Contains("every line failed CMTrace parsing — if this is a plain-text log, set parameter format=text", trace);
+        }
+
+        [Fact]
+        public void Match_traces_line_number_matched_text_and_groups()
+        {
+            var path = Path.Combine(_outsideUsers, "match.log");
+            File.WriteAllText(path, "boring line\nError 0x80070005 in setup\n");
+
+            new LogParserCollector().Execute(
+                Rule(path, @"Error (?<code>0x[0-9A-Fa-f]+)", format: "text"), _context);
+
+            Assert.Single(_events);
+            var trace = TraceContent();
+            Assert.Contains("match.log: line 2 matched \"Error 0x80070005\"", trace);
+            Assert.Contains("groups: code=\"0x80070005\"", trace);
+        }
+
+        [Fact]
+        public void MatchTraces_are_capped_per_file()
+        {
+            var path = Path.Combine(_outsideUsers, "many.log");
+            var sb = new System.Text.StringBuilder();
+            for (var i = 1; i <= 15; i++)
+                sb.Append("hit number ").Append(i).Append('\n');
+            File.WriteAllText(path, sb.ToString());
+
+            new LogParserCollector().Execute(Rule(path, "hit", format: "text"), _context);
+
+            Assert.Equal(15, _events.Count); // all matches still emit events
+            var trace = TraceContent();
+            Assert.Contains("many.log: line 10 matched", trace);
+            Assert.Contains("further matches not traced individually", trace);
+            Assert.DoesNotContain("many.log: line 11 matched", trace);
+            Assert.Contains("matched 15", trace); // summary still carries the full count
+        }
+
+        [Fact]
+        public void InvalidRegex_traces_the_pattern_itself()
+        {
+            var path = Path.Combine(_outsideUsers, "irrelevant.log");
+            File.WriteAllText(path, "content\n");
+
+            new LogParserCollector().Execute(Rule(path, "([unclosed", format: "text"), _context);
+
+            Assert.Empty(_events);
+            var trace = TraceContent();
+            Assert.Contains("invalid regex pattern '([unclosed'", trace);
+            Assert.Contains("rule can never match", trace);
+        }
+
+        [Fact]
+        public void MissingFile_traces_no_files_matched()
+        {
+            var path = Path.Combine(_outsideUsers, "does-not-exist.log");
+
+            new LogParserCollector().Execute(Rule(path, "x", format: "text"), _context);
+
+            Assert.Contains("no files matched target", TraceContent());
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Ime/CmTraceLogParserTests.cs

@@ -1,5 +1,5 @@
 using System;
-using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
+using AutopilotMonitor.Shared.Logging;
 using Xunit;
 
 namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Ime
@@ -27,7 +27,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Ime
         [InlineData("   ")]                                    // whitespace only
         [InlineData("<![LOG[truncated line with no closing")]  // truncated / missing fields
         [InlineData("garbage prefix <![LOG[msg]LOG]!><time=\"06:08:04.8834397\" date=\"2-8-2026\" component=\"C\" context=\"\" type=\"1\" thread=\"1\" file=\"\">")] // leading junk (non-ignorable) fails the StartsWith gate
-        public void TryParseLine_returns_false_without_throwing_for_malformed_input(string line)
+        public void TryParseLine_returns_false_without_throwing_for_malformed_input(string? line)
         {
             var ok = CmTraceLogParser.TryParseLine(line, out var entry);
 
@@ -92,6 +92,28 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Ime
             Assert.InRange(entry.Timestamp, before.AddSeconds(-5), after.AddSeconds(5));
         }
 
+        // ── UTC-bias suffix on the time field → honored, not dropped ──────────
+
+        [Theory]
+        [InlineData("+480", 8 * 60)]   // PST writer (UTC-8): UTC = local + 480min
+        [InlineData("-060", -60)]      // UTC+1 writer: UTC = local - 60min
+        public void TryParseLine_applies_utc_bias_suffix(string bias, int expectedOffsetMinutes)
+        {
+            // Session df1fcf47: a writer whose timezone differs from the agent's stamped its
+            // lines with an explicit bias. Without bias handling the line either failed to
+            // match at all (old regex) or would be misread in agent-local time.
+            var line = CmTraceLine("msg", "11:46:19.0226610" + bias, "7-29-2026");
+
+            var ok = CmTraceLogParser.TryParseLine(line, out var entry);
+
+            Assert.True(ok);
+            Assert.NotNull(entry);
+            Assert.Equal(
+                new DateTime(2026, 7, 29, 11, 46, 19, DateTimeKind.Utc).AddTicks(226610).AddMinutes(expectedOffsetMinutes),
+                entry.Timestamp);
+            Assert.Equal(DateTimeKind.Utc, entry.Timestamp.Kind);
+        }
+
         // ── Oversized line → parses, no throw, no truncation of the message ───
 
         [Fact]

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Ime/ImeLogPatternReDoSTests.cs

@@ -24,12 +24,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Ime
     /// </summary>
     public sealed class ImeLogPatternReDoSTests
     {
-        private static ImeLogPattern Pattern(string id, string regex, string action = null) => new ImeLogPattern
+        private static ImeLogPattern Pattern(string id, string regex, string? action = null) => new ImeLogPattern
         {
             PatternId = id,
             Pattern = regex,
             Category = "always",
-            Action = action,
+            // Action is optional on the wire (absent = null); the model declares it non-nullable.
+            Action = action!,
             Enabled = true,
             Parameters = new Dictionary<string, string>(),
         };

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Ime/ImeLogTrackerHistoricReplayGuardTests.cs

@@ -0,0 +1,166 @@
+using System;
+using System.Collections.Generic;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Ime
+{
+    /// <summary>
+    /// Tracker-level historic-replay guard (session eaf3d8c4 part 2): source lines > 24 h older
+    /// than now are content from a previous enrollment whose IME log survived on disk. The guard
+    /// in <c>HandlePatternMatch</c> skips app-mutating actions for such lines so replayed apps
+    /// never enter <c>_packageStates</c> / phase snapshots / persistence — keeping
+    /// app_tracking_summary, culprit lists and final-status clean. Script actions pass through
+    /// (the adapter suppresses their emissions), and SimulationMode bypasses the guard entirely.
+    /// </summary>
+    public sealed class ImeLogTrackerHistoricReplayGuardTests
+    {
+        private static readonly DateTime Now = new DateTime(2026, 7, 23, 15, 42, 0, DateTimeKind.Utc);
+
+        private static List<ImeLogPattern> TestPatterns() => new List<ImeLogPattern>
+        {
+            new ImeLogPattern
+            {
+                PatternId = "T-POLICIES", Category = "always", Enabled = true,
+                Pattern = @"policies discovered = (?<policies>\[.*\])",
+                Action = "policiesDiscovered",
+                Parameters = new Dictionary<string, string>(),
+            },
+            new ImeLogPattern
+            {
+                PatternId = "T-INSTALLED", Category = "always", Enabled = true,
+                Pattern = @"app (?<id>[\w-]+) installed",
+                Action = "updateStateInstalled",
+                Parameters = new Dictionary<string, string>(),
+            },
+            new ImeLogPattern
+            {
+                PatternId = "T-ESP-PHASE", Category = "always", Enabled = true,
+                Pattern = @"In EspPhase: (?<espPhase>\w+)",
+                Action = "espPhaseDetected",
+                Parameters = new Dictionary<string, string>(),
+            },
+            new ImeLogPattern
+            {
+                PatternId = "T-SCRIPT-START", Category = "always", Enabled = true,
+                Pattern = @"script (?<id>[\w-]+) started",
+                Action = "scriptStarted",
+                Parameters = new Dictionary<string, string> { ["scriptType"] = "platform" },
+            },
+        };
+
+        private static ImeLogTracker BuildTracker(TempDirectory tmp)
+        {
+            var tracker = new ImeLogTracker(
+                logFolder: tmp.Path,
+                patterns: TestPatterns(),
+                logger: new AgentLogger(tmp.Path, AgentLogLevel.Info));
+            tracker.UtcNowProvider = () => Now;
+            return tracker;
+        }
+
+        private const string PoliciesLine = @"policies discovered = [{""Id"":""app-1"",""Name"":""App One""}]";
+
+        [Fact]
+        public void Stale_policies_line_does_not_populate_package_states()
+        {
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+
+            tracker.ProcessLogMessageForTest(PoliciesLine, Now.AddDays(-7));
+
+            Assert.Empty(tracker.GetAllKnownPackageStates());
+        }
+
+        [Fact]
+        public void Fresh_relog_of_same_policies_is_tracked_after_stale_skip()
+        {
+            // IME re-logs the full policy JSON on every app-policy check-in — skipping the
+            // stale copy cannot starve the current enrollment.
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+
+            tracker.ProcessLogMessageForTest(PoliciesLine, Now.AddDays(-7));
+            tracker.ProcessLogMessageForTest(PoliciesLine, Now.AddMinutes(-2));
+
+            var all = tracker.GetAllKnownPackageStates();
+            var pkg = Assert.Single(all);
+            Assert.Equal("app-1", pkg.Id);
+        }
+
+        [Fact]
+        public void Stale_state_update_against_fresh_app_is_skipped()
+        {
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+            var stateChanges = 0;
+            tracker.OnAppStateChanged = (_, __, ___) => stateChanges++;
+
+            tracker.ProcessLogMessageForTest(PoliciesLine, Now.AddMinutes(-5));   // fresh discovery
+            tracker.ProcessLogMessageForTest("app app-1 installed", Now.AddDays(-7)); // stale mutation
+
+            Assert.Equal(0, stateChanges);
+            var pkg = Assert.Single(tracker.GetAllKnownPackageStates());
+            Assert.NotEqual(AppInstallationState.Installed, pkg.InstallationState);
+        }
+
+        [Fact]
+        public void Stale_esp_phase_line_does_not_block_fresh_phase_detection()
+        {
+            // A stale "AccountSetup" would advance _currentPhaseOrder and make the fresh
+            // enrollment's DeviceSetup bounce as "backward" — the guard must skip it.
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+            var phases = new List<string>();
+            tracker.OnEspPhaseChanged = p => phases.Add(p);
+
+            tracker.ProcessLogMessageForTest("In EspPhase: AccountSetup", Now.AddDays(-7));
+            tracker.ProcessLogMessageForTest("In EspPhase: DeviceSetup", Now.AddMinutes(-1));
+
+            Assert.Equal(new[] { "DeviceSetup" }, phases);
+        }
+
+        [Fact]
+        public void Stale_script_line_still_reaches_script_handlers()
+        {
+            // Script tracker state is harmless for stale lines (adapter suppresses the
+            // emissions; the stale-slot hardening covers leftovers) — the guard must not
+            // swallow script actions.
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+            var started = new List<ScriptStartedInfo>();
+            tracker.OnScriptStarted = i => started.Add(i);
+
+            tracker.ProcessLogMessageForTest("script aaaa1111-0000-0000-0000-000000000000 started", Now.AddDays(-7));
+
+            Assert.Single(started);
+        }
+
+        [Fact]
+        public void SimulationMode_bypasses_the_guard()
+        {
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+            tracker.SimulationMode = true;
+
+            tracker.ProcessLogMessageForTest(PoliciesLine, Now.AddDays(-7));
+
+            Assert.Single(tracker.GetAllKnownPackageStates());
+        }
+
+        [Fact]
+        public void Lines_without_timestamp_are_not_treated_as_stale()
+        {
+            // Non-CMTrace lines carry no source timestamp (entry == null) — never stale.
+            using var tmp = new TempDirectory();
+            using var tracker = BuildTracker(tmp);
+
+            tracker.ProcessLogMessageForTest(PoliciesLine, sourceTimestampUtc: null);
+
+            Assert.Single(tracker.GetAllKnownPackageStates());
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Interop/NetshWifiFallbackTests.cs

@@ -0,0 +1,209 @@
+#nullable enable
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Interop;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Interop
+{
+    /// <summary>
+    /// Tests for the pure netsh-output parser of the WiFi fallback path. netsh labels follow
+    /// the OS UI language — the parser must extract SSID/signal/radio/channel from the label
+    /// variants of the languages commonly seen in enrollments, and degrade gracefully (fields
+    /// absent, never throw) on unrecognized ones.
+    /// </summary>
+    public sealed class NetshWifiFallbackTests
+    {
+        [Fact]
+        public void Parse_english_output_extracts_all_fields()
+        {
+            const string output = @"
+There is 1 interface on the system:
+
+    Name                   : Wi-Fi
+    Description            : Intel(R) Wi-Fi 6 AX201 160MHz
+    GUID                   : 754b6c07-5ae9-49d5-ba6c-4fbd6e38bbf6
+    State                  : connected
+    SSID                   : contoso-corp
+    AP BSSID               : 3c:37:12:53:c8:44
+    Band                   : 5 GHz
+    Channel                : 116
+    Radio type             : 802.11ax
+    Signal                 : 94%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-corp", r!.Ssid);
+            Assert.Equal(94, r.SignalPercent);
+            Assert.Equal("802.11ax", r.RadioType);
+            Assert.Equal(116, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_german_output_extracts_all_fields()
+        {
+            const string output = @"
+Es ist 1 Schnittstelle auf dem System vorhanden:
+
+    Name                   : WLAN
+    Beschreibung           : Intel(R) Wi-Fi 6 AX201 160MHz
+    Status                 : Verbunden
+    SSID                   : fabrikam-wlan
+    Kanal                  : 44
+    Funktyp                : 802.11ac
+    Signal                 : 87%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("fabrikam-wlan", r!.Ssid);
+            Assert.Equal(87, r.SignalPercent);
+            Assert.Equal("802.11ac", r.RadioType);
+            Assert.Equal(44, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_spanish_output_extracts_signal_and_channel()
+        {
+            const string output = @"
+    Nombre                 : Wi-Fi
+    SSID                   : contoso-es
+    Canal                  : 6
+    Tipo de radio          : 802.11n
+    Señal                  : 72%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-es", r!.Ssid);
+            Assert.Equal(72, r.SignalPercent);
+            Assert.Equal("802.11n", r.RadioType);
+            Assert.Equal(6, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_chinese_simplified_output_extracts_all_fields()
+        {
+            const string output = @"
+    名称                   : WLAN
+    SSID                   : contoso-cn
+    信道                   : 149
+    无线电类型             : 802.11ac
+    信号                   : 68%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-cn", r!.Ssid);
+            Assert.Equal(68, r.SignalPercent);
+            Assert.Equal("802.11ac", r.RadioType);
+            Assert.Equal(149, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_korean_output_extracts_all_fields()
+        {
+            const string output = @"
+    이름                   : Wi-Fi
+    SSID                   : contoso-kr
+    채널                   : 36
+    라디오 종류            : 802.11ax
+    신호                   : 91%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-kr", r!.Ssid);
+            Assert.Equal(91, r.SignalPercent);
+            Assert.Equal("802.11ax", r.RadioType);
+            Assert.Equal(36, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_signal_with_space_before_percent_is_parsed()
+        {
+            var r = NetshWifiFallback.Parse("    Signal : 81 %\r\n    SSID : x\r\n");
+
+            Assert.NotNull(r);
+            Assert.Equal(81, r!.SignalPercent);
+        }
+
+        [Fact]
+        public void Parse_ap_bssid_does_not_overwrite_ssid()
+        {
+            const string output = @"
+    SSID                   : contoso-corp
+    AP BSSID               : aa:bb:cc:dd:ee:ff
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.Equal("contoso-corp", r!.Ssid);
+        }
+
+        [Fact]
+        public void Parse_finnish_output_extracts_all_fields()
+        {
+            const string output = @"
+    Nimi                   : Wi-Fi
+    SSID                   : contoso-fi
+    Kanava                 : 100
+    Radiotyyppi            : 802.11ax
+    Signaali               : 79%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-fi", r!.Ssid);
+            Assert.Equal(79, r.SignalPercent);
+            Assert.Equal("802.11ax", r.RadioType);
+            Assert.Equal(100, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_indonesian_output_extracts_all_fields()
+        {
+            const string output = @"
+    Nama                   : Wi-Fi
+    SSID                   : contoso-id
+    Saluran                : 11
+    Jenis radio            : 802.11n
+    Sinyal                 : 64%
+";
+            var r = NetshWifiFallback.Parse(output);
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-id", r!.Ssid);
+            Assert.Equal(64, r.SignalPercent);
+            Assert.Equal("802.11n", r.RadioType);
+            Assert.Equal(11, r.Channel);
+        }
+
+        [Fact]
+        public void Parse_unknown_language_without_ssid_returns_null()
+        {
+            // Greek is not in the enrollment-geography label set -> nothing to report.
+            var r = NetshWifiFallback.Parse("    Κατάσταση : συνδεδεμένο\r\n    Σήμα : 90%\r\n");
+
+            Assert.Null(r);
+        }
+
+        [Fact]
+        public void Parse_unknown_language_still_yields_ssid()
+        {
+            // SSID is untranslated in all locales — partial result beats none.
+            var r = NetshWifiFallback.Parse("    SSID : contoso-gr\r\n    Σήμα : 90%\r\n");
+
+            Assert.NotNull(r);
+            Assert.Equal("contoso-gr", r!.Ssid);
+            Assert.Null(r.SignalPercent);
+        }
+
+        [Theory]
+        [InlineData(null)]
+        [InlineData("")]
+        [InlineData("Der WLAN-AutoKonfig-Dienst (wlansvc) wird nicht ausgeführt.")]
+        public void Parse_empty_or_error_output_returns_null(string? output)
+        {
+            Assert.Null(NetshWifiFallback.Parse(output));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Interop/WifiInfoReaderTests.cs

@@ -0,0 +1,98 @@
+#nullable enable
+using System.Text;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Interop;
+using Xunit;
+using static AutopilotMonitor.Agent.V2.Core.Monitoring.Interop.WlanNativeMethods;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Interop
+{
+    /// <summary>
+    /// Tests for the native-WLAN-API WiFi reader. The WLAN state of the test machine is
+    /// unknown (CI runners/VMs have no WLAN service), so the live path only pins the
+    /// fail-soft contract; the pure helpers (SSID decode, PHY-type mapping) are pinned
+    /// exactly — their output feeds wifi_signal_info event payloads and must stay
+    /// consistent with the strings netsh historically reported.
+    /// </summary>
+    public sealed class WifiInfoReaderTests
+    {
+        [Fact]
+        public void TryGetCurrentConnection_never_throws_and_returns_sane_values()
+        {
+            var result = WifiInfoReader.TryGetCurrentConnection();
+
+            if (result != null)
+            {
+                Assert.True(result.SignalPercent.HasValue, "native API path must always carry signal quality");
+                Assert.InRange(result.SignalPercent.Value, 0, 100);
+                if (result.Channel.HasValue)
+                    Assert.True(result.Channel.Value > 0, "channel must be positive when present");
+            }
+        }
+
+        // ----- DecodeSsid ---------------------------------------------------
+
+        [Fact]
+        public void DecodeSsid_decodes_utf8_bytes()
+        {
+            var raw = new byte[32];
+            var ssid = Encoding.UTF8.GetBytes("Contoso-Büro");
+            ssid.CopyTo(raw, 0);
+
+            Assert.Equal("Contoso-Büro", WifiInfoReader.DecodeSsid(raw, (uint)ssid.Length));
+        }
+
+        [Fact]
+        public void DecodeSsid_returns_null_for_empty_or_missing()
+        {
+            Assert.Null(WifiInfoReader.DecodeSsid(null, 5));
+            Assert.Null(WifiInfoReader.DecodeSsid(new byte[32], 0));
+        }
+
+        [Fact]
+        public void DecodeSsid_clamps_length_to_buffer_size()
+        {
+            var raw = Encoding.UTF8.GetBytes("abc");
+
+            // A corrupt native length beyond the buffer must not throw.
+            Assert.Equal("abc", WifiInfoReader.DecodeSsid(raw, 200));
+        }
+
+        [Fact]
+        public void DecodeSsid_uses_only_declared_length()
+        {
+            var raw = new byte[32];
+            Encoding.UTF8.GetBytes("HomeNet-Rest-Ignored").CopyTo(raw, 0);
+
+            Assert.Equal("HomeNet", WifiInfoReader.DecodeSsid(raw, 7));
+        }
+
+        // ----- PhyTypeToRadioType -------------------------------------------
+
+        // int parameters (cast inside): DOT11_PHY_TYPE is internal and may not appear in a
+        // public test method signature (CS0051).
+        [Theory]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_ofdm, "802.11a")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_hrdsss, "802.11b")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_erp, "802.11g")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_ht, "802.11n")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_vht, "802.11ac")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_dmg, "802.11ad")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_he, "802.11ax")]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_eht, "802.11be")]
+        public void PhyTypeToRadioType_maps_known_generations(int phyType, string expected)
+        {
+            Assert.Equal(expected, WifiInfoReader.PhyTypeToRadioType((DOT11_PHY_TYPE)phyType));
+        }
+
+        [Theory]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_unknown)]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_fhss)]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_dsss)]
+        [InlineData((int)DOT11_PHY_TYPE.dot11_phy_type_irbaseband)]
+        [InlineData(9999)]
+        public void PhyTypeToRadioType_returns_null_for_legacy_or_unknown(int phyType)
+        {
+            Assert.Null(WifiInfoReader.PhyTypeToRadioType((DOT11_PHY_TYPE)phyType));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Office/OfficeBinaryWatcherTests.cs

@@ -17,6 +17,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Office
     /// cadence and stops at its bound, is idempotent, the initial scan raises when binaries already
     /// exist, a filesystem create raises, and Dispose cancels the re-probe.
     /// </summary>
+    [Collection("SerialThreading")] // the bounded re-probe runs on the shared ThreadPool
     public sealed class OfficeBinaryWatcherTests
     {
         private static readonly string[] CoreBinaries = { "WINWORD.EXE", "EXCEL.EXE", "POWERPNT.EXE", "OUTLOOK.EXE" };

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/OobeStateReaderTests.cs

@@ -0,0 +1,40 @@
+#nullable enable
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Interop;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring
+{
+    /// <summary>
+    /// Smoke tests for the WinRT <c>SystemSetupInfo.OutOfBoxExperienceState</c> reader.
+    /// The actual state on the test machine is unknown (CI runners are post-OOBE; Server
+    /// SKUs may lack the UniversalApiContract entirely), so only the fail-soft contract
+    /// is pinned: never throw, always return a member of the known value set.
+    /// </summary>
+    public sealed class OobeStateReaderTests
+    {
+        [Fact]
+        public void Read_never_throws_and_returns_known_value()
+        {
+            var value = OobeStateReader.Read();
+
+            Assert.False(string.IsNullOrEmpty(value));
+            Assert.True(
+                value == "not_started"
+                || value == "in_progress"
+                || value == "completed"
+                || value == OobeStateReader.Unavailable
+                || value.StartsWith("unknown_"),
+                $"unexpected reader value '{value}'");
+        }
+
+        [Fact]
+        public void Read_is_stable_across_repeated_calls()
+        {
+            // Exercises the cached-PropertyInfo path (second call skips resolution).
+            var first = OobeStateReader.Read();
+            var second = OobeStateReader.Read();
+
+            Assert.Equal(first, second);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Runtime/CleanupServiceScriptIntegrationTests.cs

@@ -0,0 +1,208 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime;
+using AutopilotMonitor.Agent.V2.Core.Security;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Runtime
+{
+    /// <summary>
+    /// Executes the generated cleanup script against REAL scratch trees with a real
+    /// powershell.exe — end-to-end replays of the 2026-07-22 incident mechanics that the
+    /// string pins in <see cref="CleanupServiceScriptTests"/> cannot prove:
+    /// <list type="bullet">
+    ///   <item>a locked tree must abort WITHOUT deleting anything (old script force-deleted
+    ///     marker + state around the locks and orphaned the binaries),</item>
+    ///   <item>a straggler agent process (the incident's second instance) must be found by
+    ///     NAME, killed, and the cleanup must then complete — simulated via function
+    ///     shadowing, NEVER by launching a renamed executable (EDR isolation, see the test),</item>
+    ///   <item>concurrent cleanup scripts must be serialized by the lock file.</item>
+    /// </list>
+    /// Timings are dialed down via the test-only BuildCleanupScript parameters so each case
+    /// runs in seconds. Every test uses GUID-unique process/task/tree names so nothing real
+    /// (a dev-box agent, a real Scheduled Task) can ever be touched.
+    /// </summary>
+    [Collection("SerialThreading")]
+    public class CleanupServiceScriptIntegrationTests : IDisposable
+    {
+        private readonly string _root;
+        private readonly string _basePath;
+        private readonly string _taskName = $"AmTest-NoSuchTask-{Guid.NewGuid():N}";
+        private readonly string _fakeProcessName = $"AmTestAgent{Guid.NewGuid().ToString("N").Substring(0, 8)}";
+
+        public CleanupServiceScriptIntegrationTests()
+        {
+            _root = Path.Combine(Path.GetTempPath(), $"am-cleanup-it-{Guid.NewGuid():N}");
+            _basePath = Path.Combine(_root, "AutopilotMonitor");
+            Directory.CreateDirectory(Path.Combine(_basePath, "Agent"));
+            Directory.CreateDirectory(Path.Combine(_basePath, "State"));
+            Directory.CreateDirectory(Path.Combine(_basePath, "Logs"));
+            File.WriteAllText(Path.Combine(_basePath, "Agent", "fake.exe"), "x");
+            File.WriteAllText(Path.Combine(_basePath, "State", "enrollment-complete.marker"), "x");
+            File.WriteAllText(Path.Combine(_basePath, "Logs", "agent.log"), "x");
+        }
+
+        public void Dispose()
+        {
+            try { Directory.Delete(_root, recursive: true); } catch { }
+        }
+
+        private static string LockPath => Path.Combine(Path.GetTempPath(), "AutopilotMonitor-Cleanup.lock");
+
+        private string BuildScript(bool keepLogs = false, int processWaitSeconds = 1)
+            => CleanupService.BuildCleanupScript(
+                agentProcessName: _fakeProcessName,
+                agentBasePath: _basePath,
+                keepLogs: keepLogs,
+                scheduledTaskName: _taskName,
+                rebootOnComplete: false,
+                initialDelaySeconds: 0,
+                processWaitSeconds: processWaitSeconds,
+                renameRetries: 2,
+                renameRetryDelaySeconds: 1);
+
+        /// <summary>Runs the script synchronously in a real powershell.exe. Returns the script path.</summary>
+        private string RunScript(string script)
+        {
+            var scriptPath = Path.Combine(_root, $"cleanup-{Guid.NewGuid():N}.ps1");
+            File.WriteAllText(scriptPath, script);
+            using (var proc = Process.Start(new ProcessStartInfo
+            {
+                FileName = SystemPaths.PowerShell,
+                Arguments = $"-NoProfile -ExecutionPolicy Bypass -File \"{scriptPath}\"",
+                UseShellExecute = false,
+                CreateNoWindow = true,
+            }))
+            {
+                Assert.True(proc.WaitForExit(90_000), "cleanup script did not finish within 90s");
+            }
+            return scriptPath;
+        }
+
+        [Fact]
+        public void Happy_path_deletes_tree_and_removes_lock_and_script()
+        {
+            var scriptPath = RunScript(BuildScript());
+
+            Assert.False(Directory.Exists(_basePath), "tree should be fully deleted");
+            Assert.Empty(Directory.GetFileSystemEntries(_root, "*.del-*"));
+            Assert.False(File.Exists(scriptPath), "script should self-delete");
+            Assert.False(File.Exists(LockPath), "cleanup lock should be released");
+        }
+
+        [Fact]
+        public void Locked_tree_aborts_completely_marker_and_files_survive()
+        {
+            // The incident regression: with a file locked inside the tree the OLD script
+            // deleted everything else (incl. the enrollment-complete marker) and left the
+            // binaries orphaned with the task already gone. The hardened script must treat
+            // the failed probe-rename as "someone still holds this" and walk away entirely.
+            using (File.Open(Path.Combine(_basePath, "Agent", "fake.exe"),
+                       FileMode.Open, FileAccess.Read, FileShare.None))
+            {
+                RunScript(BuildScript());
+            }
+
+            Assert.True(File.Exists(Path.Combine(_basePath, "Agent", "fake.exe")), "binaries must stay in place");
+            Assert.True(File.Exists(Path.Combine(_basePath, "State", "enrollment-complete.marker")),
+                "marker must survive so the next boot retries cleanup");
+            Assert.Empty(Directory.GetFileSystemEntries(_root, "*.del-*"));
+            Assert.False(File.Exists(LockPath));
+        }
+
+        [Fact]
+        public void Straggler_agent_process_is_waited_on_and_force_killed_via_name_backstop()
+        {
+            // Incident replay of the second-instance mechanics WITHOUT spawning a process:
+            // an earlier version of this test copied powershell.exe under the fake agent name
+            // and launched it — textbook MITRE T1036.003 ("Rename Legitimate Utilities"),
+            // which Defender for Endpoint answered with a machine ISOLATION on the dev box
+            // (see tasks/lessons.md). Instead, a harness script shadows Get-Process /
+            // Stop-Process with functions (PowerShell resolves functions before cmdlets, so
+            // the dot-sourced cleanup script binds to the stubs): Get-Process reports a live
+            // agent-named straggler on every probe; Stop-Process records the kill. This pins
+            // the same contract — the script polls by NAME until the deadline, then
+            // force-kills by NAME before deleting — with zero EDR-visible behavior.
+            var probeLog = Path.Combine(_root, "probe.log");
+            var cleanupScriptPath = Path.Combine(_root, $"cleanup-{Guid.NewGuid():N}.ps1");
+            File.WriteAllText(cleanupScriptPath, BuildScript(processWaitSeconds: 2));
+
+            var harness = @"
+$probeLog = 'LOG_PATH'
+$global:AmProbeCount = 0
+function Get-Process {
+    [CmdletBinding()]
+    param([string[]]$Name)
+    if ($Name -contains 'FAKE_NAME') {
+        $global:AmProbeCount++
+        Add-Content -Path $probeLog -Value ('probe ' + $global:AmProbeCount)
+        return [pscustomobject]@{ Name = 'FAKE_NAME'; Id = 424242 }
+    }
+    Microsoft.PowerShell.Management\Get-Process @PSBoundParameters
+}
+function Stop-Process {
+    [CmdletBinding()]
+    param([Parameter(ValueFromPipeline = $true)]$InputObject, [switch]$Force)
+    process { Add-Content -Path $probeLog -Value ('kill ' + $InputObject.Id + ' force=' + $Force) }
+}
+. 'SCRIPT_PATH'
+"
+                .Replace("LOG_PATH", probeLog)
+                .Replace("FAKE_NAME", _fakeProcessName)
+                .Replace("SCRIPT_PATH", cleanupScriptPath);
+
+            RunScript(harness);
+
+            var log = File.ReadAllLines(probeLog);
+            Assert.Contains("kill 424242 force=True", log);
+            Assert.True(Array.FindAll(log, l => l.StartsWith("probe")).Length >= 2,
+                "script must poll by name in the wait loop AND re-probe for the kill backstop");
+            Assert.False(Directory.Exists(_basePath), "after the kill the tree must be fully deleted");
+            Assert.Empty(Directory.GetFileSystemEntries(_root, "*.del-*"));
+            Assert.False(File.Exists(LockPath));
+        }
+
+        [Fact]
+        public void Fresh_foreign_lock_backs_off_without_touching_the_tree()
+        {
+            File.WriteAllText(LockPath, "held by another cleanup");
+            try
+            {
+                var scriptPath = RunScript(BuildScript());
+
+                Assert.True(File.Exists(Path.Combine(_basePath, "Agent", "fake.exe")),
+                    "loser script must not touch the tree — the lock holder owns the deletion");
+                Assert.True(File.Exists(LockPath), "foreign lock must not be deleted by the loser");
+                Assert.False(File.Exists(scriptPath), "loser still self-deletes its script");
+            }
+            finally
+            {
+                try { File.Delete(LockPath); } catch { }
+            }
+        }
+
+        [Fact]
+        public void Stale_foreign_lock_is_taken_over_and_cleanup_proceeds()
+        {
+            File.WriteAllText(LockPath, "crashed cleanup from a previous boot");
+            File.SetLastWriteTime(LockPath, DateTime.Now.AddMinutes(-15));
+
+            RunScript(BuildScript());
+
+            Assert.False(Directory.Exists(_basePath), "stale lock must be taken over, cleanup must run");
+            Assert.False(File.Exists(LockPath));
+        }
+
+        [Fact]
+        public void KeepLogs_variant_deletes_everything_except_logs()
+        {
+            RunScript(BuildScript(keepLogs: true));
+
+            Assert.True(File.Exists(Path.Combine(_basePath, "Logs", "agent.log")), "Logs must survive");
+            Assert.False(Directory.Exists(Path.Combine(_basePath, "Agent")));
+            Assert.False(Directory.Exists(Path.Combine(_basePath, "State")));
+            Assert.Empty(Directory.GetFileSystemEntries(_basePath, "*.del-*"));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Runtime/CleanupServiceScriptTests.cs

@@ -0,0 +1,135 @@
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Runtime
+{
+    /// <summary>
+    /// Pins the LIFE-F7 hardening invariants of the self-destruct cleanup script
+    /// (incident 2026-07-22: a second agent instance held exe + loaded DLLs while the
+    /// old script — waiting on the launcher PID only — force-deleted around the locks
+    /// AFTER removing the Scheduled Task, orphaning the binaries with no retry path).
+    /// These are string-level pins on <see cref="CleanupService.BuildCleanupScript"/>:
+    /// weakening any of them silently re-introduces the orphaned-binaries failure mode.
+    /// </summary>
+    public class CleanupServiceScriptTests
+    {
+        private const string ProcessName = "AutopilotMonitor.Agent";
+        private const string BasePath = @"C:\ProgramData\AutopilotMonitor";
+        private const string TaskName = "AutopilotMonitorAgent";
+
+        private static string Script(bool keepLogs = false, bool reboot = false)
+            => CleanupService.BuildCleanupScript(ProcessName, BasePath, keepLogs, TaskName, reboot);
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Waits_by_process_name_not_launcher_pid(bool keepLogs)
+        {
+            var script = Script(keepLogs);
+
+            // LIFE-F7 #2: name-based wait covers marker-retry / self-update / manual instances
+            // and is immune to PID reuse. Wait-Process -Id saw exactly one PID and nothing else.
+            Assert.Contains($"Get-Process -Name '{ProcessName}'", script);
+            Assert.DoesNotContain("Wait-Process", script);
+
+            // Backstop: stragglers are force-killed — their images are deleted right after.
+            Assert.Contains("Stop-Process -Force", script);
+        }
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Never_deletes_the_original_path(bool keepLogs)
+        {
+            var script = Script(keepLogs);
+
+            // LIFE-F7 #3: deletion happens exclusively on successfully renamed targets
+            // ($entry.Renamed). A Remove-Item against the original tree is what deleted
+            // marker + state around locked binaries in the incident.
+            Assert.DoesNotContain($"Remove-Item -Path '{BasePath}'", script);
+            Assert.Contains("Remove-Item -Path $entry.Renamed", script);
+        }
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Task_removal_is_gated_on_probe_and_deletion_on_task_gone(bool keepLogs)
+        {
+            var script = Script(keepLogs);
+
+            // Probe-rename first; only a successful probe reaches task removal, and only a
+            // removed task reaches deletion. Both failure branches rename BACK so the next
+            // boot retries with task + marker + files intact.
+            Assert.Contains("if ($probeOk)", script);
+            Assert.Contains("if ($taskGone)", script);
+            Assert.Contains("Rename-Item -Path $entry.Renamed -NewName $entry.Original", script);
+
+            // LIFE-F6 task-removal loop + module-independent fallback stay intact.
+            Assert.Contains("Unregister-ScheduledTask -TaskName $taskName", script);
+            Assert.Contains("schtasks.exe /Delete /TN $taskName /F", script);
+        }
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Concurrent_cleanup_scripts_are_serialized_by_lock_file(bool keepLogs)
+        {
+            var script = Script(keepLogs);
+
+            // LIFE-F7 #1: CreateNew is the atomic single-flight gate; the loser exits without
+            // touching the tree. Stale locks (>10 min) are taken over.
+            Assert.Contains("AutopilotMonitor-Cleanup.lock", script);
+            Assert.Contains("[System.IO.FileMode]::CreateNew", script);
+            Assert.Contains("$lockAge.TotalMinutes -gt 10", script);
+        }
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Rename_targets_carry_a_guid_suffix(bool keepLogs)
+        {
+            // A fixed '.del' target collides with leftovers of earlier attempts and with a
+            // concurrent script's rename — the GUID makes every attempt's target unique.
+            Assert.Contains(".del-' + [Guid]::NewGuid().ToString('N')", Script(keepLogs));
+        }
+
+        [Fact]
+        public void KeepLogs_variant_excludes_logs_directory()
+        {
+            var script = Script(keepLogs: true);
+            Assert.Contains("-Exclude 'Logs'", script);
+            Assert.DoesNotContain($"Rename-Item -Path '{BasePath}' -NewName", script);
+        }
+
+        [Fact]
+        public void Full_variant_renames_the_whole_tree()
+        {
+            var script = Script(keepLogs: false);
+            Assert.Contains($"Rename-Item -Path '{BasePath}' -NewName $renamedPath", script);
+            Assert.DoesNotContain("-Exclude 'Logs'", script);
+        }
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Reboot_flag_controls_shutdown_invocation(bool reboot)
+        {
+            var script = Script(keepLogs: false, reboot: reboot);
+            if (reboot)
+                Assert.Contains("shutdown.exe /r /t 10", script);
+            else
+                Assert.DoesNotContain("shutdown.exe", script);
+        }
+
+        [Theory]
+        [InlineData(false)]
+        [InlineData(true)]
+        public void Script_and_lock_are_released_in_finally(bool keepLogs)
+        {
+            var script = Script(keepLogs);
+            Assert.Contains("finally", script);
+            Assert.Contains("$lockStream.Dispose()", script);
+            Assert.Contains("Remove-Item -Path $scriptPath -Force", script);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Runtime/DiagnosticsPackageServiceTests.cs

@@ -226,6 +226,95 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Runtime
             return archive.Entries.Select(e => e.FullName).ToArray();
         }
 
+        private static string ZipEntryText(byte[] zipBytes, string entryName)
+        {
+            using var ms = new MemoryStream(zipBytes);
+            using var archive = new ZipArchive(ms, ZipArchiveMode.Read);
+            var entry = archive.GetEntry(entryName);
+            Assert.NotNull(entry);
+            using var reader = new StreamReader(entry!.Open(), Encoding.UTF8);
+            return reader.ReadToEnd();
+        }
+
+        // ── Nullable outcome (on-demand mid-session) — gate + sessioninfo semantics ──
+
+        /// <summary>
+        /// Sentinel subclass: throws before any HTTP so gate-pass-through is observable as a
+        /// non-null error result (a skip returns null BEFORE the archive is ever built).
+        /// </summary>
+        private sealed class ThrowOnBuildService : DiagnosticsPackageService
+        {
+            public ThrowOnBuildService(AgentConfiguration cfg, AgentLogger logger, BackendApiClient api)
+                : base(cfg, logger, api) { }
+            internal override byte[] BuildArchiveBytes(bool? enrollmentSucceeded) =>
+                throw new System.InvalidOperationException("gate-passed-sentinel");
+        }
+
+        private static DiagnosticsPackageService BuildGateProbe(AgentLogger logger, string mode)
+        {
+            var cfg = Cfg();
+            cfg.DiagnosticsUploadEnabled = true;
+            cfg.DiagnosticsUploadMode = mode;
+            var apiClient = new BackendApiClient(
+                httpClient: new System.Net.Http.HttpClient(),
+                baseUrl: "http://localhost",
+                manufacturer: string.Empty,
+                model: string.Empty,
+                serialNumber: string.Empty,
+                useBootstrapTokenAuth: false,
+                bootstrapToken: null,
+                agentVersion: "0.0.0",
+                logger: logger);
+            return new ThrowOnBuildService(cfg, logger, apiClient);
+        }
+
+        [Fact]
+        public async System.Threading.Tasks.Task CreateAndUploadAsync_null_outcome_passes_OnFailure_gate()
+        {
+            // On-demand mid-session (no outcome yet): the OnFailure gate must NOT skip —
+            // there is no known success to skip on. Reaching the archive build (sentinel
+            // throw → error result) proves the gate was passed; a skip would return null.
+            using var rig = new Rig();
+            var result = await BuildGateProbe(rig.Logger, "OnFailure")
+                .CreateAndUploadAsync(enrollmentSucceeded: null, fileNameSuffix: "server-requested");
+
+            Assert.NotNull(result);
+            Assert.Equal("gate-passed-sentinel", result!.ErrorCode);
+        }
+
+        [Fact]
+        public async System.Threading.Tasks.Task CreateAndUploadAsync_known_success_still_skipped_by_OnFailure_gate()
+        {
+            using var rig = new Rig();
+            var result = await BuildGateProbe(rig.Logger, "OnFailure")
+                .CreateAndUploadAsync(enrollmentSucceeded: true);
+
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public async System.Threading.Tasks.Task CreateAndUploadAsync_null_outcome_still_blocked_by_mode_Off()
+        {
+            using var rig = new Rig();
+            var result = await BuildGateProbe(rig.Logger, "Off")
+                .CreateAndUploadAsync(enrollmentSucceeded: null);
+
+            Assert.Null(result);
+        }
+
+        [Theory]
+        [InlineData(true, "Succeeded")]
+        [InlineData(false, "Failed")]
+        [InlineData(null, "In Progress")]
+        public void BuildArchiveBytes_sessioninfo_reflects_nullable_outcome(bool? outcome, string expected)
+        {
+            using var rig = new Rig();
+            var bytes = rig.Build().BuildArchiveBytes(outcome);
+
+            var sessionInfo = ZipEntryText(bytes, "sessioninfo.txt");
+            Assert.Contains($"Enrollment Result: {expected}", sessionInfo);
+        }
+
         // ── BuildBlobUploadUrl — destination-aware URL construction ─────────────────
 
         [Theory]

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/SystemSignals/AppxFailureAnalyzerTests.cs

@@ -256,7 +256,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
         [InlineData(null, false)]
         [InlineData("", false)]
         [InlineData("0x8007", false)]
-        public void IsAppxFamilyHresult_MatchesOnlyAppxDeploymentRange(string hresult, bool expected)
+        public void IsAppxFamilyHresult_MatchesOnlyAppxDeploymentRange(string? hresult, bool expected)
         {
             Assert.Equal(expected, AppxFailureAnalyzer.IsAppxFamilyHresult(hresult));
         }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/SystemSignals/EspFailureRecoveryStoryTests.cs

@@ -0,0 +1,256 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Agent.V2.Core.Tests.Orchestration;
+using AutopilotMonitor.DecisionCore.Engine;
+using AutopilotMonitor.DecisionCore.Signals;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
+{
+    /// <summary>
+    /// Session 4910a5a5 (2026-07-23) — post-terminal recovery story. Field sequence:
+    /// DeviceSetup/Apps failed (culprit app never started installing) → settle window expired
+    /// → terminal EspFailureDetected → the user pressed "Try again" ~23 min later → Apps left
+    /// the failed state → 10/10 installed → DeviceSetup resolved. Pre-fix, that recovery only
+    /// appeared as a generic <c>subcategory_state_change</c>. Coverage:
+    /// <list type="bullet">
+    ///   <item><c>esp_failure_retry_detected</c> fires once when the failed subcategory leaves
+    ///         the failed state AFTER the terminal fire.</item>
+    ///   <item><c>esp_failure_recovered</c> fires once when the category then resolves to
+    ///         success.</item>
+    ///   <item>An in-settle-window recovery keeps emitting only
+    ///         <c>esp_failure_settle_recovered</c> — the post-terminal pair stays silent.</item>
+    ///   <item>Apps failures carry <c>LikelyCulpritApps</c> on the EspFailureDetected args,
+    ///         never-started apps ranked first.</item>
+    /// </list>
+    /// </summary>
+    public sealed class EspFailureRecoveryStoryTests
+    {
+        private static readonly DateTime Fixed = new DateTime(2026, 7, 23, 4, 30, 0, DateTimeKind.Utc);
+
+        private sealed class Fixture : IDisposable
+        {
+            public TempDirectory Tmp { get; } = new TempDirectory();
+            public FakeSignalIngressSink Sink { get; } = new FakeSignalIngressSink();
+            public List<EspFailureDetectedEventArgs> EspFailures { get; } = new List<EspFailureDetectedEventArgs>();
+            public ProvisioningStatusTracker Tracker { get; }
+
+            public Fixture(Func<IReadOnlyList<AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppPackageState>>? packageStatesProbe = null)
+            {
+                var clock = new VirtualClock(Fixed);
+                var post = new InformationalEventPost(Sink, clock);
+                var logger = new AgentLogger(Tmp.Path, AgentLogLevel.Info);
+                Tracker = new ProvisioningStatusTracker(
+                    sessionId: "S1",
+                    tenantId: "T1",
+                    post: post,
+                    logger: logger,
+                    appxScanner: new FakeAppxDeploymentFailureScanner(),
+                    backgroundDispatcher: action => action(),
+                    packageStatesProbe: packageStatesProbe);
+                Tracker.EspFailureDetected += (_, args) => EspFailures.Add(args);
+            }
+
+            public IReadOnlyList<(string EventType, IReadOnlyDictionary<string, object> Data)> CapturedEvents()
+            {
+                return Sink.Posted
+                    .Where(p => p.Kind == DecisionSignalKind.InformationalEvent && p.Payload != null)
+                    .Select(p =>
+                    {
+                        var eventType = p.Payload!.TryGetValue(SignalPayloadKeys.EventType, out var et) ? et : "";
+                        var data = p.TypedPayload as IReadOnlyDictionary<string, object>
+                                   ?? (IReadOnlyDictionary<string, object>)new Dictionary<string, object>();
+                        return (eventType, data);
+                    })
+                    .ToList();
+            }
+
+            /// <summary>Drive the session-4910a5a5 shape up to the terminal fire.</summary>
+            public void DriveToTerminalDeviceSetupAppsFailure()
+            {
+                Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                    ""categorySucceeded"": null,
+                    ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                    ""AppsSubcategory"": {""subcategoryState"":""inProgress"",""subcategoryStatusText"":""Apps (9 of 10 installed)""}
+                }");
+                Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                    ""categorySucceeded"": null,
+                    ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                    ""AppsSubcategory"": {""subcategoryState"":""failed"",""subcategoryStatusText"":""Apps (Error)""}
+                }");
+                Tracker.TriggerSettleTimerForTest("DeviceSetupCategory.Status");
+            }
+
+            public void Dispose()
+            {
+                Tracker.Dispose();
+                Tmp.Dispose();
+            }
+        }
+
+        [Fact]
+        public void PostTerminalRetry_EmitsRetryDetected_Once()
+        {
+            using var f = new Fixture();
+            f.DriveToTerminalDeviceSetupAppsFailure();
+            Assert.Single(f.EspFailures);
+
+            // "Try again": Apps leaves the failed state well after the settle window.
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                ""AppsSubcategory"": {""subcategoryState"":""inProgress"",""subcategoryStatusText"":""Apps (Working on it...)""}
+            }");
+
+            var retry = Assert.Single(f.CapturedEvents(), e => e.EventType == "esp_failure_retry_detected");
+            Assert.Equal("DeviceSetup", (string)retry.Data["category"]);
+            Assert.Equal("Apps", (string)retry.Data["subcategory"]);
+            Assert.Equal("failed", (string)retry.Data["previousState"]);
+            Assert.Equal("inProgress", (string)retry.Data["newState"]);
+            Assert.Equal("Provisioning_DeviceSetup_Apps_Failed", (string)retry.Data["failureType"]);
+            Assert.True(retry.Data.ContainsKey("minutesSinceFailure"));
+
+            // A later unrelated transition does not re-emit.
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                ""AppsSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Apps (10 of 10 installed)""}
+            }");
+            Assert.Single(f.CapturedEvents(), e => e.EventType == "esp_failure_retry_detected");
+        }
+
+        [Fact]
+        public void PostTerminalRecovery_EmitsRecovered_OnCategorySuccess()
+        {
+            using var f = new Fixture();
+            f.DriveToTerminalDeviceSetupAppsFailure();
+
+            // Retry → all apps installed → Windows resolves the category boolean.
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                ""AppsSubcategory"": {""subcategoryState"":""inProgress"",""subcategoryStatusText"":""Apps (Working on it...)""}
+            }");
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": true,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                ""AppsSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Apps (10 of 10 installed)""}
+            }");
+
+            var recovered = Assert.Single(f.CapturedEvents(), e => e.EventType == "esp_failure_recovered");
+            Assert.Equal("DeviceSetup", (string)recovered.Data["category"]);
+            Assert.Equal("Apps", (string)recovered.Data["failedSubcategory"]);
+            Assert.Equal("Provisioning_DeviceSetup_Apps_Failed", (string)recovered.Data["failureType"]);
+            Assert.True(recovered.Data.ContainsKey("minutesSinceFailure"));
+
+            // Duplicate category-success writes do not re-emit (fire-once).
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": true,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Security policies (1 of 1 applied)""},
+                ""AppsSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Apps (10 of 10 installed, take 2)""}
+            }");
+            Assert.Single(f.CapturedEvents(), e => e.EventType == "esp_failure_recovered");
+        }
+
+        [Fact]
+        public void InSettleWindowRecovery_KeepsPostTerminalPairSilent()
+        {
+            using var f = new Fixture();
+
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""AppsSubcategory"": {""subcategoryState"":""inProgress"",""subcategoryStatusText"":""Apps (0 of 1 installed)""}
+            }");
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""AppsSubcategory"": {""subcategoryState"":""failed"",""subcategoryStatusText"":""Apps (Error)""}
+            }");
+            // Recovery INSIDE the settle window — terminal fire is suppressed.
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""AppsSubcategory"": {""subcategoryState"":""inProgress"",""subcategoryStatusText"":""Apps (Working on it...)""}
+            }");
+            f.Tracker.TriggerSettleTimerForTest("DeviceSetupCategory.Status");
+            Assert.Empty(f.EspFailures);
+
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": true,
+                ""AppsSubcategory"": {""subcategoryState"":""succeeded"",""subcategoryStatusText"":""Apps (1 of 1 installed)""}
+            }");
+
+            var events = f.CapturedEvents();
+            Assert.Contains(events, e => e.EventType == "esp_failure_settle_recovered");
+            Assert.DoesNotContain(events, e => e.EventType == "esp_failure_retry_detected");
+            Assert.DoesNotContain(events, e => e.EventType == "esp_failure_recovered");
+        }
+
+        [Fact]
+        public void AppsFailure_TerminalArgs_CarryLikelyCulprits_NeverStartedFirst()
+        {
+            var neverStarted = BuildApp("app-bg", "Teams Backgrounds v2",
+                AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Unknown,
+                downloadingSeen: false);
+            var startedButPending = BuildApp("app-slow", "Slow Installer",
+                AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Unknown,
+                downloadingSeen: true);
+            var installed = BuildApp("app-ok", "Falcon Sensor",
+                AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Installed,
+                downloadingSeen: true);
+            using var f = new Fixture(() => new[] { startedButPending, neverStarted, installed });
+
+            f.DriveToTerminalDeviceSetupAppsFailure();
+
+            var fired = Assert.Single(f.EspFailures);
+            Assert.Equal(2, fired.LikelyCulpritApps.Count);
+            // Never-started app ranked first — it starved the ESP gate without any IME event.
+            Assert.Equal("Teams Backgrounds v2", fired.LikelyCulpritApps[0]);
+            Assert.Equal("Slow Installer", fired.LikelyCulpritApps[1]);
+        }
+
+        [Fact]
+        public void NonAppsFailure_TerminalArgs_CarryNoCulprits()
+        {
+            var neverStarted = BuildApp("app-bg", "Teams Backgrounds v2",
+                AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Unknown,
+                downloadingSeen: false);
+            using var f = new Fixture(() => new[] { neverStarted });
+
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""inProgress"",""subcategoryStatusText"":""Working""}
+            }");
+            f.Tracker.ProcessCategoryStatusForTest("DeviceSetupCategory.Status", @"{
+                ""categorySucceeded"": null,
+                ""SecurityPoliciesSubcategory"": {""subcategoryState"":""failed"",""subcategoryStatusText"":""Failed""}
+            }");
+            f.Tracker.TriggerSettleTimerForTest("DeviceSetupCategory.Status");
+
+            var fired = Assert.Single(f.EspFailures);
+            Assert.Empty(fired.LikelyCulpritApps);
+        }
+
+        private static AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppPackageState BuildApp(
+            string id, string name,
+            AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState state,
+            bool downloadingSeen)
+        {
+            var pkg = new AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppPackageState(id, 0);
+            pkg.UpdateName(name);
+            pkg.UpdateIntent(AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppIntent.Install);
+            pkg.UpdateTargeted(AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppTargeted.Device);
+            // DownloadingOrInstallingSeen is derived inside UpdateState (Downloading..Installing
+            // range) — drive it through a Downloading transition instead of setting it directly.
+            if (downloadingSeen)
+                pkg.UpdateState(AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Downloading);
+            if (state != AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Unknown
+                && state != AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppInstallationState.Downloading)
+                pkg.UpdateState(state);
+            return pkg;
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/SystemSignals/EspPolicyProviderStallDetectorTests.cs

@@ -0,0 +1,465 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Agent.V2.Core.Persistence;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Agent.V2.Core.Tests.Orchestration;
+using AutopilotMonitor.DecisionCore.Engine;
+using AutopilotMonitor.DecisionCore.Signals;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
+{
+    /// <summary>
+    /// Session 5d735290 — pure detection logic of <see cref="EspPolicyProviderStallDetector"/>:
+    /// the CSP completion rule and the dwell/one-shot transition. No registry, no timers.
+    /// </summary>
+    public sealed class EspPolicyProviderStallLogicTests
+    {
+        private static readonly DateTime T0 = new DateTime(2026, 7, 23, 10, 0, 0, DateTimeKind.Utc);
+        private static readonly TimeSpan Dwell = TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes);
+
+        private static PolicyProviderState SetupApps(string name, int? tracking, string scope = "device") =>
+            new PolicyProviderState(name, scope, EspPolicyProviderProbe.KindSetupApps, tracking, null);
+
+        private static PolicyProviderState DevicePrep(string name, int? installState) =>
+            new PolicyProviderState(name, "device", EspPolicyProviderProbe.KindDevicePreparation, null, installState);
+
+        private static EspPolicyProviderSnapshot Snapshot(params PolicyProviderState[] providers) =>
+            new EspPolicyProviderSnapshot(providers);
+
+        // ------------------------------------------------- completion rule (CSP contract)
+
+        [Theory]
+        [InlineData(1, true)]   // TrackingPoliciesCreated=true
+        [InlineData(0, false)]  // explicit false (the CSP default)
+        [InlineData(null, false)] // value missing — the field case
+        [InlineData(2, false)]  // anything else is not "true"
+        public void SetupApps_provider_complete_only_at_tracking_1(int? tracking, bool expected)
+            => Assert.Equal(expected, EspPolicyProviderProbe.IsProviderComplete(
+                EspPolicyProviderProbe.KindSetupApps, tracking, null));
+
+        [Theory]
+        [InlineData(2, true)]   // NotRequired
+        [InlineData(3, true)]   // Completed
+        [InlineData(1, false)]  // NotInstalled
+        [InlineData(4, false)]  // Error
+        [InlineData(null, false)]
+        public void DevicePreparation_provider_complete_at_state_2_or_3(int? state, bool expected)
+            => Assert.Equal(expected, EspPolicyProviderProbe.IsProviderComplete(
+                EspPolicyProviderProbe.KindDevicePreparation, null, state));
+
+        [Fact]
+        public void TryReadInt_tolerates_dword_string_and_bool_forms()
+        {
+            Assert.Equal(1, EspPolicyProviderProbe.TryReadInt(1));
+            Assert.Equal(3, EspPolicyProviderProbe.TryReadInt(3L));
+            Assert.Equal(1, EspPolicyProviderProbe.TryReadInt(" 1 "));
+            Assert.Equal(1, EspPolicyProviderProbe.TryReadInt(true));
+            Assert.Equal(0, EspPolicyProviderProbe.TryReadInt(false));
+            Assert.Null(EspPolicyProviderProbe.TryReadInt(null));
+            Assert.Null(EspPolicyProviderProbe.TryReadInt("not-a-number"));
+            Assert.Null(EspPolicyProviderProbe.TryReadInt(new byte[] { 1 }));
+        }
+
+        // ------------------------------------------------- dwell transition
+
+        [Fact]
+        public void Empty_or_missing_snapshot_clears_dwell_state_and_never_stalls()
+        {
+            var previous = new Dictionary<string, DateTime> { ["setupApps|device|ConfigMgr"] = T0 };
+
+            var missing = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                EspPolicyProviderSnapshot.Empty, previous, new HashSet<string>(), T0, false, T0.AddHours(2), Dwell);
+            Assert.Empty(missing.UpdatedFirstSeenUtc);
+            Assert.Empty(missing.NewlyStalled);
+            Assert.Null(missing.UpdatedSidecarMissingSinceUtc); // arm 2 resets too
+            Assert.Null(missing.SidecarMissingStalledForMinutes);
+
+            var registeredButEmpty = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(), previous, new HashSet<string>(), T0, false, T0.AddHours(2), Dwell);
+            Assert.Empty(registeredButEmpty.UpdatedFirstSeenUtc);
+            Assert.Empty(registeredButEmpty.NewlyStalled);
+            Assert.Null(registeredButEmpty.UpdatedSidecarMissingSinceUtc);
+        }
+
+        [Fact]
+        public void Incomplete_provider_accrues_dwell_but_does_not_stall_before_threshold()
+        {
+            var snapshot = Snapshot(SetupApps("ConfigMgr", tracking: null));
+
+            var round1 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, new Dictionary<string, DateTime>(), new HashSet<string>(), null, false, T0, Dwell);
+            Assert.Equal(T0, round1.UpdatedFirstSeenUtc["setupApps|device|ConfigMgr"]);
+            Assert.Empty(round1.NewlyStalled);
+
+            var round2 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, round1.UpdatedFirstSeenUtc, new HashSet<string>(),
+                round1.UpdatedSidecarMissingSinceUtc, false, T0.AddMinutes(14), Dwell);
+            Assert.Equal(T0, round2.UpdatedFirstSeenUtc["setupApps|device|ConfigMgr"]); // first-seen preserved
+            Assert.Empty(round2.NewlyStalled);
+            Assert.Null(round2.SidecarMissingStalledForMinutes); // 14 min < dwell on arm 2 as well
+        }
+
+        [Fact]
+        public void Provider_stalls_at_dwell_threshold_with_correct_minutes()
+        {
+            var snapshot = Snapshot(SetupApps("ConfigMgr", tracking: 0));
+            var seen = new Dictionary<string, DateTime> { ["setupApps|device|ConfigMgr"] = T0 };
+
+            var eval = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, seen, new HashSet<string>(), null, false, T0.AddMinutes(15), Dwell);
+
+            var stalled = Assert.Single(eval.NewlyStalled);
+            Assert.Equal("ConfigMgr", stalled.Provider.Name);
+            Assert.Equal(15.0, stalled.StalledForMinutes, precision: 3);
+        }
+
+        [Fact]
+        public void Completion_or_disappearance_resets_the_dwell_clock()
+        {
+            var key = "setupApps|device|ConfigMgr";
+            var seen = new Dictionary<string, DateTime> { [key] = T0 };
+
+            // Completes mid-dwell → dropped from the map.
+            var completed = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("ConfigMgr", tracking: 1)), seen, new HashSet<string>(), null, false, T0.AddMinutes(10), Dwell);
+            Assert.Empty(completed.UpdatedFirstSeenUtc);
+
+            // Re-appears incomplete much later → dwell restarts from the new now, no stall yet.
+            var reappeared = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("ConfigMgr", tracking: 0)), completed.UpdatedFirstSeenUtc,
+                new HashSet<string>(), null, false, T0.AddHours(3), Dwell);
+            Assert.Equal(T0.AddHours(3), reappeared.UpdatedFirstSeenUtc[key]);
+            Assert.Empty(reappeared.NewlyStalled);
+
+            // Disappearance behaves the same as completion.
+            var disappeared = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("Sidecar", tracking: 1)), new Dictionary<string, DateTime> { [key] = T0 },
+                new HashSet<string>(), null, false, T0.AddMinutes(20), Dwell);
+            Assert.False(disappeared.UpdatedFirstSeenUtc.ContainsKey(key));
+        }
+
+        [Fact]
+        public void Already_fired_provider_is_never_reported_again()
+        {
+            var snapshot = Snapshot(SetupApps("ConfigMgr", tracking: null));
+            var seen = new Dictionary<string, DateTime> { ["setupApps|device|ConfigMgr"] = T0 };
+            var fired = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "setupApps|device|ConfigMgr" };
+
+            var eval = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, seen, fired, null, false, T0.AddHours(5), Dwell);
+
+            Assert.Empty(eval.NewlyStalled);
+            Assert.True(eval.UpdatedFirstSeenUtc.ContainsKey("setupApps|device|ConfigMgr")); // still tracked
+        }
+
+        [Fact]
+        public void Mixed_kinds_and_scopes_are_tracked_under_distinct_keys()
+        {
+            var snapshot = Snapshot(
+                SetupApps("ConfigMgr", tracking: null),
+                SetupApps("ConfigMgr", tracking: null, scope: "user:S-1-5-21-1111"),
+                DevicePrep("ConfigMgr", installState: 1));
+
+            var eval = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, new Dictionary<string, DateTime>(), new HashSet<string>(), null, false, T0, Dwell);
+
+            Assert.Equal(3, eval.UpdatedFirstSeenUtc.Count);
+            Assert.Contains("setupApps|device|ConfigMgr", eval.UpdatedFirstSeenUtc.Keys);
+            Assert.Contains("setupApps|user:S-1-5-21-1111|ConfigMgr", eval.UpdatedFirstSeenUtc.Keys);
+            Assert.Contains("devicePreparation|device|ConfigMgr", eval.UpdatedFirstSeenUtc.Keys);
+        }
+
+        [Fact]
+        public void SidecarRegistered_matches_setupApps_sidecar_only()
+        {
+            Assert.True(Snapshot(SetupApps("Sidecar", tracking: 0)).SidecarRegistered);
+            Assert.True(Snapshot(SetupApps("sidecar", tracking: 1, scope: "user:S-1-5-21-1")).SidecarRegistered);
+            Assert.False(Snapshot(SetupApps("ConfigMgr", tracking: 1)).SidecarRegistered);
+            Assert.False(Snapshot(DevicePrep("Sidecar", installState: 3)).SidecarRegistered); // wrong kind
+            Assert.False(EspPolicyProviderSnapshot.Empty.SidecarRegistered);
+        }
+
+        // ------------------------------------------------- arm 2: sidecar-missing transition
+
+        [Fact]
+        public void Issue106_foreign_provider_complete_but_sidecar_missing_stalls_after_dwell()
+        {
+            // The actual field case: ConfigMgr with TrackingPoliciesCreated=1 — "complete" by the
+            // CSP value contract, arm 1 never fires — yet the ESP waits on the absent Sidecar.
+            var snapshot = Snapshot(SetupApps("ConfigMgr", tracking: 1));
+
+            var round1 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, new Dictionary<string, DateTime>(), new HashSet<string>(), null, false, T0, Dwell);
+            Assert.Empty(round1.NewlyStalled);                       // arm 1 stays silent...
+            Assert.Equal(T0, round1.UpdatedSidecarMissingSinceUtc);  // ...but arm 2 starts its clock
+            Assert.Null(round1.SidecarMissingStalledForMinutes);
+
+            var round2 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                snapshot, round1.UpdatedFirstSeenUtc, new HashSet<string>(),
+                round1.UpdatedSidecarMissingSinceUtc, false, T0.AddMinutes(15), Dwell);
+            Assert.Empty(round2.NewlyStalled);
+            Assert.Equal(15.0, round2.SidecarMissingStalledForMinutes!.Value, precision: 3);
+        }
+
+        [Fact]
+        public void Sidecar_registering_resets_the_sidecar_missing_clock()
+        {
+            // ConfigMgr first (legitimate startup ordering) → clock runs...
+            var round1 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("ConfigMgr", tracking: 1)),
+                new Dictionary<string, DateTime>(), new HashSet<string>(), null, false, T0, Dwell);
+            Assert.Equal(T0, round1.UpdatedSidecarMissingSinceUtc);
+
+            // ...Sidecar joins → condition clears, state resets.
+            var round2 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("ConfigMgr", tracking: 1), SetupApps("Sidecar", tracking: 0)),
+                round1.UpdatedFirstSeenUtc, new HashSet<string>(),
+                round1.UpdatedSidecarMissingSinceUtc, false, T0.AddMinutes(10), Dwell);
+            Assert.Null(round2.UpdatedSidecarMissingSinceUtc);
+            Assert.Null(round2.SidecarMissingStalledForMinutes);
+
+            // Sidecar gone again much later → clock restarts from the new now, no instant stall.
+            var round3 = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("ConfigMgr", tracking: 1)),
+                round2.UpdatedFirstSeenUtc, new HashSet<string>(),
+                round2.UpdatedSidecarMissingSinceUtc, false, T0.AddHours(3), Dwell);
+            Assert.Equal(T0.AddHours(3), round3.UpdatedSidecarMissingSinceUtc);
+            Assert.Null(round3.SidecarMissingStalledForMinutes);
+        }
+
+        [Fact]
+        public void Sidecar_missing_one_shot_and_deviceprep_only_scoping()
+        {
+            // Already fired → never re-reported, but the clock keeps running.
+            var latched = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(SetupApps("ConfigMgr", tracking: 1)),
+                new Dictionary<string, DateTime>(), new HashSet<string>(), T0, true, T0.AddHours(5), Dwell);
+            Assert.Null(latched.SidecarMissingStalledForMinutes);
+            Assert.Equal(T0, latched.UpdatedSidecarMissingSinceUtc);
+
+            // DevicePreparation providers alone don't constitute the Setup/Apps wait — arm 2 off.
+            var devicePrepOnly = EspPolicyProviderStallDetector.EvaluateStallTransition(
+                Snapshot(DevicePrep("ConfigMgr", installState: 1)),
+                new Dictionary<string, DateTime>(), new HashSet<string>(), null, false, T0, Dwell);
+            Assert.Null(devicePrepOnly.UpdatedSidecarMissingSinceUtc);
+        }
+    }
+
+    /// <summary>
+    /// Emission surface of the detector via the real <see cref="InformationalEventPost"/> rail.
+    /// Static probe override → serial collection (same contract as
+    /// <c>EspConfigDetectedTrackingFieldsTests</c>).
+    /// </summary>
+    [Collection("SerialThreading")]
+    public sealed class EspPolicyProviderStallDetectorEmissionTests : IDisposable
+    {
+        private static readonly DateTime At = new DateTime(2026, 7, 23, 12, 0, 0, DateTimeKind.Utc);
+
+        private readonly TempDirectory _tmp = new TempDirectory();
+
+        public void Dispose() => _tmp.Dispose();
+
+        private (EspPolicyProviderStallDetector sut, FakeSignalIngressSink sink, VirtualClock clock)
+            BuildDetector(StartupEventGate? gate = null)
+        {
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            var sink = new FakeSignalIngressSink();
+            var clock = new VirtualClock(At);
+            var post = new InformationalEventPost(sink, clock);
+            var sut = new EspPolicyProviderStallDetector("S1", "T1", post, logger, clock, gate);
+            return (sut, sink, clock);
+        }
+
+        private static EspPolicyProviderSnapshot ConfigMgrOnly() => new EspPolicyProviderSnapshot(new[]
+        {
+            new PolicyProviderState("ConfigMgr", "device", EspPolicyProviderProbe.KindSetupApps,
+                trackingPoliciesCreated: null, installationState: null),
+        });
+
+        private static EspPolicyProviderSnapshot SidecarCompleteConfigMgrIncomplete() => new EspPolicyProviderSnapshot(new[]
+        {
+            new PolicyProviderState("Sidecar", "device", EspPolicyProviderProbe.KindSetupApps, 1, null),
+            new PolicyProviderState("ConfigMgr", "device", EspPolicyProviderProbe.KindSetupApps, 0, null),
+        });
+
+        private static IReadOnlyList<FakeSignalIngressSink.PostedSignal> StalledEvents(FakeSignalIngressSink sink) =>
+            sink.Posted.Where(p =>
+                p.Payload != null
+                && p.Payload.TryGetValue(SignalPayloadKeys.EventType, out var et)
+                && et == "esp_policy_provider_stalled").ToList();
+
+        [Fact]
+        public void CustomerScenario_configmgr_without_sidecar_emits_one_warning_after_dwell()
+        {
+            using var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => ConfigMgrOnly());
+            var (sut, sink, clock) = BuildDetector();
+
+            sut.Tick();                                     // first sighting — dwell starts
+            Assert.Empty(StalledEvents(sink));
+
+            clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+            sut.Tick();                                     // threshold crossed → emit
+
+            var evt = Assert.Single(StalledEvents(sink));
+            Assert.Equal(DecisionSignalKind.InformationalEvent, evt.Kind);
+            Assert.Equal("Warning", evt.Payload![SignalPayloadKeys.Severity]);
+            Assert.Equal("true", evt.Payload[SignalPayloadKeys.ImmediateUpload]);
+            Assert.Equal(EspPolicyProviderStallDetector.SourceLabel, evt.Payload[SignalPayloadKeys.Source]);
+
+            var data = Assert.IsAssignableFrom<IReadOnlyDictionary<string, object>>(evt.TypedPayload);
+            // Both arms cross in the same round (ConfigMgr incomplete AND Sidecar absent) →
+            // ONE event; sidecar-missing is the dominant reason.
+            Assert.Equal(EspPolicyProviderStallDetector.ReasonSidecarMissing, data["reason"]);
+            Assert.Equal(false, data["sidecarRegistered"]);
+            Assert.Equal(15.0, data["sidecarMissingForMinutes"]);
+            Assert.Equal(EspPolicyProviderStallDetector.DwellMinutes, data["dwellMinutes"]);
+            var stalled = Assert.IsAssignableFrom<IReadOnlyList<Dictionary<string, object>>>(data["stalledProviders"]);
+            var entry = Assert.Single(stalled);
+            Assert.Equal("ConfigMgr", entry["name"]);
+            Assert.Equal(EspPolicyProviderProbe.KindSetupApps, entry["kind"]);
+            Assert.Equal(15.0, entry["stalledForMinutes"]);
+        }
+
+        [Fact]
+        public void Issue106_configmgr_complete_without_sidecar_still_emits_sidecar_missing()
+        {
+            // Regression test for the customer's follow-up on issue #106: TrackingPoliciesCreated=1
+            // WAS present under ConfigMgr — the provider looks "complete", arm 1 never fires, yet
+            // the ESP hangs because Sidecar is absent. Arm 2 must catch exactly this.
+            var configMgrComplete = new EspPolicyProviderSnapshot(new[]
+            {
+                new PolicyProviderState("ConfigMgr", "device", EspPolicyProviderProbe.KindSetupApps,
+                    trackingPoliciesCreated: 1, installationState: null),
+            });
+            using var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => configMgrComplete);
+            var (sut, sink, clock) = BuildDetector();
+
+            sut.Tick();
+            Assert.Empty(StalledEvents(sink));
+
+            clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+            sut.Tick();
+
+            var evt = Assert.Single(StalledEvents(sink));
+            var data = Assert.IsAssignableFrom<IReadOnlyDictionary<string, object>>(evt.TypedPayload);
+            Assert.Equal(EspPolicyProviderStallDetector.ReasonSidecarMissing, data["reason"]);
+            Assert.Equal(false, data["sidecarRegistered"]);
+            Assert.Equal(15.0, data["sidecarMissingForMinutes"]);
+            Assert.Empty(Assert.IsAssignableFrom<IReadOnlyList<Dictionary<string, object>>>(data["stalledProviders"]));
+            var providers = Assert.IsAssignableFrom<IReadOnlyList<Dictionary<string, object?>>>(data["providers"]);
+            Assert.Equal(true, Assert.Single(providers)["complete"]); // the misleading "complete" is visible
+        }
+
+        [Fact]
+        public void Sidecar_complete_configmgr_incomplete_reports_only_configmgr_with_sidecar_flag()
+        {
+            using var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => SidecarCompleteConfigMgrIncomplete());
+            var (sut, sink, clock) = BuildDetector();
+
+            sut.Tick();
+            clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+            sut.Tick();
+
+            var evt = Assert.Single(StalledEvents(sink));
+            var data = Assert.IsAssignableFrom<IReadOnlyDictionary<string, object>>(evt.TypedPayload);
+            Assert.Equal(EspPolicyProviderStallDetector.ReasonProviderIncomplete, data["reason"]); // arm 2 off — Sidecar is there
+            Assert.Equal(true, data["sidecarRegistered"]);
+            Assert.False(data.ContainsKey("sidecarMissingForMinutes"));
+            var stalled = Assert.IsAssignableFrom<IReadOnlyList<Dictionary<string, object>>>(data["stalledProviders"]);
+            Assert.Equal("ConfigMgr", Assert.Single(stalled)["name"]);
+            var providers = Assert.IsAssignableFrom<IReadOnlyList<Dictionary<string, object?>>>(data["providers"]);
+            Assert.Equal(2, providers.Count); // full table always attached
+        }
+
+        [Fact]
+        public void Latch_prevents_second_emission_for_the_same_provider()
+        {
+            using var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => ConfigMgrOnly());
+            var (sut, sink, clock) = BuildDetector();
+
+            sut.Tick();
+            clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+            sut.Tick();
+            clock.Advance(TimeSpan.FromMinutes(30));
+            sut.Tick();
+            sut.Tick();
+
+            Assert.Single(StalledEvents(sink));
+        }
+
+        [Fact]
+        public void Startup_gate_suppresses_same_stall_across_restart_but_reports_new_provider_set()
+        {
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+
+            // Run 1: fires and persists the fingerprint.
+            using (var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => ConfigMgrOnly()))
+            {
+                var (sut, sink, clock) = BuildDetector(new StartupEventGate(_tmp.Path, logger));
+                sut.Tick();
+                clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+                sut.Tick();
+                Assert.Single(StalledEvents(sink));
+            }
+
+            // Run 2 (simulated restart — fresh detector, gate reloaded from the same state dir):
+            // identical stall re-accrues dwell but lands on the same fingerprint → suppressed.
+            using (var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => ConfigMgrOnly()))
+            {
+                var (sut, sink, clock) = BuildDetector(new StartupEventGate(_tmp.Path, logger));
+                sut.Tick();
+                clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+                sut.Tick();
+                Assert.Empty(StalledEvents(sink));
+            }
+
+            // Run 3: a SECOND provider joins the stall → fingerprint changes → reported.
+            var widened = new EspPolicyProviderSnapshot(new[]
+            {
+                new PolicyProviderState("ConfigMgr", "device", EspPolicyProviderProbe.KindSetupApps, null, null),
+                new PolicyProviderState("Contoso", "device", EspPolicyProviderProbe.KindSetupApps, 0, null),
+            });
+            using (var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => widened))
+            {
+                var (sut, sink, clock) = BuildDetector(new StartupEventGate(_tmp.Path, logger));
+                sut.Tick();
+                clock.Advance(TimeSpan.FromMinutes(EspPolicyProviderStallDetector.DwellMinutes));
+                sut.Tick();
+                Assert.Single(StalledEvents(sink));
+            }
+        }
+
+        [Fact]
+        public void Healthy_or_absent_tracking_never_emits()
+        {
+            var healthy = new EspPolicyProviderSnapshot(new[]
+            {
+                new PolicyProviderState("Sidecar", "device", EspPolicyProviderProbe.KindSetupApps, 1, null),
+                new PolicyProviderState("ConfigMgr", "device", EspPolicyProviderProbe.KindDevicePreparation, null, 3),
+            });
+            using (var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => healthy))
+            {
+                var (sut, sink, clock) = BuildDetector();
+                sut.Tick();
+                clock.Advance(TimeSpan.FromHours(4));
+                sut.Tick();
+                Assert.Empty(StalledEvents(sink));
+            }
+
+            using (var _probe = new EspPolicyProviderProbe.ScopedOverride(_ => EspPolicyProviderSnapshot.Empty))
+            {
+                var (sut, sink, clock) = BuildDetector();
+                sut.Tick();
+                clock.Advance(TimeSpan.FromHours(4));
+                sut.Tick();
+                Assert.Empty(StalledEvents(sink));
+            }
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/SystemSignals/MdmRebootPolicyTrackerTests.cs

@@ -0,0 +1,336 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Agent.V2.Core.Tests.Orchestration;
+using AutopilotMonitor.DecisionCore.Engine;
+using AutopilotMonitor.DecisionCore.Signals;
+using AutopilotMonitor.Shared;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
+{
+    /// <summary>
+    /// MdmRebootPolicyTracker — aggregates DM-Enterprise EventID 2800 bursts into ONE neutral
+    /// <c>mdm_policy_reboot_required</c> event (session b2e890c1 rework: per-record events were
+    /// spam, and the raw event must not CLAIM a reboot — ANALYZE-ESP-005 does, gated on an
+    /// observed system_reboot_detected). Drives the primitive ProcessEvent seam + explicit
+    /// FlushPending (debounce 0 = manual-flush mode; no timers, no SerialThreading needed).
+    /// The registry probe is always overridden — tests never touch the live registry.
+    /// </summary>
+    public sealed class MdmRebootPolicyTrackerTests : IDisposable
+    {
+        private static readonly DateTime At = new DateTime(2026, 7, 20, 16, 20, 57, DateTimeKind.Utc);
+        private const string UriSvchost = "./Device/Vendor/MSFT/Policy/Config/ServiceControlManager/SvchostProcessMitigation";
+        private const string UriSystemGuard = "./Device/Vendor/MSFT/Policy/Config/DeviceGuard/ConfigureSystemGuardLaunch";
+
+        // Verified real 2800 description shape (session b2e890c1, 2026-07-20).
+        private const string RealDescription =
+            "The following URI has triggered a reboot: (./Device/Vendor/MSFT/Policy/Config/ServiceControlManager/SvchostProcessMitigation).";
+
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly FakeSignalIngressSink _sink;
+        private readonly MdmRebootPolicyTracker _tracker;
+        private long _nextRecordId = 1;
+
+        public MdmRebootPolicyTrackerTests()
+        {
+            _sink = new FakeSignalIngressSink();
+            _tracker = MakeTracker(stateDirectory: null);
+        }
+
+        public void Dispose() => _tmp.Dispose();
+
+        private MdmRebootPolicyTracker MakeTracker(string? stateDirectory)
+        {
+            var post = new InformationalEventPost(_sink, new VirtualClock(At));
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            var tracker = new MdmRebootPolicyTracker(
+                sessionId: "sess-mdm",
+                tenantId: "tenant-mdm",
+                post: post,
+                logger: logger,
+                backfillEnabled: false,
+                stateDirectory: stateDirectory,
+                debounceMilliseconds: 0); // manual-flush mode — tests call FlushPending explicitly
+            tracker.RebootRequiredFlagProbe = () => null; // registry untouched by default
+            return tracker;
+        }
+
+        private void Buffer(string? rebootUri, long? recordId = null, bool isBackfill = false, DateTime? timeCreatedUtc = null, string? description = null)
+        {
+            _tracker.ProcessEvent(
+                eventId: MdmRebootPolicyTracker.EventId_PolicyRebootRequired,
+                recordId: recordId ?? _nextRecordId++,
+                timeCreatedUtc: timeCreatedUtc ?? At,
+                rebootUri: rebootUri,
+                formattedDescription: description,
+                isBackfill: isBackfill);
+        }
+
+        private IReadOnlyList<FakeSignalIngressSink.PostedSignal> Emitted() =>
+            _sink.Posted.Where(p =>
+                p.Kind == DecisionSignalKind.InformationalEvent
+                && p.Payload != null
+                && p.Payload.TryGetValue(SignalPayloadKeys.EventType, out var et)
+                && et == Constants.EventTypes.MdmPolicyRebootRequired).ToList();
+
+        private static IReadOnlyDictionary<string, object> Data(FakeSignalIngressSink.PostedSignal s) =>
+            (IReadOnlyDictionary<string, object>)s.TypedPayload!;
+
+        [Fact]
+        public void Burst_FlushesAsOneAggregatedEvent_InfoSeverity_ImmediateUpload()
+        {
+            Buffer(UriSvchost, timeCreatedUtc: At);
+            Buffer(UriSystemGuard, timeCreatedUtc: At.AddMilliseconds(120));
+            _tracker.FlushPending();
+
+            var s = Assert.Single(Emitted());
+            Assert.Equal("Info", s.Payload![SignalPayloadKeys.Severity]);
+            Assert.Equal("true", s.Payload![SignalPayloadKeys.ImmediateUpload]);
+
+            var data = Data(s);
+            Assert.Equal(2, data["uriCount"]);
+            Assert.Equal(2, data["recordCount"]);
+            Assert.Equal(UriSvchost, data["firstRebootUri"]);
+            var uris = Assert.IsType<List<string>>(data["rebootUris"]);
+            Assert.Equal(2, uris.Count);
+            Assert.Contains(UriSvchost, uris);
+            Assert.Contains(UriSystemGuard, uris);
+        }
+
+        [Fact]
+        public void Message_IsNeutralObservation_NoRebootClaim()
+        {
+            // Session b2e890c1: flags raised during AccountSetup have no effect — the raw event
+            // must state the observation only, never a future consequence.
+            Buffer(UriSvchost);
+            _tracker.FlushPending();
+
+            var s = Assert.Single(Emitted());
+            var message = s.Payload![SignalPayloadKeys.Message];
+            Assert.Contains("flagged", message);
+            Assert.DoesNotContain("will restart", message);
+            Assert.DoesNotContain("second sign-in", message);
+        }
+
+        [Fact]
+        public void FlushPending_Empty_EmitsNothing()
+        {
+            _tracker.FlushPending();
+            Assert.Empty(Emitted());
+        }
+
+        [Fact]
+        public void AggregateTimestamp_IsEarliestRecordTime()
+        {
+            var early = At.AddMinutes(-30);
+            Buffer(UriSystemGuard, timeCreatedUtc: At, isBackfill: true);
+            Buffer(UriSvchost, timeCreatedUtc: early, isBackfill: true);
+            _tracker.FlushPending();
+
+            var s = Assert.Single(Emitted());
+            Assert.Equal(early, s.OccurredAtUtc);
+            Assert.Equal(true, Data(s)["backfilled"]);
+            // firstRebootUri follows record-time order, not buffer order.
+            Assert.Equal(UriSvchost, Data(s)["firstRebootUri"]);
+        }
+
+        [Fact]
+        public void Backfilled_False_WhenAnyRecordIsLive()
+        {
+            Buffer(UriSvchost, isBackfill: true);
+            Buffer(UriSystemGuard, isBackfill: false);
+            _tracker.FlushPending();
+
+            Assert.Equal(false, Data(Assert.Single(Emitted()))["backfilled"]);
+        }
+
+        [Fact]
+        public void DuplicateUris_AreDistinctInAggregate()
+        {
+            Buffer(UriSvchost);
+            Buffer(UriSvchost);
+            _tracker.FlushPending();
+
+            var data = Data(Assert.Single(Emitted()));
+            Assert.Equal(1, data["uriCount"]);
+            Assert.Equal(2, data["recordCount"]);
+        }
+
+        [Fact]
+        public void UnparsedRecords_CountedWithSampleDescription_StillEmitted()
+        {
+            Buffer(rebootUri: null, description: "Some unexpected 2800 wording");
+            _tracker.FlushPending();
+
+            var s = Assert.Single(Emitted());
+            var data = Data(s);
+            Assert.False(data.ContainsKey("rebootUris"));
+            Assert.False(data.ContainsKey("firstRebootUri"));
+            Assert.Equal(0, data["uriCount"]);
+            Assert.Equal(1, data["unparsedCount"]);
+            Assert.Equal("Some unexpected 2800 wording", data["sampleDescription"]);
+        }
+
+        [Fact]
+        public void SameRecordId_BufferedTwice_CountsOnce()
+        {
+            Buffer(UriSvchost, recordId: 42);
+            Buffer(UriSvchost, recordId: 42);
+            _tracker.FlushPending();
+
+            Assert.Equal(1, Data(Assert.Single(Emitted()))["recordCount"]);
+        }
+
+        [Fact]
+        public void RecordAfterFlush_GoesIntoNextAggregate()
+        {
+            Buffer(UriSvchost, recordId: 10);
+            _tracker.FlushPending();
+            Buffer(UriSystemGuard, recordId: 11);
+            _tracker.FlushPending();
+
+            Assert.Equal(2, Emitted().Count);
+        }
+
+        [Fact]
+        public void BackfillRecordWithLowerRecordId_AfterLiveRecord_IsStillBuffered()
+        {
+            // Live watcher is armed BEFORE the backfill scan — an older, never-seen backfill
+            // record must not be suppressed by a high-water mark.
+            Buffer(UriSvchost, recordId: 100);
+            Buffer(UriSystemGuard, recordId: 50, isBackfill: true);
+            _tracker.FlushPending();
+
+            Assert.Equal(2, Data(Assert.Single(Emitted()))["recordCount"]);
+        }
+
+        [Fact]
+        public void NegativeRecordId_IsNeverDeduped()
+        {
+            Buffer(UriSvchost, recordId: -1);
+            Buffer(UriSvchost, recordId: -1);
+            _tracker.FlushPending();
+
+            Assert.Equal(2, Data(Assert.Single(Emitted()))["recordCount"]);
+        }
+
+        [Fact]
+        public void Watermark_PersistedAtFlush_SkipsReReadAcrossInstances()
+        {
+            // The coalesced reboot restarts the agent; the post-reboot backfill re-reads the same
+            // records — a FLUSHED record must be skipped by the next instance.
+            var first = MakeTracker(stateDirectory: _tmp.Path);
+            first.ProcessEvent(MdmRebootPolicyTracker.EventId_PolicyRebootRequired, recordId: 500,
+                timeCreatedUtc: At, rebootUri: UriSvchost, formattedDescription: null, isBackfill: false);
+            first.FlushPending();
+
+            var second = MakeTracker(stateDirectory: _tmp.Path);
+            second.LoadWatermark();
+            second.ProcessEvent(MdmRebootPolicyTracker.EventId_PolicyRebootRequired, recordId: 500,
+                timeCreatedUtc: At, rebootUri: UriSvchost, formattedDescription: null, isBackfill: true);
+            second.FlushPending();
+
+            Assert.Single(Emitted());
+        }
+
+        [Fact]
+        public void Watermark_NotPersisted_WhenBufferedButNeverFlushed()
+        {
+            // Process killed by the very reboot the records announce: nothing was flushed, so the
+            // next instance must re-read and emit the records.
+            var first = MakeTracker(stateDirectory: _tmp.Path);
+            first.ProcessEvent(MdmRebootPolicyTracker.EventId_PolicyRebootRequired, recordId: 500,
+                timeCreatedUtc: At, rebootUri: UriSvchost, formattedDescription: null, isBackfill: false);
+            // no FlushPending — simulated reboot kill
+
+            var second = MakeTracker(stateDirectory: _tmp.Path);
+            second.LoadWatermark();
+            second.ProcessEvent(MdmRebootPolicyTracker.EventId_PolicyRebootRequired, recordId: 500,
+                timeCreatedUtc: At, rebootUri: UriSvchost, formattedDescription: null, isBackfill: true);
+            second.FlushPending();
+
+            var s = Assert.Single(Emitted());
+            Assert.Equal(true, Data(s)["backfilled"]);
+        }
+
+        [Fact]
+        public void RebootRequiredFlagProbe_True_AddsField_Null_OmitsIt()
+        {
+            _tracker.RebootRequiredFlagProbe = () => true;
+            Buffer(UriSvchost, recordId: 1);
+            _tracker.FlushPending();
+
+            _tracker.RebootRequiredFlagProbe = () => null;
+            Buffer(UriSystemGuard, recordId: 2);
+            _tracker.FlushPending();
+
+            var emitted = Emitted();
+            Assert.Equal(2, emitted.Count);
+            Assert.Equal(true, Data(emitted[0])["omadmRebootRequiredFlag"]);
+            Assert.False(Data(emitted[1]).ContainsKey("omadmRebootRequiredFlag"));
+        }
+
+        [Fact]
+        public void RebootRequiredFlagProbe_Throwing_IsFailSoft()
+        {
+            _tracker.RebootRequiredFlagProbe = () => throw new InvalidOperationException("boom");
+            Buffer(UriSvchost);
+            _tracker.FlushPending();
+
+            Assert.False(Data(Assert.Single(Emitted())).ContainsKey("omadmRebootRequiredFlag"));
+        }
+
+        [Fact]
+        public void BuildXPath_Targets2800()
+        {
+            Assert.Equal("*[System[(EventID=2800)]]", MdmRebootPolicyTracker.BuildXPath());
+        }
+
+        // ------------------------------------------------------------------ URI extraction
+
+        [Fact]
+        public void ExtractRebootUri_FromVerifiedRealDescription()
+        {
+            // Real 2800 text wraps the URI in parentheses and ends with a period — both must be
+            // excluded from the extracted URI.
+            var uri = MdmRebootPolicyTracker.ExtractRebootUri(null, RealDescription);
+            Assert.Equal(UriSvchost, uri);
+        }
+
+        [Fact]
+        public void ExtractRebootUri_PrefersEventDataValue_OverDescription()
+        {
+            var eventData = new Dictionary<string, string> { ["Data0"] = " " + UriSystemGuard + " " };
+            var uri = MdmRebootPolicyTracker.ExtractRebootUri(eventData, RealDescription);
+            Assert.Equal(UriSystemGuard, uri);
+        }
+
+        [Fact]
+        public void ExtractRebootUri_ReturnsNull_WhenNothingUriLike()
+        {
+            Assert.Null(MdmRebootPolicyTracker.ExtractRebootUri(
+                new Dictionary<string, string> { ["Data0"] = "plain" }, "no uri here"));
+            Assert.Null(MdmRebootPolicyTracker.ExtractRebootUri(null, null));
+        }
+
+        [Fact]
+        public void ParseEventData_CollectsNamedAndPositionalData()
+        {
+            const string xml =
+                "<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>" +
+                "<System><EventID>2800</EventID></System>" +
+                "<EventData><Data Name='Uri'>./Device/Vendor/MSFT/X</Data><Data>positional</Data></EventData>" +
+                "</Event>";
+
+            var parsed = MdmRebootPolicyTracker.ParseEventData(xml);
+            Assert.Equal("./Device/Vendor/MSFT/X", parsed["Uri"]);
+            Assert.Equal("positional", parsed["Data0"]);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/SystemSignals/ModernDeploymentTrackerErrorBackfillTests.cs

@@ -112,6 +112,36 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
             Assert.Equal(false, data["backfilled"]);
         }
 
+        [Fact]
+        public void ErrorBackfillSummary_EmitsInfoLogEvent_AnnouncingTheReplayBlock()
+        {
+            _tracker.EmitErrorBackfillSummary(replayedCount: 6, droppedOverCap: 0);
+
+            var posted = _sink.Posted.Single(p => p.Kind == DecisionSignalKind.InformationalEvent);
+            Assert.Equal("modern_deployment_log", posted.Payload![SignalPayloadKeys.EventType]);
+
+            var data = Assert.IsAssignableFrom<IReadOnlyDictionary<string, object>>(posted.TypedPayload);
+            Assert.Equal(true, data["backfillSummary"]);
+            Assert.Equal(6, data["replayedCount"]);
+            Assert.Equal(0, data["droppedOverCap"]);
+            Assert.Equal(240, data["lookbackMinutes"]);
+
+            var message = (string)posted.Payload[SignalPayloadKeys.Message];
+            Assert.Contains("Replaying 6 error event(s)", message);
+            Assert.Contains("before the agent started", message);
+            Assert.DoesNotContain("cap", message);
+        }
+
+        [Fact]
+        public void ErrorBackfillSummary_MentionsDroppedRecords_WhenCapWasHit()
+        {
+            _tracker.EmitErrorBackfillSummary(replayedCount: 25, droppedOverCap: 7);
+
+            var posted = _sink.Posted.Single(p => p.Kind == DecisionSignalKind.InformationalEvent);
+            var message = (string)posted.Payload![SignalPayloadKeys.Message];
+            Assert.Contains("7 older record(s) beyond the 25-record cap", message);
+        }
+
         [Fact]
         public void BackfilledHarmlessId_StillRunsThroughRollupSuppression()
         {

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/SystemSignals/ProvisioningFailureSettleWindowTests.cs

@@ -39,7 +39,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
             public List<EspFailureDetectedEventArgs> EspFailures { get; } = new List<EspFailureDetectedEventArgs>();
             public ProvisioningStatusTracker Tracker { get; }
 
-            public Fixture(Func<IReadOnlyList<AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppPackageState>> packageStatesProbe = null)
+            public Fixture(Func<IReadOnlyList<AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime.AppPackageState>>? packageStatesProbe = null)
             {
                 var clock = new VirtualClock(Fixed);
                 var post = new InformationalEventPost(Sink, clock);
@@ -179,7 +179,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
             }");
 
             var captured = f.CapturedEvents();
-            Assert.Single(captured.Where(e => e.EventType == "esp_failure_settle_started"));
+            Assert.Single(captured, e => e.EventType == "esp_failure_settle_started");
         }
 
         // =====================================================================
@@ -214,8 +214,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
             // No terminal fire — the failure was retracted.
             Assert.Empty(f.EspFailures);
 
-            var recovered = Assert.Single(f.CapturedEvents()
-                .Where(e => e.EventType == "esp_failure_settle_recovered"));
+            var recovered = Assert.Single(
+                f.CapturedEvents(), e => e.EventType == "esp_failure_settle_recovered");
             Assert.Equal("AccountSetup", (string)recovered.Data["category"]);
             Assert.Equal("Apps", (string)recovered.Data["failedSubcategory"]);
             Assert.Equal("inProgress", (string)recovered.Data["observedState"]);
@@ -280,7 +280,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
             f.Tracker.TriggerSettleTimerForTest("AccountSetupCategory.Status");
 
             Assert.Single(f.EspFailures);
-            Assert.Empty(f.CapturedEvents().Where(e => e.EventType == "esp_failure_settle_recovered"));
+            Assert.DoesNotContain(f.CapturedEvents(), e => e.EventType == "esp_failure_settle_recovered");
         }
 
         // =====================================================================
@@ -326,8 +326,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
                 ""AppsSubcategory"": {""subcategoryState"":""failed"",""subcategoryStatusText"":""Apps (Error)""}
             }");
 
-            var settleStarted = Assert.Single(f.CapturedEvents()
-                .Where(e => e.EventType == "esp_failure_settle_started"));
+            var settleStarted = Assert.Single(
+                f.CapturedEvents(), e => e.EventType == "esp_failure_settle_started");
             Assert.Equal(1, (int)settleStarted.Data["trackedAppsNotCompletedCount"]);
             var apps = (List<Dictionary<string, object>>)settleStarted.Data["trackedAppsNotCompleted"];
             var app = Assert.Single(apps);
@@ -354,8 +354,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.SystemSignals
                 ""SecurityPoliciesSubcategory"": {""subcategoryState"":""failed"",""subcategoryStatusText"":""Failed""}
             }");
 
-            var settleStarted = Assert.Single(f.CapturedEvents()
-                .Where(e => e.EventType == "esp_failure_settle_started"));
+            var settleStarted = Assert.Single(
+                f.CapturedEvents(), e => e.EventType == "esp_failure_settle_started");
             Assert.False(settleStarted.Data.ContainsKey("trackedAppsNotCompleted"));
             Assert.False(settleStarted.Data.ContainsKey("trackedAppsNotCompletedCount"));
         }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Telemetry/Gather/GuardrailsParityTests.cs

@@ -0,0 +1,69 @@
+using System.IO;
+using System.Linq;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather;
+using Newtonsoft.Json.Linq;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Telemetry.Gather
+{
+    /// <summary>
+    /// Pins the display mirror in rules/guardrails.json (embedded into this assembly)
+    /// to the agent's hard-block CONSTANTS in <see cref="GatherRuleGuards"/>.
+    /// Enforcement is code-only by design (a JSON parse error must never lift a hard
+    /// block); the JSON mirror exists so the portal and the MCP validator can
+    /// pre-flight the same blocks. This test keeps the two from drifting: an addition
+    /// on either side fails here until the other side follows.
+    /// </summary>
+    public sealed class GuardrailsParityTests
+    {
+        private static JObject LoadEmbeddedGuardrails()
+        {
+            var assembly = typeof(GatherRuleGuards).Assembly;
+            using var stream = assembly.GetManifestResourceStream(
+                "AutopilotMonitor.Agent.V2.Core.Resources.guardrails.json");
+            Assert.NotNull(stream);
+            using var reader = new StreamReader(stream!);
+            return JObject.Parse(reader.ReadToEnd());
+        }
+
+        [Fact]
+        public void Blocked_file_prefixes_match_code_constants()
+        {
+            var json = LoadEmbeddedGuardrails()["blockedFilePrefixes"]!.ToObject<string[]>()!;
+            var code = new[] { GatherRuleGuards.BlockedUsersPrefix }
+                .Concat(GatherRuleGuards.AdditionalHardBlockedPathPrefixes);
+
+            Assert.Equal(
+                code.Select(p => p.ToLowerInvariant()).OrderBy(p => p),
+                json.Select(p => Path.GetFullPath(p).ToLowerInvariant()).OrderBy(p => p));
+        }
+
+        [Fact]
+        public void Blocked_command_patterns_match_code_constants()
+        {
+            var json = LoadEmbeddedGuardrails()["blockedCommandPatterns"]!.ToObject<string[]>()!;
+
+            Assert.Equal(
+                GatherRuleGuards.HardBlockedCommandPatterns.OrderBy(p => p),
+                json.OrderBy(p => p));
+        }
+
+        [Fact]
+        public void Max_command_length_matches_code_constant()
+        {
+            Assert.Equal(
+                GatherRuleGuards.MaxCommandLength,
+                LoadEmbeddedGuardrails()["maxCommandLength"]!.Value<int>());
+        }
+
+        [Fact]
+        public void Blocked_event_log_channels_match_code_constants()
+        {
+            var json = LoadEmbeddedGuardrails()["blockedEventLogChannels"]!.ToObject<string[]>()!;
+
+            Assert.Equal(
+                GatherRuleGuards.HardBlockedEventLogChannels.OrderBy(c => c),
+                json.OrderBy(c => c));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Transport/EmergencyReporterTests.cs

@@ -0,0 +1,143 @@
+using System;
+using System.Collections.Generic;
+using System.Net.Http;
+using System.Threading.Tasks;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Transport;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Transport
+{
+    /// <summary>
+    /// Pins the anti-flood semantics of <see cref="EmergencyReporter.TrySendAsync"/> after the
+    /// delivery-hardening change (2026-07-23): the once-per-session dedup and the per-session
+    /// budget count DELIVERED reports. The previous mark-before-send permanently suppressed an
+    /// error key after its first transport failure — fatal for single-shot callers like the 48h
+    /// emergency break, whose process exits right after the attempt.
+    /// </summary>
+    public class EmergencyReporterTests
+    {
+        private sealed class FakeApiClient : BackendApiClient
+        {
+            public readonly List<TimeSpan?> Timeouts = new List<TimeSpan?>();
+            public readonly Queue<bool> Results = new Queue<bool>();
+
+            public FakeApiClient() : base(
+                httpClient: new HttpClient(),
+                baseUrl: "http://localhost",
+                manufacturer: string.Empty,
+                model: string.Empty,
+                serialNumber: string.Empty,
+                useBootstrapTokenAuth: false,
+                bootstrapToken: null,
+                agentVersion: "0.0.0",
+                logger: null)
+            {
+            }
+
+            public int Calls => Timeouts.Count;
+
+            public override Task<bool> ReportAgentErrorAsync(AgentErrorReport report, TimeSpan? timeout = null)
+            {
+                Timeouts.Add(timeout);
+                return Task.FromResult(Results.Count > 0 && Results.Dequeue());
+            }
+        }
+
+        private static EmergencyReporter Reporter(FakeApiClient client)
+            => new EmergencyReporter(client, "session", "tenant", "0.0.0", logger: null);
+
+        [Fact]
+        public async Task Failed_send_rolls_back_reservation_so_a_later_call_retries()
+        {
+            var client = new FakeApiClient();
+            client.Results.Enqueue(false); // first call fails
+            client.Results.Enqueue(true);  // second call succeeds
+            var reporter = Reporter(client);
+
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+
+            // Old behaviour: second call suppressed as "already reported" ⇒ 1 call.
+            Assert.Equal(2, client.Calls);
+        }
+
+        [Fact]
+        public async Task Delivered_send_is_deduplicated_per_key()
+        {
+            var client = new FakeApiClient();
+            client.Results.Enqueue(true);
+            var reporter = Reporter(client);
+
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+
+            Assert.Equal(1, client.Calls);
+        }
+
+        [Fact]
+        public async Task Retries_stay_inside_one_reservation_and_stop_on_success()
+        {
+            var client = new FakeApiClient();
+            client.Results.Enqueue(false);
+            client.Results.Enqueue(true); // second attempt delivers — third must not fire
+            var reporter = Reporter(client);
+
+            await reporter.TrySendAsync(
+                AgentErrorType.SessionAgeEmergencyBreak, "m",
+                attempts: 3, perAttemptTimeout: TimeSpan.FromMilliseconds(50), retryDelay: TimeSpan.Zero);
+
+            Assert.Equal(2, client.Calls);
+
+            // Delivered ⇒ dedup holds for the session.
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+            Assert.Equal(2, client.Calls);
+        }
+
+        [Fact]
+        public async Task Per_attempt_timeout_is_forwarded_to_the_api_client()
+        {
+            var client = new FakeApiClient();
+            client.Results.Enqueue(true);
+            var reporter = Reporter(client);
+
+            var timeout = TimeSpan.FromSeconds(15);
+            await reporter.TrySendAsync(
+                AgentErrorType.SessionAgeEmergencyBreak, "m",
+                attempts: 1, perAttemptTimeout: timeout);
+
+            Assert.Equal(timeout, Assert.Single(client.Timeouts));
+        }
+
+        [Fact]
+        public async Task All_attempts_failing_rolls_back_after_exhausting_attempts()
+        {
+            var client = new FakeApiClient(); // queue empty ⇒ every attempt fails
+            var reporter = Reporter(client);
+
+            await reporter.TrySendAsync(
+                AgentErrorType.SessionAgeEmergencyBreak, "m",
+                attempts: 3, retryDelay: TimeSpan.Zero);
+            Assert.Equal(3, client.Calls);
+
+            // Rolled back ⇒ a later call may try again (budget + dedup + cooldown restored).
+            client.Results.Enqueue(true);
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+            Assert.Equal(4, client.Calls);
+        }
+
+        [Fact]
+        public async Task Different_keys_do_not_suppress_each_other_after_rollback()
+        {
+            var client = new FakeApiClient();
+            client.Results.Enqueue(false); // break report fails → rollback (incl. cooldown restore)
+            client.Results.Enqueue(true);  // unrelated report must still go out
+            var reporter = Reporter(client);
+
+            await reporter.TrySendAsync(AgentErrorType.SessionAgeEmergencyBreak, "m");
+            await reporter.TrySendAsync(AgentErrorType.ConfigFetchFailed, "m");
+
+            Assert.Equal(2, client.Calls);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/UefiSecureBootCertReaderTests.cs

@@ -0,0 +1,212 @@
+#nullable enable
+using System.Collections.Generic;
+using System.Text;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Interop;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring
+{
+    /// <summary>
+    /// Pins the pure parts of the UEFI Secure Boot certificate probe: the ASCII substring
+    /// search over raw signature-list bytes and the <c>secureboot_status</c> payload shaping
+    /// (in particular the one-sided <c>uefiCa2023FirmwareConfirmed</c> marker whose ABSENCE
+    /// is load-bearing for ANALYZE-SEC-001's not_exists precondition). The actual firmware
+    /// read is only smoke-tested: test machines may be VMs, non-elevated, or legacy BIOS,
+    /// so only the fail-soft contract is asserted.
+    /// </summary>
+    public sealed class UefiSecureBootCertReaderTests
+    {
+        // --- ContainsAscii ---
+
+        [Fact]
+        public void ContainsAscii_finds_needle_embedded_in_binary_noise()
+        {
+            var bytes = Concat(new byte[] { 0x00, 0xA1, 0x30, 0x82 },
+                Encoding.ASCII.GetBytes("Windows UEFI CA 2023"),
+                new byte[] { 0x00, 0xFF });
+
+            Assert.True(UefiSecureBootCertReader.ContainsAscii(bytes, "Windows UEFI CA 2023"));
+        }
+
+        [Fact]
+        public void ContainsAscii_finds_needle_at_the_very_end()
+        {
+            var bytes = Concat(new byte[] { 0x01, 0x02 }, Encoding.ASCII.GetBytes("KEK 2K CA 2023"));
+
+            Assert.True(UefiSecureBootCertReader.ContainsAscii(bytes, "KEK 2K CA 2023"));
+        }
+
+        [Fact]
+        public void ContainsAscii_rejects_partial_overlap_and_absent_needle()
+        {
+            var bytes = Encoding.ASCII.GetBytes("Windows UEFI CA 2011 something else");
+
+            Assert.False(UefiSecureBootCertReader.ContainsAscii(bytes, "Windows UEFI CA 2023"));
+            // Repeated prefix bytes must not confuse the scan.
+            var tricky = Encoding.ASCII.GetBytes("ababac");
+            Assert.True(UefiSecureBootCertReader.ContainsAscii(tricky, "abac"));
+        }
+
+        [Fact]
+        public void ContainsAscii_handles_null_empty_and_oversized_needle()
+        {
+            Assert.False(UefiSecureBootCertReader.ContainsAscii(null, "x"));
+            Assert.False(UefiSecureBootCertReader.ContainsAscii(new byte[0], "x"));
+            Assert.False(UefiSecureBootCertReader.ContainsAscii(new byte[] { 1, 2 }, ""));
+            Assert.False(UefiSecureBootCertReader.ContainsAscii(new byte[] { 1, 2 }, "abc"));
+        }
+
+        // --- Payload shaping ---
+
+        [Fact]
+        public void Marker_emitted_only_when_db_ok_and_ca2023_present()
+        {
+            var data = new Dictionary<string, object>();
+            DeviceInfoCollector.AppendFirmwareCertFields(data, new UefiSecureBootCertSnapshot
+            {
+                DbStatus = UefiSecureBootCertReader.StatusOk,
+                KekStatus = UefiSecureBootCertReader.StatusOk,
+                DbHasWindowsUefiCa2023 = true,
+                KekHasMicrosoftKek2kCa2023 = true
+            });
+
+            Assert.Equal(true, data["uefiCa2023FirmwareConfirmed"]);
+            Assert.Equal("ok", data["uefiFirmwareReadStatus"]);
+            Assert.Equal(true, data["uefiDbHasWindowsUefiCa2023"]);
+            Assert.Equal(true, data["uefiKekHasMicrosoftKek2kCa2023"]);
+        }
+
+        [Fact]
+        public void Marker_absent_when_ca2023_missing_even_though_read_succeeded()
+        {
+            var data = new Dictionary<string, object>();
+            DeviceInfoCollector.AppendFirmwareCertFields(data, new UefiSecureBootCertSnapshot
+            {
+                DbStatus = UefiSecureBootCertReader.StatusOk,
+                KekStatus = UefiSecureBootCertReader.StatusOk,
+                DbHasWindowsUefiCa2023 = false,
+                DbHasWindowsProductionPca2011 = true
+            });
+
+            // The marker must be OMITTED, not false — not_exists fails on any present value.
+            Assert.False(data.ContainsKey("uefiCa2023FirmwareConfirmed"));
+            Assert.Equal(false, data["uefiDbHasWindowsUefiCa2023"]);
+            Assert.Equal(true, data["uefiDbHasWindowsProductionPca2011"]);
+        }
+
+        [Fact]
+        public void Failed_db_read_emits_status_but_no_cert_booleans_and_no_marker()
+        {
+            var data = new Dictionary<string, object>();
+            DeviceInfoCollector.AppendFirmwareCertFields(data, new UefiSecureBootCertSnapshot
+            {
+                DbStatus = UefiSecureBootCertReader.StatusPrivilegeDenied,
+                KekStatus = UefiSecureBootCertReader.StatusPrivilegeDenied
+            });
+
+            Assert.Equal(UefiSecureBootCertReader.StatusPrivilegeDenied, data["uefiFirmwareReadStatus"]);
+            Assert.False(data.ContainsKey("uefiDbHasWindowsUefiCa2023"));
+            Assert.False(data.ContainsKey("uefiKekHasMicrosoftKek2kCa2023"));
+            Assert.False(data.ContainsKey("uefiCa2023FirmwareConfirmed"));
+        }
+
+        [Fact]
+        public void Db_ok_but_kek_failed_keeps_db_booleans_and_reports_kek_status()
+        {
+            var data = new Dictionary<string, object>();
+            DeviceInfoCollector.AppendFirmwareCertFields(data, new UefiSecureBootCertSnapshot
+            {
+                DbStatus = UefiSecureBootCertReader.StatusOk,
+                KekStatus = UefiSecureBootCertReader.StatusVariableNotFound,
+                DbHasWindowsUefiCa2023 = true
+            });
+
+            Assert.Equal(UefiSecureBootCertReader.StatusVariableNotFound, data["uefiFirmwareReadStatus"]);
+            Assert.Equal(true, data["uefiDbHasWindowsUefiCa2023"]);
+            Assert.Equal(true, data["uefiCa2023FirmwareConfirmed"]);
+            Assert.False(data.ContainsKey("uefiKekHasMicrosoftKek2kCa2023"));
+        }
+
+        [Fact]
+        public void Null_snapshot_leaves_payload_untouched()
+        {
+            var data = new Dictionary<string, object> { { "uefiSecureBootEnabled", true } };
+            DeviceInfoCollector.AppendFirmwareCertFields(data, null);
+
+            Assert.Single(data);
+        }
+
+        [Fact]
+        public void DescribeFirmwareVerdict_covers_all_shapes()
+        {
+            Assert.Equal("unavailable", DeviceInfoCollector.DescribeFirmwareVerdict(null));
+            Assert.Equal(UefiSecureBootCertReader.StatusNotUefi, DeviceInfoCollector.DescribeFirmwareVerdict(
+                new UefiSecureBootCertSnapshot { DbStatus = UefiSecureBootCertReader.StatusNotUefi }));
+            Assert.Equal("CA2023 confirmed", DeviceInfoCollector.DescribeFirmwareVerdict(
+                new UefiSecureBootCertSnapshot { DbStatus = UefiSecureBootCertReader.StatusOk, DbHasWindowsUefiCa2023 = true }));
+            Assert.Equal("CA2023 missing", DeviceInfoCollector.DescribeFirmwareVerdict(
+                new UefiSecureBootCertSnapshot { DbStatus = UefiSecureBootCertReader.StatusOk, DbHasWindowsUefiCa2023 = false }));
+        }
+
+        // --- Reader smoke (real firmware; machine state unknown) ---
+
+        [Fact]
+        public void Read_never_throws_and_reports_a_status_for_both_variables()
+        {
+            var snapshot = UefiSecureBootCertReader.Read();
+
+            Assert.NotNull(snapshot);
+            Assert.False(string.IsNullOrEmpty(snapshot.DbStatus));
+            Assert.False(string.IsNullOrEmpty(snapshot.KekStatus));
+        }
+
+        /// <summary>
+        /// SeSystemEnvironmentPrivilege is adjusted on the PROCESS token, so the enable →
+        /// read → restore sequence is a process-wide side effect. Unserialized, a second
+        /// reader observes "already enabled", skips its own restore, and then loses the
+        /// privilege mid-read when the first reader disposes — surfacing as a privilege_denied
+        /// that disagrees with the other readers. The machine's actual privilege state does
+        /// not matter here: whatever it is, every reader must report the SAME status.
+        /// </summary>
+        [Fact]
+        public void Read_is_serialized_across_concurrent_callers()
+        {
+            const int readers = 8;
+            var snapshots = new UefiSecureBootCertSnapshot[readers];
+            var failures = new System.Exception[readers];
+
+            var threads = new System.Threading.Thread[readers];
+            for (var i = 0; i < readers; i++)
+            {
+                var index = i;
+                threads[i] = new System.Threading.Thread(() =>
+                {
+                    try { snapshots[index] = UefiSecureBootCertReader.Read(); }
+                    catch (System.Exception ex) { failures[index] = ex; }
+                });
+                threads[i].Start();
+            }
+            foreach (var thread in threads) thread.Join();
+
+            Assert.All(failures, Assert.Null);
+            Assert.All(snapshots, s => Assert.False(string.IsNullOrEmpty(s.DbStatus)));
+            Assert.All(snapshots, s => Assert.Equal(snapshots[0].DbStatus, s.DbStatus));
+            Assert.All(snapshots, s => Assert.Equal(snapshots[0].KekStatus, s.KekStatus));
+        }
+
+        private static byte[] Concat(params byte[][] parts)
+        {
+            var total = 0;
+            foreach (var part in parts) total += part.Length;
+            var result = new byte[total];
+            var offset = 0;
+            foreach (var part in parts)
+            {
+                System.Array.Copy(part, 0, result, offset, part.Length);
+                offset += part.Length;
+            }
+            return result;
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Orchestration/DecisionStepProcessorParkedTripwireTests.cs

@@ -44,7 +44,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
         private readonly FakeQuarantineSink _quarantine = new FakeQuarantineSink();
         private readonly FakeSignalIngressSink _sink = new FakeSignalIngressSink();
         private readonly DecisionEngine _engine = new DecisionEngine();
-        private DecisionStepProcessor _sut;
+        private DecisionStepProcessor? _sut;
 
         public DecisionStepProcessorParkedTripwireTests()
         {
@@ -107,7 +107,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             return (step, signal);
         }
 
-        private FakeSignalIngressSink.PostedSignal FindTripwirePost()
+        private FakeSignalIngressSink.PostedSignal? FindTripwirePost()
         {
             foreach (var posted in _sink.Posted)
             {
@@ -121,6 +121,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             return null;
         }
 
+        /// <summary>The tripwire post, asserted present — for the assertions that only run
+        /// after <c>WaitForTripwire()</c> has already confirmed one was emitted.</summary>
+        private FakeSignalIngressSink.PostedSignal RequireTripwirePost()
+        {
+            var post = FindTripwirePost();
+            Assert.NotNull(post);
+            return post!;
+        }
+
         private int CountTripwirePosts()
         {
             var count = 0;
@@ -165,9 +174,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             Thread.Sleep(SuppressWait);
             Assert.Equal(1, CountTripwirePosts());
 
-            var post = FindTripwirePost();
+            var post = RequireTripwirePost();
             Assert.Equal(DecisionSignalKind.InformationalEvent, post.Kind);
-            Assert.Equal(nameof(SessionStage.EspAccountSetup), post.Payload["stage"]);
+            Assert.Equal(nameof(SessionStage.EspAccountSetup), post.Payload!["stage"]);
             Assert.Equal("Warning", post.Payload[SignalPayloadKeys.Severity]);
             Assert.Equal("true", post.Payload[SignalPayloadKeys.ImmediateUpload]);
             Assert.Contains("esp_final_exit", post.Payload["signalsSeen"]);
@@ -222,7 +231,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             sut.ApplyStep(step, signal);
 
             Assert.True(WaitForTripwire());
-            Assert.Equal(DeadlineNames.ClassifierTick, FindTripwirePost().Payload["armedDeadlines"]);
+            Assert.Equal(DeadlineNames.ClassifierTick, RequireTripwirePost().Payload!["armedDeadlines"]);
         }
 
         [Fact]
@@ -237,7 +246,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             sut.ApplyStep(step, signal);
 
             Assert.True(WaitForTripwire());
-            Assert.Equal(nameof(SessionStage.AwaitingDesktop), FindTripwirePost().Payload["stage"]);
+            Assert.Equal(nameof(SessionStage.AwaitingDesktop), RequireTripwirePost().Payload!["stage"]);
         }
 
         // ===================================================================== Dwell semantics

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Orchestration/DeviceInfoHostTriggerTests.cs

@@ -37,5 +37,41 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             Assert.False(DeviceInfoHost.IsEndTrigger(DecisionSignalKind.EspPhaseChanged, null));
             Assert.False(DeviceInfoHost.IsEndTrigger(DecisionSignalKind.InformationalEvent, Phase("FinalizingSetup")));
         }
+
+        // Audit Q2 — the payload shape the adapter's apps sub-phase declaration produces on the
+        // ingress rail (InformationalEventPost: eventType + declared phase enum name).
+        private static IReadOnlyDictionary<string, string> SubPhaseDeclaration(string declaredPhase) =>
+            new Dictionary<string, string>
+            {
+                { SignalPayloadKeys.EventType, AutopilotMonitor.Shared.Constants.EventTypes.PhaseTransition },
+                { AutopilotMonitor.Agent.V2.Core.Telemetry.Events.EventTimelineEmitter.PhaseParamKey, declaredPhase },
+            };
+
+        [Fact]
+        public void Apps_subphase_declarations_classify_as_esp_config_refresh_triggers()
+        {
+            Assert.Equal(DeviceInfoHost.EspConfigTriggerAppsDevice,
+                DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.InformationalEvent, SubPhaseDeclaration("AppsDevice")));
+            Assert.Equal(DeviceInfoHost.EspConfigTriggerAppsUser,
+                DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.InformationalEvent, SubPhaseDeclaration("AppsUser")));
+            // Non-apps phase declarations (e.g. the reducer's Finalizing entry) never classify.
+            Assert.Null(DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.InformationalEvent, SubPhaseDeclaration("FinalizingSetup")));
+            // A phase_transition without a declared phase never classifies.
+            Assert.Null(DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.InformationalEvent,
+                new Dictionary<string, string> { { SignalPayloadKeys.EventType, AutopilotMonitor.Shared.Constants.EventTypes.PhaseTransition } }));
+        }
+
+        [Fact]
+        public void AccountSetup_phase_classifies_as_the_user_setup_refresh_trigger()
+        {
+            Assert.Equal(DeviceInfoHost.EspConfigTriggerAccountSetup,
+                DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.EspPhaseChanged, Phase("AccountSetup")));
+            // DeviceSetup is the enrollment-start trigger, not an ESP-config refresh.
+            Assert.Null(DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.EspPhaseChanged, Phase("DeviceSetup")));
+            Assert.Null(DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.EspPhaseChanged, null));
+            // Unrelated informational events never classify.
+            Assert.Null(DeviceInfoHost.ClassifyEspConfigRefreshTrigger(DecisionSignalKind.InformationalEvent,
+                new Dictionary<string, string> { { SignalPayloadKeys.EventType, "esp_config_detected" } }));
+        }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Orchestration/EnrollmentOrchestratorEventBridgeTests.cs

@@ -54,6 +54,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
             public ISignalIngressSink? CapturedIngress { get; private set; }
             public IClock? CapturedClock { get; private set; }
             public AutopilotMonitor.Agent.V2.Core.Transport.Telemetry.ITelemetrySpool? CapturedTelemetrySpool { get; private set; }
+            public TimelineEventStream? CapturedTimelineEvents { get; private set; }
 
             public CollectorSurfaces CreateCollectorHosts(
                 string sessionId,
@@ -62,12 +63,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
                 IReadOnlyCollection<string> whiteGloveSealingPatternIds,
                 ISignalIngressSink ingress,
                 IClock clock,
-                AutopilotMonitor.Agent.V2.Core.Transport.Telemetry.ITelemetrySpool? telemetrySpool)
+                AutopilotMonitor.Agent.V2.Core.Transport.Telemetry.ITelemetrySpool? telemetrySpool,
+                TimelineEventStream? timelineEvents = null)
             {
                 CapturedWhiteGloveSealingPatternIds = whiteGloveSealingPatternIds;
                 CapturedIngress = ingress;
                 CapturedClock = clock;
                 CapturedTelemetrySpool = telemetrySpool;
+                CapturedTimelineEvents = timelineEvents;
                 foreach (var name in HostNames)
                 {
                     Hosts.Add(new FakeCollectorHost(name));