fix(release): stamp Cache-Control no-cache on every blob upload

The first release after the download-alias migration exposed Front Door
caching as a correctness hazard: the alias kept serving the previous
version.json (X-Cache: TCP_REMOTE_HIT) after the origin had rotated to
2.0.1370, pinning the portal's version badge to the old build. The dangerous
variant is worse than a stale badge -- manifest and ZIP are independent cache
entries, so a stale manifest paired with a fresh ZIP fails the bootstrap's
SHA-256 integrity check and the install dies.

Route caching on /agent/* has been disabled (infra side); this commit is the
defense-in-depth half: every upload now carries x-ms-blob-cache-control
no-cache -- the CI Send-Blob (eu and legacy mirror alike), the local build.ps1
counterpart (gitignored, changed in lockstep), and the versions/*.json
manifest publishes. Uniform no-cache rather than an immutable/mutable split
because every blob in the agent container rotates in place, including the
per-line AutopilotMonitor-Agent-v2.zip -- nothing there is safely cacheable.
Existing blobs get the header with the next release's re-upload.

Log/docs updated in url-registry.md; no code paths changed, YAML and ps1
parse-checked.

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,77 +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: '8.0.x'
+          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>') {
@@ -227,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
           }
@@ -265,12 +220,23 @@ jobs:
         run: |
           $containerUrl = "https://autopilotmonitoreu.blob.core.windows.net/agent"
           $sasToken = "${{ secrets.AZURE_BLOB_AGENT_SAS_TOKEN }}".TrimStart('?')
+          # Legacy mirror (transition until customers moved to the download.-alias):
+          # blobs are ALSO pushed to the old account so the bootstrap URL baked into
+          # customers' Intune scripts keeps serving current bits. Fail-soft -- a
+          # legacy hiccup must never fail a release. Counter lives ONLY on eu.
+          $legacyContainerUrl = "https://autopilotmonitor.blob.core.windows.net/agent"
+          $legacySasToken = "${{ secrets.AZURE_BLOB_AGENT_LEGACY_SAS_TOKEN }}".TrimStart('?')
 
           function Send-Blob {
             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))
@@ -279,6 +245,14 @@ jobs:
             Write-Host "Uploading $BlobName ($([math]::Round($bytes.Length / 1MB, 2)) MB)..."
             Invoke-RestMethod -Uri $url -Method Put -Headers $headers -Body $bytes
             Write-Host "  uploaded $BlobName"
+            if (-not [string]::IsNullOrEmpty($legacySasToken)) {
+              try {
+                Invoke-RestMethod -Uri "$legacyContainerUrl/$BlobName`?$legacySasToken" -Method Put -Headers $headers -Body $bytes
+                Write-Host "  mirrored $BlobName to legacy storage"
+              } catch {
+                Write-Host "::warning::legacy mirror failed for $BlobName -- $($_.Exception.Message)"
+              }
+            }
           }
 
           # Versioned namespace (always)
@@ -337,13 +311,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,120 @@
+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: '20'
+          cache: npm
+          cache-dependency-path: src/Web/autopilot-monitor-web/package-lock.json
+
+      - run: npm ci
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - 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: '20'
+          cache: npm
+          cache-dependency-path: src/McpServer/autopilot-monitor-mcp/package-lock.json
+
+      - run: npm ci
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - name: Tests
+        run: npm test
+
+  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: '20'
+
+      - 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
+        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
+        with:
+          category: /language:${{ matrix.language }}

.github/workflows/combine-rules.yml

@@ -22,9 +22,9 @@ 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'
 

.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

@@ -1,4 +1,4 @@
-name: Azure Static Web Apps CI/CD
+name: Deploy Web (Static Web App)
 
 on:
   push:
@@ -6,7 +6,7 @@ on:
       - main
     paths:
       - 'src/Web/autopilot-monitor-web/**'
-      - '.github/workflows/azure-static-web-apps-brave-grass-0070b5703.yml'
+      - '.github/workflows/deploy-web.yml'
   workflow_dispatch:
   pull_request:
     types: [opened, synchronize, reopened, closed]
@@ -14,7 +14,7 @@ on:
       - main
     paths:
       - 'src/Web/autopilot-monitor-web/**'
-      - '.github/workflows/azure-static-web-apps-brave-grass-0070b5703.yml'
+      - '.github/workflows/deploy-web.yml'
 
 jobs:
   build_and_deploy_job:
@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Build and Deploy Job
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           lfs: false
           fetch-depth: 0  # Full history needed for git-based sitemap lastmod dates
@@ -37,8 +37,11 @@ jobs:
           NEXT_PUBLIC_PLATFORM_STATS_MANIFEST_URL: ${{ vars.NEXT_PUBLIC_PLATFORM_STATS_MANIFEST_URL }}
           NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING: ${{ secrets.NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING }}
         with:
-          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_BRAVE_GRASS_0070B5703 }}
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
           repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
+          # Dependabot PRs run without repo secrets, so the deploy token is absent.
+          # Skip (green) instead of failing the check; real deploys on main still have the token.
+          skip_deploy_on_missing_secrets: true
           action: "upload"
           ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
           # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
@@ -56,7 +59,7 @@ jobs:
         id: closepullrequest
         uses: Azure/static-web-apps-deploy@v1
         with:
-          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_BRAVE_GRASS_0070B5703 }}
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
           action: "close"
 
 

.gitignore

@@ -117,8 +117,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/

README.md

@@ -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
 

build.ps1

@@ -53,7 +53,7 @@ try {
     Write-Host "  ✓ .NET SDK version: $dotnetVersion" -ForegroundColor Green
 }
 catch {
-    Write-Host "  ✗ .NET SDK not found. Please install .NET 8 SDK." -ForegroundColor Red
+    Write-Host "  ✗ .NET SDK not found. Please install .NET 10 SDK." -ForegroundColor Red
     exit 1
 }
 
@@ -145,7 +145,7 @@ Write-Host "============================================" -ForegroundColor Cyan
 Write-Host ""
 Write-Host "Output locations:" -ForegroundColor White
 Write-Host "  Agent:     src\Agent\AutopilotMonitor.Agent.V2\bin\$Configuration\net48\" -ForegroundColor Gray
-Write-Host "  Functions: src\Backend\AutopilotMonitor.Functions\bin\$Configuration\net8.0\" -ForegroundColor Gray
+Write-Host "  Functions: src\Backend\AutopilotMonitor.Functions\bin\$Configuration\net10.0\" -ForegroundColor Gray
 
 if ($IncludeWeb) {
     Write-Host "  Web UI:    src\Web\autopilot-monitor-web\.next\" -ForegroundColor Gray

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/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/endpoint-migration.md

@@ -0,0 +1,88 @@
+---
+type: Concept
+title: Agent Endpoint Migration — Config-Channel Re-Home
+description: How the backend re-homes agents to a new API base URL (backend move or per-tenant region move) via MigrateToApiBaseUrl on the agent config response, and why HTTP redirects were rejected.
+resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/EndpointMigration.cs
+tags:
+  - agent
+  - backend
+  - config
+  - migration
+  - security
+timestamp: 2026-07-18T00:00:00+02:00
+---
+
+# Problem
+
+The agent's API base URL is compiled into the binary (`Constants.ApiBaseUrl`). No DNS/domain
+indirection is possible in front of the API: mTLS client-cert auth does not survive a reverse
+proxy (Front Door), and Flex Consumption custom-domain TLS is broken. A backend move (like the
+2026-07-18 WEU→GWC subscription migration) therefore hard-cuts every deployed agent still
+pointing at the old hostname. In-flight agents self-terminate safely (local MaxLifetime watchdog
++ CleanupService), but their sessions are lost and a per-tenant region move (EU→US) has no
+mechanism at all.
+
+# Mechanism
+
+`AgentConfigResponse.MigrateToApiBaseUrl` — served on `GET /api/agent/config` (incl. the
+bootstrap wrapper), the same control channel as the kill switch, fetched at every agent
+process start.
+
+Agent flow (`Program.RunAgent`, Phase 4):
+
+1. Config fetched from the compiled-in (old) base URL.
+2. Kill-switch check runs FIRST — **kill wins over migrate**.
+3. `AgentRuntimeConfig.Resolve` detects the migration signal directly after the fetch and
+   returns early, BEFORE merge / binary-integrity / bootstrap-cleanup — none of those side
+   effects may run against a config from the backend being abandoned (a migration stub may
+   advertise stale agent hashes; a spurious `IntegrityCheckFailed` + force-update would be
+   harmful).
+4. `Program.RunAgent` swaps `AgentConfiguration.ApiBaseUrl`, disposes the old client stack,
+   rebuilds Phase 3 (auth clients) and re-runs Phase 4 against the new URL —
+   `allowEndpointMigration: false`, so the new backend's config **cannot chain a second hop**.
+5. Kill-switch check runs again on the NEW backend's config; startup continues normally
+   (Phase 5+ builds mTLS/telemetry clients from the updated base URL).
+
+# Hardening (mirrors the kill switch)
+
+* **Live fetch only** — the on-disk config cache strips `MigrateToApiBaseUrl` on write AND
+  read (`RemoteConfigService.CacheConfig` / `LoadCachedConfig`); `EndpointMigration.ResolveTarget`
+  re-checks `LastFetchOutcome == Succeeded` as defence-in-depth. A planted cache file can
+  never re-home an agent.
+* **Allowlist validated on BOTH sides** — `AgentEndpointMigrationRules` (Shared, single
+  source): https only, host must end in `.azurewebsites.net` on a label boundary, no
+  path/query/userinfo/port. The backend refuses to serve an invalid admin value
+  (`AgentMigrateRejected` warning); the agent refuses to honour one even if the backend was
+  compromised.
+* **One hop, no loops** — second Resolve pass never migrates; a target equal to the current
+  base URL is a no-op (steady state during the migration window).
+
+# Operation
+
+Global admin settings (`AdminConfiguration`, admin portal → Global Settings):
+
+* `AgentMigrateApiBaseUrl` — global target, set on the backend being **abandoned**; clear it
+  after the migration window.
+* `AgentMigrateTenantOverridesJson` — JSON object `tenantId → URL` for per-tenant moves.
+  An entry with an **empty string** pins that tenant against the global target (staged rollout).
+  Overrides win over the global value.
+
+Delivery evidence: every served target logs `AgentMigrateServed` (Warning — reaches App
+Insights) with tenant, serial, agent version and target. Agent-side, the re-home is logged as
+`Endpoint migration: backend re-homed this agent from … to …`.
+
+Reach limitation: agents that cannot complete an authenticated config fetch (e.g. cert-broken
+devices) never see the signal — they fall back to the local MaxLifetime/emergency-break
+lifecycle. During a migration window the old backend must keep running as a serving stub;
+keeping the old `*.azurewebsites.net` name parked afterwards also prevents hostname
+re-registration by third parties while stragglers drain.
+
+# Citations
+
+* `src/Shared/AutopilotMonitor.Shared/Services/AgentEndpointMigrationRules.cs` — shared validation rules
+* `src/Shared/AutopilotMonitor.Shared/Models/Config/AgentConfigResponse.cs` — wire field
+* `src/Backend/AutopilotMonitor.Functions/Functions/Config/GetAgentConfigFunction.cs` — `ResolveMigrateTarget` + serving (ConfigVersion 33)
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/EndpointMigration.cs` — agent-side evaluation
+* `src/Agent/AutopilotMonitor.Agent.V2/Runtime/AgentRuntimeConfig.cs` — early return before merge/integrity
+* `src/Agent/AutopilotMonitor.Agent.V2/Program.cs` — one-hop rebuild in `RunAgent`
+* Tests: `AgentEndpointMigrationTests` (backend), `EndpointMigrationTests` + `RemoteConfigServiceCacheHardeningTests` (agent)

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

@@ -12,11 +12,28 @@ 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.
+* [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.
+
+# 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.
+
+# 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.
+
+# 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.
 
 # Security & Identity
 

docs/log.md

@@ -1,5 +1,45 @@
 # Log
 
+## 2026-07-23
+
+* **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-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/rules/gather-rule-guardrails.md

@@ -0,0 +1,81 @@
+---
+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-07-22
+---
+
+# Concept
+
+A gather rule is authored by a **tenant administrator** through `POST /api/rules/gather` and executed by the agent as **SYSTEM** on an enrolling device. The backend does not validate `collectorType`, `target`, or `parameters` at all — it only enforces scope/emit-mode fields, a 1 MB body cap, and that the rule lands in the caller's own tenant partition. Everything that decides *what a rule may reach* is therefore enforced **on the agent**, in `GatherRuleGuards`.
+
+This is the security boundary. The portal's `ValidationIndicator` is a convenience: it does not block submit, and the API is reachable directly.
+
+# 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` | prefix, boundary whitespace or end |
+| `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`) **for display only**. Enforcement is the C# constant.
+
+# 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.
+
+# 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

@@ -0,0 +1,136 @@
+---
+type: Concept
+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
+---
+
+# Problem
+
+Interval gather rules (e.g. a registry poll every 60 s) ran during **all** enrollment phases
+and emitted an event on **every** tick — including `exists=false` events while the target key
+did not exist yet. A rule needed only from Account Setup onwards produced hundreds of
+identical noise events per session and wasted collector runs.
+
+# Schema
+
+Three opt-in fields on `GatherRule` (Shared model, `rules/schema/gather-rule.schema.json`,
+delivered to the agent via `GET agent/config`; ConfigVersion 34). Absent fields = legacy
+behavior — full back-compat.
+
+| Field | Type | Semantics |
+|---|---|---|
+| `activePhases` | `string[]` \| null | Rule runs only while the current phase is in the list. Null/empty = unrestricted. |
+| `activeFromPhase` | `string` \| null | Sticky latch: activates when the phase first reaches the threshold, then stays active for the rest of the session — including through `Failed`. Null = unrestricted. |
+| `emitMode` | `"always"` \| `"on_change"` \| null | `on_change`: poll on the trigger cadence, emit only when the collected result changes. Null/`always` = emit every collection (legacy). |
+
+Canonical phase tokens are the `EnrollmentPhase` enum **names** `Start`(0) …`Complete`(7).
+Backend validation (`GatherRulesFunction.ValidateScopeAndEmitMode`) rejects `Unknown`/`Failed`,
+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.
+
+# Scope semantics (agent, `GatherRuleExecutor`)
+
+* Scope applies to **all trigger types**:
+  * `interval` — timers keep running; an out-of-scope tick is a free early-return (no
+    start/stop lifecycle races on phase transitions).
+  * `startup` — a scoped startup rule not yet in scope at `UpdateRules` is **deferred**: it
+    runs exactly once from `OnPhaseChanged` when its scope activates (same
+    `_startupRulesExecuted` dedup; it is not part of the `WaitForStartupRules` latch).
+  * `phase_change` — evaluated against the **new** phase; the scope gate runs before the
+    per-(rule, phase) dedup so an out-of-scope pass does not consume the execution slot.
+  * `on_event` — gated by the current phase.
+* **Before the first phase signal** of a session (`_currentPhase == Unknown`) scoped rules are
+  inactive. Sessions that never produce phase signals never run them (documented behavior).
+* **From-phase latch**: activates when `phase != Unknown && phase != Failed && (int)phase >=
+  (int)fromPhase`. `Failed=99` would ordinal-satisfy every threshold, hence the explicit
+  exclusion — but once latched, a rule stays active through `Failed`. A config refresh that
+  delivers a from-phase rule after its threshold passed latches it immediately.
+* `--run-gather-rules` (diagnostic CLI) sets `IgnorePhaseScope = true` — no phase context
+  exists there, scoped rules execute unconditionally (log line marks the bypass).
+
+# Emit-on-change semantics
+
+* The collector result dict is canonically hashed (keys ordinal-sorted at every nesting
+  level, invariant value formatting, SHA-256) **before** `ruleId`/`ruleTitle` injection.
+* First in-scope non-empty result always emits — on an absent registry key that first
+  `exists=false` event *is* the visible "we're polling now" indicator.
+* Unchanged results increment a per-rule suppression counter; the next emitted event carries
+  `suppressedPolls` + `suppressedSinceUtc` in its `Data` so the gap is observable.
+* Composition with `emitOnlyIfExists=true` (collector-level): a miss returns an empty dict —
+  no emit AND no hash update. Result: zero noise while absent, one event on appearance, then
+  only on change.
+* State is in-memory and survives `UpdateRules` config refreshes; an agent restart causes at
+  most one re-emit per rule (acceptable under the per-enrollment lifecycle).
+* Volatile collectors (eventlog timestamps, logparser positions) degrade `on_change` to
+  `always` — every poll hashes differently. The option stays visible for them since some
+  outputs are stable; this is documented, not hidden.
+
+# Portal & delivery
+
+* Create form defaults new rules to `emitMode: "on_change"`; existing rules load as
+  `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
+  preserves `CreatedAt` on full edits. This fix is a prerequisite: without it every toggle
+  would silently clear the new fields.
+* Old agents (Newtonsoft) ignore unknown config properties: scoped rules run everywhere,
+  `emitMode` is ignored — graceful degradation until the fleet rolls forward.
+* `ContentEquivalent` treats null and empty `activePhases` as equal, so pre-existing DB rows
+  (absent columns → null) never diff against seeds — no reseed churn.
+
+# Citations
+
+* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs` — scope gates, latch, canonical hash
+* `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)

docs/url-registry.md

@@ -0,0 +1,85 @@
+---
+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`, `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.
+
+# 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

global.json

@@ -0,0 +1,6 @@
+{
+  "sdk": {
+    "version": "10.0.200",
+    "rollForward": "latestFeature"
+  }
+}

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.')
+param entraClientId string = '1a400946-62c1-4ab4-aa37-f730ac89704d'
+
+@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)')
+param toolLoggingEnabled bool = false
+
+// --- 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/dist/analyze-rules.json

@@ -1785,6 +1785,105 @@
         "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-ID-001",
       "title": "Expected Machine Certificate Not Found",

rules/guardrails.json

@@ -109,6 +109,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",

rules/schema/gather-rule.schema.json

@@ -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,12 +90,30 @@
         },
         "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",
           "description": "Event type to trigger on (only used when trigger = \"on_event\")."
         },
+        "activePhases": {
+          "type": "array",
+          "description": "Run the rule only while the current enrollment phase is one of these phases (EnrollmentPhase enum names). Empty/absent = unrestricted. Mutually exclusive with activeFromPhase.",
+          "items": {
+            "type": "string",
+            "enum": ["Start", "DevicePreparation", "DeviceSetup", "AppsDevice", "AccountSetup", "AppsUser", "FinalizingSetup", "Complete"]
+          }
+        },
+        "activeFromPhase": {
+          "type": "string",
+          "description": "Activate the rule once the enrollment phase first reaches this phase, then keep it active for the rest of the session (sticky latch). Absent = unrestricted. Mutually exclusive with activePhases.",
+          "enum": ["Start", "DevicePreparation", "DeviceSetup", "AppsDevice", "AccountSetup", "AppsUser", "FinalizingSetup", "Complete"]
+        },
+        "emitMode": {
+          "type": "string",
+          "description": "Emit behavior: \"always\" (default — emit on every collection) or \"on_change\" (poll on the trigger cadence but emit only when the collected result changes; the first in-scope result always emits).",
+          "enum": ["always", "on_change"]
+        },
         "outputEventType": {
           "type": "string",
           "description": "EventType for the emitted event (e.g., \"gather_proxy_settings\")."

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,18 @@ ${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)}
+];
 `;
 
   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');
 }

scripts/Bootstrap/Install-AutopilotMonitor-dev.ps1

@@ -56,6 +56,10 @@
       PowerShell 5.1 (IME) reads scripts without BOM as ANSI, corrupting multi-byte chars.
 
 .CHANGELOG
+    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
@@ -80,7 +84,7 @@
 [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",
@@ -93,7 +97,7 @@ param(
 )
 
 # Script version (bump on meaningful changes; see .CHANGELOG above)
-$ScriptVersion = "2.1"
+$ScriptVersion = "2.2"
 
 # Configuration - Everything in ProgramData for easy cleanup
 $AgentBasePath = "$env:ProgramData\AutopilotMonitor"

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

@@ -0,0 +1,99 @@
+using AutopilotMonitor.Agent.V2.Core.Configuration;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
+{
+    /// <summary>
+    /// Pins the agent-side endpoint-migration contract (<see cref="EndpointMigration"/>):
+    /// only a LIVE fetch is honoured, the target must pass the shared allowlist rules even
+    /// though the backend already validated it, and serving the agent its own current URL is
+    /// a no-op — the exact mirror of the kill-switch live-fetch hardening.
+    /// </summary>
+    public sealed class EndpointMigrationTests
+    {
+        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) =>
+            new AgentConfigResponse { MigrateToApiBaseUrl = migrateUrl };
+
+        [Fact]
+        public void Live_fetch_with_valid_differing_target_migrates()
+        {
+            var target = EndpointMigration.ResolveTarget(
+                Config(TargetUrl), RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null);
+
+            Assert.Equal(TargetUrl, target);
+        }
+
+        [Fact]
+        public void Target_is_normalized_to_lowercase_host_without_trailing_slash()
+        {
+            var target = EndpointMigration.ResolveTarget(
+                Config("https://AutopilotMonitor-API-US.azurewebsites.net/"),
+                RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null);
+
+            Assert.Equal(TargetUrl, target);
+        }
+
+        [Theory]
+        [InlineData(RemoteConfigFetchOutcome.FromCache)]
+        [InlineData(RemoteConfigFetchOutcome.UsedDefaults)]
+        [InlineData(RemoteConfigFetchOutcome.NotAttempted)]
+        public void Non_live_fetch_is_never_honoured(RemoteConfigFetchOutcome outcome)
+        {
+            Assert.Null(EndpointMigration.ResolveTarget(
+                Config(TargetUrl), outcome, CurrentUrl, logger: null));
+        }
+
+        [Fact]
+        public void Null_config_and_empty_signal_are_noops()
+        {
+            Assert.Null(EndpointMigration.ResolveTarget(
+                null, RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null));
+            Assert.Null(EndpointMigration.ResolveTarget(
+                Config(null), RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null));
+            Assert.Null(EndpointMigration.ResolveTarget(
+                Config("   "), RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null));
+        }
+
+        [Fact]
+        public void Target_equal_to_current_url_is_a_noop()
+        {
+            // Steady state during a migration window: agent already runs on the target
+            // (case/trailing-slash differences must not cause a rebuild loop).
+            Assert.Null(EndpointMigration.ResolveTarget(
+                Config(CurrentUrl), RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null));
+            Assert.Null(EndpointMigration.ResolveTarget(
+                Config(CurrentUrl.ToUpperInvariant() + "/"), RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null));
+        }
+
+        [Theory]
+        [InlineData("http://autopilotmonitor-api-us.azurewebsites.net")]        // https only
+        [InlineData("https://attacker.example.com")]                             // host not allowlisted
+        [InlineData("https://evil-azurewebsites.net")]                           // suffix must sit on a label boundary
+        [InlineData("https://.azurewebsites.net")]                               // empty host prefix
+        [InlineData("https://api.azurewebsites.net:8443")]                       // non-default port
+        [InlineData("https://user:pw@api.azurewebsites.net")]                    // userinfo
+        [InlineData("https://api.azurewebsites.net/some/path")]                  // base URL only
+        [InlineData("https://api.azurewebsites.net?x=1")]                        // no query
+        [InlineData("not a url")]
+        public void Invalid_targets_are_rejected(string candidate)
+        {
+            Assert.Null(EndpointMigration.ResolveTarget(
+                Config(candidate), RemoteConfigFetchOutcome.Succeeded, CurrentUrl, logger: null));
+        }
+
+        [Fact]
+        public void Dev_api_url_override_still_migrates_to_valid_target()
+        {
+            // The running base URL may be a non-allowlisted dev override (--api-url); the
+            // comparison falls back to plain normalization and the migration still applies.
+            var target = EndpointMigration.ResolveTarget(
+                Config(TargetUrl), RemoteConfigFetchOutcome.Succeeded, "http://localhost:7071", logger: null);
+
+            Assert.Equal(TargetUrl, target);
+        }
+    }
+}

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

@@ -62,6 +62,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
                 DeviceBlocked = true,
                 DeviceKillSignal = true,
                 UnblockAt = new DateTime(2099, 1, 1, 0, 0, 0, DateTimeKind.Utc),
+                MigrateToApiBaseUrl = "https://attacker.azurewebsites.net",
             };
 
             probe.DoCache(config);
@@ -69,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);
@@ -76,9 +78,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
             Assert.False(persisted.DeviceBlocked);
             Assert.False(persisted.DeviceKillSignal);
             Assert.Null(persisted.UnblockAt);
+            Assert.Null(persisted.MigrateToApiBaseUrl);
 
-            // The attacker EXE hash must not appear anywhere in the persisted bytes.
+            // The attacker EXE hash / re-home host must not appear anywhere in the persisted bytes.
             Assert.DoesNotContain("deadbeef", raw);
+            Assert.DoesNotContain("attacker.azurewebsites.net", raw);
 
             // Benign fields survive the strip.
             Assert.Equal(77, persisted.ConfigVersion);
@@ -92,6 +96,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
             Assert.True(config.DeviceBlocked);
             Assert.True(config.DeviceKillSignal);
             Assert.Equal(new DateTime(2099, 1, 1, 0, 0, 0, DateTimeKind.Utc), config.UnblockAt);
+            Assert.Equal("https://attacker.azurewebsites.net", config.MigrateToApiBaseUrl);
         }
 
         // ── Read path: LoadCachedConfig strips a planted (attacker) cache file ─
@@ -103,6 +108,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
         [InlineData("DeviceBlocked")]
         [InlineData("DeviceKillSignal")]
         [InlineData("UnblockAt")]
+        [InlineData("MigrateToApiBaseUrl")]
         public void LoadCachedConfig_strips_planted_security_sensitive_field(string field)
         {
             var probe = NewProbe();
@@ -119,6 +125,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
                 DeviceBlocked = true,
                 DeviceKillSignal = true,
                 UnblockAt = new DateTime(2099, 1, 1, 0, 0, 0, DateTimeKind.Utc),
+                MigrateToApiBaseUrl = "https://attacker.azurewebsites.net",
             };
             File.WriteAllText(_cachePath, JsonConvert.SerializeObject(attacker, Formatting.Indented));
 
@@ -145,6 +152,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Configuration
                 case "UnblockAt":
                     Assert.Null(loaded.UnblockAt);
                     break;
+                case "MigrateToApiBaseUrl":
+                    Assert.Null(loaded.MigrateToApiBaseUrl);
+                    break;
                 default:
                     throw new InvalidOperationException($"unknown field {field}");
             }

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/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/Monitoring/Gather/GatherRuleCollectorGuardTests.cs

@@ -0,0 +1,406 @@
+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
+        public void RegistryCollector_OffAllowlistPath_IsBlockedBeforeTheHiveIsOpened(string target)
+            => AssertBlocked(new RegistryCollector().Execute(Rule("registry", target), Context()), target);
+
+        [Theory]
+        [InlineData("SELECT * FROM Win32_UserAccount")]
+        [InlineData("SELECT * FROM Win32_ShadowCopy")]
+        [InlineData("SELECT * FROM Win32_OperatingSystemExtra")]          // prefix spoofing
+        public void WmiCollector_OffAllowlistQuery_IsBlockedBeforeTheQueryRuns(string query)
+            => AssertBlocked(new WmiCollector().Execute(Rule("wmi", query), Context()), query);
+
+        [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/GatherRuleExecutorEmitModeTests.cs

@@ -0,0 +1,249 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Linq;
+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>
+    /// EmitMode "on_change" on <see cref="GatherRuleExecutor"/>: poll on the trigger cadence but
+    /// emit only when the collected result changes. The dedup state machine is asserted
+    /// synchronously via the internal <c>ShouldEmitOnChange</c> / <c>ComputeCanonicalHash</c>
+    /// (no timer races); the ExecuteRule wiring (hash-before-injection, empty-result no-op,
+    /// emitOnlyIfExists composition) through the public startup path.
+    /// </summary>
+    [Collection("SerialThreading")] // startup rules execute on the shared ThreadPool
+    public sealed class GatherRuleExecutorEmitModeTests : 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_7e3a1f4b-0000-0000-0000-000000000000";
+
+        public GatherRuleExecutorEmitModeTests()
+        {
+            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 EnrollmentEvent SingleEvent()
+        {
+            lock (_eventsGate) return Assert.Single(_events);
+        }
+
+        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 OnChangeRule(string id = "GATHER-OC-001") => new GatherRule
+        {
+            RuleId = id,
+            Title = id,
+            CollectorType = "registry",
+            Target = AbsentPath,
+            Trigger = "interval",
+            IntervalSeconds = 3600,
+            OutputEventType = "gather_test",
+            Enabled = true,
+            EmitMode = "on_change",
+        };
+
+        private static Dictionary<string, object> Result(params (string Key, object Value)[] pairs)
+        {
+            var d = new Dictionary<string, object>();
+            foreach (var (key, value) in pairs) d[key] = value;
+            return d;
+        }
+
+        // ── on_change state machine (synchronous) ──────────────────────────
+
+        [Fact]
+        public void FirstResult_AlwaysEmits_ThenUnchangedIsSuppressed_ThenChangeReemits()
+        {
+            var rule = OnChangeRule();
+
+            Assert.True(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));   // first
+            Assert.False(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));  // unchanged
+            Assert.False(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));  // unchanged
+            Assert.True(_executor.ShouldEmitOnChange(rule, Result(("exists", true), ("Version", "1")))); // changed
+        }
+
+        [Fact]
+        public void EmitAfterSuppressionStreak_CarriesSuppressedPollCount_AndResets()
+        {
+            var rule = OnChangeRule();
+
+            Assert.True(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));
+            Assert.False(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));
+            Assert.False(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));
+            Assert.False(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));
+
+            var changed = Result(("exists", true));
+            Assert.True(_executor.ShouldEmitOnChange(rule, changed));
+            Assert.Equal(3, changed["suppressedPolls"]);
+            Assert.True(changed.ContainsKey("suppressedSinceUtc"));
+
+            // Counter must reset: the next change emits without a suppression payload.
+            var changedAgain = Result(("exists", false));
+            Assert.True(_executor.ShouldEmitOnChange(rule, changedAgain));
+            Assert.False(changedAgain.ContainsKey("suppressedPolls"));
+            Assert.False(changedAgain.ContainsKey("suppressedSinceUtc"));
+        }
+
+        [Fact]
+        public void SuppressionState_IsIsolatedPerRule()
+        {
+            var ruleA = OnChangeRule("GATHER-OC-A");
+            var ruleB = OnChangeRule("GATHER-OC-B");
+            var payload = Result(("exists", false));
+
+            Assert.True(_executor.ShouldEmitOnChange(ruleA, new Dictionary<string, object>(payload)));
+            // Same content, different rule: B has no hash yet — must emit.
+            Assert.True(_executor.ShouldEmitOnChange(ruleB, new Dictionary<string, object>(payload)));
+            Assert.False(_executor.ShouldEmitOnChange(ruleA, new Dictionary<string, object>(payload)));
+            Assert.False(_executor.ShouldEmitOnChange(ruleB, new Dictionary<string, object>(payload)));
+        }
+
+        [Fact]
+        public void DedupState_SurvivesUpdateRulesRefresh()
+        {
+            var rule = OnChangeRule();
+            Assert.True(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));
+
+            // Config refresh mid-session must not reset the last-emitted hash (that would
+            // re-emit an unchanged result on every refresh).
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            Assert.False(_executor.ShouldEmitOnChange(rule, Result(("exists", false))));
+        }
+
+        // ── Canonical hashing ──────────────────────────────────────────────
+
+        [Fact]
+        public void CanonicalHash_IsKeyOrderInsensitive()
+        {
+            var a = new Dictionary<string, object> { ["alpha"] = 1, ["beta"] = "x" };
+            var b = new Dictionary<string, object> { ["beta"] = "x", ["alpha"] = 1 };
+
+            Assert.Equal(
+                GatherRuleExecutor.ComputeCanonicalHash(a),
+                GatherRuleExecutor.ComputeCanonicalHash(b));
+        }
+
+        [Fact]
+        public void CanonicalHash_DetectsValueChanges_IncludingNested()
+        {
+            var baseline = new Dictionary<string, object>
+            {
+                ["exists"] = true,
+                ["entries"] = new List<object> { new Dictionary<string, object> { ["id"] = 1 } },
+            };
+            var changedScalar = new Dictionary<string, object>
+            {
+                ["exists"] = false,
+                ["entries"] = new List<object> { new Dictionary<string, object> { ["id"] = 1 } },
+            };
+            var changedNested = new Dictionary<string, object>
+            {
+                ["exists"] = true,
+                ["entries"] = new List<object> { new Dictionary<string, object> { ["id"] = 2 } },
+            };
+
+            var baseHash = GatherRuleExecutor.ComputeCanonicalHash(baseline);
+            Assert.NotEqual(baseHash, GatherRuleExecutor.ComputeCanonicalHash(changedScalar));
+            Assert.NotEqual(baseHash, GatherRuleExecutor.ComputeCanonicalHash(changedNested));
+        }
+
+        [Fact]
+        public void CanonicalHash_DistinguishesTypeShapes()
+        {
+            // "1" (string) vs 1 (int) and null vs "<null>"-like strings must not collide.
+            Assert.NotEqual(
+                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>" }));
+        }
+
+        // ── ExecuteRule wiring (async via startup path) ────────────────────
+
+        [Fact]
+        public void AlwaysMode_EmitsEveryCollection()
+        {
+            // EmitMode absent (legacy) — repeated identical results all emit. Two executions of
+            // the same collector via two rules sharing the target prove no dedup is applied.
+            var rule1 = OnChangeRule("GATHER-AL-1"); rule1.EmitMode = null; rule1.Trigger = "startup";
+            var rule2 = OnChangeRule("GATHER-AL-2"); rule2.EmitMode = null; rule2.Trigger = "startup";
+
+            _executor.UpdateRules(new List<GatherRule> { rule1, rule2 });
+
+            Assert.True(_executor.WaitForStartupRules(30));
+            Assert.True(WaitForEventCount(2));
+        }
+
+        [Fact]
+        public void OnChange_FirstInScopePoll_EmitsExistsFalse_AsPollingIndicator()
+        {
+            // The first result on an absent key IS the visible "we're polling now" indicator.
+            var rule = OnChangeRule();
+            rule.Trigger = "startup";
+
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            Assert.True(_executor.WaitForStartupRules(30));
+            Assert.True(WaitForEventCount(1));
+            var evt = SingleEvent();
+            Assert.Equal(false, evt.Data["exists"]);
+            Assert.Equal("GATHER-OC-001", evt.Data["ruleId"]); // injection happened after hashing
+        }
+
+        [Fact]
+        public void OnChange_ComposedWithEmitOnlyIfExists_EmptyResultDoesNotTouchHashState()
+        {
+            // emitOnlyIfExists miss → empty result → no emit AND no hash update: the eventual
+            // first real result must still count as "first emit".
+            var rule = OnChangeRule();
+            rule.Trigger = "startup";
+            rule.Parameters = new Dictionary<string, string> { ["emitOnlyIfExists"] = "true" };
+
+            _executor.UpdateRules(new List<GatherRule> { rule });
+            Assert.True(_executor.WaitForStartupRules(30));
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount); // zero noise while the key is absent
+
+            // When the key appears (simulated via the state machine), the result emits as first.
+            Assert.True(_executor.ShouldEmitOnChange(rule, Result(("exists", true), ("Version", "1"))));
+        }
+    }
+}

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

@@ -0,0 +1,326 @@
+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>
+    /// Phase scoping on <see cref="GatherRuleExecutor"/> (ActivePhases / ActiveFromPhase):
+    /// the scope matrix is asserted synchronously via the internal <c>IsRuleInScope</c>
+    /// (no timer races); the trigger-path wiring (deferred startup, phase_change / on_event
+    /// gating) is asserted through the public API with positive event waits.
+    /// Rules use the absent-registry-path pattern from
+    /// <see cref="RegistryCollectorEmitOnlyIfExistsTests"/> so no real system state is touched.
+    /// </summary>
+    [Collection("SerialThreading")] // deferred startup rules execute on the shared ThreadPool
+    public sealed class GatherRuleExecutorPhaseScopeTests : 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_5b1c8d2e-0000-0000-0000-000000000000";
+
+        public GatherRuleExecutorPhaseScopeTests()
+        {
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            _executor = new GatherRuleExecutor(
+                "sess", "tenant",
+                evt => { lock (_eventsGate) _events.Add(evt); },
+                logger)
+            {
+                // Bypass the registry allowlist guard for the synthetic test path.
+                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;
+        }
+
+        /// <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)
+            => new GatherRule
+            {
+                RuleId = id,
+                Title = id,
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "interval",
+                IntervalSeconds = 3600,
+                OutputEventType = "gather_test",
+                Enabled = true,
+                ActivePhases = activePhases,
+                ActiveFromPhase = fromPhase,
+            };
+
+        private static GatherRule StartupRule(string id, List<string>? activePhases = null, string? fromPhase = null)
+            => new GatherRule
+            {
+                RuleId = id,
+                Title = id,
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "startup",
+                OutputEventType = "gather_test",
+                Enabled = true,
+                ActivePhases = activePhases,
+                ActiveFromPhase = fromPhase,
+            };
+
+        // ── Scope matrix (synchronous) ─────────────────────────────────────
+
+        [Fact]
+        public void UnscopedRule_IsInScope_EvenBeforeAnyPhaseSignal()
+        {
+            var rule = ScopeProbeRule("GATHER-SCOPE-000");
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            Assert.True(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void ActivePhases_InactiveBeforeFirstPhaseSignal()
+        {
+            var rule = ScopeProbeRule("GATHER-SCOPE-001", activePhases: new List<string> { "AccountSetup" });
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            Assert.False(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void ActivePhases_ActiveDuringListedPhase_InactiveAfterLeaving()
+        {
+            var rule = ScopeProbeRule("GATHER-SCOPE-002", activePhases: new List<string> { "AccountSetup" });
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            Assert.False(_executor.IsRuleInScope(rule));
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.True(_executor.IsRuleInScope(rule));
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+            Assert.False(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void ActivePhases_MatchIsCaseInsensitive()
+        {
+            var rule = ScopeProbeRule("GATHER-SCOPE-003", activePhases: new List<string> { "accountsetup" });
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.True(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void FromPhase_LatchesAtThreshold_AndStaysSticky_IncludingThroughFailed()
+        {
+            var rule = ScopeProbeRule("GATHER-SCOPE-010", fromPhase: "AccountSetup");
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            Assert.False(_executor.IsRuleInScope(rule)); // threshold not reached
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.True(_executor.IsRuleInScope(rule)); // latched
+
+            _executor.OnPhaseChanged(EnrollmentPhase.Failed);
+            Assert.True(_executor.IsRuleInScope(rule)); // sticky through Failed
+        }
+
+        [Fact]
+        public void FromPhase_NoSpuriousActivationViaFailed()
+        {
+            // Failed=99 would ordinal-satisfy every threshold — it must never latch.
+            var rule = ScopeProbeRule("GATHER-SCOPE-011", fromPhase: "AccountSetup");
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.Failed);
+            Assert.False(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void FromPhase_LatchesWhenThresholdIsSkippedOver()
+        {
+            // The session may never report the exact threshold phase — a later phase latches too.
+            var rule = ScopeProbeRule("GATHER-SCOPE-012", fromPhase: "AccountSetup");
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.FinalizingSetup);
+            Assert.True(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void FromPhase_RuleDeliveredByRefreshAfterPhaseReached_LatchesImmediately()
+        {
+            _executor.UpdateRules(new List<GatherRule>());
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+
+            // Config refresh delivers a new from-phase rule whose threshold already passed.
+            var rule = ScopeProbeRule("GATHER-SCOPE-013", fromPhase: "DeviceSetup");
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            Assert.True(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void BothFieldsSet_ActivePhasesWins()
+        {
+            // Backend validation rejects this shape; the agent defensively prefers ActivePhases.
+            var rule = ScopeProbeRule("GATHER-SCOPE-020",
+                activePhases: new List<string> { "DeviceSetup" }, fromPhase: "Start");
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.False(_executor.IsRuleInScope(rule)); // FromPhase(Start) would say yes — list wins
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            Assert.True(_executor.IsRuleInScope(rule));
+        }
+
+        [Fact]
+        public void IgnorePhaseScope_BypassesScope_WithoutPhaseContext()
+        {
+            _executor.IgnorePhaseScope = true;
+            var during = ScopeProbeRule("GATHER-SCOPE-030", activePhases: new List<string> { "AccountSetup" });
+            var from = ScopeProbeRule("GATHER-SCOPE-031", fromPhase: "Complete");
+            _executor.UpdateRules(new List<GatherRule> { during, from });
+
+            Assert.True(_executor.IsRuleInScope(during));
+            Assert.True(_executor.IsRuleInScope(from));
+        }
+
+        // ── Trigger-path wiring (async, positive waits) ────────────────────
+
+        [Fact]
+        public void UnscopedStartupRule_RunsImmediately()
+        {
+            _executor.UpdateRules(new List<GatherRule> { StartupRule("GATHER-START-000") });
+
+            Assert.True(_executor.WaitForStartupRules(30));
+            Assert.True(WaitForEventCount(1));
+        }
+
+        [Fact]
+        public void ScopedStartupRule_IsDeferred_ThenFiresExactlyOnce_WhenScopeActivates()
+        {
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                StartupRule("GATHER-START-001", fromPhase: "AccountSetup")
+            });
+
+            // Not in scope at UpdateRules: nothing queued, latch trivially satisfied.
+            Assert.True(_executor.WaitForStartupRules(30));
+            Assert.Equal(0, EventCount);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            Assert.Equal(0, EventCount);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.True(WaitForEventCount(1), "deferred startup rule should fire when its scope activates");
+
+            // Later phase changes must not re-fire it (dedup via _startupRulesExecuted).
+            _executor.OnPhaseChanged(EnrollmentPhase.AppsUser);
+            _executor.OnPhaseChanged(EnrollmentPhase.FinalizingSetup);
+            Thread.Sleep(300);
+            Assert.Equal(1, EventCount);
+        }
+
+        [Fact]
+        public void PhaseChangeRule_OutOfScopePhase_DoesNotFire_InScopePhaseFires()
+        {
+            // TriggerPhase empty = fires on every phase change; scope narrows it to AccountSetup.
+            var rule = new GatherRule
+            {
+                RuleId = "GATHER-PC-001",
+                Title = "pc",
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "phase_change",
+                TriggerPhase = "",
+                OutputEventType = "gather_test",
+                Enabled = true,
+                ActivePhases = new List<string> { "AccountSetup" },
+            };
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnPhaseChanged(EnrollmentPhase.DeviceSetup);
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Assert.True(WaitForEventCount(1));
+
+            // Same phase again: the (rule, phase) dedup slot is now consumed.
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            Thread.Sleep(300);
+            Assert.Equal(1, EventCount);
+        }
+
+        [Fact]
+        public void OnEventRule_GatedByScope()
+        {
+            var rule = new GatherRule
+            {
+                RuleId = "GATHER-OE-001",
+                Title = "oe",
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = "on_event",
+                TriggerEventType = "app_install_failed",
+                OutputEventType = "gather_test",
+                Enabled = true,
+                ActivePhases = new List<string> { "AccountSetup" },
+            };
+            _executor.UpdateRules(new List<GatherRule> { rule });
+
+            _executor.OnEvent("app_install_failed"); // no phase signal yet → out of scope
+            Thread.Sleep(300);
+            Assert.Equal(0, EventCount);
+
+            _executor.OnPhaseChanged(EnrollmentPhase.AccountSetup);
+            _executor.OnEvent("app_install_failed");
+            Assert.True(WaitForEventCount(1));
+        }
+
+        [Fact]
+        public void IgnorePhaseScope_ScopedStartupRule_RunsImmediately()
+        {
+            // The --run-gather-rules diagnostic path: scoped rules must execute unconditionally.
+            _executor.IgnorePhaseScope = true;
+            _executor.UpdateRules(new List<GatherRule>
+            {
+                StartupRule("GATHER-START-002", activePhases: new List<string> { "AccountSetup" })
+            });
+
+            Assert.True(_executor.WaitForStartupRules(30));
+            Assert.True(WaitForEventCount(1));
+        }
+    }
+}

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

@@ -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);
 

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/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/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/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/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/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/Program/LifecycleEmittersRemoteConfigTests.cs

@@ -256,8 +256,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
                 RemoteConfigFetchOutcome outcome,
                 int configVersion = 0,
                 int attempts = 1,
-                string failureType = null,
-                string failureMessage = null,
+                string? failureType = null,
+                string? failureMessage = null,
                 int? authStatusCode = null)
             {
                 // CurrentConfig is set via the protected SetConfig path — easiest:

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/SignalAdapters/EspFailureDetectedHResultTests.cs

@@ -33,7 +33,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
         [InlineData("Network connections (1 of 1 added)", null)]
         [InlineData("", null)]
         [InlineData(null, null)]
-        public void TryExtractErrorCode_extracts_parenthesised_hex_tail(string statusText, string expected)
+        public void TryExtractErrorCode_extracts_parenthesised_hex_tail(string? statusText, string? expected)
         {
             var actual = ProvisioningStatusTracker.TryExtractErrorCode(statusText);
             Assert.Equal(expected, actual);

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/SignalAdapters/ImeLogTrackerAdapterTimingTests.cs

@@ -195,7 +195,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
             var all = f.InfoEvents(SharedEventTypes.ScriptCompleted);
             Assert.Equal(2, all.Count);
             Assert.Equal("65.00", all[1].Payload!["durationSeconds"]);
-            Assert.Equal("cycle_including_reporting_latency", all[1].Payload["durationBasis"]);
+            Assert.Equal("cycle_including_reporting_latency", all[1].Payload!["durationBasis"]);
         }
 
         [Fact]

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/SignalAdapters/RealmJoinWatcherAdapterTests.cs

@@ -151,17 +151,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
         }
 
         [Fact]
-        public void TriggerPhaseChangedFromTest_emits_informational_only_no_decision_signal()
+        public void TriggerPhaseChangedFromTest_emits_typed_signal_and_informational_event()
         {
             using var f = new Fixture();
             using var adapter = new RealmJoinWatcherAdapter(f.Watcher, f.Ingress, f.Clock);
 
             adapter.TriggerPhaseChangedFromTest(prev: 100, curr: 200);
 
-            // Phase change is observability-only. There is no DecisionSignalKind.RealmJoinPhaseChanged.
+            // 1) Typed signal — persists LastDeploymentPhase and drives the aborted-RJ-ESP
+            //    detection in the reducer (session 224b2087). Not Detected/Resolved.
             Assert.DoesNotContain(f.Ingress.Posted, p => p.Kind == DecisionSignalKind.RealmJoinDetected);
             Assert.DoesNotContain(f.Ingress.Posted, p => p.Kind == DecisionSignalKind.RealmJoinResolved);
+            var decision = f.Ingress.Posted.Single(p => p.Kind == DecisionSignalKind.RealmJoinPhaseChanged);
+            Assert.Equal("RealmJoinWatcher", decision.SourceOrigin);
+            Assert.Equal("200", decision.Payload![DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase]);
+            Assert.Equal("100", decision.Payload[DecisionEngine.RealmJoinPayloadKeys.PreviousPhase]);
 
+            // 2) Dual-emit informational event keeps the existing timeline entry.
             var info = f.Ingress.Posted.Single(p =>
                 p.Kind == DecisionSignalKind.InformationalEvent
                 && p.Payload != null

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Telemetry/BandwidthEstimatorTests.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic;
 using Xunit;
@@ -19,7 +19,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
         private static List<BandwidthJobSample> Jobs(params BandwidthJobSample[] jobs)
             => new List<BandwidthJobSample>(jobs);
 
-        private static BandwidthJobSample Job(string fileId, long wan, long lan = 0)
+        private static BandwidthJobSample Job(string? fileId, long wan, long lan = 0)
             => new BandwidthJobSample { FileId = fileId, WanBytes = wan, LanBytes = lan };
 
         [Fact]
@@ -43,8 +43,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
             var estimate = estimator.TryBuildEstimate();
             Assert.NotNull(estimate);
             Assert.Equal(1, estimate.WanSampleCount);
-            Assert.Equal(16.0, estimate.WanMbpsP90.Value, 3);
-            Assert.Equal(16.0, estimate.WanMbpsMax.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsP90!.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsMax!.Value, 3);
             Assert.Equal(6_000_000, estimate.WanBytesObserved);
             Assert.Equal("10-50", estimate.Bucket);
         }
@@ -58,7 +58,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
             estimator.AddSnapshot(T0.AddSeconds(3), Jobs(Job("a", 3_000_000), Job("b", 3_000_000)));
 
             var estimate = estimator.TryBuildEstimate();
-            Assert.Equal(16.0, estimate.WanMbpsP90.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsP90!.Value, 3);
         }
 
         [Fact]
@@ -74,7 +74,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
 
             var estimate = estimator.TryBuildEstimate();
             Assert.Equal(2, estimate.WanSampleCount);
-            Assert.Equal(16.0, estimate.WanMbpsMax.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsMax!.Value, 3);
         }
 
         [Fact]
@@ -91,7 +91,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
             estimator.AddSnapshot(T0.AddSeconds(63), Jobs(Job("a", 106_000_000)));
             var estimate = estimator.TryBuildEstimate();
             Assert.Equal(1, estimate.WanSampleCount);
-            Assert.Equal(16.0, estimate.WanMbpsP90.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsP90!.Value, 3);
         }
 
         [Fact]
@@ -130,8 +130,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
             estimator.AddSnapshot(T0.AddSeconds(3), Jobs(Job("a", wan: 6_000_000, lan: 375_000_000)));
 
             var estimate = estimator.TryBuildEstimate();
-            Assert.Equal(16.0, estimate.WanMbpsP90.Value, 3);
-            Assert.Equal(1000.0, estimate.LanMbpsP90.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsP90!.Value, 3);
+            Assert.Equal(1000.0, estimate.LanMbpsP90!.Value, 3);
             Assert.Equal("10-50", estimate.Bucket); // bucket keyed to WAN, not LAN
         }
 
@@ -182,8 +182,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
 
             var estimate = estimator.TryBuildEstimate();
             Assert.Equal(20, estimate.WanSampleCount);
-            Assert.Equal(16.0, estimate.WanMbpsP90.Value, 3); // p90 stays on the steady plateau
-            Assert.Equal(160.0, estimate.WanMbpsMax.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsP90!.Value, 3); // p90 stays on the steady plateau
+            Assert.Equal(160.0, estimate.WanMbpsMax!.Value, 3);
         }
 
         [Fact]
@@ -265,7 +265,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry
 
             var estimate = estimator.TryBuildEstimate();
             Assert.Equal(1, estimate.WanSampleCount); // only the finite positive sample survived
-            Assert.Equal(16.0, estimate.WanMbpsP90.Value, 3);
+            Assert.Equal(16.0, estimate.WanMbpsP90!.Value, 3);
             Assert.Equal(0, estimate.WanBytesObserved);
         }
 

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Telemetry/Events/TelemetryEventEmitterTests.cs

@@ -17,13 +17,25 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry.Events
             FakeTelemetryTransport transport,
             out EventSequenceCounter counter,
             string sessionId = "sess-1",
-            string tenantId = "tenant-1")
+            string tenantId = "tenant-1",
+            Func<bool>? traceEventsEnabled = null)
         {
             var tmp = new TempDirectory();
             counter = new EventSequenceCounter(new EventSequencePersistence(tmp.File("seq.json")));
-            return new TelemetryEventEmitter(transport, counter, sessionId, tenantId);
+            return new TelemetryEventEmitter(transport, counter, sessionId, tenantId, traceEventsEnabled);
         }
 
+        private static EnrollmentEvent NewTraceEvent(string eventType = "outbound_ip") =>
+            new EnrollmentEvent
+            {
+                EventType = eventType,
+                Severity = EventSeverity.Trace,
+                Source = "test",
+                Timestamp = At,
+                Phase = EnrollmentPhase.Unknown,
+                Message = "trace message",
+            };
+
         private static EnrollmentEvent NewTestEvent(string eventType = "enrollment_complete") =>
             new EnrollmentEvent
             {
@@ -49,6 +61,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry.Events
             Assert.Equal("sess-1", evt.SessionId);
             Assert.Equal("tenant-1", evt.TenantId);
 
+            Assert.NotNull(item);
             Assert.Equal(TelemetryItemKind.Event, item.Kind);
             Assert.Equal("tenant-1_sess-1", item.PartitionKey);
             Assert.Equal(evt.RowKey, item.RowKey);
@@ -174,5 +187,86 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry.Events
             Assert.Equal("test-reason", (string?)data["reason"]);
             Assert.Equal("Strong", (string?)data["wgConfidence"]);
         }
+
+        // ============================================================ Trace-event gate
+
+        [Fact]
+        public void Trace_event_is_dropped_when_gate_is_off()
+        {
+            var transport = new FakeTelemetryTransport();
+            var emitter = Build(transport, out _, traceEventsEnabled: () => false);
+
+            var item = emitter.Emit(NewTraceEvent());
+
+            Assert.Null(item);
+            Assert.Equal(0, transport.EnqueueCount);
+        }
+
+        [Fact]
+        public void Trace_event_flows_when_gate_is_on()
+        {
+            var transport = new FakeTelemetryTransport();
+            var emitter = Build(transport, out _, traceEventsEnabled: () => true);
+
+            Assert.NotNull(emitter.Emit(NewTraceEvent()));
+            Assert.Equal(1, transport.EnqueueCount);
+        }
+
+        [Fact]
+        public void Trace_event_flows_when_no_gate_is_wired()
+        {
+            var transport = new FakeTelemetryTransport();
+            var emitter = Build(transport, out _);
+
+            Assert.NotNull(emitter.Emit(NewTraceEvent()));
+            Assert.Equal(1, transport.EnqueueCount);
+        }
+
+        [Fact]
+        public void Gate_off_does_not_suppress_non_trace_events()
+        {
+            var transport = new FakeTelemetryTransport();
+            var emitter = Build(transport, out _, traceEventsEnabled: () => false);
+
+            foreach (var severity in new[] { EventSeverity.Info, EventSeverity.Warning, EventSeverity.Error })
+            {
+                var evt = NewTestEvent();
+                evt.Severity = severity;
+                Assert.NotNull(emitter.Emit(evt));
+            }
+
+            Assert.Equal(3, transport.EnqueueCount);
+        }
+
+        [Fact]
+        public void Dropped_trace_event_does_not_consume_a_sequence_number()
+        {
+            var transport = new FakeTelemetryTransport();
+            var traceAllowed = true;
+            // ReSharper disable once AccessToModifiedClosure — deliberate: the gate is read
+            // per event, mirroring a mid-session remote-config merge.
+            var emitter = Build(transport, out _, traceEventsEnabled: () => traceAllowed);
+
+            emitter.Emit(NewTestEvent());          // seq 1
+            traceAllowed = false;
+            emitter.Emit(NewTraceEvent());         // dropped — must not burn seq 2
+            emitter.Emit(NewTestEvent());          // seq 2
+
+            Assert.Equal(2, transport.EnqueueCount);
+            var first = JObject.Parse(transport.Enqueued[0].PayloadJson);
+            var second = JObject.Parse(transport.Enqueued[1].PayloadJson);
+            Assert.Equal(1, (long)first["Sequence"]!);
+            Assert.Equal(2, (long)second["Sequence"]!);
+        }
+
+        [Fact]
+        public void Throwing_gate_fails_open_so_diagnostics_are_never_silently_lost()
+        {
+            var transport = new FakeTelemetryTransport();
+            var emitter = Build(transport, out _, traceEventsEnabled: () => throw new InvalidOperationException("boom"));
+
+            Assert.NotNull(emitter.Emit(NewTraceEvent()));
+            Assert.Equal(1, transport.EnqueueCount);
+        }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/EndpointMigration.cs

@@ -0,0 +1,57 @@
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Shared.Models;
+using AutopilotMonitor.Shared.Services;
+
+namespace AutopilotMonitor.Agent.V2.Core.Configuration
+{
+    /// <summary>
+    /// Agent-side evaluation of the config-channel endpoint migration signal
+    /// (<see cref="AgentConfigResponse.MigrateToApiBaseUrl"/>). Mirrors the kill-switch
+    /// hardening: only a LIVE fetch is honoured (the on-disk config cache strips the field on
+    /// write and read, and this check re-validates the outcome as defence-in-depth), and the
+    /// target must pass <see cref="AgentEndpointMigrationRules"/> even though the backend
+    /// already validated it — a compromised or misconfigured backend must not be able to
+    /// re-home agents to an arbitrary host.
+    /// </summary>
+    public static class EndpointMigration
+    {
+        /// <summary>
+        /// Returns the normalized migration target when the config carries a valid, live-fetched
+        /// re-home signal that differs from <paramref name="currentBaseUrl"/>; otherwise null.
+        /// Never throws — every rejection is logged and degrades to "no migration".
+        /// </summary>
+        public static string ResolveTarget(
+            AgentConfigResponse remoteConfig,
+            RemoteConfigFetchOutcome fetchOutcome,
+            string currentBaseUrl,
+            AgentLogger logger)
+        {
+            if (remoteConfig == null || string.IsNullOrWhiteSpace(remoteConfig.MigrateToApiBaseUrl))
+                return null;
+
+            if (fetchOutcome != RemoteConfigFetchOutcome.Succeeded)
+            {
+                logger?.Warning(
+                    $"Endpoint migration signal ignored — config source is {fetchOutcome}, not a live fetch.");
+                return null;
+            }
+
+            if (!AgentEndpointMigrationRules.IsEffectiveMigration(
+                    remoteConfig.MigrateToApiBaseUrl, currentBaseUrl, out var target))
+            {
+                // Either the target failed validation (scheme/host allowlist) or it equals the
+                // URL the agent is already using (steady state during a migration window once
+                // the new backend's own config echoes nothing).
+                if (target == null && !AgentEndpointMigrationRules.TryNormalizeTarget(
+                        remoteConfig.MigrateToApiBaseUrl, out _))
+                {
+                    logger?.Warning(
+                        $"Endpoint migration signal REJECTED — target failed validation: '{remoteConfig.MigrateToApiBaseUrl}'");
+                }
+                return null;
+            }
+
+            return target;
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/RemoteConfigService.cs

@@ -249,18 +249,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                 //   - DeviceBlocked/DeviceKillSignal/UnblockAt: kill is only honoured from a
                 //     live fetch — a planted cached kill would self-destruct every future
                 //     session, a stale cached kill would outlive the admin removing the rule
+                //   - MigrateToApiBaseUrl: endpoint re-home is only honoured from a live
+                //     fetch — a planted cached URL would silently redirect every future
+                //     session's telemetry to an attacker-chosen host
                 var liveUnrestricted = config.UnrestrictedMode;
                 var liveAllowDowngrade = config.AllowAgentDowngrade;
                 var liveExeHash = config.LatestAgentExeSha256;
                 var liveBlocked = config.DeviceBlocked;
                 var liveKill = config.DeviceKillSignal;
                 var liveUnblockAt = config.UnblockAt;
+                var liveMigrateUrl = config.MigrateToApiBaseUrl;
                 config.UnrestrictedMode = false;
                 config.AllowAgentDowngrade = false;
                 config.LatestAgentExeSha256 = null;
                 config.DeviceBlocked = false;
                 config.DeviceKillSignal = false;
                 config.UnblockAt = null;
+                config.MigrateToApiBaseUrl = null;
                 var json = JsonConvert.SerializeObject(config, Formatting.Indented);
                 config.UnrestrictedMode = liveUnrestricted;
                 config.AllowAgentDowngrade = liveAllowDowngrade;
@@ -268,6 +273,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                 config.DeviceBlocked = liveBlocked;
                 config.DeviceKillSignal = liveKill;
                 config.UnblockAt = liveUnblockAt;
+                config.MigrateToApiBaseUrl = liveMigrateUrl;
 
                 File.WriteAllText(_cacheFilePath, json);
                 _logger.Debug("Remote config cached to disk");
@@ -299,6 +305,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                         config.DeviceBlocked = false;
                         config.DeviceKillSignal = false;
                         config.UnblockAt = null;
+                        config.MigrateToApiBaseUrl = null;
                     }
                     return config;
                 }

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/MdmRebootPolicyTracker.cs

@@ -0,0 +1,628 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.Eventing.Reader;
+using System.IO;
+using System.Linq;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Xml.Linq;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Shared;
+using AutopilotMonitor.Shared.Models;
+using Newtonsoft.Json;
+
+namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals
+{
+    /// <summary>
+    /// Watches <c>Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider/Admin</c> for
+    /// EventID 2800 — logged once per MDM policy URI that matches the OS reboot-required catalog —
+    /// and emits ONE aggregated <c>mdm_policy_reboot_required</c> event per burst carrying the URI
+    /// list (<c>rebootUris</c>, <c>uriCount</c>, <c>firstRebootUri</c>).
+    /// <para>
+    /// Verified against session b2e890c1 (2026-07-20): the 2800 description reads
+    /// <c>The following URI has triggered a reboot: (./Device/...).</c> and records arrive in
+    /// sub-second bursts during policy sync — hence the debounce aggregation instead of per-record
+    /// events. CRITICAL semantics: only URIs applied DURING ESP DeviceSetup cause the coalesced
+    /// mid-ESP reboot ("second sign-in", PMPC research); later syncs (AccountSetup and beyond)
+    /// merely flag the requirement with no forced reboot. The event is therefore a NEUTRAL
+    /// observation (Info) — the reboot claim lives in ANALYZE-ESP-005, which requires an
+    /// actually-observed <c>system_reboot_detected</c> before attributing anything.
+    /// </para>
+    /// <para>
+    /// <b>Backfill + watermark.</b> Device policies can apply before the agent starts, and a
+    /// genuine coalesced reboot kills the agent BEFORE the debounced emit — in both cases the
+    /// post-(re)start backfill re-reads the .evtx and emits the aggregate then (historical
+    /// timestamps). The cross-restart RecordId watermark is persisted only at successful flush, so
+    /// a pre-emit death loses nothing and a completed emit is never repeated.
+    /// </para>
+    /// </summary>
+    internal sealed class MdmRebootPolicyTracker : IDisposable
+    {
+        internal const string Channel = "Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider/Admin";
+        internal const int EventId_PolicyRebootRequired = 2800;
+
+        internal const string WatermarkStateFileName = "mdm-reboot-watermark.json";
+
+        /// <summary>Cap for the emitted <c>rebootUris</c> list — <c>uriCount</c> always carries the uncapped distinct total.</summary>
+        internal const int MaxUrisPerEvent = 20;
+
+        /// <summary>Default quiet-period before a burst of 2800 records is flushed as one event.</summary>
+        internal const int DefaultDebounceMilliseconds = 10000;
+
+        /// <summary>Registry key whose <c>RebootRequired</c> value/subkey flags a pending OMA-DM coalesced reboot.</summary>
+        internal const string OmadmSyncMlKeyPath = @"SOFTWARE\Microsoft\Provisioning\OMADM\SyncML";
+
+        // Permissive OMA-DM URI shape ("./Device/Vendor/MSFT/...", "./User/..."). The verified 2800
+        // text wraps the URI in parentheses — ')' is deliberately outside the class so the match
+        // stops cleanly; trailing sentence punctuation is trimmed after the match.
+        private static readonly Regex UriPattern = new Regex(
+            @"\./[A-Za-z0-9_\-./\[\]{}%~+]+", RegexOptions.Compiled);
+
+        private readonly AgentLogger _logger;
+        private readonly string _sessionId;
+        private readonly string _tenantId;
+        private readonly InformationalEventPost _post;
+        private readonly bool _backfillEnabled;
+        private readonly int _backfillLookbackMinutes;
+        private readonly string _stateDirectory;
+        private readonly int _debounceMilliseconds;
+
+        private EventLogWatcher _watcher;
+        private Timer _debounceTimer;
+
+        private sealed class PendingRecord
+        {
+            public long RecordId;
+            public DateTime TimeUtc;
+            public string Uri;          // null when extraction failed
+            public string Description;  // may be null
+            public bool IsBackfill;
+        }
+
+        // Pending burst buffer + dedup state, all guarded by _stateLock. Same claim contract as
+        // WindowsUpdateTracker (immutable cross-restart boundary + intra-run HashSet), with ONE
+        // deliberate difference: the watermark is persisted at FLUSH time, not at claim time —
+        // records buffered but never flushed (process killed by the very reboot they announce)
+        // must be re-read and emitted by the post-restart backfill.
+        private readonly List<PendingRecord> _pending = new List<PendingRecord>();
+        private long _restartWatermark = -1;
+        private readonly HashSet<long> _seenThisRun = new HashSet<long>();
+        private long _maxPersistedRecordId = -1;
+        private readonly object _stateLock = new object();
+
+        /// <summary>
+        /// Fail-soft corroboration probe for the OMA-DM RebootRequired flag — null = unknown
+        /// (key absent or unreadable). Settable test seam; the default reads the live registry.
+        /// </summary>
+        internal Func<bool?> RebootRequiredFlagProbe { get; set; } = ReadOmadmRebootRequiredFlag;
+
+        public MdmRebootPolicyTracker(
+            string sessionId,
+            string tenantId,
+            InformationalEventPost post,
+            AgentLogger logger,
+            bool backfillEnabled = true,
+            int backfillLookbackMinutes = 60,
+            string stateDirectory = null,
+            int debounceMilliseconds = DefaultDebounceMilliseconds)
+        {
+            _sessionId = sessionId ?? throw new ArgumentNullException(nameof(sessionId));
+            _tenantId = tenantId ?? throw new ArgumentNullException(nameof(tenantId));
+            _post = post ?? throw new ArgumentNullException(nameof(post));
+            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+            _backfillEnabled = backfillEnabled;
+            _backfillLookbackMinutes = backfillLookbackMinutes;
+            _stateDirectory = stateDirectory != null ? Environment.ExpandEnvironmentVariables(stateDirectory) : null;
+            _debounceMilliseconds = debounceMilliseconds;
+        }
+
+        public void Start()
+        {
+            LoadWatermark();
+            StartWatcher();
+
+            if (_backfillEnabled && _backfillLookbackMinutes > 0)
+            {
+                BackfillRecentEvents();
+                // The backfill batch is complete — flush immediately instead of waiting out the
+                // debounce (live records that raced in are simply included).
+                FlushPending();
+            }
+            else
+            {
+                _logger.Info("MdmRebootPolicy backfill disabled by config");
+            }
+        }
+
+        public void Stop()
+        {
+            // Flush any un-emitted burst before tearing down (normal agent shutdown path).
+            try { FlushPending(); }
+            catch (Exception ex) { _logger.Warning($"MdmRebootPolicy flush on stop failed: {ex.Message}"); }
+
+            var timer = Interlocked.Exchange(ref _debounceTimer, null);
+            if (timer != null)
+            {
+                try { timer.Dispose(); } catch { }
+            }
+
+            if (_watcher == null) return;
+            try
+            {
+                _watcher.Enabled = false;
+                _watcher.Dispose();
+                _logger.Info("MdmRebootPolicy watcher stopped");
+            }
+            catch (Exception ex)
+            {
+                _logger.Error("Error stopping MdmRebootPolicy watcher", ex);
+            }
+            finally
+            {
+                _watcher = null;
+            }
+        }
+
+        public void Dispose() => Stop();
+
+        // -----------------------------------------------------------------------
+        // Watcher lifecycle
+        // -----------------------------------------------------------------------
+
+        private void StartWatcher()
+        {
+            try
+            {
+                var query = new EventLogQuery(Channel, PathType.LogName, BuildXPath());
+                _watcher = new EventLogWatcher(query);
+                _watcher.EventRecordWritten += OnEventRecordWritten;
+                _watcher.Enabled = true;
+                _logger.Info($"MdmRebootPolicy watcher started: {Channel} (EventID {EventId_PolicyRebootRequired})");
+            }
+            catch (EventLogNotFoundException)
+            {
+                _logger.Warning($"MdmRebootPolicy event log not found: {Channel} (normal on non-MDM-enrolled test environments)");
+            }
+            catch (UnauthorizedAccessException ex)
+            {
+                _logger.Warning($"MdmRebootPolicy watcher access denied for {Channel}: {ex.Message}");
+            }
+            catch (Exception ex)
+            {
+                _logger.Error($"Failed to start MdmRebootPolicy watcher for {Channel}", ex);
+                // MON-D1: surface a dead watcher as one-shot telemetry, not just a local log line.
+                CollectorDegradationReporter.Report(_post, _sessionId, _tenantId,
+                    collectorName: "MdmRebootPolicyTracker", reason: $"watcher_arm_failed:{Channel}", ex: ex);
+            }
+        }
+
+        /// <summary>Targeted-EventID XPath filter. Exposed as internal for tests.</summary>
+        internal static string BuildXPath() =>
+            $"*[System[(EventID={EventId_PolicyRebootRequired})]]";
+
+        // -----------------------------------------------------------------------
+        // Event processing — buffer + debounce
+        // -----------------------------------------------------------------------
+
+        private void OnEventRecordWritten(object sender, EventRecordWrittenEventArgs e)
+        {
+            if (e.EventRecord == null) return;
+            try
+            {
+                ProcessRecord(e.EventRecord, isBackfill: false);
+            }
+            catch (Exception ex)
+            {
+                _logger.Error("Error processing MdmRebootPolicy event", ex);
+            }
+        }
+
+        private void ProcessRecord(EventRecord record, bool isBackfill)
+        {
+            var recordId = record.RecordId ?? -1;
+
+            // Cheap dedup gate BEFORE the expensive XML/FormatDescription work.
+            if (IsAlreadyProcessed(recordId))
+                return;
+
+            string xml = null;
+            try { xml = record.ToXml(); }
+            catch { /* fall back to description-only parse below */ }
+
+            string description = null;
+            try { description = record.FormatDescription(); }
+            catch { /* some events lack formatting resources */ }
+
+            var rebootUri = ExtractRebootUri(ParseEventData(xml), description);
+
+            ProcessEvent(
+                eventId: record.Id,
+                recordId: recordId,
+                timeCreatedUtc: record.TimeCreated?.ToUniversalTime(),
+                rebootUri: rebootUri,
+                formattedDescription: description,
+                isBackfill: isBackfill);
+        }
+
+        /// <summary>
+        /// Buffers one 2800 record into the pending burst (primitive-input test seam, mirroring the
+        /// WindowsUpdateTracker pattern). The aggregated event is emitted by <see cref="FlushPending"/>
+        /// — after the debounce quiet-period, at backfill completion, or at <see cref="Stop"/>.
+        /// </summary>
+        internal void ProcessEvent(
+            int eventId,
+            long recordId,
+            DateTime? timeCreatedUtc,
+            string rebootUri,
+            string formattedDescription,
+            bool isBackfill)
+        {
+            lock (_stateLock)
+            {
+                if (recordId >= 0)
+                {
+                    // Already emitted in a prior run, or already buffered/emitted this run.
+                    if (recordId <= _restartWatermark || !_seenThisRun.Add(recordId))
+                        return;
+                }
+
+                _pending.Add(new PendingRecord
+                {
+                    RecordId = recordId,
+                    TimeUtc = timeCreatedUtc ?? DateTime.UtcNow,
+                    Uri = string.IsNullOrEmpty(rebootUri) ? null : rebootUri,
+                    Description = formattedDescription,
+                    IsBackfill = isBackfill,
+                });
+            }
+
+            ArmDebounce();
+        }
+
+        private void ArmDebounce()
+        {
+            if (_debounceMilliseconds <= 0) return; // manual-flush mode (tests; backfill/Stop flush explicitly)
+
+            var timer = _debounceTimer;
+            if (timer == null)
+            {
+                var created = new Timer(_ =>
+                {
+                    try { FlushPending(); }
+                    catch (Exception ex) { _logger.Warning($"MdmRebootPolicy debounce flush failed: {ex.Message}"); }
+                }, null, Timeout.Infinite, Timeout.Infinite);
+
+                timer = Interlocked.CompareExchange(ref _debounceTimer, created, null) ?? created;
+                if (!ReferenceEquals(timer, created))
+                {
+                    try { created.Dispose(); } catch { }
+                }
+            }
+
+            try { timer.Change(_debounceMilliseconds, Timeout.Infinite); }
+            catch (ObjectDisposedException) { /* raced Stop() — Stop's flush covers the buffer */ }
+        }
+
+        /// <summary>
+        /// Emits the pending burst as ONE aggregated <c>mdm_policy_reboot_required</c> event and
+        /// persists the watermark. No-op when nothing is pending. Internal for tests.
+        /// </summary>
+        internal void FlushPending()
+        {
+            List<PendingRecord> batch;
+            long watermarkToPersist = -1;
+
+            lock (_stateLock)
+            {
+                if (_pending.Count == 0) return;
+                batch = new List<PendingRecord>(_pending);
+                _pending.Clear();
+
+                foreach (var r in batch)
+                {
+                    if (r.RecordId > _maxPersistedRecordId)
+                        _maxPersistedRecordId = r.RecordId;
+                }
+                watermarkToPersist = _maxPersistedRecordId;
+            }
+
+            if (watermarkToPersist >= 0) PersistWatermark(watermarkToPersist);
+
+            batch.Sort((a, b) => a.TimeUtc.CompareTo(b.TimeUtc));
+
+            var distinctUris = batch
+                .Where(r => r.Uri != null)
+                .Select(r => r.Uri)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .ToList();
+            var firstUri = batch.FirstOrDefault(r => r.Uri != null)?.Uri;
+            var unparsedCount = batch.Count(r => r.Uri == null);
+            var allBackfill = batch.All(r => r.IsBackfill);
+            var earliest = batch[0].TimeUtc;
+
+            var data = new Dictionary<string, object>
+            {
+                { "windowsEventId", EventId_PolicyRebootRequired },
+                { "eventLogChannel", Channel },
+                { "recordCount", batch.Count },
+                { "uriCount", distinctUris.Count },
+                { "backfilled", allBackfill },
+            };
+            if (distinctUris.Count > 0)
+            {
+                data["rebootUris"] = distinctUris
+                    .OrderBy(u => u, StringComparer.OrdinalIgnoreCase)
+                    .Take(MaxUrisPerEvent)
+                    .ToList();
+                data["firstRebootUri"] = firstUri;
+            }
+            if (unparsedCount > 0)
+            {
+                data["unparsedCount"] = unparsedCount;
+                var sample = batch.FirstOrDefault(r => r.Uri == null && !string.IsNullOrEmpty(r.Description))?.Description;
+                if (sample != null)
+                    data["sampleDescription"] = sample.Length > 500 ? sample.Substring(0, 500) + "…" : sample;
+            }
+
+            var flag = SafeProbeRebootRequiredFlag();
+            if (flag.HasValue) data["omadmRebootRequiredFlag"] = flag.Value;
+
+            string message;
+            if (distinctUris.Count == 1)
+                message = $"Windows flagged an MDM policy URI as reboot-required: {firstUri}";
+            else if (distinctUris.Count > 1)
+                message = $"Windows flagged {distinctUris.Count} MDM policy URIs as reboot-required: {firstUri} (+{distinctUris.Count - 1} more)";
+            else
+                message = $"Windows flagged {batch.Count} MDM policy record(s) as reboot-required (URI not parsed — see sampleDescription)";
+
+            _post.Emit(new EnrollmentEvent
+            {
+                SessionId = _sessionId,
+                TenantId = _tenantId,
+                // Earliest record time, not UtcNow: backfilled (and post-reboot re-read) bursts
+                // must land on the timeline at when the policies were actually flagged.
+                Timestamp = earliest,
+                EventType = Constants.EventTypes.MdmPolicyRebootRequired,
+                // Neutral observation — reboot-required flags outside ESP DeviceSetup have no
+                // immediate effect. The reboot CLAIM is ANALYZE-ESP-005's job, gated on an
+                // actually-observed system_reboot_detected.
+                Severity = EventSeverity.Info,
+                Source = "MdmRebootPolicyWatcher",
+                Phase = EnrollmentPhase.Unknown,
+                Message = message,
+                Data = data,
+                // Cheap (one event per burst) and still time-critical: a burst DURING DeviceSetup
+                // precedes a coalesced reboot that kills the agent.
+                ImmediateUpload = true,
+            });
+
+            _logger.Info($"MdmRebootPolicy: flushed {batch.Count} record(s) as one event " +
+                $"(uris={distinctUris.Count}, unparsed={unparsedCount}, backfilled={allBackfill})");
+        }
+
+        /// <summary>
+        /// Extracts the reboot-forcing OMA-DM URI. Preference order: (1) a structured EventData
+        /// value that starts with <c>./</c>, (2) a permissive regex over the formatted description
+        /// (verified shape: <c>The following URI has triggered a reboot: (./Device/...).</c>).
+        /// Returns null when nothing URI-like is found — the record still counts into the
+        /// aggregate (<c>unparsedCount</c> + <c>sampleDescription</c>).
+        /// </summary>
+        internal static string ExtractRebootUri(Dictionary<string, string> eventData, string description)
+        {
+            if (eventData != null)
+            {
+                foreach (var value in eventData.Values)
+                {
+                    var trimmed = value?.Trim();
+                    if (!string.IsNullOrEmpty(trimmed) && trimmed.StartsWith("./", StringComparison.Ordinal))
+                        return trimmed;
+                }
+            }
+
+            if (!string.IsNullOrEmpty(description))
+            {
+                var match = UriPattern.Match(description);
+                if (match.Success)
+                {
+                    // The permissive pattern can swallow sentence punctuation trailing the URI.
+                    // OMA-DM URI segments never end in punctuation — trim it.
+                    var candidate = match.Value.TrimEnd('.', ',', ';', ':', '\'', '"', ')');
+                    if (candidate.Length > 2) return candidate;
+                }
+            }
+
+            return null;
+        }
+
+        /// <summary>
+        /// Extracts <c>&lt;Data Name="..."&gt;value&lt;/Data&gt;</c> pairs from an event's rendered
+        /// XML, keyed case-insensitively. Also collects UNNAMED Data elements under positional keys
+        /// (<c>Data0</c>, <c>Data1</c>, …) — DM-Enterprise events frequently carry positional-only
+        /// payloads. Namespace-agnostic; returns an empty map on null/malformed XML — never throws.
+        /// </summary>
+        internal static Dictionary<string, string> ParseEventData(string xml)
+        {
+            var result = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+            if (string.IsNullOrEmpty(xml)) return result;
+
+            try
+            {
+                var doc = XDocument.Parse(xml);
+                var positionalIndex = 0;
+                foreach (var el in doc.Descendants().Where(e => e.Name.LocalName == "Data"))
+                {
+                    var nameAttr = el.Attribute("Name");
+                    var key = nameAttr != null && !string.IsNullOrEmpty(nameAttr.Value)
+                        ? nameAttr.Value
+                        : "Data" + positionalIndex++;
+                    if (!result.ContainsKey(key))
+                        result[key] = el.Value;
+                }
+            }
+            catch
+            {
+                // Malformed / unexpected XML — best effort, return what we have.
+            }
+
+            return result;
+        }
+
+        // -----------------------------------------------------------------------
+        // OMA-DM RebootRequired flag probe (fail-soft corroboration)
+        // -----------------------------------------------------------------------
+
+        private bool? SafeProbeRebootRequiredFlag()
+        {
+            try
+            {
+                return RebootRequiredFlagProbe?.Invoke();
+            }
+            catch
+            {
+                return null; // corroboration only — never let the probe break the emit
+            }
+        }
+
+        /// <summary>
+        /// Reads the pending-reboot flag under <see cref="OmadmSyncMlKeyPath"/>. Both a value and a
+        /// subkey named <c>RebootRequired</c> count as "pending". Fail-soft: null = unknown
+        /// (key absent / unreadable), matching the EspSkipConfigurationProbe convention.
+        /// </summary>
+        internal static bool? ReadOmadmRebootRequiredFlag()
+        {
+            try
+            {
+                using (var key = Microsoft.Win32.Registry.LocalMachine.OpenSubKey(OmadmSyncMlKeyPath))
+                {
+                    if (key == null) return null;
+                    if (key.GetValue("RebootRequired") != null) return true;
+                    using (var sub = key.OpenSubKey("RebootRequired"))
+                    {
+                        return sub != null ? (bool?)true : false;
+                    }
+                }
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        // -----------------------------------------------------------------------
+        // Backfill
+        // -----------------------------------------------------------------------
+
+        private void BackfillRecentEvents()
+        {
+            try
+            {
+                var lookbackMs = (long)_backfillLookbackMinutes * 60 * 1000;
+                var xpath = $"*[System[(EventID={EventId_PolicyRebootRequired}) and TimeCreated[timediff(@SystemTime) <= {lookbackMs}]]]";
+
+                _logger.Info($"MdmRebootPolicy backfill: scanning {Channel} " +
+                    $"(lookback={_backfillLookbackMinutes}min, restartWatermark={_restartWatermark})");
+
+                var query = new EventLogQuery(Channel, PathType.LogName, xpath);
+
+                int processed = 0;
+                using (var reader = new EventLogReader(query))
+                {
+                    EventRecord record;
+                    while ((record = reader.ReadEvent()) != null)
+                    {
+                        using (record)
+                        {
+                            ProcessRecord(record, isBackfill: true);
+                            processed++;
+                        }
+                    }
+                }
+
+                if (processed == 0)
+                    _logger.Debug($"MdmRebootPolicy backfill: no EventID {EventId_PolicyRebootRequired} records in last {_backfillLookbackMinutes} minutes");
+                else
+                    _logger.Info($"MdmRebootPolicy backfill: scanned {processed} record(s)");
+            }
+            catch (EventLogNotFoundException)
+            {
+                _logger.Warning($"MdmRebootPolicy event log not found during backfill: {Channel} (normal on non-MDM-enrolled test environments)");
+            }
+            catch (UnauthorizedAccessException ex)
+            {
+                _logger.Warning($"MdmRebootPolicy backfill access denied: {ex.Message}");
+            }
+            catch (Exception ex)
+            {
+                _logger.Warning($"MdmRebootPolicy backfill failed: {ex.Message}");
+            }
+        }
+
+        // -----------------------------------------------------------------------
+        // Watermark dedup (cross-restart) — persisted at flush, not at claim
+        // -----------------------------------------------------------------------
+
+        private bool IsAlreadyProcessed(long recordId)
+        {
+            if (recordId < 0) return false; // no RecordId → cannot dedup, let it through
+            lock (_stateLock)
+            {
+                return recordId <= _restartWatermark || _seenThisRun.Contains(recordId);
+            }
+        }
+
+        internal void LoadWatermark()
+        {
+            if (string.IsNullOrEmpty(_stateDirectory)) return;
+
+            var filePath = Path.Combine(_stateDirectory, WatermarkStateFileName);
+            if (!File.Exists(filePath)) return;
+
+            try
+            {
+                var json = File.ReadAllText(filePath);
+                var state = JsonConvert.DeserializeObject<WatermarkState>(json);
+                if (state != null)
+                {
+                    lock (_stateLock)
+                    {
+                        _restartWatermark = state.LastRecordId;
+                        _maxPersistedRecordId = state.LastRecordId;
+                    }
+                    _logger.Info($"MdmRebootPolicy watermark loaded: lastRecordId={state.LastRecordId} (persisted {state.PersistedUtc:O})");
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.Warning($"Failed to load MdmRebootPolicy watermark: {ex.Message}");
+            }
+        }
+
+        private void PersistWatermark(long recordId)
+        {
+            if (string.IsNullOrEmpty(_stateDirectory)) return;
+
+            try
+            {
+                Directory.CreateDirectory(_stateDirectory);
+                var filePath = Path.Combine(_stateDirectory, WatermarkStateFileName);
+                var state = new WatermarkState { LastRecordId = recordId, PersistedUtc = DateTime.UtcNow };
+                var json = JsonConvert.SerializeObject(state, Formatting.Indented);
+                var tempPath = filePath + ".tmp";
+                File.WriteAllText(tempPath, json);
+                File.Copy(tempPath, filePath, overwrite: true);
+                try { File.Delete(tempPath); } catch { }
+            }
+            catch (Exception ex)
+            {
+                _logger.Warning($"Failed to persist MdmRebootPolicy watermark: {ex.Message}");
+            }
+        }
+
+        internal sealed class WatermarkState
+        {
+            public long LastRecordId { get; set; }
+            public DateTime PersistedUtc { get; set; }
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/ShellCoreTracker.cs

@@ -17,6 +17,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals
     ///             CommercialOOBE_ESPProgress_WhiteGlove_Success — WhiteGlove complete
     ///             CommercialOOBE_ESPProgress_Failure/_Timeout/_Abort/WhiteGlove_Failed — ESP failure
     ///
+    /// NOTE (session b2e890c1, 2026-07-20): a bare "RebootCoalescing" substring match on 62407 was
+    /// tried and REMOVED — the token appears in the ROUTINE SubcategoryProcessing_Started marker
+    /// ("Starting subcategory DeviceSetup.RebootCoalescing...") on every enrollment, so it proves
+    /// nothing about an actual coalesced reboot. Policy-reboot attribution lives entirely in
+    /// MdmRebootPolicyTracker (EventID 2800) + the ANALYZE-ESP-005 rule gated on an observed reboot.
+    ///
     /// Raises <see cref="FinalizingSetupPhaseTriggered"/>, <see cref="WhiteGloveCompleted"/>,
     /// and <see cref="EspFailureDetected"/>. Cross-notifies the <see cref="HelloTracker"/>
     /// on Hello wizard start and ESP exit so Hello timers can react.

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Runtime/SelfUpdater.cs

@@ -370,7 +370,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
         {
             try
             {
-                var versionUrl = $"{Constants.AgentBlobBaseUrl}/{Constants.AgentVersionFileNameForLine(2)}";
+                // Download alias, not the legacy blob account: the legacy mirror in the
+                // release pipeline is fail-soft, so it can silently lag behind eu.
+                var versionUrl = $"{Constants.AgentDownloadBaseUrl}/{Constants.AgentVersionFileNameForLine(2)}";
 
                 using (var handler = new HttpClientHandler())
                 using (var client = new HttpClient(handler) { Timeout = TimeSpan.FromMilliseconds(VersionCheckTimeoutMs) })
@@ -497,7 +499,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
         {
             try
             {
-                var zipUrl = $"{Constants.AgentBlobBaseUrl}/{Constants.AgentZipFileNameForLine(2)}";
+                var zipUrl = $"{Constants.AgentDownloadBaseUrl}/{Constants.AgentZipFileNameForLine(2)}";
 
                 // Clean up any previous download (fragment from aborted run, or symlink/junction).
                 // Pre-delete + FileMode.CreateNew below: CreateNew refuses to open an existing

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/Collectors/CommandCollector.cs

@@ -12,6 +12,24 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
     {
         public string CollectorType => "command_allowlisted";
 
+        private const int CommandTimeoutMs = 30000;
+
+        /// <summary>
+        /// Returns what the reader captured, or an empty string if it did not finish
+        /// (a killed process can leave the read faulted or still pending).
+        /// </summary>
+        private static string DrainOrEmpty(System.Threading.Tasks.Task<string> readTask)
+        {
+            try
+            {
+                return readTask.Wait(2000) ? readTask.Result : string.Empty;
+            }
+            catch
+            {
+                return string.Empty;
+            }
+        }
+
         public Dictionary<string, object> Execute(GatherRule rule, GatherRuleContext context)
         {
             var data = new Dictionary<string, object>();
@@ -81,12 +99,29 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
 
                 using (var process = Process.Start(psi))
                 {
-                    var output = process.StandardOutput.ReadToEnd();
-                    var error = process.StandardError.ReadToEnd();
-                    process.WaitForExit(30000); // 30 second timeout
+                    // Read asynchronously: a synchronous ReadToEnd() blocks until the pipe
+                    // closes, which only happens when the process exits — the WaitForExit
+                    // timeout below would never be reached and a hung command would pin
+                    // this worker forever.
+                    var outputTask = process.StandardOutput.ReadToEndAsync();
+                    var errorTask = process.StandardError.ReadToEndAsync();
+
+                    var exited = process.WaitForExit(CommandTimeoutMs);
+                    if (!exited)
+                    {
+                        context.Logger.Warning(
+                            $"Command timed out after {CommandTimeoutMs / 1000}s, killing: {command} (Rule: {rule.RuleId})");
+                        try { process.Kill(); } catch { /* already gone */ }
+                        // Give the readers a moment to drain once the pipes close.
+                        try { process.WaitForExit(5000); } catch { /* best effort */ }
+                        data["timed_out"] = true;
+                    }
 
                     data["command"] = command;
-                    data["exit_code"] = process.ExitCode;
+                    data["exit_code"] = exited ? process.ExitCode : -1;
+
+                    var output = DrainOrEmpty(outputTask);
+                    var error = DrainOrEmpty(errorTask);
 
                     if (!string.IsNullOrWhiteSpace(output))
                     {

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/Collectors/EventLogCollector.cs

@@ -17,6 +17,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             if (string.IsNullOrEmpty(logName))
                 return data;
 
+            // Guard: only allow enrollment-relevant channels
+            if (!GatherRuleGuards.IsEventLogChannelAllowed(logName, context.UnrestrictedMode))
+                return context.EmitSecurityWarning(rule, "eventlog", logName);
+
             // Optional: escalate severity when matching entries are found
             string severityIfFound = null;
             rule.Parameters?.TryGetValue("severityIfFound", out severityIfFound);

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/Collectors/LogParserCollector.cs

@@ -34,11 +34,30 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             if (filePath == null)
                 return null; // Token present but no user logged on — skip silently
 
-            // Apply IME log path override if set
+            // Apply IME log path override if set. The override comes from the local
+            // --ime-log-path flag only (never from remote config), so the operator
+            // running it is already a local admin — it relaxes the allowlist the same
+            // way unrestricted mode does, while the hard blocks below still apply.
+            var localOverride = false;
             if (!string.IsNullOrEmpty(context.ImeLogPathOverride))
             {
                 var fileName = Path.GetFileName(filePath);
                 filePath = Path.Combine(context.ImeLogPathOverride, fileName);
+                localOverride = true;
+            }
+
+            var relaxAllowlist = context.UnrestrictedMode || localOverride;
+
+            // Guard: only allow enrollment-relevant file paths. Checked before resolution
+            // so a blocked target is reported even when no file matches it. A wildcard
+            // target is checked by its directory — Path.GetFullPath rejects '*' and '?'.
+            var guardPath = HasWildcard(Path.GetFileName(filePath))
+                ? Path.GetDirectoryName(filePath)
+                : filePath;
+            if (!GatherRuleGuards.IsFilePathAllowed(guardPath, relaxAllowlist, userProfilePath))
+            {
+                context.EmitSecurityWarning(rule, "logparser", filePath);
+                return null;
             }
 
             // Get parameters
@@ -87,18 +106,30 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
 
             foreach (var resolvedPath in resolvedPaths)
             {
+                // Re-check each resolved path: wildcard expansion can surface files
+                // reached through a junction that the directory check did not cover.
+                if (!GatherRuleGuards.IsFilePathAllowed(resolvedPath, relaxAllowlist, userProfilePath))
+                {
+                    context.EmitSecurityWarning(rule, "logparser", resolvedPath);
+                    continue;
+                }
+
                 ProcessLogFile(resolvedPath, rule, pattern, trackPosition, maxLines, isTextMode, context);
             }
 
             return null;
         }
 
+        private static bool HasWildcard(string fileNamePart)
+            => !string.IsNullOrEmpty(fileNamePart) &&
+               (fileNamePart.Contains("*") || fileNamePart.Contains("?"));
+
         private static List<string> ResolveLogPaths(string filePath, string ruleId, GatherRuleContext context)
         {
             var fileNamePart = Path.GetFileName(filePath);
 
             // No wildcards — single file
-            if (!fileNamePart.Contains("*") && !fileNamePart.Contains("?"))
+            if (!HasWildcard(fileNamePart))
             {
                 if (File.Exists(filePath))
                     return new List<string> { filePath };

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs

@@ -1,6 +1,9 @@
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
 using System.Threading;
 using AutopilotMonitor.Agent.V2.Core.Logging;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors;
@@ -28,6 +31,25 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         private readonly HashSet<string> _phaseRulesExecuted = new HashSet<string>();
         private CountdownEvent _startupRulesLatch;   // non-null only while startup rules are pending
 
+        // Phase-scope + emit-mode state (ActivePhases / ActiveFromPhase / EmitMode on GatherRule).
+        // Guarded by _scopeLock; collector work always runs outside the lock. The state deliberately
+        // survives UpdateRules config refreshes — an agent restart causes at most one re-emit per
+        // on_change rule (acceptable under the per-enrollment lifecycle).
+        private readonly object _scopeLock = new object();
+        private EnrollmentPhase _currentPhase = EnrollmentPhase.Unknown;
+        private readonly HashSet<string> _fromPhaseLatched = new HashSet<string>();
+        private readonly Dictionary<string, string> _lastEmittedHash = new Dictionary<string, string>();
+        private readonly Dictionary<string, (int Count, DateTime SinceUtc)> _suppressed =
+            new Dictionary<string, (int Count, DateTime SinceUtc)>();
+        private readonly HashSet<string> _scopeBypassLogged = new HashSet<string>();
+
+        /// <summary>
+        /// When true, phase scoping (ActivePhases / ActiveFromPhase) is bypassed and scoped rules
+        /// execute unconditionally. Used by the standalone <c>--run-gather-rules</c> diagnostic
+        /// mode, which has no enrollment phase context. EmitMode is unaffected.
+        /// </summary>
+        public bool IgnorePhaseScope { get; set; }
+
         /// <summary>
         /// When true, guardrails are relaxed: all registry, WMI, and command targets are allowed.
         /// File paths allow everything except C:\Users. Set from tenant configuration.
@@ -89,10 +111,27 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
             _activeRules = rules.Where(r => r.Enabled).ToList();
 
-            // Execute startup rules — track completion via CountdownEvent so callers can wait
-            var pendingStartup = _activeRules
-                .Where(r => r.Trigger == "startup" && !_startupRulesExecuted.Contains(r.RuleId))
-                .ToList();
+            // Execute startup rules — track completion via CountdownEvent so callers can wait.
+            // Scoped startup rules that are not yet in scope are deferred: they run once from
+            // OnPhaseChanged when their scope activates (same _startupRulesExecuted dedup — a
+            // rule runs either here or there, never both). Unscoped rules behave as before.
+            List<GatherRule> pendingStartup;
+            lock (_scopeLock)
+            {
+                // A config refresh may deliver new from-phase rules after their phase was
+                // already reached — evaluate latches against the current phase first.
+                EvaluateFromPhaseLatchesLocked();
+
+                pendingStartup = _activeRules
+                    .Where(r => r.Trigger == "startup" && !_startupRulesExecuted.Contains(r.RuleId))
+                    .Where(r => IsRuleInScopeLocked(r))
+                    .ToList();
+
+                foreach (var rule in pendingStartup)
+                {
+                    _startupRulesExecuted.Add(rule.RuleId);
+                }
+            }
 
             if (pendingStartup.Count > 0)
             {
@@ -101,7 +140,6 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
                 foreach (var rule in pendingStartup)
                 {
-                    _startupRulesExecuted.Add(rule.RuleId);
                     ThreadPool.QueueUserWorkItem(_ =>
                     {
                         try   { ExecuteRule(rule); }
@@ -110,18 +148,26 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 }
             }
 
-            // Set up interval timers
+            // Set up interval timers. Timers for scoped rules keep running while out of scope —
+            // the tick gate makes an out-of-scope tick a free no-op, avoiding start/stop
+            // lifecycle races on phase transitions.
             foreach (var rule in _activeRules.Where(r => r.Trigger == "interval" && r.IntervalSeconds.HasValue))
             {
-                var interval = TimeSpan.FromSeconds(rule.IntervalSeconds.Value);
+                var intervalRule = rule;
+                var interval = TimeSpan.FromSeconds(intervalRule.IntervalSeconds.Value);
                 var timer = new Timer(
-                    _ => ExecuteRule(rule),
+                    _ =>
+                    {
+                        if (!IsRuleInScope(intervalRule))
+                            return;
+                        ExecuteRule(intervalRule);
+                    },
                     null,
                     interval, // Initial delay = one interval
                     interval
                 );
-                _intervalTimers[rule.RuleId] = timer;
-                _logger.Info($"  Interval rule {rule.RuleId} scheduled every {rule.IntervalSeconds}s");
+                _intervalTimers[intervalRule.RuleId] = timer;
+                _logger.Info($"  Interval rule {intervalRule.RuleId} scheduled every {intervalRule.IntervalSeconds}s");
             }
 
             _logger.Info($"GatherRuleExecutor: {_activeRules.Count(r => r.Trigger == "startup")} startup, " +
@@ -130,16 +176,95 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
         /// <summary>
         /// Called when a phase change event occurs - executes rules triggered by phase changes
+        /// (<c>phase_change</c> on entering the new phase, <c>phase_exit</c> on leaving the old one).
         /// </summary>
         public void OnPhaseChanged(EnrollmentPhase newPhase)
         {
             var phaseName = newPhase.ToString();
 
+            // phase_exit runs FIRST and against the phase being LEFT: both the TriggerPhase match
+            // and the scope gate must see the old phase, so this block has to complete before
+            // _currentPhase moves below. A transition INTO Failed still fires the exit rules of the
+            // phase that failed — that snapshot is the whole point at a failure boundary.
+            List<GatherRule> exitRules = null;
+            lock (_scopeLock)
+            {
+                var previousPhase = _currentPhase;
+                if (previousPhase != EnrollmentPhase.Unknown && previousPhase != newPhase)
+                {
+                    var previousPhaseName = previousPhase.ToString();
+                    exitRules = new List<GatherRule>();
+
+                    foreach (var rule in _activeRules)
+                    {
+                        if (rule.Trigger != "phase_exit") continue;
+                        if (!string.IsNullOrEmpty(rule.TriggerPhase)
+                            && !string.Equals(rule.TriggerPhase, previousPhaseName, StringComparison.OrdinalIgnoreCase))
+                            continue;
+
+                        // Scope gate before the dedup add — an out-of-scope pass must not consume
+                        // the once-per-(rule, phase) slot. IsRuleInScopeLocked still sees the old phase.
+                        if (!IsRuleInScopeLocked(rule)) continue;
+
+                        // "exit:" prefix keeps this key space disjoint from the phase_change keys.
+                        if (!_phaseRulesExecuted.Add($"exit:{rule.RuleId}|{previousPhaseName}"))
+                        {
+                            _logger.Debug($"Phase-exit rule {rule.RuleId} already executed for exit of {previousPhaseName}, skipping");
+                            continue;
+                        }
+
+                        _logger.Info($"Phase exit triggered rule {rule.RuleId} (left phase: {previousPhaseName}, now: {phaseName})");
+                        exitRules.Add(rule);
+                    }
+                }
+            }
+
+            if (exitRules != null)
+            {
+                foreach (var rule in exitRules)
+                {
+                    var exitRule = rule;
+                    ThreadPool.QueueUserWorkItem(_ => ExecuteRule(exitRule));
+                }
+            }
+
+            // Update the phase + from-phase latches so deferred startup activation and
+            // the phase_change rules below all evaluate against the NEW phase.
+            List<GatherRule> deferredStartup;
+            lock (_scopeLock)
+            {
+                _currentPhase = newPhase;
+                EvaluateFromPhaseLatchesLocked();
+
+                deferredStartup = _activeRules
+                    .Where(r => r.Trigger == "startup" && HasPhaseScope(r)
+                                && !_startupRulesExecuted.Contains(r.RuleId)
+                                && IsRuleInScopeLocked(r))
+                    .ToList();
+
+                foreach (var rule in deferredStartup)
+                {
+                    _startupRulesExecuted.Add(rule.RuleId);
+                }
+            }
+
+            foreach (var rule in deferredStartup)
+            {
+                var deferredRule = rule;
+                _logger.Info($"Phase {phaseName} activated deferred startup rule {deferredRule.RuleId}");
+                ThreadPool.QueueUserWorkItem(_ => ExecuteRule(deferredRule));
+            }
+
             foreach (var rule in _activeRules.Where(r => r.Trigger == "phase_change"))
             {
                 if (string.IsNullOrEmpty(rule.TriggerPhase) ||
                     string.Equals(rule.TriggerPhase, phaseName, StringComparison.OrdinalIgnoreCase))
                 {
+                    // Scope gate BEFORE the dedup add — an out-of-scope pass must not consume
+                    // the once-per-(rule, phase) execution slot.
+                    if (!IsRuleInScope(rule))
+                        continue;
+
                     // Deduplicate: only fire once per (ruleId, phase) combination
                     var deduplicationKey = $"{rule.RuleId}|{phaseName}";
                     if (!_phaseRulesExecuted.Add(deduplicationKey))
@@ -163,6 +288,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             {
                 if (string.Equals(rule.TriggerEventType, eventType, StringComparison.OrdinalIgnoreCase))
                 {
+                    if (!IsRuleInScope(rule))
+                        continue;
+
                     _logger.Info($"Event triggered rule {rule.RuleId} (event: {eventType})");
                     ThreadPool.QueueUserWorkItem(_ => ExecuteRule(rule));
                 }
@@ -192,6 +320,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
                 if (result.Count > 0)
                 {
+                    // EmitMode "on_change": hash the raw collector result (before ruleId/title
+                    // injection) and only emit when it differs from the last emitted one. An
+                    // empty result never reaches this point, so an emitOnlyIfExists miss neither
+                    // emits nor updates the hash — composing to "one event on appearance, then
+                    // only on change".
+                    if (IsOnChangeMode(rule) && !ShouldEmitOnChange(rule, result))
+                        return;
+
                     result["ruleId"] = rule.RuleId;
                     result["ruleTitle"] = rule.Title;
 
@@ -229,6 +365,199 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             }
         }
 
+        // ===== Phase scope (ActivePhases / ActiveFromPhase) =====
+
+        private static bool HasPhaseScope(GatherRule rule)
+        {
+            return (rule.ActivePhases != null && rule.ActivePhases.Count > 0)
+                || !string.IsNullOrEmpty(rule.ActiveFromPhase);
+        }
+
+        // Internal so the scope matrix is testable synchronously (no timer/ThreadPool races).
+        internal bool IsRuleInScope(GatherRule rule)
+        {
+            lock (_scopeLock)
+            {
+                return IsRuleInScopeLocked(rule);
+            }
+        }
+
+        private bool IsRuleInScopeLocked(GatherRule rule)
+        {
+            if (!HasPhaseScope(rule))
+                return true; // unscoped — legacy behavior
+
+            if (IgnorePhaseScope)
+            {
+                if (_scopeBypassLogged.Add(rule.RuleId))
+                    _logger.Info($"Gather rule {rule.RuleId}: phase scope ignored (diagnostic mode)");
+                return true;
+            }
+
+            // Both fields set is rejected by backend validation; defensively prefer ActivePhases.
+            if (rule.ActivePhases != null && rule.ActivePhases.Count > 0)
+            {
+                // No phase signal yet (or scope tokens that never match, e.g. "Unknown"):
+                // scoped rules stay inactive.
+                if (_currentPhase == EnrollmentPhase.Unknown)
+                    return false;
+
+                var phaseName = _currentPhase.ToString();
+                foreach (var phase in rule.ActivePhases)
+                {
+                    if (string.Equals(phase, phaseName, StringComparison.OrdinalIgnoreCase))
+                        return true;
+                }
+                return false;
+            }
+
+            return _fromPhaseLatched.Contains(rule.RuleId);
+        }
+
+        /// <summary>
+        /// Latches every from-phase rule whose threshold the current phase has reached.
+        /// Never latches on Unknown/Failed (Failed=99 would ordinal-satisfy every threshold);
+        /// once latched a rule stays active for the session — including through Failed.
+        /// Caller must hold <see cref="_scopeLock"/>.
+        /// </summary>
+        private void EvaluateFromPhaseLatchesLocked()
+        {
+            if (_currentPhase == EnrollmentPhase.Unknown || _currentPhase == EnrollmentPhase.Failed)
+                return;
+
+            foreach (var rule in _activeRules)
+            {
+                if (string.IsNullOrEmpty(rule.ActiveFromPhase)) continue;
+                if (rule.ActivePhases != null && rule.ActivePhases.Count > 0) continue; // ActivePhases wins
+                if (_fromPhaseLatched.Contains(rule.RuleId)) continue;
+
+                if (Enum.TryParse<EnrollmentPhase>(rule.ActiveFromPhase, ignoreCase: true, out var fromPhase)
+                    && fromPhase != EnrollmentPhase.Unknown
+                    && fromPhase != EnrollmentPhase.Failed
+                    && (int)_currentPhase >= (int)fromPhase)
+                {
+                    _fromPhaseLatched.Add(rule.RuleId);
+                    _logger.Info($"Gather rule {rule.RuleId}: from-phase scope latched at {_currentPhase} (activeFromPhase={rule.ActiveFromPhase})");
+                }
+            }
+        }
+
+        // ===== Emit mode (on_change) =====
+
+        private static bool IsOnChangeMode(GatherRule rule)
+        {
+            return string.Equals(rule.EmitMode, "on_change", StringComparison.OrdinalIgnoreCase);
+        }
+
+        /// <summary>
+        /// on_change decision for a non-empty collector result: true = emit (first result for the
+        /// rule, or the result changed), false = suppress. Hashes the result BEFORE ruleId/title
+        /// injection. On emit after a suppression streak, injects <c>suppressedPolls</c> and
+        /// <c>suppressedSinceUtc</c> into the result so the gap is observable.
+        /// Internal so the state machine is testable synchronously (no timer/ThreadPool races).
+        /// </summary>
+        internal bool ShouldEmitOnChange(GatherRule rule, Dictionary<string, object> result)
+        {
+            var hash = ComputeCanonicalHash(result);
+            bool emit;
+            lock (_scopeLock)
+            {
+                string lastHash;
+                if (_lastEmittedHash.TryGetValue(rule.RuleId, out lastHash) && lastHash == hash)
+                {
+                    (int Count, DateTime SinceUtc) streak;
+                    _suppressed[rule.RuleId] = _suppressed.TryGetValue(rule.RuleId, out streak)
+                        ? (streak.Count + 1, streak.SinceUtc)
+                        : (1, DateTime.UtcNow);
+                    emit = false;
+                }
+                else
+                {
+                    _lastEmittedHash[rule.RuleId] = hash;
+                    (int Count, DateTime SinceUtc) streak;
+                    if (_suppressed.TryGetValue(rule.RuleId, out streak) && streak.Count > 0)
+                    {
+                        result["suppressedPolls"] = streak.Count;
+                        result["suppressedSinceUtc"] = streak.SinceUtc.ToString("o", CultureInfo.InvariantCulture);
+                    }
+                    _suppressed.Remove(rule.RuleId);
+                    emit = true;
+                }
+            }
+
+            if (!emit)
+                _logger.Debug($"Gather rule {rule.RuleId}: result unchanged, emit suppressed (on_change)");
+            return emit;
+        }
+
+        /// <summary>
+        /// Canonical hash of a collector result: keys ordinal-sorted at every dictionary level,
+        /// values rendered with invariant formatting, then SHA-256. Internal for direct test
+        /// coverage of the canonicalization.
+        /// </summary>
+        internal static string ComputeCanonicalHash(Dictionary<string, object> result)
+        {
+            var sb = new StringBuilder();
+            AppendCanonicalValue(sb, result);
+            using (var sha = SHA256.Create())
+            {
+                var hashBytes = sha.ComputeHash(Encoding.UTF8.GetBytes(sb.ToString()));
+                return Convert.ToBase64String(hashBytes);
+            }
+        }
+
+        private static void AppendCanonicalValue(StringBuilder sb, object value)
+        {
+            if (value == null)
+            {
+                sb.Append("<null>");
+                return;
+            }
+
+            // string first — it is IEnumerable and must not be treated as a sequence
+            if (value is string str)
+            {
+                sb.Append('"').Append(str).Append('"');
+                return;
+            }
+
+            if (value is System.Collections.IDictionary dict)
+            {
+                sb.Append('{');
+                var keys = dict.Keys.Cast<object>()
+                    .Select(k => k?.ToString() ?? string.Empty)
+                    .OrderBy(k => k, StringComparer.Ordinal);
+                foreach (var key in keys)
+                {
+                    sb.Append(key).Append('=');
+                    AppendCanonicalValue(sb, dict[key]);
+                    sb.Append(';');
+                }
+                sb.Append('}');
+                return;
+            }
+
+            if (value is System.Collections.IEnumerable sequence)
+            {
+                sb.Append('[');
+                foreach (var item in sequence)
+                {
+                    AppendCanonicalValue(sb, item);
+                    sb.Append(';');
+                }
+                sb.Append(']');
+                return;
+            }
+
+            if (value is IFormattable formattable)
+            {
+                sb.Append(formattable.ToString(null, CultureInfo.InvariantCulture));
+                return;
+            }
+
+            sb.Append(value);
+        }
+
         private EventSeverity ParseSeverity(string severity)
         {
             return GatherRuleContext.ParseSeverity(severity);
@@ -245,7 +574,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
         /// <summary>
         /// Blocks until all startup rules that were queued by the most recent <see cref="UpdateRules"/>
-        /// call have finished executing, or the timeout elapses.
+        /// call have finished executing, or the timeout elapses. Deferred scoped startup rules
+        /// (waiting for their phase scope) are not part of the latch.
         /// Returns true if all rules completed within the timeout; false if timed out.
         /// </summary>
         public bool WaitForStartupRules(int timeoutSeconds = 120)

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleGuards.cs

@@ -33,6 +33,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         public static readonly IReadOnlyList<string> AllowedFilePrefixes;
         public static readonly IReadOnlyList<string> AllowedWmiQueryPrefixes;
         public static readonly IReadOnlyCollection<string> AllowedCommands;
+        public static readonly IReadOnlyList<string> AllowedEventLogChannels;
 
         // Hard blocks: never allowed, even in unrestricted mode
         private static readonly string BlockedUsersPrefix = Path.GetFullPath(@"C:\Users");
@@ -51,6 +52,19 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         // Hard limit: maximum command length (even in unrestricted mode)
         private const int MaxCommandLength = 2000;
 
+        // Event log channels that are never readable, even in unrestricted mode.
+        // Security carries the audit trail of user behaviour; the PowerShell channels
+        // carry script-block logging, which routinely contains secrets in clear text.
+        // Mirrored in rules/guardrails.json ("blockedEventLogChannels") for the portal
+        // to display — enforcement lives here so a parse error cannot lift it.
+        private static readonly string[] HardBlockedEventLogChannels = new[]
+        {
+            "Security",
+            "Microsoft-Windows-PowerShell",
+            "Windows PowerShell",
+            "Microsoft-Windows-Sysmon",
+        };
+
         // Hard-blocked command patterns: never allowed, even in unrestricted mode.
         // These prevent privilege escalation, persistence, and data exfiltration.
         private static readonly string[] HardBlockedCommandPatterns = new[]
@@ -85,6 +99,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
                     var commands = FlattenCategorized(obj, "allowedCommands", "commands");
                     AllowedCommands = new HashSet<string>(commands, StringComparer.OrdinalIgnoreCase);
+
+                    AllowedEventLogChannels = FlattenCategorized(obj, "eventLogChannels", "channels");
                     return;
                 }
             }
@@ -98,6 +114,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             AllowedFilePrefixes = new List<string>();
             AllowedWmiQueryPrefixes = new List<string>();
             AllowedCommands = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            AllowedEventLogChannels = new List<string>();
         }
 
         private static string LoadEmbeddedGuardrails()
@@ -257,6 +274,44 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 (trimmed.Length == prefix.Length || char.IsWhiteSpace(trimmed[prefix.Length])));
         }
 
+        /// <summary>
+        /// Returns true if the event log channel matches an allowed entry with
+        /// boundary matching (next char must be '/' or end of string), so that
+        /// "Microsoft-Windows-AAD" admits "Microsoft-Windows-AAD/Operational"
+        /// but not "Microsoft-Windows-AADSomethingElse".
+        /// </summary>
+        public static bool IsEventLogChannelAllowed(string channel)
+            => IsEventLogChannelAllowed(channel, unrestrictedMode: false);
+
+        /// <summary>
+        /// Returns true if the event log channel is allowed.
+        /// When unrestrictedMode is true, all channels are allowed except the
+        /// hard-blocked ones (audit trail and script-block logging).
+        /// </summary>
+        public static bool IsEventLogChannelAllowed(string channel, bool unrestrictedMode)
+        {
+            if (string.IsNullOrEmpty(channel))
+                return false;
+
+            var trimmed = channel.Trim();
+
+            // Hard blocks apply even in unrestricted mode
+            foreach (var blocked in HardBlockedEventLogChannels)
+            {
+                if (MatchesChannel(trimmed, blocked))
+                    return false;
+            }
+
+            if (unrestrictedMode)
+                return true;
+
+            return AllowedEventLogChannels.Any(allowed => MatchesChannel(trimmed, allowed));
+        }
+
+        private static bool MatchesChannel(string channel, string prefix)
+            => channel.StartsWith(prefix, StringComparison.OrdinalIgnoreCase) &&
+               (channel.Length == prefix.Length || channel[prefix.Length] == '/');
+
         /// <summary>
         /// Returns true if the command (trimmed) exactly matches an entry in the allowlist.
         /// Exact matching is intentional — no prefix spoofing possible.

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Periodic/NetworkChangeDetector.cs

@@ -45,10 +45,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic
         /// </summary>
         private static readonly (string Name, string Url)[] MdmEndpoints =
         {
-            ("Entra ID", "https://login.microsoftonline.com"),
+            ("Entra ID", Constants.EntraLoginBaseUrl),
             ("Device Registration", "https://enterpriseregistration.windows.net"),
             ("Intune Portal", "https://portal.manage.microsoft.com"),
-            ("Microsoft Graph", "https://graph.microsoft.com"),
+            ("Microsoft Graph", Constants.GraphBaseUrl),
         };
 
         public NetworkChangeDetector(

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Security/ConsoleBypassWatcher.cs

@@ -136,6 +136,25 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Security
                 }
 
                 watcher.Start();
+
+                // Re-check after arming: Dispose() may have run between the lock release above and
+                // Start() — it then stopped a not-yet-armed watcher and this thread armed it right
+                // back, leaving a WMI subscription no code path could ever reach again. If disposal
+                // won that race, tear the watcher down here.
+                bool disposedDuringArm;
+                lock (_lock)
+                {
+                    disposedDuringArm = _disposed;
+                    if (disposedDuringArm) _startWatcher = null;
+                }
+                if (disposedDuringArm)
+                {
+                    try { watcher.EventArrived -= OnProcessStartTrace; } catch { }
+                    try { watcher.Stop(); } catch { }
+                    try { watcher.Dispose(); } catch { }
+                    return;
+                }
+
                 _logger.Info($"[ConsoleBypassWatcher] watching Win32_ProcessStartTrace for " +
                     $"{string.Join(", ", WatchedProcessNames)} (interactive-session + bare command line)");
             }

src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/DefaultComponentFactory.cs

@@ -335,6 +335,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                     osBuildChangedProvider: () => osBuildChangeHost.BuildChanged));
             }
 
+            // MDM reboot-policy watcher — subscribes to DeviceManagement-Enterprise-Diagnostics-
+            // Provider/Admin EventID 2800 and attributes the "unexpected reboot + second sign-in"
+            // pattern to the device-assigned policy URIs that forced the coalesced reboot.
+            // Agent-native collector (NOT an IAgentAnalyzer); the config flag is an internal
+            // steering lever only.
+            if (collectors.MdmRebootPolicyWatcherEnabled)
+            {
+                hosts.Add(new MdmRebootPolicyWatcherHost(
+                    sessionId: sessionId,
+                    tenantId: tenantId,
+                    logger: logger,
+                    ingress: ingress,
+                    clock: clock,
+                    backfillLookbackMinutes: collectors.MdmRebootPolicyBackfillLookbackMinutes,
+                    stateDirectory: _stateDirectory));
+            }
+
             // ----- Peripheral hosts (event-only; driven by remote-config toggles) --------------
 
             // V1 parity (PeriodicCollectorManager) — combine Performance + AgentSelfMetrics under

src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/EnrollmentOrchestrator.cs

@@ -86,6 +86,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
         // Production always passes null → Start() creates the real DeadlineScheduler.
         private readonly IDeadlineScheduler? _schedulerOverride;
 
+        // Live accessor for TenantConfiguration.SendTraceEvents — read per event by the
+        // TelemetryEventEmitter so a mid-session remote-config merge takes effect. Null
+        // (tests / legacy callers) means trace events always flow.
+        private readonly Func<bool>? _traceEventsEnabled;
+
         // Max-lifetime watchdog (M4.6.α). Timer is armed in Start() when _agentMaxLifetime != null.
         private System.Threading.Timer? _maxLifetimeTimer;
         private int _terminatedFired;
@@ -166,7 +171,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             TimeSpan? terminalDrainTimeout = null,
             TimeSpan? agentMaxLifetime = null,
             int uploadBatchSize = 100,
-            IDeadlineScheduler? schedulerOverride = null)
+            IDeadlineScheduler? schedulerOverride = null,
+            Func<bool>? traceEventsEnabled = null)
         {
             if (string.IsNullOrEmpty(sessionId)) throw new ArgumentException("SessionId is mandatory.", nameof(sessionId));
             if (string.IsNullOrEmpty(tenantId)) throw new ArgumentException("TenantId is mandatory.", nameof(tenantId));
@@ -206,6 +212,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             _uploadBatchSize = uploadBatchSize;
 
             _schedulerOverride = schedulerOverride;
+            _traceEventsEnabled = traceEventsEnabled;
         }
 
         /// <summary>
@@ -402,7 +409,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             //    strukturelle Abhängigkeit erlischt damit, Architektur-Baseline-Test gate
             //    shrinks to exactly two permitted callers.
             _eventSequenceCounter = new EventSequenceCounter(_eventSequencePersistence);
-            var eventEmitter = new TelemetryEventEmitter(_transport, _eventSequenceCounter, _sessionId, _tenantId);
+            var eventEmitter = new TelemetryEventEmitter(
+                _transport, _eventSequenceCounter, _sessionId, _tenantId, _traceEventsEnabled);
             _signalEmitter = new TelemetrySignalEmitter(_transport, _sessionId, _tenantId);
             _transitionEmitter = new TelemetryTransitionEmitter(_transport, _sessionId, _tenantId);
             _timelineEmitter = new EventTimelineEmitter(eventEmitter);

src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/Hosts/MdmRebootPolicyWatcherHost.cs

@@ -0,0 +1,68 @@
+#nullable enable
+using System;
+using System.Threading;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals;
+using AutopilotMonitor.DecisionCore.Engine;
+using AutopilotMonitor.DecisionCore.Signals;
+
+namespace AutopilotMonitor.Agent.V2.Core.Orchestration
+{
+    /// <summary>
+    /// Standalone host for the <see cref="MdmRebootPolicyTracker"/> — watches
+    /// <c>Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider/Admin</c> (EventID
+    /// 2800) for MDM policies that force a coalesced reboot during ESP DeviceSetup and forwards
+    /// them via the shared single-rail ingress. Mirrors <see cref="WindowsUpdateWatcherHost"/>:
+    /// builds its own <see cref="InformationalEventPost"/> and delegates Start/Stop to the tracker.
+    /// </summary>
+    internal sealed class MdmRebootPolicyWatcherHost : ICollectorHost
+    {
+        public string Name => "MdmRebootPolicyTracker";
+
+        private readonly MdmRebootPolicyTracker _tracker;
+        private readonly AgentLogger _logger;
+        private int _disposed;
+
+        public MdmRebootPolicyWatcherHost(
+            string sessionId,
+            string tenantId,
+            AgentLogger logger,
+            ISignalIngressSink ingress,
+            IClock clock,
+            int backfillLookbackMinutes,
+            string stateDirectory)
+        {
+            if (ingress == null) throw new ArgumentNullException(nameof(ingress));
+            if (clock == null) throw new ArgumentNullException(nameof(clock));
+            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+
+            var post = new InformationalEventPost(ingress, clock, logger);
+            _tracker = new MdmRebootPolicyTracker(
+                sessionId: sessionId,
+                tenantId: tenantId,
+                post: post,
+                logger: logger,
+                backfillEnabled: backfillLookbackMinutes > 0,
+                backfillLookbackMinutes: backfillLookbackMinutes,
+                stateDirectory: stateDirectory);
+        }
+
+        public void Start()
+        {
+            _tracker.Start();
+            _logger.Info("MdmRebootPolicyWatcherHost: started.");
+        }
+
+        public void Stop()
+        {
+            try { _tracker.Stop(); }
+            catch (Exception ex) { _logger.Warning($"MdmRebootPolicyWatcherHost: stop failed: {ex.Message}"); }
+        }
+
+        public void Dispose()
+        {
+            if (Interlocked.Exchange(ref _disposed, 1) == 1) return;
+            Stop();
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core/SignalAdapters/RealmJoinWatcherAdapter.cs

@@ -137,7 +137,24 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
 
         private void OnPhaseChanged(object? sender, RealmJoinPhaseChangedEventArgs e)
         {
-            // Phase change is observability-only: no DecisionSignalKind, just a timeline event.
+            // Dual-emission like OnDetected/OnResolved: (1) the typed signal persists the phase
+            // into RealmJoinFacts.LastDeploymentPhase (restart-safe) and lets the reducer detect
+            // the aborted-RJ-ESP shape (phase left 100/101 for 200/210 without 110 — session
+            // 224b2087); (2) the InformationalEvent keeps the existing timeline entry.
+            var payload = new Dictionary<string, string>(StringComparer.Ordinal)
+            {
+                [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = e.CurrentPhase.ToString(),
+                [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = e.PreviousPhase.ToString(),
+            };
+            _ingress.Post(
+                kind: DecisionSignalKind.RealmJoinPhaseChanged,
+                occurredAtUtc: _clock.UtcNow,
+                sourceOrigin: SourceLabel,
+                evidence: BuildEvidence(
+                    "realmjoin-phase-changed-v1",
+                    $"RealmJoin DeploymentPhase {e.PreviousPhase} -> {e.CurrentPhase}"),
+                payload: payload);
+
             // Both raw int (deploymentPhase / previousPhase) and human-readable name
             // (deploymentPhaseName / previousPhaseName) flow through — int stays for downstream
             // filters / KQL, name fields make the message + UI rows readable without a lookup.

src/Agent/AutopilotMonitor.Agent.V2.Core/Telemetry/Events/TelemetryEventEmitter.cs

@@ -30,12 +30,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Telemetry.Events
         private readonly string _sessionId;
         private readonly string _tenantId;
         private readonly string _partitionKey;
+        private readonly Func<bool>? _traceEventsEnabled;
 
         public TelemetryEventEmitter(
             ITelemetryTransport transport,
             EventSequenceCounter sequenceCounter,
             string sessionId,
-            string tenantId)
+            string tenantId,
+            Func<bool>? traceEventsEnabled = null)
         {
             if (string.IsNullOrEmpty(sessionId)) throw new ArgumentException("SessionId is mandatory.", nameof(sessionId));
             if (string.IsNullOrEmpty(tenantId)) throw new ArgumentException("TenantId is mandatory.", nameof(tenantId));
@@ -44,13 +46,18 @@ namespace AutopilotMonitor.Agent.V2.Core.Telemetry.Events
             _sessionId = sessionId;
             _tenantId = tenantId;
             _partitionKey = $"{tenantId}_{sessionId}";
+            _traceEventsEnabled = traceEventsEnabled;
         }
 
         /// <summary>
         /// Weist Sequence zu, serialisiert im Legacy-Wire-Format und enqueued via Transport.
         /// Thread-safe (EventSequenceCounter + ITelemetryTransport.Enqueue beide unter Lock).
+        /// <para>
+        /// Returns <c>null</c> when the event was suppressed by the trace-event gate — the
+        /// only drop path. Both permitted callers ignore the return value.
+        /// </para>
         /// </summary>
-        internal TelemetryItem Emit(EnrollmentEvent evt)
+        internal TelemetryItem? Emit(EnrollmentEvent evt)
         {
             if (evt == null) throw new ArgumentNullException(nameof(evt));
             if (string.IsNullOrEmpty(evt.EventType))
@@ -58,6 +65,16 @@ namespace AutopilotMonitor.Agent.V2.Core.Telemetry.Events
                 throw new ArgumentException("EnrollmentEvent.EventType is mandatory.", nameof(evt));
             }
 
+            // Trace-event gate (TenantConfiguration.SendTraceEvents, default on). Dropped
+            // before the sequence counter advances, so suppression leaves no gaps in the
+            // per-session sequence and the timeline stays contiguous. Evaluated per event
+            // rather than captured at construction: remote config is merged into the live
+            // AgentConfiguration mid-session, and the gate must follow it.
+            if (evt.Severity == EventSeverity.Trace && !TraceEventsEnabled())
+            {
+                return null;
+            }
+
             evt.Sequence = _sequenceCounter.Next();
             if (string.IsNullOrEmpty(evt.SessionId)) evt.SessionId = _sessionId;
             if (string.IsNullOrEmpty(evt.TenantId)) evt.TenantId = _tenantId;
@@ -77,5 +94,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Telemetry.Events
 
             return _transport.Enqueue(draft);
         }
+
+        /// <summary>
+        /// Fail-open: no gate wired (legacy ctor / tests) or a throwing accessor means trace
+        /// events flow. The gate suppresses diagnostics, so a broken accessor must not be able
+        /// to silently blind the timeline.
+        /// </summary>
+        private bool TraceEventsEnabled()
+        {
+            if (_traceEventsEnabled == null) return true;
+            try
+            {
+                return _traceEventsEnabled();
+            }
+            catch
+            {
+                return true;
+            }
+        }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2/Program.GatherRulesMode.cs

@@ -224,6 +224,11 @@ namespace AutopilotMonitor.Agent.V2
                     // Step 4 — run the executor and wait.
                     using (var executor = new GatherRuleExecutor(sessionId, tenantId, emitEvent, logger, config.ImeLogPathOverride))
                     {
+                        // Diagnostic mode has no enrollment phase context — scoped rules
+                        // (activePhases / activeFromPhase) execute unconditionally here.
+                        executor.IgnorePhaseScope = true;
+                        logger.Info("--run-gather-rules: phase scoping bypassed (no phase context in diagnostic mode).");
+
                         executor.UpdateRules(rules);
 
                         if (consoleMode) Console.WriteLine($"Running {startupRules.Count} rule(s)...");

src/Agent/AutopilotMonitor.Agent.V2/Program.cs

@@ -213,6 +213,8 @@ namespace AutopilotMonitor.Agent.V2
             // Control-channel kill-switch: a live-fetch DeviceKillSignal terminates the agent
             // BEFORE mTLS/registration spin-up. Covers agents the telemetry-channel kill can
             // never reach (paused drain, empty spool) at their next process start / boot.
+            // Checked BEFORE any endpoint migration — a kill from the current backend is
+            // terminal, not re-homed.
             if (CheckConfigKillSignal(
                     runtimeConfig.RemoteConfig,
                     runtimeConfig.RemoteConfigService.LastFetchOutcome,
@@ -223,6 +225,37 @@ namespace AutopilotMonitor.Agent.V2
                 return 0;
             }
 
+            // Endpoint migration (config-channel re-home): the backend served a validated
+            // MigrateToApiBaseUrl on a live fetch. Rebuild Phase 3 clients against the new base
+            // URL and re-run Phase 4 there (single hop — the second Resolve cannot migrate
+            // again), then re-check the kill signal against the NEW backend's config.
+            if (runtimeConfig.PendingMigrationTarget != null)
+            {
+                logger.Warning(
+                    $"Endpoint migration: backend re-homed this agent from {bootstrap.AgentConfig.ApiBaseUrl} " +
+                    $"to {runtimeConfig.PendingMigrationTarget} — rebuilding backend clients.");
+
+                bootstrap.AgentConfig.ApiBaseUrl = runtimeConfig.PendingMigrationTarget;
+
+                // Best-effort disposal of the old-URL client stack before it goes out of scope.
+                try { auth.BackendApiClient?.Dispose(); } catch { }
+
+                auth = Runtime.BackendClientFactory.BuildAuthClients(bootstrap.AgentConfig, GetAgentVersion(), logger);
+                runtimeConfig = Runtime.AgentRuntimeConfig.Resolve(
+                    bootstrap.AgentConfig, auth, GetAgentVersion(), consoleMode, logger,
+                    allowEndpointMigration: false);
+
+                if (CheckConfigKillSignal(
+                        runtimeConfig.RemoteConfig,
+                        runtimeConfig.RemoteConfigService.LastFetchOutcome,
+                        dataDirectory, stateSubdir,
+                        () => new CleanupService(bootstrap.AgentConfig, logger),
+                        logger, consoleMode))
+                {
+                    return 0;
+                }
+            }
+
             // Phase 5 (mTLS HttpClient + BackendTelemetryUploader) is encapsulated in
             // BackendClientFactory. Construction failures map to V1-parity exit codes
             // (4 = mTLS, 5 = uploader). See Runtime/BackendClientFactory.cs.

src/Agent/AutopilotMonitor.Agent.V2/Runtime/AgentRuntimeConfig.cs

@@ -32,7 +32,8 @@ namespace AutopilotMonitor.Agent.V2.Runtime
             BackendAuthBundle auth,
             string agentVersion,
             bool consoleMode,
-            AgentLogger logger)
+            AgentLogger logger,
+            bool allowEndpointMigration = true)
         {
             if (agentConfig == null) throw new ArgumentNullException(nameof(agentConfig));
             if (auth == null) throw new ArgumentNullException(nameof(auth));
@@ -49,6 +50,25 @@ namespace AutopilotMonitor.Agent.V2.Runtime
                 .FetchConfigAsync(retryOnTransientErrors: true)
                 .GetAwaiter().GetResult();
 
+            // Endpoint migration (config-channel re-home): decided BEFORE merge / binary-
+            // integrity / bootstrap-cleanup so none of those side effects run against a config
+            // from the backend being abandoned — a migration stub may advertise stale agent
+            // hashes, and a spurious IntegrityCheckFailed + force-update against them would be
+            // actively harmful. RunAgent rebuilds Phase 3 clients on the new base URL and calls
+            // Resolve again with allowEndpointMigration:false (single hop — the new backend's
+            // config cannot chain another migration).
+            if (allowEndpointMigration)
+            {
+                var migrationTarget = EndpointMigration.ResolveTarget(
+                    remoteConfig, remoteConfigService.LastFetchOutcome, agentConfig.ApiBaseUrl, logger);
+                if (migrationTarget != null)
+                {
+                    return new RuntimeConfigBundle(
+                        remoteConfigService, remoteConfig, mergeResult: null,
+                        pendingMigrationTarget: migrationTarget);
+                }
+            }
+
             // Project remote tenant-controlled knobs onto the runtime AgentConfiguration so that
             // downstream consumers (CleanupService, SummaryDialogLauncher, StartupEnvironmentProbes,
             // DiagnosticsPackageService, EnrollmentTerminationHandler, the logger, the watchdog)
@@ -71,7 +91,7 @@ namespace AutopilotMonitor.Agent.V2.Runtime
 
             TryCleanupBootstrapConfig(agentConfig, agentVersion, logger);
 
-            return new RuntimeConfigBundle(remoteConfigService, remoteConfig, configMergeResult);
+            return new RuntimeConfigBundle(remoteConfigService, remoteConfig, configMergeResult, pendingMigrationTarget: null);
         }
 
         /// <summary>
@@ -145,21 +165,30 @@ namespace AutopilotMonitor.Agent.V2.Runtime
     /// <c>rotate_config</c> ServerAction callback), the fetched <see cref="AgentConfigResponse"/>
     /// and the <see cref="RemoteConfigMergeResult"/> diff snapshot (used by the
     /// <c>EmitUnrestrictedModeAuditIfChanged</c> lifecycle hook).
+    /// <para>
+    /// When <see cref="PendingMigrationTarget"/> is non-null the bundle is a partial result:
+    /// the fetch found a live endpoint-migration signal and Resolve returned before merge /
+    /// integrity / bootstrap-cleanup (<see cref="MergeResult"/> is null). RunAgent must
+    /// rebuild the backend clients on the target URL and Resolve again.
+    /// </para>
     /// </summary>
     internal sealed class RuntimeConfigBundle
     {
         public RemoteConfigService RemoteConfigService { get; }
         public AgentConfigResponse RemoteConfig { get; }
         public RemoteConfigMergeResult MergeResult { get; }
+        public string PendingMigrationTarget { get; }
 
         public RuntimeConfigBundle(
             RemoteConfigService remoteConfigService,
             AgentConfigResponse remoteConfig,
-            RemoteConfigMergeResult mergeResult)
+            RemoteConfigMergeResult mergeResult,
+            string pendingMigrationTarget = null)
         {
             RemoteConfigService = remoteConfigService;
             RemoteConfig = remoteConfig;
             MergeResult = mergeResult;
+            PendingMigrationTarget = pendingMigrationTarget;
         }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2/Runtime/AgentRuntimeHost.cs

@@ -132,7 +132,10 @@ namespace AutopilotMonitor.Agent.V2.Runtime
                 whiteGloveSealingPatternIds: whiteGloveSealingPatternIds,
                 drainInterval: drainInterval,
                 agentMaxLifetime: agentMaxLifetime,
-                uploadBatchSize: uploadBatchSize))
+                uploadBatchSize: uploadBatchSize,
+                // Live read: remote config is merged into agentConfig mid-session, so the
+                // trace-event gate must follow it rather than snapshot at construction.
+                traceEventsEnabled: () => agentConfig.SendTraceEvents))
             {
                 using (var shutdown = new ManualResetEventSlim(false))
                 using (var shutdownComplete = new ManualResetEventSlim(false))

src/Agent/AutopilotMonitor.DecisionCore.Tests/AutopilotMonitor.DecisionCore.Tests.csproj

@@ -2,11 +2,11 @@
 
   <PropertyGroup>
     <!--
-      Plan §4 M2: xUnit, .NET-8-Testrunner gegen netstandard2.0-Lib.
-      DecisionCore itself targets netstandard2.0, but the test runner uses .NET 8
-      so we benefit from modern xUnit + coverlet tooling.
+      Plan §4 M2: xUnit test runner against the netstandard2.0 lib.
+      DecisionCore itself targets netstandard2.0; the runner tracks the
+      repo-wide .NET version (global.json) for modern xUnit + coverlet tooling.
     -->
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
     <LangVersion>latest</LangVersion>
     <Nullable>enable</Nullable>
     <IsPackable>false</IsPackable>

src/Agent/AutopilotMonitor.DecisionCore.Tests/RealmJoinGateTests.cs

@@ -241,6 +241,199 @@ namespace AutopilotMonitor.DecisionCore.Tests
                 e.Parameters.TryGetValue("eventType", out var et) && et == "realmjoin_timeout");
         }
 
+        // ============================================================== Aborted first deployment (session 224b2087)
+
+        [Fact]
+        public void PhaseChanged_leaving_first_deployment_for_200_releases_gate_with_warning()
+        {
+            // Session 224b2087: interactive logon 17 s after phase 101 → RJ reclassifies the run
+            // as secondary-user deployment and writes 200/210, never 110. The 101 -> 200
+            // transition is impossible in a healthy first deployment, so it releases the gate
+            // with Outcome=FirstDeploymentIncomplete and a Warning timeline entry.
+            var engine = new DecisionEngine();
+            var state = PrimeClassicAwaitingDesktop(engine);
+            state = engine.Reduce(state, MakeSignal(5, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(5),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "101" })).NewState;
+            state = engine.Reduce(state, MakeSignal(6, DecisionSignalKind.DesktopArrived, T0.AddMinutes(6))).NewState;
+            Assert.NotEqual(SessionStage.Finalizing, state.Stage);
+
+            var step = engine.Reduce(state, MakeSignal(7, DecisionSignalKind.RealmJoinPhaseChanged, T0.AddMinutes(10),
+                new Dictionary<string, string>
+                {
+                    [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "200",
+                    [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = "101",
+                }));
+
+            Assert.Equal(SessionStage.Finalizing, step.NewState.Stage);
+            Assert.Equal("FirstDeploymentIncomplete", step.NewState.RealmJoinFacts.Outcome!.Value);
+            Assert.NotNull(step.NewState.RealmJoinFacts.ResolvedUtc);
+            Assert.Equal(200, step.NewState.RealmJoinFacts.LastDeploymentPhase!.Value);
+
+            // Hard-timeout deadline cancelled in state AND as a scheduler effect.
+            Assert.DoesNotContain(step.NewState.Deadlines, d => d.Name == DeadlineNames.RealmJoinTimeout);
+            Assert.Contains(step.Effects, e =>
+                e.Kind == DecisionEffectKind.CancelDeadline &&
+                e.CancelDeadlineName == DeadlineNames.RealmJoinTimeout);
+
+            // Warning timeline entry names both phases.
+            var warning = Assert.Single(step.Effects, e =>
+                e.Kind == DecisionEffectKind.EmitEventTimelineEntry &&
+                e.Parameters != null &&
+                e.Parameters.TryGetValue("eventType", out var et) && et == "realmjoin_first_deployment_incomplete");
+            Assert.Equal("Warning", warning.Parameters!["severity"]);
+            Assert.Equal("101", warning.Parameters["previousPhase"]);
+            Assert.Equal("200", warning.Parameters["deploymentPhase"]);
+            Assert.Contains("110", warning.Parameters["message"]);
+        }
+
+        [Fact]
+        public void PhaseChanged_within_first_deployment_window_is_bookkeeping_only()
+        {
+            // 100 -> 101 stays inside the first-deployment window — no release, but the phase
+            // fact must advance (it is the restart-safe witness for the abort rule).
+            var engine = new DecisionEngine();
+            var state = PrimeClassicAwaitingDesktop(engine);
+            state = engine.Reduce(state, MakeSignal(5, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(5),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "100" })).NewState;
+
+            var step = engine.Reduce(state, MakeSignal(6, DecisionSignalKind.RealmJoinPhaseChanged, T0.AddMinutes(6),
+                new Dictionary<string, string>
+                {
+                    [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "101",
+                    [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = "100",
+                }));
+
+            Assert.Equal(101, step.NewState.RealmJoinFacts.LastDeploymentPhase!.Value);
+            Assert.Null(step.NewState.RealmJoinFacts.Outcome);
+            Assert.Contains(step.NewState.Deadlines, d => d.Name == DeadlineNames.RealmJoinTimeout);
+            Assert.Empty(step.Effects);
+        }
+
+        [Fact]
+        public void PhaseChanged_from_completed_deployment_start_does_not_release()
+        {
+            // Session 6f1959c0 protection: RJ already stood at CompletedDeployment (210) when
+            // the agent booted and only deployed AFTERWARDS (210 -> 200 -> 210). Neither
+            // transition starts from the first-deployment window, so the abort rule must not
+            // fire — this ambiguous shape keeps waiting for 110 / the hard timeout (status quo).
+            var engine = new DecisionEngine();
+            var state = PrimeClassicAwaitingDesktop(engine);
+            state = engine.Reduce(state, MakeSignal(5, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(5),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "210" })).NewState;
+
+            state = engine.Reduce(state, MakeSignal(6, DecisionSignalKind.RealmJoinPhaseChanged, T0.AddMinutes(6),
+                new Dictionary<string, string>
+                {
+                    [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "200",
+                    [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = "210",
+                })).NewState;
+            Assert.Null(state.RealmJoinFacts.Outcome);
+
+            var step = engine.Reduce(state, MakeSignal(7, DecisionSignalKind.RealmJoinPhaseChanged, T0.AddMinutes(7),
+                new Dictionary<string, string>
+                {
+                    [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "210",
+                    [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = "200",
+                }));
+
+            Assert.Null(step.NewState.RealmJoinFacts.Outcome);
+            Assert.Contains(step.NewState.Deadlines, d => d.Name == DeadlineNames.RealmJoinTimeout);
+        }
+
+        [Fact]
+        public void Detected_replay_after_restart_with_deployment_phase_releases_gate()
+        {
+            // Agent restarted between the 101 and 200 observations: the watcher re-fires
+            // Detected with the CURRENT phase (200) and no PhaseChanged ever carries the
+            // transition. The persisted LastDeploymentPhase=101 is the witness — the Detected
+            // replay path must release the gate exactly like the PhaseChanged path.
+            var engine = new DecisionEngine();
+            var state = PrimeClassicAwaitingDesktop(engine);
+            state = engine.Reduce(state, MakeSignal(5, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(5),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "101" })).NewState;
+            state = engine.Reduce(state, MakeSignal(6, DecisionSignalKind.DesktopArrived, T0.AddMinutes(6))).NewState;
+            Assert.NotEqual(SessionStage.Finalizing, state.Stage);
+            Assert.Equal(101, state.RealmJoinFacts.LastDeploymentPhase!.Value);
+
+            var step = engine.Reduce(state, MakeSignal(7, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(12),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "200" }));
+
+            Assert.Equal(SessionStage.Finalizing, step.NewState.Stage);
+            Assert.Equal("FirstDeploymentIncomplete", step.NewState.RealmJoinFacts.Outcome!.Value);
+            Assert.Contains(step.Effects, e =>
+                e.Kind == DecisionEffectKind.EmitEventTimelineEntry &&
+                e.Parameters != null &&
+                e.Parameters.TryGetValue("eventType", out var et) && et == "realmjoin_first_deployment_incomplete");
+        }
+
+        [Fact]
+        public void Timeout_message_reports_persisted_last_phase_instead_of_zero()
+        {
+            // Before RealmJoinPhaseChanged became a typed signal, LastDeploymentPhase was only
+            // written at detection time — every realmjoin_timeout claimed "last phase: 0" no
+            // matter how far RJ actually got, hiding this whole failure class from ops.
+            var engine = new DecisionEngine();
+            var state = PrimeClassicAwaitingDesktop(engine);
+            state = engine.Reduce(state, MakeSignal(5, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(5),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "100" })).NewState;
+            state = engine.Reduce(state, MakeSignal(6, DecisionSignalKind.RealmJoinPhaseChanged, T0.AddMinutes(6),
+                new Dictionary<string, string>
+                {
+                    [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "101",
+                    [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = "100",
+                })).NewState;
+            state = engine.Reduce(state, MakeSignal(7, DecisionSignalKind.DesktopArrived, T0.AddMinutes(7))).NewState;
+
+            var step = engine.Reduce(state, MakeSignal(8, DecisionSignalKind.DeadlineFired, T0.AddMinutes(65),
+                new Dictionary<string, string> { [SignalPayloadKeys.Deadline] = DeadlineNames.RealmJoinTimeout }));
+
+            var timeout = Assert.Single(step.Effects, e =>
+                e.Kind == DecisionEffectKind.EmitEventTimelineEntry &&
+                e.Parameters != null &&
+                e.Parameters.TryGetValue("eventType", out var et) && et == "realmjoin_timeout");
+            Assert.Contains("last phase: 101", timeout.Parameters!["message"]);
+            Assert.Equal("101", timeout.Parameters["lastSeenPhase"]);
+        }
+
+        [Fact]
+        public void SelfDeploying_deferred_terminal_released_by_first_deployment_incomplete()
+        {
+            // Same deferred-release contract as RealmJoinResolved: when the SelfDeploying
+            // terminal was deferred on the closed RJ gate, the aborted-first-deployment release
+            // must complete the session directly (Completed + enrollment_complete), with the
+            // Warning entry leading the effects.
+            var engine = new DecisionEngine();
+            var state = DecisionState.CreateInitial("rj-sd-3", "rj-tenant", T0);
+            state = engine.Reduce(state, MakeSignal(0, DecisionSignalKind.SessionStarted, T0)).NewState;
+            state = engine.Reduce(state, MakeSignal(1, DecisionSignalKind.EspPhaseChanged, T0.AddMinutes(1),
+                new Dictionary<string, string> { [SignalPayloadKeys.EspPhase] = "DeviceSetup" })).NewState;
+            state = engine.Reduce(state, MakeSignal(2, DecisionSignalKind.RealmJoinDetected, T0.AddMinutes(2),
+                new Dictionary<string, string> { [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "101" })).NewState;
+            state = engine.Reduce(state, MakeSignal(3, DecisionSignalKind.DeviceSetupProvisioningComplete, T0.AddMinutes(3))).NewState;
+            state = engine.Reduce(state, MakeSignal(4, DecisionSignalKind.DeadlineFired, T0.AddMinutes(8),
+                new Dictionary<string, string> { [SignalPayloadKeys.Deadline] = DeadlineNames.DeviceOnlyEspDetection })).NewState;
+            Assert.True(state.RealmJoinFacts.SelfDeployingDeferredCompletion?.Value);
+
+            var step = engine.Reduce(state, MakeSignal(5, DecisionSignalKind.RealmJoinPhaseChanged, T0.AddMinutes(10),
+                new Dictionary<string, string>
+                {
+                    [DecisionEngine.RealmJoinPayloadKeys.DeploymentPhase] = "200",
+                    [DecisionEngine.RealmJoinPayloadKeys.PreviousPhase] = "101",
+                }));
+
+            Assert.Equal(SessionStage.Completed, step.NewState.Stage);
+            Assert.Equal(SessionOutcome.EnrollmentComplete, step.NewState.Outcome);
+            Assert.Equal("FirstDeploymentIncomplete", step.NewState.RealmJoinFacts.Outcome!.Value);
+            Assert.Contains(step.Effects, e =>
+                e.Kind == DecisionEffectKind.EmitEventTimelineEntry &&
+                e.Parameters != null &&
+                e.Parameters.TryGetValue("eventType", out var et) && et == "realmjoin_first_deployment_incomplete");
+            Assert.Contains(step.Effects, e =>
+                e.Kind == DecisionEffectKind.EmitEventTimelineEntry &&
+                e.Parameters != null &&
+                e.Parameters.TryGetValue("eventType", out var et) && et == "enrollment_complete");
+        }
+
         // ============================================================== SelfDeploying flow
 
         [Fact]

src/Backend/AutopilotMonitor.Functions.Tests/AgentEndpointMigrationTests.cs

@@ -0,0 +1,160 @@
+using AutopilotMonitor.Functions.Functions.Config;
+using AutopilotMonitor.Shared.Models;
+using AutopilotMonitor.Shared.Services;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Pins the endpoint-migration serving contract: the shared allowlist rules
+/// (<see cref="AgentEndpointMigrationRules"/>, used verbatim by the agent too) and the
+/// backend-side per-tenant resolution (<see cref="GetAgentConfigFunction.ResolveMigrateTarget"/> —
+/// tenant override wins, empty override pins, invalid values are never served).
+/// </summary>
+public class AgentEndpointMigrationTests
+{
+    private const string TenantA = "11111111-2222-3333-4444-555555555555";
+    private const string TenantB = "66666666-7777-8888-9999-000000000000";
+    private const string UsUrl = "https://autopilotmonitor-api-us.azurewebsites.net";
+    private const string EuUrl = "https://autopilotmonitor-api-eu.azurewebsites.net";
+
+    // ── Shared validation rules ─────────────────────────────────────────────
+
+    [Theory]
+    [InlineData("https://autopilotmonitor-api-us.azurewebsites.net", "https://autopilotmonitor-api-us.azurewebsites.net")]
+    [InlineData("https://AutopilotMonitor-API-US.AzureWebsites.NET/", "https://autopilotmonitor-api-us.azurewebsites.net")]
+    [InlineData("  https://x.azurewebsites.net  ", "https://x.azurewebsites.net")]
+    public void TryNormalizeTarget_accepts_and_normalizes(string candidate, string expected)
+    {
+        Assert.True(AgentEndpointMigrationRules.TryNormalizeTarget(candidate, out var normalized));
+        Assert.Equal(expected, normalized);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData("http://x.azurewebsites.net")]          // https only
+    [InlineData("https://attacker.example.com")]        // not allowlisted
+    [InlineData("https://evil-azurewebsites.net")]      // label-boundary bypass attempt
+    [InlineData("https://.azurewebsites.net")]          // bare suffix
+    [InlineData("https://x.azurewebsites.net:8443")]    // non-default port
+    [InlineData("https://u:p@x.azurewebsites.net")]     // userinfo
+    [InlineData("https://x.azurewebsites.net/api")]     // path
+    [InlineData("https://x.azurewebsites.net?a=1")]     // query
+    [InlineData("https://x.azurewebsites.net#frag")]    // fragment
+    [InlineData("ftp://x.azurewebsites.net")]
+    [InlineData("not a url")]
+    public void TryNormalizeTarget_rejects(string? candidate)
+    {
+        Assert.False(AgentEndpointMigrationRules.TryNormalizeTarget(candidate!, out var normalized));
+        Assert.Null(normalized);
+    }
+
+    [Fact]
+    public void TryNormalizeTarget_rejects_overlong_candidate()
+    {
+        var candidate = "https://" + new string('a', AgentEndpointMigrationRules.MaxTargetLength) + ".azurewebsites.net";
+        Assert.False(AgentEndpointMigrationRules.TryNormalizeTarget(candidate, out _));
+    }
+
+    [Fact]
+    public void IsEffectiveMigration_rejects_target_equal_to_current()
+    {
+        Assert.False(AgentEndpointMigrationRules.IsEffectiveMigration(EuUrl, EuUrl + "/", out var target));
+        Assert.Null(target);
+
+        Assert.True(AgentEndpointMigrationRules.IsEffectiveMigration(UsUrl, EuUrl, out target));
+        Assert.Equal(UsUrl, target);
+    }
+
+    // ── Backend resolution: global vs per-tenant override ──────────────────
+
+    [Fact]
+    public void No_configuration_resolves_to_null()
+    {
+        var config = new AdminConfiguration();
+
+        Assert.Null(GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out var rejected));
+        Assert.Null(rejected);
+    }
+
+    [Fact]
+    public void Global_target_applies_to_every_tenant()
+    {
+        var config = new AdminConfiguration { AgentMigrateApiBaseUrl = UsUrl };
+
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out _));
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantB, out _));
+    }
+
+    [Fact]
+    public void Tenant_override_wins_over_global()
+    {
+        var config = new AdminConfiguration
+        {
+            AgentMigrateApiBaseUrl = UsUrl,
+            AgentMigrateTenantOverridesJson = $"{{\"{TenantA}\": \"{EuUrl}\"}}"
+        };
+
+        Assert.Equal(EuUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out _));
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantB, out _));
+    }
+
+    [Fact]
+    public void Empty_tenant_override_pins_tenant_against_global_target()
+    {
+        var config = new AdminConfiguration
+        {
+            AgentMigrateApiBaseUrl = UsUrl,
+            AgentMigrateTenantOverridesJson = $"{{\"{TenantA}\": \"\"}}"
+        };
+
+        Assert.Null(GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out var rejected));
+        Assert.Null(rejected); // pinned, not rejected
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantB, out _));
+    }
+
+    [Fact]
+    public void Tenant_override_key_is_case_insensitive()
+    {
+        var config = new AdminConfiguration
+        {
+            AgentMigrateTenantOverridesJson = $"{{\"{TenantA.ToUpperInvariant()}\": \"{UsUrl}\"}}"
+        };
+
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out _));
+    }
+
+    [Fact]
+    public void Invalid_configured_target_is_never_served_and_reported_as_rejected()
+    {
+        var config = new AdminConfiguration { AgentMigrateApiBaseUrl = "https://attacker.example.com" };
+
+        Assert.Null(GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out var rejected));
+        Assert.Equal("https://attacker.example.com", rejected);
+    }
+
+    [Fact]
+    public void Malformed_overrides_json_degrades_to_global_target()
+    {
+        var config = new AdminConfiguration
+        {
+            AgentMigrateApiBaseUrl = UsUrl,
+            AgentMigrateTenantOverridesJson = "{not json"
+        };
+
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out _));
+    }
+
+    [Fact]
+    public void Served_target_is_normalized()
+    {
+        var config = new AdminConfiguration
+        {
+            AgentMigrateApiBaseUrl = "https://AutopilotMonitor-API-US.azurewebsites.net/"
+        };
+
+        Assert.Equal(UsUrl, GetAgentConfigFunction.ResolveMigrateTarget(config, TenantA, out _));
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/AuthFunctionSideEffectTests.cs

@@ -55,7 +55,7 @@ public class AuthFunctionSideEffectTests
         { CallBase = false };
 
         var previewMock = new Mock<PreviewWhitelistService>(
-            configRepo, cache, Mock.Of<ILogger<PreviewWhitelistService>>())
+            configRepo, cache, Mock.Of<ILogger<PreviewWhitelistService>>(), _tenantConfigMock.Object)
         { CallBase = false };
 
         _telegramMock = new Mock<TelegramNotificationService>(

src/Backend/AutopilotMonitor.Functions.Tests/BusinessTimestampDecodeTests.cs

@@ -0,0 +1,83 @@
+using AutopilotMonitor.Functions.Helpers;
+using AutopilotMonitor.Functions.Services;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// RowKey → business-time decoders. These are the read-path compensation for rows whose
+/// system Timestamp was reset by the 2026-07-18 storage migration: the RowKey is the only
+/// time carrier that survives a row rewrite, so the decode must round-trip exactly and
+/// must reject every foreign format (falling back instead of mis-dating rows).
+/// </summary>
+public class BusinessTimestampDecodeTests
+{
+    private static readonly DateTime Ts = new DateTime(2026, 6, 15, 10, 30, 45, 123, DateTimeKind.Utc).AddTicks(4567);
+
+    [Fact]
+    public void Audit_rowkey_roundtrips_tick_exact()
+    {
+        var rowKey = TableStorageService.BuildAuditLogRowKey(Ts, Guid.NewGuid());
+        Assert.True(BusinessTimestamp.TryDecodeAuditRowKey(rowKey, out var decoded));
+        Assert.Equal(Ts, decoded);
+        Assert.Equal(DateTimeKind.Utc, decoded.Kind);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("!")]
+    [InlineData("!123")] // too short
+    [InlineData("!123456789012345678x_guid")] // non-digit in revtick
+    [InlineData("d6f6dd90f41c4b16b290aac042e5b466")] // legacy bare GUID (:N)
+    [InlineData("0000000000000000000")] // ops-style bare revtick is not an audit key
+    public void Audit_decoder_rejects_foreign_formats(string? rowKey)
+    {
+        Assert.False(BusinessTimestamp.TryDecodeAuditRowKey(rowKey, out _));
+    }
+
+    [Fact]
+    public void Ops_rowkey_roundtrips_tick_exact()
+    {
+        var rowKey = $"{DateTime.MaxValue.Ticks - Ts.Ticks:D19}";
+        Assert.True(BusinessTimestamp.TryDecodeOpsRowKey(rowKey, out var decoded));
+        Assert.Equal(Ts, decoded);
+        Assert.Equal(DateTimeKind.Utc, decoded.Kind);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("123456789012345678")] // 18 digits
+    [InlineData("12345678901234567890")] // 20 digits
+    [InlineData("123456789012345678x")] // non-digit
+    [InlineData("!1234567890123456789")] // audit-prefixed
+    public void Ops_decoder_rejects_foreign_formats(string? rowKey)
+    {
+        Assert.False(BusinessTimestamp.TryDecodeOpsRowKey(rowKey, out _));
+    }
+
+    [Fact]
+    public void Event_rowkey_prefix_decodes_to_millisecond_truncated_agent_time()
+    {
+        var rowKey = $"{Ts:yyyyMMddHHmmssfff}_{42L:D10}";
+        Assert.True(BusinessTimestamp.TryDecodeEventRowKeyPrefix(rowKey, out var decoded));
+        // The RowKey format truncates sub-millisecond ticks at write time.
+        var expected = new DateTime(2026, 6, 15, 10, 30, 45, 123, DateTimeKind.Utc);
+        Assert.Equal(expected, decoded);
+        Assert.Equal(DateTimeKind.Utc, decoded.Kind);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("20260615103045123")] // no separator/sequence
+    [InlineData("2026061510304512_0000000042")] // 16-digit prefix
+    [InlineData("202606151030451234_0000000042")] // 18-digit prefix
+    [InlineData("2026061510304512x_0000000042")] // non-digit in prefix
+    [InlineData("20261315103045123_0000000042")] // month 13
+    [InlineData("d6f6dd90f41c4b16b290aac042e5b466")] // GUID
+    public void Event_decoder_rejects_foreign_formats(string? rowKey)
+    {
+        Assert.False(BusinessTimestamp.TryDecodeEventRowKeyPrefix(rowKey, out _));
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/BusinessTimestampFilterClauseTests.cs

@@ -0,0 +1,181 @@
+using System.Text.RegularExpressions;
+using AutopilotMonitor.Functions.DataAccess.TableStorage;
+using AutopilotMonitor.Functions.Helpers;
+using AutopilotMonitor.Functions.Services;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// RowKey-range date-window / retention clauses. Date filtering moved off the system
+/// Timestamp (reset by storage migrations) onto the reverse-tick RowKey; these tests pin
+/// (a) tick-exact inclusive/exclusive boundary semantics identical to the old
+/// `Timestamp ge/le` clauses, and (b) the GUID-safety invariant: legacy bare-GUID audit
+/// rows sort AFTER all '!'-rows, so any lower RowKey bound without the `RowKey lt '"'`
+/// guard would match — and a retention sweep would DELETE — every legacy row.
+/// </summary>
+public class BusinessTimestampFilterClauseTests
+{
+    private static readonly DateTime T = new DateTime(2026, 6, 15, 12, 0, 0, DateTimeKind.Utc).AddTicks(789);
+    private static readonly string Tenant = "11111111-1111-1111-1111-111111111111";
+
+    private static string AuditRk(DateTime ts) => TableStorageService.BuildAuditLogRowKey(ts, Guid.NewGuid());
+    private static string OpsRk(DateTime ts) => $"{DateTime.MaxValue.Ticks - ts.Ticks:D19}";
+
+    /// <summary>Evaluates a clause of the form "RowKey op 'literal' [and RowKey op 'literal']…" against a RowKey.</summary>
+    private static bool Matches(string clause, string rowKey)
+    {
+        var parts = Regex.Matches(clause, @"RowKey (ge|gt|le|lt) '([^']*)'");
+        Assert.True(parts.Count > 0, $"no RowKey comparisons in clause: {clause}");
+        foreach (Match m in parts)
+        {
+            var cmp = string.CompareOrdinal(rowKey, m.Groups[2].Value);
+            var ok = m.Groups[1].Value switch
+            {
+                "ge" => cmp >= 0,
+                "gt" => cmp > 0,
+                "le" => cmp <= 0,
+                "lt" => cmp < 0,
+                _ => throw new InvalidOperationException(),
+            };
+            if (!ok) return false;
+        }
+        return true;
+    }
+
+    // ===== Audit boundaries =====
+
+    [Fact]
+    public void Audit_dateFrom_is_inclusive_to_the_tick()
+    {
+        var clause = BusinessTimestamp.AuditDateFromClause(T);
+        Assert.True(Matches(clause, AuditRk(T)));                  // ts == from → included
+        Assert.True(Matches(clause, AuditRk(T.AddTicks(1))));      // newer → included
+        Assert.False(Matches(clause, AuditRk(T.AddTicks(-1))));    // 1 tick older → excluded
+    }
+
+    [Fact]
+    public void Audit_dateTo_is_inclusive_to_the_tick()
+    {
+        var clause = BusinessTimestamp.AuditDateToClause(T);
+        Assert.True(Matches(clause, AuditRk(T)));                  // ts == to → included
+        Assert.True(Matches(clause, AuditRk(T.AddTicks(-1))));     // older → included
+        Assert.False(Matches(clause, AuditRk(T.AddTicks(1))));     // 1 tick newer → excluded
+    }
+
+    [Fact]
+    public void Audit_retention_is_strictly_older_than_cutoff()
+    {
+        var clause = BusinessTimestamp.AuditRetentionClause(T);
+        Assert.False(Matches(clause, AuditRk(T)));                 // ts == cutoff → kept
+        Assert.True(Matches(clause, AuditRk(T.AddTicks(-1))));     // 1 tick older → deleted
+        Assert.False(Matches(clause, AuditRk(T.AddTicks(1))));     // newer → kept
+    }
+
+    // ===== Audit GUID safety (the single most dangerous invariant of this change) =====
+
+    [Fact]
+    public void Legacy_guid_rowkeys_sort_after_the_time_encoded_guard()
+    {
+        for (var i = 0; i < 20; i++)
+        {
+            var guidRk = Guid.NewGuid().ToString("N");
+            Assert.True(string.CompareOrdinal(guidRk, BusinessTimestamp.AuditTimeEncodedUpperBound) > 0);
+        }
+    }
+
+    [Fact]
+    public void No_audit_date_or_retention_clause_matches_legacy_guid_rowkeys()
+    {
+        var clauses = new[]
+        {
+            BusinessTimestamp.AuditDateFromClause(T),
+            BusinessTimestamp.AuditDateToClause(T),
+            BusinessTimestamp.AuditDateToClause(DateTime.MaxValue.AddTicks(-1)), // widest possible window
+            BusinessTimestamp.AuditRetentionClause(T),
+            BusinessTimestamp.AuditRetentionClause(DateTime.MaxValue.AddTicks(-1)), // widest possible sweep
+        };
+        foreach (var clause in clauses)
+        {
+            for (var i = 0; i < 20; i++)
+            {
+                Assert.False(Matches(clause, Guid.NewGuid().ToString("N")),
+                    $"clause matched a legacy GUID RowKey: {clause}");
+            }
+        }
+    }
+
+    [Fact]
+    public void Audit_lower_bounded_clauses_carry_the_time_encoded_guard()
+    {
+        Assert.Contains($"RowKey lt '{BusinessTimestamp.AuditTimeEncodedUpperBound}'",
+            BusinessTimestamp.AuditDateToClause(T));
+        Assert.Contains($"RowKey lt '{BusinessTimestamp.AuditTimeEncodedUpperBound}'",
+            BusinessTimestamp.AuditRetentionClause(T));
+    }
+
+    // ===== Ops boundaries =====
+
+    [Fact]
+    public void Ops_dateFrom_is_inclusive_to_the_tick()
+    {
+        var clause = BusinessTimestamp.OpsDateFromClause(T);
+        Assert.True(Matches(clause, OpsRk(T)));
+        Assert.True(Matches(clause, OpsRk(T.AddTicks(1))));
+        Assert.False(Matches(clause, OpsRk(T.AddTicks(-1))));
+    }
+
+    [Fact]
+    public void Ops_dateTo_is_inclusive_to_the_tick()
+    {
+        var clause = BusinessTimestamp.OpsDateToClause(T);
+        Assert.True(Matches(clause, OpsRk(T)));
+        Assert.True(Matches(clause, OpsRk(T.AddTicks(-1))));
+        Assert.False(Matches(clause, OpsRk(T.AddTicks(1))));
+    }
+
+    [Fact]
+    public void Ops_retention_is_strictly_older_than_cutoff()
+    {
+        var clause = BusinessTimestamp.OpsRetentionClause(T);
+        Assert.False(Matches(clause, OpsRk(T)));
+        Assert.True(Matches(clause, OpsRk(T.AddTicks(-1))));
+        Assert.False(Matches(clause, OpsRk(T.AddTicks(1))));
+    }
+
+    // ===== Composition into the filter builders =====
+
+    [Fact]
+    public void Audit_filter_builders_emit_rowkey_windows_not_timestamp_clauses()
+    {
+        var from = new DateTime(2026, 6, 1, 0, 0, 0, DateTimeKind.Utc);
+        var to = new DateTime(2026, 7, 1, 0, 0, 0, DateTimeKind.Utc);
+
+        var plain = TableStorageService.BuildAuditLogFilter(Tenant, from, to);
+        var fanOut = TableStorageService.BuildAuditLogFilterWithRowKeyBound(
+            Tenant, from, to, lastRowKey: "!0123_x", excludeDeletions: false);
+
+        foreach (var f in new[] { plain!, fanOut })
+        {
+            Assert.DoesNotContain("Timestamp ge", f);
+            Assert.DoesNotContain("Timestamp le", f);
+            Assert.Contains(BusinessTimestamp.AuditDateFromClause(from), f);
+            Assert.Contains(BusinessTimestamp.AuditDateToClause(to), f);
+        }
+        Assert.Contains("RowKey gt '!0123_x'", fanOut); // fan-out cursor composes with the window
+    }
+
+    [Fact]
+    public void Ops_filter_builder_emits_rowkey_window_not_timestamp_clauses()
+    {
+        var from = new DateTime(2026, 6, 1, 0, 0, 0, DateTimeKind.Utc);
+        var to = new DateTime(2026, 7, 1, 0, 0, 0, DateTimeKind.Utc);
+
+        var f = TableOpsEventRepository.BuildFilter("Security", from, to);
+
+        Assert.NotNull(f);
+        Assert.DoesNotContain("Timestamp ge", f);
+        Assert.DoesNotContain("Timestamp le", f);
+        Assert.Contains(BusinessTimestamp.OpsDateFromClause(from), f);
+        Assert.Contains(BusinessTimestamp.OpsDateToClause(to), f);
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/BusinessTimestampPrecedenceTests.cs

@@ -0,0 +1,118 @@
+using Azure.Data.Tables;
+using AutopilotMonitor.Functions.DataAccess.TableStorage;
+using AutopilotMonitor.Functions.Helpers;
+using AutopilotMonitor.Functions.Services;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Read-mapper resolution order for the three affected tables:
+/// OccurredUtc column → RowKey decode → system Timestamp. The last hop is the
+/// migration-corrupted value (a row rewrite resets it), so it must only ever win when
+/// the row carries no better source (audit legacy bare-GUID rows).
+/// </summary>
+public class BusinessTimestampPrecedenceTests
+{
+    private static readonly DateTime Occurred = new(2026, 5, 10, 8, 0, 0, DateTimeKind.Utc);
+    private static readonly DateTime RowKeyTime = new(2026, 6, 20, 9, 30, 0, DateTimeKind.Utc);
+    private static readonly DateTimeOffset SystemTs = new(2026, 7, 18, 13, 58, 0, TimeSpan.Zero); // migration moment
+
+    private static TableEntity WithSystemTimestamp(TableEntity e)
+    {
+        e["Timestamp"] = SystemTs;
+        return e;
+    }
+
+    // ===== Audit =====
+
+    [Fact]
+    public void Audit_occurredutc_wins_over_rowkey_and_system()
+    {
+        var e = WithSystemTimestamp(new TableEntity("t", TableStorageService.BuildAuditLogRowKey(RowKeyTime, Guid.NewGuid()))
+        {
+            [BusinessTimestamp.OccurredUtcColumn] = new DateTimeOffset(Occurred),
+        });
+        Assert.Equal(Occurred, TableStorageService.ResolveAuditTimestamp(e));
+    }
+
+    [Fact]
+    public void Audit_rowkey_decode_wins_over_system_when_column_missing()
+    {
+        var e = WithSystemTimestamp(new TableEntity("t", TableStorageService.BuildAuditLogRowKey(RowKeyTime, Guid.NewGuid())));
+        Assert.Equal(RowKeyTime, TableStorageService.ResolveAuditTimestamp(e));
+    }
+
+    [Fact]
+    public void Audit_legacy_guid_row_falls_back_to_system_timestamp()
+    {
+        var e = WithSystemTimestamp(new TableEntity("t", Guid.NewGuid().ToString("N")));
+        Assert.Equal(SystemTs.UtcDateTime, TableStorageService.ResolveAuditTimestamp(e));
+    }
+
+    // ===== Ops =====
+
+    [Fact]
+    public void Ops_occurredutc_wins_over_rowkey_and_system()
+    {
+        var e = WithSystemTimestamp(new TableEntity("Security", $"{DateTime.MaxValue.Ticks - RowKeyTime.Ticks:D19}")
+        {
+            [BusinessTimestamp.OccurredUtcColumn] = new DateTimeOffset(Occurred),
+        });
+        Assert.Equal(Occurred, TableOpsEventRepository.ResolveTimestamp(e));
+    }
+
+    [Fact]
+    public void Ops_rowkey_decode_wins_over_system_when_column_missing()
+    {
+        var e = WithSystemTimestamp(new TableEntity("Security", $"{DateTime.MaxValue.Ticks - RowKeyTime.Ticks:D19}"));
+        Assert.Equal(RowKeyTime, TableOpsEventRepository.ResolveTimestamp(e));
+    }
+
+    [Fact]
+    public void Ops_undecodable_rowkey_falls_back_to_system_timestamp()
+    {
+        var e = WithSystemTimestamp(new TableEntity("Security", "not-a-revtick"));
+        Assert.Equal(SystemTs.UtcDateTime, TableOpsEventRepository.ResolveTimestamp(e));
+    }
+
+    // ===== Events =====
+
+    private static string EventRowKey(DateTime ts, long seq = 42) => $"{ts:yyyyMMddHHmmssfff}_{seq:D10}";
+
+    [Fact]
+    public void Event_occurredutc_wins_over_rowkey_and_system()
+    {
+        var e = WithSystemTimestamp(new TableEntity("tenant_session", EventRowKey(RowKeyTime))
+        {
+            [BusinessTimestamp.OccurredUtcColumn] = new DateTimeOffset(Occurred),
+        });
+        Assert.Equal(Occurred, TableStorageService.ResolveEventTimestamp(e));
+    }
+
+    [Fact]
+    public void Event_rowkey_prefix_wins_over_system_when_column_missing()
+    {
+        // The pre-cutover case: no OccurredUtc column, system Timestamp = migration moment.
+        var e = WithSystemTimestamp(new TableEntity("tenant_session", EventRowKey(RowKeyTime)));
+        Assert.Equal(RowKeyTime, TableStorageService.ResolveEventTimestamp(e));
+    }
+
+    [Fact]
+    public void Event_undecodable_rowkey_falls_back_to_system_timestamp()
+    {
+        var e = WithSystemTimestamp(new TableEntity("tenant_session", "weird-rowkey"));
+        Assert.Equal(SystemTs.UtcDateTime, TableStorageService.ResolveEventTimestamp(e));
+    }
+
+    [Fact]
+    public void Event_occurredutc_read_tolerates_datetime_materialization()
+    {
+        // SDK reads surface Edm.DateTime as DateTimeOffset or DateTime depending on payload
+        // shape — the resolver must accept both (dual-reader lesson).
+        var e = new TableEntity("tenant_session", EventRowKey(RowKeyTime))
+        {
+            [BusinessTimestamp.OccurredUtcColumn] = Occurred, // plain DateTime, not DateTimeOffset
+        };
+        Assert.Equal(Occurred, TableStorageService.ResolveEventTimestamp(e));
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/EnrollmentTimeoutClassifierTests.cs

@@ -113,9 +113,11 @@ public class EnrollmentTimeoutClassifierTests
         // Negative Hello terminals leave the agent waiting — must NOT count as resolved.
         Assert.False(EnrollmentTimeoutClassifier.ExtractRollup(new[] { Evt("hello_provisioning_failed") }).HelloResolved);
         Assert.False(EnrollmentTimeoutClassifier.ExtractRollup(new[] { Evt("hello_completion_timeout") }).HelloResolved);
-        // Both RealmJoin gate terminals count as resolved (phase 110 or 60-min hard timeout).
+        // All RealmJoin gate terminals count as resolved (phase 110, aborted first
+        // deployment — session 224b2087 — or 60-min hard timeout).
         Assert.True(EnrollmentTimeoutClassifier.ExtractRollup(new[] { Evt("realmjoin_resolved") }).RealmJoinResolved);
         Assert.True(EnrollmentTimeoutClassifier.ExtractRollup(new[] { Evt("realmjoin_timeout") }).RealmJoinResolved);
+        Assert.True(EnrollmentTimeoutClassifier.ExtractRollup(new[] { Evt("realmjoin_first_deployment_incomplete") }).RealmJoinResolved);
     }
 
     [Fact]

src/Backend/AutopilotMonitor.Functions.Tests/GatherRuleScopeFieldsTests.cs

@@ -0,0 +1,283 @@
+using AutopilotMonitor.Functions.Functions.Rules;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.Models;
+using Azure;
+using Azure.Data.Tables;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Covers the three gather-rule scope/emit fields (ActivePhases, ActiveFromPhase, EmitMode):
+/// Store↔Map table-serialization roundtrip (table-serialization rule: every model field in BOTH
+/// directions), legacy rows without the new columns, the <see cref="GatherRuleService.ContentEquivalent"/>
+/// null-tolerance (no reseed churn), and the create/update validation matrix in
+/// <see cref="GatherRulesFunction.ValidateScopeAndEmitMode"/>.
+/// </summary>
+public class GatherRuleScopeFieldsTests
+{
+    // ── Store ↔ Map roundtrip ──────────────────────────────────────────────
+
+    private static (TableStorageService service, Func<TableEntity?> lastUpserted) BuildStorageHarness()
+    {
+        TableEntity? captured = null;
+        var tableClient = new Mock<TableClient>();
+        tableClient
+            .Setup(c => c.UpsertEntityAsync(
+                It.IsAny<TableEntity>(), It.IsAny<TableUpdateMode>(), It.IsAny<CancellationToken>()))
+            .Returns<TableEntity, TableUpdateMode, CancellationToken>((e, _, _) =>
+            {
+                captured = e;
+                return Task.FromResult(new Mock<Response>().Object);
+            });
+
+        var serviceClient = new Mock<TableServiceClient>();
+        serviceClient.Setup(c => c.GetTableClient(It.IsAny<string>())).Returns(tableClient.Object);
+
+        var service = new TableStorageService(serviceClient.Object, NullLogger<TableStorageService>.Instance);
+        return (service, () => captured);
+    }
+
+    [Fact]
+    public async Task Roundtrip_ScopeFields_SurviveStoreAndMap()
+    {
+        var (service, lastUpserted) = BuildStorageHarness();
+        var rule = new GatherRule
+        {
+            RuleId = "GATHER-SCOPE-001",
+            Title = "Scoped rule",
+            CollectorType = "registry",
+            Target = "HKLM\\SOFTWARE\\Contoso",
+            Trigger = "interval",
+            IntervalSeconds = 60,
+            OutputEventType = "gather_scoped",
+            ActivePhases = new List<string> { "AccountSetup", "AppsUser" },
+            EmitMode = "on_change",
+        };
+
+        Assert.True(await service.StoreGatherRuleAsync(rule, "global"));
+        var mapped = service.MapToGatherRule(lastUpserted()!);
+
+        Assert.NotNull(mapped.ActivePhases);
+        Assert.Equal(new[] { "AccountSetup", "AppsUser" }, mapped.ActivePhases);
+        Assert.Null(mapped.ActiveFromPhase);
+        Assert.Equal("on_change", mapped.EmitMode);
+    }
+
+    [Fact]
+    public async Task Roundtrip_FromPhase_SurvivesStoreAndMap()
+    {
+        var (service, lastUpserted) = BuildStorageHarness();
+        var rule = new GatherRule
+        {
+            RuleId = "GATHER-SCOPE-002",
+            Title = "From-phase rule",
+            CollectorType = "registry",
+            Target = "HKLM\\SOFTWARE\\Contoso",
+            Trigger = "interval",
+            OutputEventType = "gather_scoped",
+            ActiveFromPhase = "AccountSetup",
+        };
+
+        Assert.True(await service.StoreGatherRuleAsync(rule, "global"));
+        var mapped = service.MapToGatherRule(lastUpserted()!);
+
+        Assert.Null(mapped.ActivePhases);
+        Assert.Equal("AccountSetup", mapped.ActiveFromPhase);
+        Assert.Null(mapped.EmitMode);
+    }
+
+    [Fact]
+    public async Task Roundtrip_NullScopeFields_StayNull()
+    {
+        var (service, lastUpserted) = BuildStorageHarness();
+        var rule = new GatherRule
+        {
+            RuleId = "GATHER-SCOPE-003",
+            Title = "Unscoped rule",
+            CollectorType = "registry",
+            Target = "HKLM\\SOFTWARE\\Contoso",
+            Trigger = "startup",
+            OutputEventType = "gather_plain",
+        };
+
+        Assert.True(await service.StoreGatherRuleAsync(rule, "global"));
+        var mapped = service.MapToGatherRule(lastUpserted()!);
+
+        Assert.Null(mapped.ActivePhases);
+        Assert.Null(mapped.ActiveFromPhase);
+        Assert.Null(mapped.EmitMode);
+    }
+
+    [Fact]
+    public void Map_LegacyRow_WithoutScopeColumns_DefaultsToNull()
+    {
+        var (service, _) = BuildStorageHarness();
+        // A row written before the scope fields existed: none of the new columns present.
+        var legacy = new TableEntity("global", "GATHER-LEGACY-001")
+        {
+            ["Title"] = "Legacy rule",
+            ["CollectorType"] = "registry",
+            ["Target"] = "HKLM\\SOFTWARE\\Contoso",
+            ["Trigger"] = "startup",
+            ["OutputEventType"] = "gather_legacy",
+        };
+
+        var mapped = service.MapToGatherRule(legacy);
+
+        Assert.Null(mapped.ActivePhases);
+        Assert.Null(mapped.ActiveFromPhase);
+        Assert.Null(mapped.EmitMode);
+    }
+
+    // ── ContentEquivalent ──────────────────────────────────────────────────
+
+    private static GatherRule BaseRule() => new()
+    {
+        RuleId = "GATHER-EQ-001",
+        Title = "Rule",
+        Description = "Desc",
+        Version = "1.0.0",
+        CollectorType = "registry",
+        Target = "HKLM\\SOFTWARE\\Contoso",
+        Trigger = "interval",
+        TriggerPhase = "",
+        OutputEventType = "gather_eq",
+    };
+
+    [Fact]
+    public void ContentEquivalent_NullAndEmptyActivePhases_AreEquivalent()
+    {
+        // Pre-existing DB rows map absent columns to null; seeds are also null — and an
+        // explicitly-empty list means the same "unrestricted". No reseed churn allowed.
+        var a = BaseRule();
+        var b = BaseRule();
+        b.ActivePhases = new List<string>();
+
+        Assert.True(GatherRuleService.ContentEquivalent(a, b));
+        Assert.True(GatherRuleService.ContentEquivalent(b, a));
+    }
+
+    [Fact]
+    public void ContentEquivalent_DetectsChangesInEachScopeField()
+    {
+        var baseline = BaseRule();
+
+        var phases = BaseRule();
+        phases.ActivePhases = new List<string> { "AccountSetup" };
+        Assert.False(GatherRuleService.ContentEquivalent(baseline, phases));
+
+        var from = BaseRule();
+        from.ActiveFromPhase = "AccountSetup";
+        Assert.False(GatherRuleService.ContentEquivalent(baseline, from));
+
+        var emit = BaseRule();
+        emit.EmitMode = "on_change";
+        Assert.False(GatherRuleService.ContentEquivalent(baseline, emit));
+    }
+
+    [Fact]
+    public void ContentEquivalent_SameScopeFields_AreEquivalent()
+    {
+        var a = BaseRule();
+        a.ActivePhases = new List<string> { "DeviceSetup", "AccountSetup" };
+        a.EmitMode = "on_change";
+        var b = BaseRule();
+        b.ActivePhases = new List<string> { "DeviceSetup", "AccountSetup" };
+        b.EmitMode = "on_change";
+
+        Assert.True(GatherRuleService.ContentEquivalent(a, b));
+    }
+
+    // ── Validation ─────────────────────────────────────────────────────────
+
+    private static GatherRule ValidationRule(
+        List<string>? activePhases = null, string? activeFromPhase = null, string? emitMode = null) => new()
+    {
+        RuleId = "GATHER-VAL-001",
+        Title = "Rule",
+        CollectorType = "registry",
+        Target = "HKLM\\SOFTWARE\\Contoso",
+        Trigger = "interval",
+        OutputEventType = "gather_val",
+        ActivePhases = activePhases,
+        ActiveFromPhase = activeFromPhase,
+        EmitMode = emitMode,
+    };
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("Start")]
+    [InlineData("DevicePreparation")]
+    [InlineData("AccountSetup")]
+    [InlineData("Complete")]
+    [InlineData("accountsetup")] // case-insensitive
+    public void Validate_AcceptsValidFromPhase(string? fromPhase)
+    {
+        Assert.Null(GatherRulesFunction.ValidateScopeAndEmitMode(ValidationRule(activeFromPhase: fromPhase)));
+    }
+
+    [Theory]
+    [InlineData("Unknown")]
+    [InlineData("Failed")]
+    [InlineData("4")]          // numeric enum value — canonical names only
+    [InlineData("DeviceESP")]  // the invalid token the old free-text UI suggested
+    public void Validate_RejectsInvalidFromPhase(string fromPhase)
+    {
+        Assert.NotNull(GatherRulesFunction.ValidateScopeAndEmitMode(ValidationRule(activeFromPhase: fromPhase)));
+    }
+
+    [Fact]
+    public void Validate_AcceptsValidActivePhases_AndRejectsInvalidEntries()
+    {
+        Assert.Null(GatherRulesFunction.ValidateScopeAndEmitMode(
+            ValidationRule(activePhases: new List<string> { "DeviceSetup", "AppsDevice" })));
+
+        Assert.NotNull(GatherRulesFunction.ValidateScopeAndEmitMode(
+            ValidationRule(activePhases: new List<string> { "DeviceSetup", "Failed" })));
+        Assert.NotNull(GatherRulesFunction.ValidateScopeAndEmitMode(
+            ValidationRule(activePhases: new List<string> { "" })));
+    }
+
+    [Fact]
+    public void Validate_RejectsBothScopeFieldsSet()
+    {
+        var error = GatherRulesFunction.ValidateScopeAndEmitMode(ValidationRule(
+            activePhases: new List<string> { "AccountSetup" }, activeFromPhase: "DeviceSetup"));
+
+        Assert.NotNull(error);
+        Assert.Contains("mutually exclusive", error);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("always")]
+    [InlineData("on_change")]
+    [InlineData("ON_CHANGE")] // case-insensitive
+    public void Validate_AcceptsValidEmitModes(string? emitMode)
+    {
+        Assert.Null(GatherRulesFunction.ValidateScopeAndEmitMode(ValidationRule(emitMode: emitMode)));
+    }
+
+    [Fact]
+    public void Validate_RejectsUnknownEmitMode()
+    {
+        Assert.NotNull(GatherRulesFunction.ValidateScopeAndEmitMode(ValidationRule(emitMode: "sometimes")));
+    }
+
+    [Fact]
+    public void Validate_TogglePartialPayload_PassesThrough()
+    {
+        // The portal toggle sends only { enabled, isBuiltIn, isCommunity } — none of the
+        // scope fields — and must not be rejected.
+        var toggle = new GatherRule { RuleId = "GATHER-VAL-002", Enabled = false };
+        Assert.Null(GatherRulesFunction.ValidateScopeAndEmitMode(toggle));
+    }
+
+    [Fact]
+    public void Validate_EmptyActivePhasesList_IsUnrestricted_AndPasses()
+    {
+        Assert.Null(GatherRulesFunction.ValidateScopeAndEmitMode(ValidationRule(activePhases: new List<string>())));
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/GatherRuleUpdatePartialMergeTests.cs

@@ -0,0 +1,146 @@
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.DataAccess;
+using AutopilotMonitor.Shared.Models;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Pins the custom-rule partial-PUT fix on <see cref="GatherRuleService.UpdateRuleAsync"/>:
+/// the portal toggle PUTs only { enabled, isBuiltIn, isCommunity }, and full-storing that
+/// payload wiped Title/Target/Trigger/Parameters of the custom rule. Toggle-style partials
+/// (empty Title/CollectorType/Target) must merge Enabled into the existing row; full payloads
+/// (edit flow) must still replace the row but preserve the original CreatedAt.
+/// </summary>
+public class GatherRuleUpdatePartialMergeTests
+{
+    private const string TenantId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+    private const string RuleId = "GATHER-CUST-001";
+
+    private static GatherRule ExistingCustomRule() => new()
+    {
+        RuleId = RuleId,
+        Title = "Collect BIOS Config",
+        Description = "Reads the RealmJoin BIOS key",
+        Category = "device",
+        CollectorType = "registry",
+        Target = "HKLM\\SOFTWARE\\RealmJoin\\Custom\\BIOS",
+        Parameters = new Dictionary<string, string> { ["valueName"] = "Version" },
+        Trigger = "interval",
+        IntervalSeconds = 60,
+        OutputEventType = "gather_bios_config",
+        Enabled = true,
+        IsBuiltIn = false,
+        IsCommunity = false,
+        CreatedAt = new DateTime(2026, 1, 15, 12, 0, 0, DateTimeKind.Utc),
+        ActiveFromPhase = "AccountSetup",
+        EmitMode = "on_change",
+    };
+
+    private static (GatherRuleService service, Mock<IRuleRepository> repo, List<GatherRule> stored) BuildService(
+        GatherRule? existingTenantRule)
+    {
+        var repo = new Mock<IRuleRepository>(MockBehavior.Loose);
+        var stored = new List<GatherRule>();
+
+        repo.Setup(r => r.GetGatherRulesAsync("global")).ReturnsAsync(new List<GatherRule>());
+        repo.Setup(r => r.GetGatherRulesAsync(TenantId)).ReturnsAsync(
+            existingTenantRule == null ? new List<GatherRule>() : new List<GatherRule> { existingTenantRule });
+        repo.Setup(r => r.StoreGatherRuleAsync(It.IsAny<GatherRule>(), TenantId))
+            .Callback<GatherRule, string>((rule, _) => stored.Add(rule))
+            .ReturnsAsync(true);
+
+        return (new GatherRuleService(repo.Object, NullLogger<GatherRuleService>.Instance), repo, stored);
+    }
+
+    [Fact]
+    public async Task TogglePartial_merges_enabled_and_preserves_definition_fields()
+    {
+        var existing = ExistingCustomRule();
+        var (service, _, stored) = BuildService(existing);
+
+        // Exactly what the portal toggle sends: { enabled, isBuiltIn, isCommunity }.
+        var togglePayload = new GatherRule { RuleId = RuleId, Enabled = false, IsBuiltIn = false, IsCommunity = false };
+
+        var ok = await service.UpdateRuleAsync(TenantId, togglePayload);
+
+        Assert.True(ok);
+        var written = Assert.Single(stored);
+        Assert.False(written.Enabled);
+        Assert.Equal("Collect BIOS Config", written.Title);
+        Assert.Equal("HKLM\\SOFTWARE\\RealmJoin\\Custom\\BIOS", written.Target);
+        Assert.Equal("registry", written.CollectorType);
+        Assert.Equal("interval", written.Trigger);
+        Assert.Equal(60, written.IntervalSeconds);
+        Assert.Equal("Version", written.Parameters["valueName"]);
+        Assert.Equal("AccountSetup", written.ActiveFromPhase);
+        Assert.Equal("on_change", written.EmitMode);
+        Assert.Equal(existing.CreatedAt, written.CreatedAt);
+    }
+
+    [Fact]
+    public async Task TogglePartial_for_unknown_custom_rule_fails_without_storing()
+    {
+        var (service, repo, stored) = BuildService(existingTenantRule: null);
+
+        var togglePayload = new GatherRule { RuleId = RuleId, Enabled = false, IsBuiltIn = false, IsCommunity = false };
+
+        var ok = await service.UpdateRuleAsync(TenantId, togglePayload);
+
+        Assert.False(ok);
+        Assert.Empty(stored);
+        repo.Verify(r => r.StoreGatherRuleAsync(It.IsAny<GatherRule>(), It.IsAny<string>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task FullPayload_replaces_rule_but_preserves_original_CreatedAt()
+    {
+        var existing = ExistingCustomRule();
+        var (service, _, stored) = BuildService(existing);
+
+        var fullPayload = new GatherRule
+        {
+            RuleId = RuleId,
+            Title = "Collect BIOS Config v2",
+            CollectorType = "registry",
+            Target = "HKLM\\SOFTWARE\\RealmJoin\\Custom\\BIOS2",
+            Trigger = "interval",
+            IntervalSeconds = 120,
+            OutputEventType = "gather_bios_config",
+            Enabled = true,
+            // Edit flow sends createdAt from the client; a JSON-mode edit may omit it and
+            // default to UtcNow — either way the stored row must keep the original.
+            CreatedAt = DateTime.UtcNow,
+        };
+
+        var ok = await service.UpdateRuleAsync(TenantId, fullPayload);
+
+        Assert.True(ok);
+        var written = Assert.Single(stored);
+        Assert.Equal("Collect BIOS Config v2", written.Title);
+        Assert.Equal("HKLM\\SOFTWARE\\RealmJoin\\Custom\\BIOS2", written.Target);
+        Assert.Equal(120, written.IntervalSeconds);
+        Assert.False(written.IsBuiltIn);
+        Assert.False(written.IsCommunity);
+        Assert.Equal(existing.CreatedAt, written.CreatedAt);
+    }
+
+    [Fact]
+    public async Task BuiltInRule_toggle_still_goes_through_RuleState_path()
+    {
+        var repo = new Mock<IRuleRepository>(MockBehavior.Loose);
+        repo.Setup(r => r.GetGatherRulesAsync("global")).ReturnsAsync(new List<GatherRule>
+        {
+            new() { RuleId = RuleId, IsBuiltIn = true, Title = "Built-in", Enabled = true }
+        });
+        repo.Setup(r => r.StoreRuleStateAsync(TenantId, RuleId, It.IsAny<RuleState>())).ReturnsAsync(true);
+        var service = new GatherRuleService(repo.Object, NullLogger<GatherRuleService>.Instance);
+
+        var ok = await service.UpdateRuleAsync(TenantId, new GatherRule { RuleId = RuleId, Enabled = false });
+
+        Assert.True(ok);
+        repo.Verify(r => r.StoreRuleStateAsync(TenantId, RuleId, It.Is<RuleState>(s => !s.Enabled)), Times.Once);
+        repo.Verify(r => r.StoreGatherRuleAsync(It.IsAny<GatherRule>(), It.IsAny<string>()), Times.Never);
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/GetAllTenantConfigurationsFunctionTests.cs

@@ -129,4 +129,30 @@ public class GetAllTenantConfigurationsFunctionTests
     [Fact]
     public void DelegatedBareArrayView_Empty_Empty()
         => Assert.Empty(GetAllTenantConfigurationsFunction.DelegatedBareArrayView(new TenantConfiguration[0]));
+
+    [Fact]
+    public void MissingManagedIds_ReturnsOnlyIdsWithoutConfig_CaseInsensitive()
+    {
+        var configs = new List<TenantConfiguration>
+        {
+            new() { TenantId = TenantB.ToUpperInvariant() }, // case variant still counts as present
+        };
+
+        var missing = GetAllTenantConfigurationsFunction.MissingManagedIds(new[] { TenantB, TenantC }, configs);
+
+        var only = Assert.Single(missing);
+        Assert.Equal(TenantC, only);
+    }
+
+    [Fact]
+    public void MissingManagedIds_AllPresent_Empty()
+        => Assert.Empty(GetAllTenantConfigurationsFunction.MissingManagedIds(
+            new[] { TenantB },
+            new List<TenantConfiguration> { new() { TenantId = TenantB } }));
+
+    [Fact]
+    public void MissingConfigCacheKey_LowercasesId_SoCaseVariantsShareOneVerdict()
+        => Assert.Equal(
+            GetAllTenantConfigurationsFunction.MissingConfigCacheKey(TenantB),
+            GetAllTenantConfigurationsFunction.MissingConfigCacheKey(TenantB.ToUpperInvariant()));
 }

src/Backend/AutopilotMonitor.Functions.Tests/HardcodedUrlGuardTests.cs

@@ -0,0 +1,101 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Enforces the URL registry: every well-known own or Microsoft host must be
+/// referenced through <c>AutopilotMonitor.Shared.Constants</c>, never as a
+/// repeated string literal. The EU cutover missed two hardcoded copies of the
+/// blob host (LatestVersionsService, ValidateBootstrapCodeFunction) precisely
+/// because they did not go through the registry — this test makes that class
+/// of drift a build failure instead of a production surprise.
+///
+/// Scope: non-test C# source under src/. Comment lines are ignored (docs and
+/// examples may cite URLs); test projects are excluded because tests use
+/// literals deliberately as independent oracles.
+/// </summary>
+public class HardcodedUrlGuardTests
+{
+    private static readonly string[] EnforcedHosts =
+    {
+        "portal.autopilotmonitor.com",
+        "www.autopilotmonitor.com",
+        "docs.autopilotmonitor.com",
+        "download.autopilotmonitor.com",
+        "mcp.autopilotmonitor.com",
+        "autopilotmonitor-api-eu.azurewebsites.net",
+        "autopilotmonitor.blob.core.windows.net",
+        "autopilotmonitoreu.blob.core.windows.net",
+        "graph.microsoft.com",
+        "login.microsoftonline.com",
+    };
+
+    /// <summary>Files allowed to carry the literals — the registry itself.</summary>
+    private static readonly string[] RegistryFiles =
+    {
+        Path.Combine("src", "Shared", "AutopilotMonitor.Shared", "Constants.cs"),
+    };
+
+    [Fact]
+    public void WellKnownHosts_OnlyAppearInTheRegistry()
+    {
+        var repoRoot = FindRepoRoot();
+        var srcDir = Path.Combine(repoRoot, "src");
+        var violations = new List<string>();
+
+        foreach (var file in Directory.EnumerateFiles(srcDir, "*.cs", SearchOption.AllDirectories))
+        {
+            var relative = Path.GetRelativePath(repoRoot, file);
+            var normalized = relative.Replace('/', Path.DirectorySeparatorChar);
+
+            // bin/obj artifacts and generated files
+            if (normalized.Contains($"{Path.DirectorySeparatorChar}bin{Path.DirectorySeparatorChar}") ||
+                normalized.Contains($"{Path.DirectorySeparatorChar}obj{Path.DirectorySeparatorChar}"))
+                continue;
+
+            // Test projects: literals there are deliberate independent oracles.
+            if (normalized.Contains("Tests"))
+                continue;
+
+            if (RegistryFiles.Any(r => normalized.EndsWith(r, StringComparison.OrdinalIgnoreCase)))
+                continue;
+
+            var lines = File.ReadAllLines(file);
+            for (var i = 0; i < lines.Length; i++)
+            {
+                var trimmed = lines[i].TrimStart();
+                // Comment approximation: full-line // and /// comments plus the
+                // body lines of XML docs and block comments. A URL after code on
+                // the same line still counts — that is the case being guarded.
+                if (trimmed.StartsWith("//") || trimmed.StartsWith("*") || trimmed.StartsWith("/*"))
+                    continue;
+
+                foreach (var host in EnforcedHosts)
+                {
+                    if (trimmed.Contains(host, StringComparison.OrdinalIgnoreCase))
+                        violations.Add($"{relative}:{i + 1}: {host}");
+                }
+            }
+        }
+
+        Assert.True(violations.Count == 0,
+            "Hardcoded well-known host(s) found outside the URL registry " +
+            "(use AutopilotMonitor.Shared.Constants.*BaseUrl instead):\n  " +
+            string.Join("\n  ", violations));
+    }
+
+    private static string FindRepoRoot()
+    {
+        var dir = new DirectoryInfo(AppContext.BaseDirectory);
+        while (dir != null && !File.Exists(Path.Combine(dir.FullName, "AutopilotMonitor.sln")))
+        {
+            dir = dir.Parent;
+        }
+        Assert.NotNull(dir);
+        return dir!.FullName;
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/HealthCheckServiceAgentBinariesTests.cs

@@ -0,0 +1,107 @@
+using System.Collections.Generic;
+using System.Net;
+using System.Threading.Tasks;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Functions.Tests.GraphResolution;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging.Abstractions;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Service-level tests for the Agent Binaries HealthCheck card. The check probes the
+/// canonical download alias (download.autopilotmonitor.com) AND the legacy blob keepalive
+/// account: alias failure is unhealthy (new installs break), legacy failure is only a
+/// warning (existing customers break until they migrate to the alias).
+/// </summary>
+public class HealthCheckServiceAgentBinariesTests
+{
+    private const string AliasHost = "download.autopilotmonitor.com";
+    private const string LegacyHost = "autopilotmonitor.blob.core.windows.net";
+
+    [Fact]
+    public async Task Check_AllEndpointsAvailable_ReportsHealthyWithoutUrlDetails()
+    {
+        var handler = new StubHttpMessageHandler()
+            .When(AliasHost, HttpStatusCode.OK, "")
+            .When(LegacyHost, HttpStatusCode.OK, "");
+
+        var check = await BuildService(handler).CheckAgentBinariesAsync(includeEndpointUrls: false);
+
+        Assert.Equal("Agent Binaries", check.Name);
+        Assert.Equal("healthy", check.Status);
+        Assert.Contains("download alias", check.Message);
+        Assert.Null(check.Details);
+        // Both hosts must actually have been probed (ZIP + PS1 each).
+        Assert.Equal(2, handler.Requests.FindAll(u => u.Contains(AliasHost)).Count);
+        Assert.Equal(2, handler.Requests.FindAll(u => u.Contains(LegacyHost)).Count);
+    }
+
+    [Fact]
+    public async Task Check_WithEndpointUrls_SurfacesAliasAndLegacyUrlsInDetails()
+    {
+        var handler = new StubHttpMessageHandler()
+            .When(AliasHost, HttpStatusCode.OK, "")
+            .When(LegacyHost, HttpStatusCode.OK, "");
+
+        var check = await BuildService(handler).CheckAgentBinariesAsync(includeEndpointUrls: true);
+
+        Assert.NotNull(check.Details);
+        Assert.Equal("https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip", check.Details!["Agent ZIP"]);
+        Assert.Equal("https://download.autopilotmonitor.com/agent/Install-AutopilotMonitor.ps1", check.Details["Bootstrap script"]);
+        Assert.Equal("https://autopilotmonitor.blob.core.windows.net/agent", check.Details["Legacy blob (keepalive)"]);
+    }
+
+    [Fact]
+    public async Task Check_LegacyBlobMissing_ReportsWarningNamingTheLegacyEndpoint()
+    {
+        var handler = new StubHttpMessageHandler()
+            .When(AliasHost, HttpStatusCode.OK, "")
+            .When(LegacyHost, HttpStatusCode.NotFound, "");
+
+        var check = await BuildService(handler).CheckAgentBinariesAsync(includeEndpointUrls: false);
+
+        Assert.Equal("warning", check.Status);
+        Assert.Contains("legacy", check.Message, System.StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("404", check.Message);
+    }
+
+    [Fact]
+    public async Task Check_AliasMissing_ReportsUnhealthy()
+    {
+        var handler = new StubHttpMessageHandler()
+            .When(AliasHost, HttpStatusCode.NotFound, "")
+            .When(LegacyHost, HttpStatusCode.OK, "");
+
+        var check = await BuildService(handler).CheckAgentBinariesAsync(includeEndpointUrls: false);
+
+        Assert.Equal("unhealthy", check.Status);
+        Assert.Contains("download alias", check.Message);
+    }
+
+    [Fact]
+    public async Task Check_EndpointsUnreachable_ReportsUnhealthy()
+    {
+        // Un-scripted URLs make the stub throw — models a connection failure.
+        var check = await BuildService(new StubHttpMessageHandler()).CheckAgentBinariesAsync(includeEndpointUrls: false);
+
+        Assert.Equal("unhealthy", check.Status);
+        Assert.Contains("unreachable", check.Message);
+    }
+
+    private static HealthCheckService BuildService(StubHttpMessageHandler handler)
+    {
+        var config = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>())
+            .Build();
+
+        return new HealthCheckService(
+            NullLogger<HealthCheckService>.Instance,
+            adminConfigService: null!,
+            httpClientFactory: new StubHttpClientFactory(handler),
+            metricsReader: null!,
+            poisonQueueProbe: null!,
+            configuration: config);
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/HealthCheckServiceMcpServerTests.cs

@@ -53,6 +53,29 @@ public class HealthCheckServiceMcpServerTests
         Assert.DoesNotContain("http", check.Message, System.StringComparison.OrdinalIgnoreCase);
     }
 
+    [Fact]
+    public async Task Check_WithEndpointUrl_SurfacesServerUrlAlongsideVersion()
+    {
+        var svc = BuildService(HttpStatusCode.OK, "{\"status\":\"healthy\",\"version\":\"1.4.0\"}");
+
+        var check = await svc.CheckMcpServerAsync(includeEndpointUrl: true);
+
+        // The Version detail must merge into — not replace — the Server URL detail.
+        Assert.Equal("https://mcp.example.test", check.Details!["Server URL"]);
+        Assert.Equal("1.4.0", check.Details["Version"]);
+    }
+
+    [Fact]
+    public async Task Check_WithEndpointUrl_SurfacesServerUrlEvenWhenUnhealthy()
+    {
+        var svc = BuildService(HttpStatusCode.ServiceUnavailable, "");
+
+        var check = await svc.CheckMcpServerAsync(includeEndpointUrl: true);
+
+        Assert.Equal("unhealthy", check.Status);
+        Assert.Equal("https://mcp.example.test", check.Details!["Server URL"]);
+    }
+
     [Fact]
     public async Task Check_TimeoutOrConnectionFailure_ReportsWarningForColdStart()
     {

src/Backend/AutopilotMonitor.Functions.Tests/LogSanitizerTests.cs

@@ -0,0 +1,72 @@
+using AutopilotMonitor.Functions.Helpers;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+public class LogSanitizerTests
+{
+    [Fact]
+    public void Clean_WithCrlf_StripsNewlines()
+    {
+        // The core log-forging vector: a value that injects a fake log line.
+        var forged = "/api/sessions\r\n[Auth Middleware] FAKE: admin granted";
+        var cleaned = LogSanitizer.Clean(forged);
+        Assert.Equal("/api/sessions[Auth Middleware] FAKE: admin granted", cleaned);
+        Assert.DoesNotContain('\r', cleaned!);
+        Assert.DoesNotContain('\n', cleaned!);
+    }
+
+    [Fact]
+    public void Clean_WithBareLineFeedOrCarriageReturn_StripsBoth()
+    {
+        Assert.Equal("ab", LogSanitizer.Clean("a\nb"));
+        Assert.Equal("ab", LogSanitizer.Clean("a\rb"));
+    }
+
+    [Fact]
+    public void Clean_WithOtherControlChars_StripsThem()
+    {
+        // Tab (9), NUL (0) and ESC (27, terminal escape) are all removed. Built
+        // from char codes so the source file carries no literal control bytes.
+        var input = $"a{(char)9}b{(char)0}c{(char)27}de";
+        Assert.Equal("abcde", LogSanitizer.Clean(input));
+    }
+
+    [Fact]
+    public void Clean_WithUnicodeLineSeparators_StripsThem()
+    {
+        // U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR are Unicode categories
+        // Zl/Zp, not Cc — so a \p{Cc}-only pass would let them through, and a log viewer
+        // or JavaScript-side reader would still break the line on them. Built from char
+        // codes so the source file carries no literal separator bytes.
+        var forged = $"/api/sessions{(char)0x2028}[Auth Middleware] FAKE: admin granted";
+        var cleaned = LogSanitizer.Clean(forged);
+
+        Assert.Equal("/api/sessions[Auth Middleware] FAKE: admin granted", cleaned);
+        Assert.DoesNotContain((char)0x2028, cleaned!);
+        Assert.Equal("ab", LogSanitizer.Clean($"a{(char)0x2029}b"));
+    }
+
+    [Theory]
+    [InlineData("/api/sessions/abc-123/events")]
+    [InlineData("user@contoso.com")]
+    [InlineData("11111111-2222-3333-4444-555555555555")]
+    [InlineData("GET")]
+    public void Clean_WithLegitimateValue_ReturnsUnchanged(string value)
+    {
+        // Real paths, UPNs, GUIDs and methods never contain control chars, so
+        // tracing fidelity is fully preserved.
+        Assert.Equal(value, LogSanitizer.Clean(value));
+    }
+
+    [Fact]
+    public void Clean_WithNull_ReturnsNull()
+    {
+        Assert.Null(LogSanitizer.Clean(null));
+    }
+
+    [Fact]
+    public void Clean_WithEmpty_ReturnsEmpty()
+    {
+        Assert.Equal("", LogSanitizer.Clean(""));
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/MaintenanceServiceExcessiveEventAutoActionTests.cs

@@ -1,4 +1,5 @@
 using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.Models;
 
 namespace AutopilotMonitor.Functions.Tests;
 
@@ -87,4 +88,61 @@ public class MaintenanceServiceExcessiveEventAutoActionTests
         // — better to no-op than block/kill on an unintended config.
         Assert.Null(MaintenanceService.DecideAutoAction(eventCount: 5000, autoMode: mode, autoThreshold: 2500));
     }
+
+    // ── Status eligibility ────────────────────────────────────────────────────
+    // A device may only be blocked over a session that can still upload. Without this gate
+    // a session that finished days ago with a high EventCount got its device blocked on the
+    // next sweep, long after it stopped sending.
+
+    [Fact]
+    public void IsAutoActionEligible_InProgress_IsEligible()
+    {
+        Assert.True(MaintenanceService.IsAutoActionEligible(SessionStatus.InProgress));
+    }
+
+    [Theory]
+    [InlineData(SessionStatus.Succeeded)]
+    [InlineData(SessionStatus.Failed)]
+    [InlineData(SessionStatus.Incomplete)]
+    [InlineData(SessionStatus.Stalled)]
+    [InlineData(SessionStatus.AwaitingUser)]
+    [InlineData(SessionStatus.Pending)]
+    [InlineData(SessionStatus.Unknown)]
+    public void IsAutoActionEligible_EverythingElse_IsRejected(SessionStatus status)
+    {
+        // Matches the time-window watchdog's `Status eq 'InProgress'` filter, so neither
+        // detector can block a device over a session that no longer sends. Stalled and
+        // AwaitingUser can heal back to InProgress — then the next sweep acts.
+        Assert.False(MaintenanceService.IsAutoActionEligible(status));
+    }
+
+    // ── Status parsing feeding that gate ──────────────────────────────────────
+    // The runaway query projects a subset of columns. SessionStatus.InProgress is ordinal 0,
+    // so an unparsed Status would leave every row looking in-progress and the gate above
+    // silently always-true — these pin the fail-closed mapping.
+
+    [Theory]
+    [InlineData("InProgress", SessionStatus.InProgress)]
+    [InlineData("inprogress", SessionStatus.InProgress)]
+    [InlineData("Succeeded", SessionStatus.Succeeded)]
+    [InlineData("AwaitingUser", SessionStatus.AwaitingUser)]
+    public void ParseStatusForAutoAction_KnownNames_RoundTrip(string stored, SessionStatus expected)
+    {
+        Assert.Equal(expected, TableStorageService.ParseStatusForAutoAction(stored));
+    }
+
+    [Theory]
+    [InlineData(null)]        // column absent from the projection or the row
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData("Enrolling")] // status name that never existed
+    [InlineData("0")]         // Enum.TryParse would map this onto InProgress and open the gate
+    [InlineData("3")]
+    [InlineData("-1")]
+    [InlineData("InProgress,Failed")] // flags-style combination is not a real status
+    public void ParseStatusForAutoAction_UnusableInput_IsUnknown(string? stored)
+    {
+        Assert.Equal(SessionStatus.Unknown, TableStorageService.ParseStatusForAutoAction(stored));
+        Assert.False(MaintenanceService.IsAutoActionEligible(TableStorageService.ParseStatusForAutoAction(stored)));
+    }
 }

src/Backend/AutopilotMonitor.Functions.Tests/MaintenanceServiceSignalRQuotaTests.cs

@@ -3,7 +3,7 @@ using AutopilotMonitor.Functions.Services;
 namespace AutopilotMonitor.Functions.Tests;
 
 /// <summary>
-/// Tier-boundary + percent-math tests for the SignalR free-tier quota watcher.
+/// Tier-boundary + percent-math tests for the SignalR quota watcher.
 /// Mirrors the cert-expiry tests' approach: pure-function coverage of the
 /// boundary risks (off-by-one, floor vs ceil, zero-division). Full-service
 /// smoke tests would require constructing 16 dependencies; the percent +

src/Backend/AutopilotMonitor.Functions.Tests/OccurredUtcBackfillServiceTests.cs

@@ -0,0 +1,61 @@
+using Azure.Data.Tables;
+using AutopilotMonitor.Functions.Helpers;
+using AutopilotMonitor.Functions.Services;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Per-row backfill decision (pure function): rows that already carry OccurredUtc are
+/// skipped (idempotent re-runs), decodable RowKeys yield the deterministic decoded value,
+/// anything else is reported undecodable — never guessed.
+/// </summary>
+public class OccurredUtcBackfillServiceTests
+{
+    private static readonly DateTime Ts = new(2026, 6, 20, 9, 30, 0, DateTimeKind.Utc);
+
+    [Fact]
+    public void Audit_row_with_existing_column_is_skipped()
+    {
+        var e = new TableEntity("t", TableStorageService.BuildAuditLogRowKey(Ts, Guid.NewGuid()))
+        {
+            [BusinessTimestamp.OccurredUtcColumn] = new DateTimeOffset(Ts),
+        };
+        Assert.Equal(OccurredUtcBackfillService.RowDecision.AlreadySet,
+            OccurredUtcBackfillService.DecideRow(OccurredUtcBackfillService.TableAudit, e, out _));
+    }
+
+    [Fact]
+    public void Audit_time_encoded_row_yields_decoded_write()
+    {
+        var e = new TableEntity("t", TableStorageService.BuildAuditLogRowKey(Ts, Guid.NewGuid()));
+        var decision = OccurredUtcBackfillService.DecideRow(OccurredUtcBackfillService.TableAudit, e, out var occurred);
+        Assert.Equal(OccurredUtcBackfillService.RowDecision.Write, decision);
+        Assert.Equal(Ts, occurred);
+    }
+
+    [Fact]
+    public void Audit_legacy_guid_row_is_undecodable_not_guessed()
+    {
+        var e = new TableEntity("t", Guid.NewGuid().ToString("N"));
+        Assert.Equal(OccurredUtcBackfillService.RowDecision.Undecodable,
+            OccurredUtcBackfillService.DecideRow(OccurredUtcBackfillService.TableAudit, e, out _));
+    }
+
+    [Fact]
+    public void Ops_row_yields_decoded_write_and_existing_column_is_skipped()
+    {
+        var rowKey = $"{DateTime.MaxValue.Ticks - Ts.Ticks:D19}";
+
+        var bare = new TableEntity("Security", rowKey);
+        var decision = OccurredUtcBackfillService.DecideRow(OccurredUtcBackfillService.TableOps, bare, out var occurred);
+        Assert.Equal(OccurredUtcBackfillService.RowDecision.Write, decision);
+        Assert.Equal(Ts, occurred);
+
+        var backfilled = new TableEntity("Security", rowKey)
+        {
+            [BusinessTimestamp.OccurredUtcColumn] = new DateTimeOffset(Ts),
+        };
+        Assert.Equal(OccurredUtcBackfillService.RowDecision.AlreadySet,
+            OccurredUtcBackfillService.DecideRow(OccurredUtcBackfillService.TableOps, backfilled, out _));
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/OffboardingSessionEnumeratorTests.cs

@@ -117,7 +117,6 @@ public class OffboardingSessionEnumeratorTests
         public Task<List<SessionSummary>> GetLegacyTimeoutFailedSessionsAsync(string tenantId, int maxResults) => throw new NotImplementedException();
         public Task<List<SessionSummary>> GetSessionsLeanAsync(string tenantId) => throw new NotImplementedException();
         public Task<List<SessionSummary>> GetAgentSilentSessionsAsync(string tenantId, DateTime silenceCutoff, DateTime hardCutoff) => throw new NotImplementedException();
-        public Task<List<SessionSummary>> GetExcessiveDataSendersAsync(string tenantId, DateTime windowCutoff, int maxSessionWindowHours) => throw new NotImplementedException();
         public Task<List<string>> GetAllTenantIdsAsync() => throw new NotImplementedException();
         public Task<int> DeleteSessionEventsAsync(string tenantId, string sessionId) => throw new NotImplementedException();
         public Task<int> DeleteSessionRuleResultsAsync(string tenantId, string sessionId) => throw new NotImplementedException();

src/Backend/AutopilotMonitor.Functions.Tests/PolicyEnforcementMiddlewareTests.cs

@@ -868,4 +868,149 @@ public class PolicyEnforcementMiddlewareTests
         Assert.False(result.Allowed);
         Assert.Equal(403, result.StatusCode);
     }
+
+    // ── Empty-UPN contract for device / anonymous routes ───────────────────────────
+    //
+    // UserRateLimitMiddleware buckets on RequestContext.UserPrincipalName and skips only when it is
+    // EMPTY. Publishing the "anonymous" placeholder there collapsed every agent of every tenant into a
+    // single shared user_ratelimit_anonymous bucket, which 429'd agent telemetry fleet-wide once the
+    // per-user limit was reached. These tests pin the contract: no JWT ⇒ empty UPN.
+
+    [Theory]
+    [InlineData("POST", "/api/agent/telemetry")]
+    [InlineData("GET", "/api/agent/config")]
+    [InlineData("POST", "/api/agent/register-session")]
+    [InlineData("POST", "/api/agent/upload-url")]
+    [InlineData("POST", "/api/agent/error")]
+    [InlineData("POST", "/api/bootstrap/register-session")]
+    [InlineData("GET", "/api/bootstrap/config")]
+    [InlineData("POST", "/api/bootstrap/error")]
+    public async Task DeviceRoute_WithoutJwt_PublishesEmptyUpn(string method, string path)
+    {
+        var h = BuildHarness();
+
+        var result = await h.Middleware.DecideAsync(method, path, null, principal: null);
+
+        Assert.True(result.Allowed);
+        // The rate-limit bucket key: empty means "no user bucket applies to this call".
+        Assert.Equal(string.Empty, result.Context!.UserPrincipalName);
+        // The placeholder still renders in log lines — it just never reaches the RequestContext.
+        Assert.Equal("anonymous", result.UserIdentifier);
+    }
+
+    [Theory]
+    [InlineData("GET", "/api/health")]
+    [InlineData("GET", "/api/stats/platform")]
+    [InlineData("POST", "/api/agent/distress")]
+    [InlineData("GET", "/api/diagnostics/download")]
+    public async Task AnonymousRoute_WithoutJwt_PublishesEmptyUpn(string method, string path)
+    {
+        var h = BuildHarness();
+
+        var result = await h.Middleware.DecideAsync(method, path, null, principal: null);
+
+        Assert.True(result.Allowed);
+        Assert.Equal(string.Empty, result.Context!.UserPrincipalName);
+    }
+
+    [Fact]
+    public async Task AuthenticatedRoute_StillPublishesTheRealUpn()
+    {
+        // Guard the other direction: the fix must not blank the UPN for genuine JWT callers, or
+        // per-user rate limiting and presence tracking would silently stop working.
+        const string upn = "admin@contoso.com";
+        var h = BuildHarness();
+        h.AsTenantAdmin(TenantA, upn);
+
+        var result = await h.Middleware.DecideAsync("GET", "/api/notifications", null, AuthedPrincipal(TenantA, upn));
+
+        Assert.True(result.Allowed);
+        Assert.Equal(upn, result.Context!.UserPrincipalName);
+        Assert.Equal(upn, result.Context!.CallerId);
+    }
+
+    // ── CallerId: throttle identity survives tokens that carry no UPN ──────────────
+    //
+    // AuthenticationMiddleware validates issuer/audience/lifetime/signature but requires NO upn and no
+    // scp, so an app-only (client-credentials) token authenticates and reaches every AuthenticatedUser
+    // route (feedback, realtime/negotiate, progress/*, health/detailed, …). UserRateLimitMiddleware
+    // skips on an EMPTY throttle identity — so if CallerId fell back to the (absent) UPN, those tokens
+    // would bypass rate limiting entirely. These tests pin the fallback chain.
+
+    /// <summary>Principal with a tid but NO upn/preferred_username — shaped like an app-only token.</summary>
+    private static ClaimsPrincipal AppOnlyPrincipal(string tenantId, params (string Type, string Value)[] claims)
+    {
+        var all = new List<Claim> { new("tid", tenantId) };
+        all.AddRange(claims.Select(c => new Claim(c.Type, c.Value)));
+        return new ClaimsPrincipal(new ClaimsIdentity(all, "TestAuth"));
+    }
+
+    [Theory]
+    [InlineData("oid", "aaaaaaaa-0000-0000-0000-000000000001")]
+    [InlineData("http://schemas.microsoft.com/identity/claims/objectidentifier", "aaaaaaaa-0000-0000-0000-000000000002")]
+    [InlineData("sub", "subject-abc")]
+    [InlineData("appid", "bbbbbbbb-0000-0000-0000-000000000003")]
+    [InlineData("azp", "cccccccc-0000-0000-0000-000000000004")]
+    public async Task AuthenticatedUserRoute_TokenWithoutUpn_StillGetsAThrottleIdentity(string claimType, string claimValue)
+    {
+        var h = BuildHarness();
+
+        // /api/feedback/status is AuthenticatedUser — admits ANY valid principal, role unresolved.
+        var result = await h.Middleware.DecideAsync(
+            "GET", "/api/feedback/status", null, AppOnlyPrincipal(TenantA, (claimType, claimValue)));
+
+        Assert.True(result.Allowed);
+        // No UPN to report — audit/presence correctly see nothing...
+        Assert.Equal(string.Empty, result.Context!.UserPrincipalName);
+        // ...but the throttle still has something stable to bucket on.
+        Assert.Equal(claimValue, result.Context!.CallerId);
+    }
+
+    [Fact]
+    public async Task AuthenticatedUserRoute_TokenWithoutUpn_PrefersOidOverSubAndAppId()
+    {
+        var h = BuildHarness();
+        var principal = AppOnlyPrincipal(TenantA,
+            ("appid", "cccccccc-0000-0000-0000-000000000009"),
+            ("sub", "subject-xyz"),
+            ("oid", "aaaaaaaa-0000-0000-0000-00000000000a"));
+
+        var result = await h.Middleware.DecideAsync("GET", "/api/feedback/status", null, principal);
+
+        Assert.True(result.Allowed);
+        Assert.Equal("aaaaaaaa-0000-0000-0000-00000000000a", result.Context!.CallerId);
+    }
+
+    [Fact]
+    public async Task AuthenticatedUserRoute_TokenWithNoIdentifyingClaim_FailsClosedToASharedBucket()
+    {
+        // Pathological (every real Entra token has a sub): must NOT resolve to empty, because empty
+        // means "skip the limiter". A shared bucket is the safe answer.
+        var h = BuildHarness();
+
+        var result = await h.Middleware.DecideAsync(
+            "GET", "/api/feedback/status", null, AppOnlyPrincipal(TenantA));
+
+        Assert.True(result.Allowed);
+        Assert.NotEqual(string.Empty, result.Context!.CallerId);
+        Assert.Equal(PolicyEnforcementMiddleware.UnidentifiedCallerBucket, result.Context!.CallerId);
+        // Never reuse the log placeholder as a bucket key — that was the original fleet-wide collapse.
+        Assert.NotEqual("anonymous", result.Context!.CallerId);
+    }
+
+    [Theory]
+    [InlineData("POST", "/api/agent/telemetry")]
+    [InlineData("GET", "/api/health")]
+    [InlineData("GET", "/api/stats/platform")]
+    public async Task UnauthenticatedRoute_HasEmptyCallerId(string method, string path)
+    {
+        // Empty CallerId is the ONLY signal that skips the user limiter — it must mean
+        // "no JWT at all", never "authenticated but unnamed".
+        var h = BuildHarness();
+
+        var result = await h.Middleware.DecideAsync(method, path, null, principal: null);
+
+        Assert.True(result.Allowed);
+        Assert.Equal(string.Empty, result.Context!.CallerId);
+    }
 }

src/Backend/AutopilotMonitor.Functions.Tests/RevokeEnforcementTests.cs

@@ -0,0 +1,269 @@
+using AutopilotMonitor.Functions.Functions.Admin;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared;
+using AutopilotMonitor.Shared.DataAccess;
+using Microsoft.Extensions.Caching.Memory;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Covers the SignalR revoke-enforcement cores of <see cref="DelegatedAdminManagementFunction"/> and
+/// <see cref="TenantGroupManagementFunction"/> (extracted seams — the HTTP entry points are intentionally
+/// not exercised, same rationale as <see cref="GetAllBlockedDevicesFunctionTests"/>). Locks in three
+/// security invariants: (1) a miss (no assignment row) neither audits nor disconnects — a typo must not
+/// write false customer-visible "access removed" rows while the real grant stays live; (2) a real
+/// revoke/disable/unassign/group-delete always cuts the affected UPN's live streams (group authorization
+/// is join-time only); (3) grant validation is fail-closed (GUID tenantId, recognized roles only).
+/// </summary>
+public class RevokeEnforcementTests
+{
+    private const string Upn = "MSP-Admin@Partner.Example";
+    private const string UpnLower = "msp-admin@partner.example";
+    private const string TenantA = "11111111-1111-1111-1111-111111111111";
+    private const string TenantB = "22222222-2222-2222-2222-222222222222";
+    private const string GroupId = "tpl-aaaaaaaa";
+
+    private static DelegatedAdminService BuildService(Mock<IAdminRepository> repo) =>
+        new(
+            repo.Object,
+            new StubTenantEntitlementService(AutopilotMonitor.Functions.Security.TenantEdition.Enterprise),
+            new MemoryCache(new MemoryCacheOptions()),
+            NullLogger<DelegatedAdminService>.Instance);
+
+    private static Mock<IMaintenanceRepository> BuildAuditRepo()
+    {
+        var audit = new Mock<IMaintenanceRepository>();
+        audit.Setup(a => a.LogAuditEntryAsync(
+                It.IsAny<string>(), It.IsAny<string>(), It.IsAny<string>(),
+                It.IsAny<string>(), It.IsAny<string>(), It.IsAny<Dictionary<string, string>?>()))
+            .ReturnsAsync(true);
+        return audit;
+    }
+
+    private static void VerifyNoAudit(Mock<IMaintenanceRepository> audit) =>
+        audit.Verify(a => a.LogAuditEntryAsync(
+            It.IsAny<string>(), It.IsAny<string>(), It.IsAny<string>(),
+            It.IsAny<string>(), It.IsAny<string>(), It.IsAny<Dictionary<string, string>?>()), Times.Never);
+
+    private static (DelegatedAdminManagementFunction Fn, Mock<IAdminRepository> Repo,
+        Mock<IMaintenanceRepository> Audit, FakeSignalRNotificationService SignalR) BuildAdminFn()
+    {
+        var repo = new Mock<IAdminRepository>();
+        var audit = BuildAuditRepo();
+        var signalR = new FakeSignalRNotificationService();
+        var fn = new DelegatedAdminManagementFunction(
+            NullLogger<DelegatedAdminManagementFunction>.Instance, BuildService(repo), audit.Object, signalR);
+        return (fn, repo, audit, signalR);
+    }
+
+    private static (TenantGroupManagementFunction Fn, Mock<IAdminRepository> Repo,
+        Mock<IMaintenanceRepository> Audit, FakeSignalRNotificationService SignalR) BuildGroupFn()
+    {
+        var repo = new Mock<IAdminRepository>();
+        // Loose-mock defaults return a null Task — every repo read the flows touch needs a concrete setup.
+        repo.Setup(r => r.GetTenantGroupAsync(It.IsAny<string>())).ReturnsAsync((TenantGroup?)null);
+        repo.Setup(r => r.GetGroupAssignmentsForUpnAsync(It.IsAny<string>()))
+            .ReturnsAsync(new List<TenantGroupAssignment>());
+        repo.Setup(r => r.GetGroupAssigneesAsync(It.IsAny<string>()))
+            .ReturnsAsync(new List<TenantGroupAssignment>());
+        var audit = BuildAuditRepo();
+        var signalR = new FakeSignalRNotificationService();
+        var fn = new TenantGroupManagementFunction(
+            NullLogger<TenantGroupManagementFunction>.Instance, BuildService(repo), audit.Object, signalR);
+        return (fn, repo, audit, signalR);
+    }
+
+    // --- Delegated grant validation (fail-closed) ---
+
+    [Fact]
+    public void ValidateGrant_NullBody_Rejected()
+        => Assert.Equal("upn and tenantId are required",
+            DelegatedAdminManagementFunction.ValidateGrantRequest(null, out _));
+
+    [Theory]
+    [InlineData("", TenantA)]
+    [InlineData("   ", TenantA)]
+    [InlineData(Upn, "")]
+    public void ValidateGrant_MissingFields_Rejected(string upn, string tenantId)
+        => Assert.Equal("upn and tenantId are required",
+            DelegatedAdminManagementFunction.ValidateGrantRequest(
+                new GrantDelegatedAdminRequest { Upn = upn, TenantId = tenantId }, out _));
+
+    [Theory]
+    [InlineData("contoso.com")]
+    [InlineData("not-a-guid")]
+    [InlineData("11111111-1111-1111-1111")]
+    public void ValidateGrant_NonGuidTenantId_Rejected(string tenantId)
+        => Assert.Equal("a valid tenantId (GUID) is required",
+            DelegatedAdminManagementFunction.ValidateGrantRequest(
+                new GrantDelegatedAdminRequest { Upn = Upn, TenantId = tenantId }, out _));
+
+    [Fact]
+    public void ValidateGrant_UnknownRole_Rejected()
+    {
+        var error = DelegatedAdminManagementFunction.ValidateGrantRequest(
+            new GrantDelegatedAdminRequest { Upn = Upn, TenantId = TenantA, Role = "GlobalAdmin" }, out _);
+        Assert.NotNull(error);
+        Assert.Contains(Constants.DelegatedRoles.DelegatedReader, error);
+    }
+
+    [Fact]
+    public void ValidateGrant_EmptyRole_DefaultsToLeastPrivilegedReader()
+    {
+        Assert.Null(DelegatedAdminManagementFunction.ValidateGrantRequest(
+            new GrantDelegatedAdminRequest { Upn = Upn, TenantId = TenantA }, out var role));
+        Assert.Equal(Constants.DelegatedRoles.DelegatedReader, role);
+    }
+
+    [Fact]
+    public void ValidateGrant_ExplicitDelegatedAdmin_Accepted()
+    {
+        Assert.Null(DelegatedAdminManagementFunction.ValidateGrantRequest(
+            new GrantDelegatedAdminRequest { Upn = Upn, TenantId = TenantA, Role = Constants.DelegatedRoles.DelegatedAdmin },
+            out var role));
+        Assert.Equal(Constants.DelegatedRoles.DelegatedAdmin, role);
+    }
+
+    // --- Revoke: 404-on-missing-row vs. audit + disconnect ---
+
+    [Fact]
+    public async Task RevokeCore_MissingRow_NoAuditNoDisconnect()
+    {
+        var (fn, repo, audit, signalR) = BuildAdminFn();
+        repo.Setup(r => r.RemoveDelegatedAdminAsync(UpnLower, TenantA)).ReturnsAsync(false);
+
+        var removed = await fn.RevokeCoreAsync(Upn, TenantA, "ga@vendor.example");
+
+        Assert.False(removed);
+        VerifyNoAudit(audit);
+        Assert.Empty(signalR.DisconnectedUsers);
+    }
+
+    [Fact]
+    public async Task RevokeCore_RemovedRow_AuditsAndDisconnectsLowercasedUpn()
+    {
+        var (fn, repo, audit, signalR) = BuildAdminFn();
+        repo.Setup(r => r.RemoveDelegatedAdminAsync(UpnLower, TenantA)).ReturnsAsync(true);
+
+        var removed = await fn.RevokeCoreAsync(Upn, TenantA, "ga@vendor.example");
+
+        Assert.True(removed);
+        // SignalR user ids are lowercased UPNs — a mixed-case route param must still hit the user's connections.
+        Assert.Equal(new[] { UpnLower }, signalR.DisconnectedUsers);
+        audit.Verify(a => a.LogAuditEntryAsync(
+            TenantA, "DELETE", "DelegatedAdmin", UpnLower, "ga@vendor.example", null), Times.Once);
+    }
+
+    // --- Disable is a revocation too; enable never disconnects ---
+
+    [Fact]
+    public async Task SetEnabledCore_MissingRow_NoAuditNoDisconnect()
+    {
+        var (fn, repo, audit, signalR) = BuildAdminFn();
+        repo.Setup(r => r.SetDelegatedAdminEnabledAsync(UpnLower, TenantA, false)).ReturnsAsync(false);
+
+        var ok = await fn.SetEnabledCoreAsync(Upn, TenantA, isEnabled: false, "ga@vendor.example");
+
+        Assert.False(ok);
+        VerifyNoAudit(audit);
+        Assert.Empty(signalR.DisconnectedUsers);
+    }
+
+    [Fact]
+    public async Task SetEnabledCore_Disable_Disconnects()
+    {
+        var (fn, repo, _, signalR) = BuildAdminFn();
+        repo.Setup(r => r.SetDelegatedAdminEnabledAsync(UpnLower, TenantA, false)).ReturnsAsync(true);
+
+        var ok = await fn.SetEnabledCoreAsync(Upn, TenantA, isEnabled: false, "ga@vendor.example");
+
+        Assert.True(ok);
+        Assert.Equal(new[] { UpnLower }, signalR.DisconnectedUsers);
+    }
+
+    [Fact]
+    public async Task SetEnabledCore_Enable_DoesNotDisconnect()
+    {
+        var (fn, repo, _, signalR) = BuildAdminFn();
+        repo.Setup(r => r.SetDelegatedAdminEnabledAsync(UpnLower, TenantA, true)).ReturnsAsync(true);
+
+        var ok = await fn.SetEnabledCoreAsync(Upn, TenantA, isEnabled: true, "ga@vendor.example");
+
+        Assert.True(ok);
+        Assert.Empty(signalR.DisconnectedUsers);
+    }
+
+    // --- Group unassign: 404-on-not-assigned vs. disconnect + per-tenant audit ---
+
+    [Fact]
+    public async Task UnassignCore_NotAssigned_NoAuditNoDisconnect()
+    {
+        var (fn, _, audit, signalR) = BuildGroupFn(); // default: no assignments for the UPN
+
+        var unassigned = await fn.UnassignCoreAsync(GroupId, Upn, "ga@vendor.example");
+
+        Assert.False(unassigned);
+        VerifyNoAudit(audit);
+        Assert.Empty(signalR.DisconnectedUsers);
+    }
+
+    [Fact]
+    public async Task UnassignCore_Assigned_DisconnectsAndAuditsPerGroupTenant()
+    {
+        var (fn, repo, audit, signalR) = BuildGroupFn();
+        repo.Setup(r => r.GetTenantGroupAsync(GroupId)).ReturnsAsync(new TenantGroup
+        {
+            GroupId = GroupId,
+            Name = "MSP Customers",
+            TenantIds = new List<string> { TenantA, TenantB },
+            AssigneeCount = 1,
+        });
+        repo.Setup(r => r.GetGroupAssignmentsForUpnAsync(UpnLower))
+            .ReturnsAsync(new List<TenantGroupAssignment> { new() { Upn = UpnLower, GroupId = GroupId } });
+        repo.Setup(r => r.UnassignGroupAsync(UpnLower, GroupId)).ReturnsAsync(true);
+
+        var unassigned = await fn.UnassignCoreAsync(GroupId, Upn, "ga@vendor.example");
+
+        Assert.True(unassigned);
+        Assert.Equal(new[] { UpnLower }, signalR.DisconnectedUsers);
+        // Lost access is audited under EACH of the group's tenants (customer-visible trail).
+        audit.Verify(a => a.LogAuditEntryAsync(
+            TenantA, "DELETE", "DelegatedGroupAccess", UpnLower, "ga@vendor.example",
+            It.IsAny<Dictionary<string, string>?>()), Times.Once);
+        audit.Verify(a => a.LogAuditEntryAsync(
+            TenantB, "DELETE", "DelegatedGroupAccess", UpnLower, "ga@vendor.example",
+            It.IsAny<Dictionary<string, string>?>()), Times.Once);
+    }
+
+    // --- Group delete: every (former) assignee's streams are cut ---
+
+    [Fact]
+    public async Task DeleteGroupCore_DisconnectsEveryAssignee_AndAuditsPerTenant()
+    {
+        var (fn, repo, audit, signalR) = BuildGroupFn();
+        var assignees = new List<TenantGroupAssignment>
+        {
+            new() { Upn = "one@partner.example", GroupId = GroupId },
+            new() { Upn = "two@partner.example", GroupId = GroupId },
+        };
+        repo.Setup(r => r.GetTenantGroupAsync(GroupId)).ReturnsAsync(new TenantGroup
+        {
+            GroupId = GroupId,
+            Name = "MSP Customers",
+            TenantIds = new List<string> { TenantA },
+            AssigneeCount = assignees.Count,
+        });
+        repo.Setup(r => r.GetGroupAssigneesAsync(GroupId)).ReturnsAsync(assignees);
+        repo.Setup(r => r.DeleteTenantGroupAsync(GroupId)).ReturnsAsync(true);
+
+        await fn.DeleteGroupCoreAsync(GroupId, "ga@vendor.example");
+
+        Assert.Equal(new[] { "one@partner.example", "two@partner.example" }, signalR.DisconnectedUsers);
+        audit.Verify(a => a.LogAuditEntryAsync(
+            TenantA, "DELETE", "DelegatedGroupAccess", "*", "ga@vendor.example",
+            It.IsAny<Dictionary<string, string>?>()), Times.Once);
+    }
+}

src/Backend/AutopilotMonitor.Functions.Tests/SessionDeletionMaintenanceFunctionTests.cs

@@ -78,15 +78,16 @@ public class SessionDeletionMaintenanceFunctionTests
     [Fact]
     public async Task RunCore_emits_LongRunning_when_body_runs_past_warning_threshold()
     {
-        // Set watchdog thresholds to sub-second; make the fanout sleep long enough to trip warning
-        // but not severe.
-        var harness = new Harness(watchdogWarn: TimeSpan.FromMilliseconds(50), watchdogSevere: TimeSpan.FromMilliseconds(500));
+        // Deterministic (no wall-clock race): the fanout body blocks until the WARN watchdog has
+        // actually recorded its OpsEvent, then returns. Severe sits minutes out, so it can never
+        // fire in the moment between warn firing and the body completing (which cancels it).
+        var harness = new Harness(watchdogWarn: TimeSpan.FromMilliseconds(20), watchdogSevere: TimeSpan.FromMinutes(10));
         harness.SetKillSwitch(false);
         harness.Fanout.Setup(f => f.RunAsync(It.IsAny<SessionRetentionFanoutService.FanoutResult>(), It.IsAny<DateTime>(), It.IsAny<CancellationToken>()))
             .Returns(async (SessionRetentionFanoutService.FanoutResult r, DateTime _, CancellationToken ct) =>
             {
                 r.TenantsProcessed = 1;
-                await Task.Delay(150, ct);
+                await harness.WaitForEventAsync("SessionDeletionMaintenanceLongRunning");
             });
 
         await harness.Sut.RunCoreAsync("Test", CancellationToken.None);
@@ -102,14 +103,17 @@ public class SessionDeletionMaintenanceFunctionTests
         // assigned only AFTER the fanout returned, so every LongRunning warning showed zeros.
         // The fanout now mutates the caller-supplied result incrementally; the watchdog snapshot
         // must reflect that progress mid-run.
-        var harness = new Harness(watchdogWarn: TimeSpan.FromMilliseconds(50), watchdogSevere: TimeSpan.FromSeconds(5));
+        // Deterministic: counters are set at fanout entry, then the body blocks until the WARN
+        // watchdog fires and snapshots them. Severe sits minutes out and never fires — no
+        // body-sleep-vs-threshold race.
+        var harness = new Harness(watchdogWarn: TimeSpan.FromMilliseconds(50), watchdogSevere: TimeSpan.FromMinutes(10));
         harness.SetKillSwitch(false);
         harness.Fanout.Setup(f => f.RunAsync(It.IsAny<SessionRetentionFanoutService.FanoutResult>(), It.IsAny<DateTime>(), It.IsAny<CancellationToken>()))
             .Returns(async (SessionRetentionFanoutService.FanoutResult r, DateTime _, CancellationToken ct) =>
             {
                 r.TenantsProcessed = 3;
                 r.SessionsEnqueued = 7;
-                await Task.Delay(200, ct); // long enough for the 50ms watchdog to fire mid-run
+                await harness.WaitForEventAsync("SessionDeletionMaintenanceLongRunning");
             });
 
         await harness.Sut.RunCoreAsync("Test", CancellationToken.None);
@@ -122,17 +126,20 @@ public class SessionDeletionMaintenanceFunctionTests
     [Fact]
     public async Task RunCore_emits_LongRunningSevere_when_body_runs_past_severe_threshold()
     {
-        var harness = new Harness(watchdogWarn: TimeSpan.FromMilliseconds(50), watchdogSevere: TimeSpan.FromMilliseconds(150));
+        // Deterministic: the body blocks until the SEVERE watchdog records its OpsEvent. Warn has a
+        // smaller threshold, so it is guaranteed to have fired first — neither depends on a body
+        // sleep outlasting a fixed wall-clock threshold.
+        var harness = new Harness(watchdogWarn: TimeSpan.FromMilliseconds(20), watchdogSevere: TimeSpan.FromMilliseconds(60));
         harness.SetKillSwitch(false);
         harness.Fanout.Setup(f => f.RunAsync(It.IsAny<SessionRetentionFanoutService.FanoutResult>(), It.IsAny<DateTime>(), It.IsAny<CancellationToken>()))
             .Returns(async (SessionRetentionFanoutService.FanoutResult _, DateTime _, CancellationToken ct) =>
             {
-                await Task.Delay(300, ct);
+                await harness.WaitForEventAsync("SessionDeletionMaintenanceLongRunningSevere");
             });
 
         await harness.Sut.RunCoreAsync("Test", CancellationToken.None);
 
-        // Both watchdogs fire: warning at 50ms, severe at 150ms.
+        // Both watchdogs fire: warning first (smaller threshold), then severe (which the body waited for).
         Assert.Contains(harness.OpsEvents, e => e.EventName == "SessionDeletionMaintenanceLongRunning");
         Assert.Contains(harness.OpsEvents, e => e.EventName == "SessionDeletionMaintenanceLongRunningSevere");
     }
@@ -345,6 +352,12 @@ public class SessionDeletionMaintenanceFunctionTests
         private readonly Dictionary<string, List<TableEntity>> _sessionsByState = new(StringComparer.Ordinal);
         private readonly List<DeletionManifestBlobSummary> _ttlBlobs = new();
 
+        // Watchdog OpsEvents are recorded from concurrent watchdog tasks; _opsSync serializes the
+        // OpsEvents append + waiter signalling, and _eventWaiters lets a test's fanout body block
+        // until a specific watchdog OpsEvent has actually fired (see WaitForEventAsync).
+        private readonly object _opsSync = new();
+        private readonly Dictionary<string, TaskCompletionSource> _eventWaiters = new(StringComparer.Ordinal);
+
         public Harness(TimeSpan? watchdogWarn = null, TimeSpan? watchdogSevere = null)
         {
             StorageMock = new Mock<TableStorageService>(Mock.Of<TableServiceClient>(), NullLogger<TableStorageService>.Instance);
@@ -376,7 +389,12 @@ public class SessionDeletionMaintenanceFunctionTests
             opsRepo.Setup(r => r.SaveOpsEventAsync(It.IsAny<OpsEventEntry>()))
                 .Returns<OpsEventEntry>(e =>
                 {
-                    OpsEvents.Add(new CapturedOpsEvent(e.EventType, e.Severity, e.Message, e.Details ?? string.Empty));
+                    lock (_opsSync)
+                    {
+                        OpsEvents.Add(new CapturedOpsEvent(e.EventType, e.Severity, e.Message, e.Details ?? string.Empty));
+                        if (_eventWaiters.TryGetValue(e.EventType, out var waiter))
+                            waiter.TrySetResult();
+                    }
                     return Task.CompletedTask;
                 });
             var alertDispatch = new OpsAlertDispatchService(
@@ -426,6 +444,27 @@ public class SessionDeletionMaintenanceFunctionTests
         public void SetKillSwitch(bool active) =>
             AdminConfig.Setup(a => a.IsSessionDeletionKillSwitchActiveAsync()).ReturnsAsync(active);
 
+        /// <summary>
+        /// Deterministic watchdog gate: returns a task that completes once an OpsEvent whose type is
+        /// <paramref name="eventName"/> has been recorded. A test's fanout body awaits this instead of
+        /// sleeping a fixed span, so the watchdog is guaranteed to have fired before the body returns —
+        /// removing the wall-clock race (body sleep vs sub-second thresholds) that flaked under CI load.
+        /// </summary>
+        public Task WaitForEventAsync(string eventName)
+        {
+            lock (_opsSync)
+            {
+                if (OpsEvents.Any(e => e.EventName == eventName))
+                    return Task.CompletedTask;
+                if (!_eventWaiters.TryGetValue(eventName, out var waiter))
+                {
+                    waiter = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+                    _eventWaiters[eventName] = waiter;
+                }
+                return waiter.Task;
+            }
+        }
+
         public void SeedTtlBlobs(params (string TenantId, string SessionId, string ManifestId, DateTime LastModified)[] entries)
         {
             foreach (var e in entries)