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

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

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

.github/workflows/build-agent.yml

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

.github/workflows/ci.yml

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

.github/workflows/codeql.yml

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

.github/workflows/deploy-web.yml

@@ -39,6 +39,10 @@ jobs:
         uses: Azure/static-web-apps-deploy@v1
         env:
           NEXT_PUBLIC_ENTRA_CLIENT_ID: ${{ vars.NEXT_PUBLIC_ENTRA_CLIENT_ID }}
+          # Dual app-reg window: previous app registration (unset = single-app behaviour)
+          # and the default app for browsers without a stored selection (legacy|primary).
+          NEXT_PUBLIC_ENTRA_LEGACY_CLIENT_ID: ${{ vars.NEXT_PUBLIC_ENTRA_LEGACY_CLIENT_ID }}
+          NEXT_PUBLIC_ENTRA_DEFAULT_APP: ${{ vars.NEXT_PUBLIC_ENTRA_DEFAULT_APP }}
           NEXT_PUBLIC_ENTRA_REDIRECT_URI: ${{ vars.NEXT_PUBLIC_ENTRA_REDIRECT_URI }}
           NEXT_PUBLIC_ENTRA_POST_LOGOUT_REDIRECT_URI: ${{ vars.NEXT_PUBLIC_ENTRA_POST_LOGOUT_REDIRECT_URI }}
           NEXT_PUBLIC_API_BASE_URL: ${{ vars.NEXT_PUBLIC_API_BASE_URL }}
@@ -52,7 +56,12 @@ jobs:
           # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
           app_location: "src/Web/autopilot-monitor-web" # App source code path
           api_location: "" # Api source code path - optional
-          output_location: "" # Built app content directory - optional
+          # Static export (next.config output:'export'): Oryx runs `npm run build`
+          # and uploads the exported out/ directory as plain static files — no
+          # managed SSR runtime is provisioned anymore. (No is_static_export
+          # input on this action version; Oryx detects the export from
+          # next.config + output_location.)
+          output_location: "out" # Built app content directory - optional
           ###### End of Repository/Build Configurations ######
 
   close_pull_request_job:

.github/workflows/pester.yml

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

.gitignore

@@ -53,6 +53,9 @@ __azurite_db*__.json
 node_modules/
 .next/
 out/
+# Managed by Next.js since v16 (regenerated by next dev/build/typegen; path
+# inside flips between .next/types and .next/dev/types) — must not be tracked.
+next-env.d.ts
 build/
 dist/
 !rules/dist/
@@ -148,3 +151,6 @@ plans/REFACTOR_AGENT_V2.md
 scripts/Backup/setup-backup-container.ps1
 docs/Introduction-AutopilotMonitor.pptx
 docs/~$Introduction-AutopilotMonitor.pptx
+
+# Playwright MCP browser artifacts (snapshots, screenshots, console logs)
+.playwright-mcp/

.mcp.json

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

Directory.Build.props

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

README.md

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

docs/agent/autopilot-ztd-diagnostics.md

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

docs/agent/continue-anyway-observation.md

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

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

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

docs/backend/cloudpc-device-validation.md

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

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

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

docs/backend/session-annotations.md

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

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

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

docs/index.md

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

docs/log.md

@@ -1,7 +1,74 @@
 # Log
 
+## 2026-08-13
+
+* **Update**: `backend/session-annotations.md` — the `/annotations` portal overview page now carries the standard tenant switcher (GA/Reader: "All tenants" aggregate + per-tenant drill-down via `GET global/session-annotations`; delegated: managed subset), with a tenant column and tenant-qualified session deep links. The global list endpoint now derives `excludeGlobalAdminLane` from `HasGlobalScope`, so delegated-rescue callers on their managed `?tenantId=` path never receive the platform-internal `globaladmin` lane (endpoint-test-pinned).
+
+## 2026-08-12
+
+* **Update**: `agent/autopilot-ztd-diagnostics.md` — Windows 365 Cloud PC exception documented: on Cloud PCs `ProfileAvailable=0` is expected (provisioned by the Windows 365 service, not Autopilot), so `autopilot_profile_missing` is emitted as Info with a Cloud-PC-specific message and an `isCloudPc` payload marker (`ResolveAutopilotProfileMissingPresentation`); the portal's Autopilot Profile card renders a neutral note instead of the amber warning for Cloud PC sessions (`session.isCloudPc` or the event marker).
+
+## 2026-08-11 (later)
+
+* **Creation**: Added `backend/session-annotations.md` — session annotations: the new `SessionAnnotations` table (PK=tenantId, RK=`{sessionId}_{lane}`, lanes operator/tenantadmin/globaladmin) storing structured verdicts (`root_cause_confirmed | analysis_wrong | different_problem | inconclusive`) + notes with server-stamped authorship and a fired-rule-id snapshot for join-free rule-quality evaluation. Per-lane write matrix re-gated in-function with own-tenant binding (a GA writes only the platform-internal `globaladmin` lane cross-tenant; tenant callers never see that lane). Surfaces: portal `SessionAnnotationsCard` (session detail, after Analysis), MCP `list_session_annotations` (ga) + `annotate_session` (strictGa, always the GA lane) + `annotations` key in `get_session_summary`. Lifecycle: per-session cascade steps 17–19, offboarding wipe, critical-backup member.
+
+## 2026-08-11
+
+* **Update**: `rules/gather-rule-guardrails.md` — hard-block mirroring closed across all pre-flight layers: `rules/guardrails.json` now also mirrors `blockedCommandPatterns` + `maxCommandLength` and carries `C:\Windows\System32\config` in `blockedFilePrefixes`; portal (`guardValidation.ts`) and MCP (`rule-validation.ts`) apply them in agent order (before the unrestricted-mode early-return), so a command the agent hard-blocks no longer shows "Allowed" in unrestricted tenants. `GuardrailsParityTests` pins the JSON mirror to the C# constants. MCP `validate_rule` additionally validates `json`/`xml` targets with file semantics (the schema's `collectorType` enum was missing both) and rejects `activePhases`+`activeFromPhase` set together (backend 400 parity). Author stamping extended to PUT-upserts: tenant and global gather-rule updates stamp the caller's JWT display name before the service call, so an upsert of a non-existing ruleId can no longer store a payload-supplied author (true updates still preserve the original author).
+
+## 2026-08-10
+
+* **Update**: `rules/gather-rule-guardrails.md` — WMI matcher generalized from literal prefix matching to shape parsing: `SELECT <* | property-list> FROM <class>` is allowed when the class is derived from the existing `SELECT * FROM <class>` entries (a projection is a strict subset; motivated by `SELECT BatteryStatus FROM Win32_Battery` + `on_change` battery polling that `SELECT *` defeats via fluctuating charge %). Same algorithm mirrored agent/portal/MCP; guardrails.json unchanged. Portal now also gates enabling on the client-side validation (invalid-target custom rules create disabled, cannot be toggled on, force-disable on invalid edit, "Blocked on devices" badge) — UX only, the agent guard stays the boundary. Gather-rule Author is now stamped from the creator's JWT (display name → UPN) at create and immutable on update.
+
+* **New**: `agent/continue-anyway-observation.md` — Continue-Anyway observation mode (`EnableEspContinueAnywayObservation`, ConfigVersion 37, operator-set): Device-phase ESP terminal failures on Continue-Anyway profiles are defanged into a 60-min observation window (Classic/Unknown, non-pre-prov only); real-user desktop + Hello gate complete the session as Succeeded + `EspSoftFailure`/`CompletionSource` (amber "with issues" badge + detail banner), category recovery resolves clean, expiry un-defangs to the original `esp_terminal_failure`. Registered in the Agent index section. Related backend fix (no doc): the auto-analyze enqueue now carries a 30 s `visibilityTimeout` so rule evaluation no longer races the agent's terminal flush (ANALYZE-ESP-004's `{{appName}}` placeholder).
+
+## 2026-08-07 (later)
+
+* **Update**: `backend/cloudpc-device-validation.md` — third `IsCloudPc` transport rail: the pre-auth distress channel. `DistressReport.IsCloudPc` (CloudPcDetector verdict captured at `DistressReporter` construction) → `DistressReportEntry`/table column → "Devices Not Registered" aggregation (sticky-true per serial, same OR semantics as the Sessions merge) → portal Cloud PC badge + actionable hint ("enable Windows 365 Cloud PC Validation + W365CloudPcValidation add-on"). Motivated by the first W365 field run: the rejected Cloud PC showed up as anonymous "Microsoft Corporation / Virtual Machine" with no clue that the fix is the Cloud PC validator, not Autopilot registration. UNVERIFIED like all distress fields; ≤18 bytes, fits the 1536-byte cap.
+
+## 2026-08-07
+
+* **Update**: `backend/cloudpc-device-validation.md` — the "deliberately out of scope" follow-up landed in the same PR: agent-side `IsCloudPc` flag (`CloudPcDetector`, bootstrap-verified marker AND: Windows365 key + CloudManagedDesktopExtension service key, SKIP-safe) rides two rails — `SessionRegistration` → Sessions/Index (sticky-true) → `SessionSummary` + `isCloudPc` search filter (portal/raw/MCP), and the `EnrollmentFactsObserved` payload → `EnrollmentScenarioObservations.CloudPc` (set-once, both values) with profile reason `cloud_pc_first_connect:no_device_esp_expected` + `cloud_pc_marker` in the audit-trail census. Reason+observation only: no completion arm depends on DeviceSetup, Mode stays AccountSetup/IME-classified, EspConfig keeps configured-FirstSync semantics. Never an auth input.
+
+## 2026-08-06
+
+* **Creation**: Added `backend/cloudpc-device-validation.md` — the CloudPc fallback validator (`ValidatorType.CloudPc = 5`, tenant flag `ValidateCloudPcDevice`): W365 Cloud PCs are structurally never Autopilot-registered, so stage 4 gains a third stage that binds the chain-validated MDM cert's Subject CN (= Intune device id, field-verified on a real Cloud PC) to the tenant's `virtualEndpoint/cloudPCs` inventory — admits exactly the service-provisioned Cloud PCs, no device-type routing, local W365 markers never consulted for auth. New optional Graph add-on `W365CloudPcValidation` → `CloudPC.Read.All` (catalog + grant script now pinned by `GraphFeatureCatalogSyncTests`; Graph 403 = definitive "grant missing", not transient). Bootstrap dev script v2.3-dev.3 exempts guard 4 (uptime) while the Cloud-PC relax is active — the fresh-profile window is the time anchor at first connect, not boot uptime. Follow-up deliberately out of scope: agent-side `IsCloudPc` classification + decision-engine "no Device ESP" expectation.
+
+## 2026-08-05 (later)
+
+* **Update**: `rules/rule-authoring-surface.md` — new section `POST /api/rules/gather/test-pattern`: the logparser pattern tester (agent-exact .NET matching: no IgnoreCase, first-match-per-line, cmtrace vs text mode, verbatim format=text hint), motivated by a field incident where a PHP-verified regex behaved differently under .NET. `CmTraceLogParser` moved Agent → `AutopilotMonitor.Shared.Logging` so agent and backend share the ONE parsing implementation (timestamp caveat: AssumeLocal = server TZ on backend, endpoint reports no timestamps). MCP: new `test_log_pattern` tool, logparser lint in `validate_rule`, guide gains the case-sensitivity/engine-mismatch pitfalls.
+
+## 2026-08-05
+
+* **Creation**: Added `mcp/tool-telemetry.md` — the three MCP tool-telemetry layers (App Insights `McpToolName`, per-user usage table, `MCP_TOOL_LOGGING` stderr lines) and the new quality signals: soft-error capture (`toolError` returns instead of throwing, so backend telemetry counted those calls as successes), `resultChars`/`overCap` vs. the inline-size hint, bounded args summaries, caller scope, `search_zero_hit` on the three search tools (unmet-demand signal), and `tool_call_rejected` for JSON-RPC-level Zod/unknown-tool rejections sniffed at the `/mcp` route (previously invisible everywhere). Bicep default for `toolLoggingEnabled` flipped to `true` (documented desired state; live flag set via `az containerapp update`).
+* **Creation**: Added `rules/rule-authoring-surface.md` — the AI-assisted rule-authoring stack: three deterministic MCP resources (`rule_authoring_guide` hand-written, `rule_schemas` + `rule_guardrails` generated into `rule-authoring.generated.ts` by a new combine.js emitter, drift-guarded twice), the MCP-local `validate_rule` (ajv 2020-12 against the single-rule $defs, guardrail pre-flight mirroring GatherRuleGuards matching semantics incl. hard blocks, semantic lint for schema-valid-but-dead rules), and the side-effect-free `POST /api/rules/analyze/dryrun` (TenantAdminOrGlobalReader; `RuleEngine.DryRun.cs` trace twin sharing the production evaluators, all-conditions trace with per-condition evidence + matchingEventCount, parity and side-effect-freedom pinned by RuleEngineDryRunTests). MCP `test_analyze_rule` wraps the endpoint with `{{token}}`-interpolated previews; `author-rule` prompt drives the draft → validate → dry-run loop. Deliberately absent: gather-rule remote execution, rule writes via MCP.
+
+## 2026-08-04
+
+* **Update**: `rules/gather-rule-phase-scoping.md` — new section "Which phase feeds the triggers": `GatherRuleExecutorHost` now drives `phase_change`/`phase_exit`/`on_event` gather triggers (and the phase-scope gates) from the post-reduce `TimelineEventStream` (every emitted event's `(eventType, phase)` published by `EventTimelineEmitter`) instead of the pre-reduce `SignalIngress.SignalPosted` payloads. Trigger: session `32312a32` (RealmJoin tenant rsneuffen.de) — a Phase-Start rule on FinalizingSetup fired at the raw ESP-exit `EspPhaseChanged(FinalizingSetup)` signal, 7 minutes before the engine's RealmJoin-gated `phase_transition(FinalizingSetup)`, reading `HKLM\SOFTWARE\RealmJoin\Custom\BIOS` before the RealmJoin package created it. Phase triggers now fire exactly when the timeline shows the phase; `on_event` additionally sees engine-emitted event types (`enrollment_complete`, `realmjoin_resolved`, …) for the first time in V2, restoring V1 semantics and the documented end-of-enrollment pattern. Other raw-signal hosts (DeviceInfo, keep-awake, PPKG) deliberately unchanged.
+
+## 2026-08-02
+
+* **Creation**: Added `backend/tenant-activation-welcome-mail.md` — triggered by the first production auto-approve (activation at signup+64 s, notification address saved at +69 s → welcome mail silently skipped, since the approval path is the only sender and reads the address once). Fix documented in the doc: the notification-email save path now also triggers the send (`PUT /api/preview/notification-email` → fresh approval check `IsApprovedFreshAsync`, bypassing the 30 s negative cache), and a conditional-insert `welcome-email-sent` marker in `PreviewWhitelist` makes the send once-only across both racing paths (marker consumed strictly after the address check; revoke clears it, offboarding wipes the partition, the GA resend endpoint sends unconditionally and consumes it best-effort).
+
+## 2026-07-29
+
+* **Update**: `agent/gather-rule-debug-log.md` — three trace enrichments: (1) new `phase` stage writing an enrollment-phase transition marker (`phase change: Old -> New`, ruleId `-`) so every rule-level line reads against the current phase; (2) logparser now writes one line per regex match — line number, matched text, capture groups — capped at 10 per file per run (the per-file summary keeps the full count); (3) the invalid-regex `error` line includes the offending pattern string.
+
+* **Update**: `url-registry.md` (+ `web/portal-navigation-prefetch.md` context) — the portal is now a **full static export** (`output: 'export'`, `trailingSlash: true`): the SWA serves plain files, the managed SSR runtime — the portal's last cold-start source ("Backend call failure" > 45 s) — no longer exists. Detail routes moved from path params to query strings (`/sessions?id=`, `/sessions/inspector?id=`, `/diagnosis?id=`, `/apps/detail?name=`, `/admin/backups/detail?id=`, `/admin/customs-archive/detail?tenantId=&rowKey=`) with all 21 link sites going through the new single-definition builders in `lib/routes.ts`; the 9 `[section]` families prerender via `generateStaticParams` server shells (37 pages, `dynamicParams=false`), server `redirect()` index pages became `ClientRedirect` shells. Legacy PATH-shaped deep links (sent Teams/Slack/webhook notifications hold `/sessions/{id}` forever) are preserved permanently: SWA wildcard rewrites serve the family page and the globally mounted `LegacyPathRedirect` rewrites to the canonical query URL (hash + query preserved; mapping pinned by `lib/__tests__/legacyPathRedirect.test.ts`). `middleware.ts` host routing became the client-side `HostRoutingGuard` (prefix list moved to `lib/hostRouting.ts`); the legacy `/go/[code]` route + `bootstrapValidation.ts` are deleted (BootstrapSessions table verified free of pre-cutover active sessions). `staticwebapp.config.json` now carries the 19 docs/marketing redirects (order-sensitive), the legacy rewrites, `404.html` override and ALL security headers incl. the literalized prod CSP — guarded by the new `swaConfig.guard.test.ts`; maintenance mode changed from whole-file swap to a first-routes-entry insert (README rewritten). Backend notification deep links go through the new `Constants.PortalSessionUrl` (query shape, pinned). Deploy: `deploy-web.yml` uploads `out/` with `is_static_export: true`.
+
+* **Creation**: Added `backend/oobe-bootstrap-go-flow.md` (and a `Bootstrap go-URL` section + web-registry update in `url-registry.md`) — the OOBE bootstrap script endpoint moved from the portal's Next.js `/go/[code]` SSR route into the Function App (`GET /api/bootstrap/go/{code}`, `GetBootstrapScriptFunction`), unblocking the portal's static export; the customer URL became **`go.autopilotmonitor.com/{code}`** (Front Door custom domain, `/*` route with origin-path rewrite, caching disabled — the script inlines the bearer token). New `Constants.BootstrapGoBaseUrl` (single producer via `CreateBootstrapSessionFunction`) + web `BOOTSTRAP_GO_URL` (display only); both guard host lists extended. Security invariants ported to C#: `BootstrapScriptValueValidator` (exact-GUID tenantId/token, https + host-allowlist + `/agent/….zip` path, expiry ≤ 14 d) and `OobeBootstrapScriptGenerator` (Replace-token raw-string template, single-quoted PS literals, 200-char error cap before quote-doubling; always-HTTP-200 text/plain contract for `irm | iex`). Endpoint is `PublicAnonymous` in the catalog, `NoStoreCacheMiddleware`-covered, self-rate-limited `bootstrap-script:{ip}` 20/min (rate-limit reply is also a 200 error script). Tests: golden byte-parity against the TS template, validator invariants incl. hostile-URL cases, format-gate table, and the previously missing BootstrapUrl shape pin. Transition: the legacy www route + `middleware.ts` `/go` prefix stay alive for pre-migration URLs (validity ≤ 168 h) and are removed in the static-export PR no earlier than 168 h after the last www URL was issued. Customer docs `network-endpoints.md` gained the `go.` host (device-facing, Bootstrap-Sessions-only).
+
+* **Update**: `agent/autopilot-ztd-diagnostics.md` — presentation layer for the startup error backfill (customer feedback: an unannounced wall of pre-agent Error events with a single identical timestamp read like a live failure). Agent: the backfill scan now buffers the capped record set, emits an Info summary event first (`modern_deployment_log`, `backfillSummary: true` + `replayedCount`/`droppedOverCap`/`lookbackMinutes`), then replays oldest-first so the timeline sequence follows event-log chronology. Web: `EventTimeline.tsx` badges `backfilled: true` events („⟲ Backfilled", tooltip) and renders the original `timeCreated` as the row time with a "(reported …)" suffix plus a `Recorded` metadata line — works retroactively for already-stored events. Severity is deliberately not downgraded.
+
+* **Creation**: Added `agent/gather-rule-debug-log.md` — the new per-tenant setting `EnableGatherRuleDebugLog` (ConfigVersion 35 → 36, portal toggle under Settings → Agent, `EnableImeMatchLog`-style bool→path projection in `RemoteConfigMerger`). When enabled, the agent writes `%ProgramData%\AutopilotMonitor\Logs\gather_rules_debug.log`: one pipe-delimited line per evaluation decision across ten previously silent "produced nothing" exits — disabled rules, `interval` without `intervalSeconds` (never runs), the first-tick-after-one-full-interval window, phase-scope skips incl. `currentPhase=Unknown`, per-(rule, phase) dedup, empty collector results (`emitOnlyIfExists`), `on_change` hash suppression (hash prefix + streak), guard blocks, logparser per-file outcomes (position skips, parse failures with a `format=text` hint when every line fails CMTrace parsing, `maxLines`/wildcard caps), and full exception stacks that the agent log drops. 10 MB cap + one `.old` generation; no hot-reload (per-enrollment lifecycle); flag survives the offline config cache; `--run-gather-rules` always traces and echoes under `--console`; zero-rules delivery leaves a one-line file instead of nothing. Side fix: `GatherRuleExecutorHost` now passes the logger into `InformationalEventPost`, so gather-event emissions appear in the agent DEBUG log.
+
+* **Correction + Update**: `web/portal-navigation-prefetch.md`. The HTTP/1.1 claim in the 2026-07-27 entry below is **wrong** and has been struck from the document: `portal.autopilotmonitor.com` negotiates **h2**, verified by `openssl s_client -alpn h2,http/1.1` and a .NET `HttpClient` returning `HTTP/2.0`. The false reading came from the Windows/Schannel curl build in this environment, which has no HTTP/2 support and therefore always reports `1.1` — do not use it to determine HTTP versions. There is no six-connection cap in play; the queue is server-side in the SWA SSR runtime, which does not change the fix or the evidence, only the mechanism. Added an `Outcome` section with 20 h of post-change telemetry: the Free → Standard plan change (16:02:44 UTC) produced **no measurable latency gain** once stratified by the gap to the previous request (p50 Free → Standard: `<10s` 85 → 95 ms, `5-30min` 429 → 441 ms; tail rates 1.64 %/0.374 % over 2 s/10 s vs 6 and 1 events at n = 258 against 4.2 and 1.0 expected; `browserTimings` Mann-Whitney z = −0.24, p = 0.81). The freezes were removed by `prefetch={false}` (16:34:13 UTC): worst `browserTimings.totalDuration` 225,277 → 4,856 ms. The prefetch storm was also an **accidental keep-alive** — requests under 10 s apart fell from 85 % to 46 %, and on the identical never-cacheable `/sessions/{id}` route the median rose 87 → 211 ms and p90 465 → 1,480 ms, with one 11,441 ms abandoned request (`resultCode 0`) after 517 minutes idle. Synthetic bursts warm the runtime and must not be used to benchmark this (round 1 p50 288 ms vs rounds 4–25 p50 113 ms).
+
 ## 2026-07-27
 
+* **Creation**: Added `web/portal-navigation-prefetch.md` (and a `Web Portal` section to the index) — root cause of the minute-long portal freezes. `GlobalSidebar` and `Navbar` render the whole navigation on every page, so the App Router's default viewport prefetch issued one `?_rsc=` request per visible link against `portal.autopilotmonitor.com` (~10,400 in 14 days). *(The original entry attributed the freeze to HTTP/1.1 and a six-connection-per-origin cap — see the 2026-07-28 correction; the queue is server-side.)* When the Static Web Apps managed runtime queued the prefetches (p50 91 ms, p95 896 ms, but max 234 s / 21 samples over 30 s), the navigation the user wanted was stuck behind that queue. Measured on the 2026-07-27 17:25 CEST incident: `/admin/presence?_rsc=` 151 s, three siblings finishing within 340 ms of each other at ~37.5 s, all `200`, while the backend API answered in 1.6–2.2 s and `browserTimings` showed `networkDuration` 16 ms against `processingDuration` 225 s. Every navigation Link now sets `prefetch={false}` — these routes are client components behind `ProtectedRoute` that fetch their own data, so the prefetched RSC payload carried no benefit. The doc also records that browser telemetry lives in a **separate** App Insights resource (`AUTOPILOT_MONITOR_WEB_APPINSIGHTS_ID`) that the MCP `query_backend_logs` tool cannot reach, which is why the freezes left no trace in the backend logs.
+
 * **Creation**: Added `backend/rule-regression-radar.md` — F3 regression radar (analyze rules only; gather rules wait for their per-batch stats dedup fix): per (tenant, rule) daily hit rate from `RuleStats`, firing only when the trailing 7-day window has ≥5 hit sessions and ≥20 evaluated sessions, the rate is ≥2× the prior 28-day baseline AND the Wilson 95 % intervals are disjoint (deterministic `MetricsMath` primitive with hand-computed test vectors). Suppressed for deleted rules, rules younger than baseline+window (`CreatedAt` grace), rules edited inside the window (`UpdatedAt`), empty baselines, and the `RuleRegressionRadarDisabled` app-setting kill switch. Alert episodes live as `ruleregression|{ruleId}` tracker rows (one bell + one `RuleFrequencyRegression` ops event per episode; numbers refreshed while active; re-armed under 1.5× baseline, on fire-stop, or by the 30-day tracker retention). On-fire dimension correlation over osBuild/model/agentVersion/imeVersion with the "correlated, not necessarily causal" wording contract. Surfaces: `regressions[]` in the rule-stats response (MCP inherits), the analyze-rules page's 30-day sparkline and regression badge.
 
 * **Creation**: Added `backend/device-journeys.md` — F2 device history / First-Time-Right: the device key (trim + case-fold serial, junk/placeholder exclusion incl. the agent's `Unknown` WMI sentinel), journey grouping over the terminal set Succeeded/Failed/Incomplete (first success ends a journey, a >30-day gap from the previous attempt's CompletedAt starts one, WhiteGlove's single session row is ONE attempt, open sessions are never attempts), the `DeviceHistories` chain (cap 20, written inline at the terminal seam, healed by the sweep, deleted-session refs pruned tombstone-driven, deliberately not in the per-session deletion manifest) and the additive `DeviceJourneyAggregates` daily rows (window rate = ratio of sums — no rolling row needed, 180-day retention). Surfaces: the session-detail "Attempt N" banner with server-computed attempt numbers (virtual-attempt rule for live sessions), the Fleet Health First-time-right section (≥20-journey gate, attempt histogram, repeat-devices violator list), and the MCP `get_device_history` tool (serial mode / fleet FTR mode).

docs/mcp/tool-telemetry.md

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

docs/rules/gather-rule-guardrails.md

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

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

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

docs/rules/rule-authoring-surface.md

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

docs/url-registry.md

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

docs/web/portal-navigation-prefetch.md

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

infra/mcp-server.bicep

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

rules/analyze/ANALYZE-SEC-008.json

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

rules/dist/analyze-rules.json

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

rules/guardrails.json

@@ -250,6 +250,27 @@
     "C:\\Install\\Log"
   ],
   "blockedFilePrefixes": [
-    "C:\\Users"
-  ]
+    "C:\\Users",
+    "C:\\Windows\\System32\\config"
+  ],
+  "blockedCommandPatterns": [
+    "Invoke-WebRequest",
+    "Invoke-RestMethod",
+    "Start-BitsTransfer",
+    "wget",
+    "curl",
+    "certutil -urlcache",
+    "New-LocalUser",
+    "Add-LocalGroupMember",
+    "net user",
+    "net localgroup",
+    "bcdedit",
+    "bcdboot",
+    "schtasks /create",
+    "Register-ScheduledTask",
+    "Remove-Item -Recurse",
+    "Format-Volume",
+    "Set-ExecutionPolicy"
+  ],
+  "maxCommandLength": 2000
 }

rules/schema/gather-rule.schema.json

@@ -67,7 +67,7 @@
         "collectorType": {
           "type": "string",
           "description": "Type of data collection.",
-          "enum": ["registry", "eventlog", "wmi", "file", "command_allowlisted", "logparser"]
+          "enum": ["registry", "eventlog", "wmi", "file", "json", "xml", "command_allowlisted", "logparser"]
         },
         "target": {
           "type": "string",

rules/scripts/combine.js

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

scripts/Bootstrap/Install-AutopilotMonitor-dev.ps1

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

scripts/Bootstrap/Install-AutopilotMonitor.Tests.ps1

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

scripts/Bootstrap/Install-AutopilotMonitor.ps1

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

scripts/Bootstrap/Test-ShouldBootstrapAgent-dev.ps1

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

scripts/Bootstrap/Test-ShouldBootstrapAgent.ps1

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

scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1

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

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

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

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

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

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

@@ -308,9 +308,52 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring.Gather
         [InlineData("SELECT * FROM Win32_UserAccount")]
         [InlineData("SELECT * FROM Win32_ShadowCopy")]
         [InlineData("SELECT * FROM Win32_OperatingSystemExtra")]          // prefix spoofing
+        [InlineData("SELECT Name FROM Win32_Process")]                    // projection of a disallowed class
+        [InlineData("SELECT BatteryStatus FROM Win32_BatteryX")]          // class spoofing via projection
         public void WmiCollector_OffAllowlistQuery_IsBlockedBeforeTheQueryRuns(string query)
             => AssertBlocked(new WmiCollector().Execute(Rule("wmi", query), Context()), query);
 
+        // -------------------------------------------------------------------
+        // WMI query matcher: "SELECT <* | property-list> FROM <allowed class>"
+        //
+        // Guard-level (no WMI touched): a property projection of an allowed class
+        // exposes a strict subset of the already-allowed SELECT *, so it is admitted.
+        // -------------------------------------------------------------------
+
+        [Theory]
+        [InlineData("SELECT * FROM Win32_Battery")]                                       // legacy form unchanged
+        [InlineData("SELECT * FROM Win32_BIOS WHERE PrimaryBIOS = TRUE")]                 // legacy + WHERE
+        [InlineData("SELECT BatteryStatus FROM Win32_Battery")]
+        [InlineData("SELECT BatteryStatus, EstimatedChargeRemaining FROM Win32_Battery")]
+        [InlineData("select batterystatus from win32_battery")]                           // case-insensitive
+        [InlineData("SELECT\tBatteryStatus\tFROM\tWin32_Battery")]                        // tabs as separators
+        [InlineData("  SELECT BatteryStatus FROM Win32_Battery  ")]                       // surrounding whitespace
+        [InlineData("SELECT BatteryStatus,EstimatedChargeRemaining FROM Win32_Battery")]  // no space after comma
+        [InlineData("SELECT Status FROM Win32_Battery WHERE BatteryStatus = 1")]          // projection + WHERE
+        public void WmiGuard_ProjectionOfAllowedClass_IsAllowed(string query)
+            => Assert.True(GatherRuleGuards.IsWmiQueryAllowed(query));
+
+        [Theory]
+        [InlineData("SELECT Name FROM Win32_Process")]                    // class not on the allowlist
+        [InlineData("SELECT BatteryStatus FROM Win32_BatteryX")]          // class spoofing
+        [InlineData("SELECT * FROM Win32_BatteryX")]
+        [InlineData("SELECT *, Name FROM Win32_BIOS")]                    // star mixed into a property list
+        [InlineData("SELECT FROM Win32_BIOS")]                            // empty property list
+        [InlineData("SELECT BatteryStatus FROM")]                         // missing class
+        [InlineData("SELECT BatteryStatus FROM Win32_Battery;DROP")]      // non-whitespace boundary after class
+        [InlineData("SELECT BatteryStatus, FROM Win32_Battery")]          // trailing comma
+        [InlineData("")]
+        public void WmiGuard_MalformedOrDisallowedQuery_IsBlocked(string query)
+            => Assert.False(GatherRuleGuards.IsWmiQueryAllowed(query));
+
+        [Fact]
+        public void WmiGuard_NullQuery_IsBlocked()
+            => Assert.False(GatherRuleGuards.IsWmiQueryAllowed(null));
+
+        [Fact]
+        public void WmiGuard_UnrestrictedMode_AllowsAnyQuery()
+            => Assert.True(GatherRuleGuards.IsWmiQueryAllowed("SELECT Name FROM Win32_Process", unrestrictedMode: true));
+
         [Fact]
         public void JsonCollector_UserProfilePath_IsBlockedBeforeTheFileIsOpened()
         {

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -27,7 +27,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
                 IReadOnlyCollection<string> whiteGloveSealingPatternIds,
                 ISignalIngressSink ingress,
                 IClock clock,
-                AutopilotMonitor.Agent.V2.Core.Transport.Telemetry.ITelemetrySpool? telemetrySpool)
+                AutopilotMonitor.Agent.V2.Core.Transport.Telemetry.ITelemetrySpool? telemetrySpool,
+                TimelineEventStream? timelineEvents = null)
             {
                 CapturedPatternIds = whiteGloveSealingPatternIds;
                 return new CollectorSurfaces(Array.Empty<ICollectorHost>());

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

@@ -0,0 +1,189 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Threading;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.DecisionCore.Engine;
+using AutopilotMonitor.DecisionCore.Signals;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Orchestration
+{
+    /// <summary>
+    /// GatherRuleExecutorHost feeds its phase_change / phase_exit / on_event triggers from the
+    /// POST-REDUCE <see cref="TimelineEventStream"/> (emitted timeline events), not from raw
+    /// signals. Regression anchor: session 32312a32 (rsneuffen.de) — a phase_change rule on
+    /// FinalizingSetup fired at the raw EspPhaseChanged(FinalizingSetup) signal (ESP exit),
+    /// 7 minutes before the engine's RealmJoin-gated phase_transition(FinalizingSetup), and read
+    /// a registry key before the RealmJoin package wrote it. With the timeline feed the rule
+    /// fires only when the phase declaration is actually emitted.
+    /// Rules use the absent-registry-path pattern so no real system state is touched; execution
+    /// is observed via the InformationalEvent posts the host sends through its ingress sink.
+    /// </summary>
+    [Collection("SerialThreading")] // rules execute on the shared ThreadPool
+    public sealed class GatherRuleExecutorHostTimelineFeedTests : IDisposable
+    {
+        private const string AbsentPath =
+            "HKLM\\SOFTWARE\\AutopilotMonitorTests\\DefinitelyAbsent_5b1f03a2-0000-0000-0000-000000000000";
+
+        private readonly TempDirectory _tmp = new TempDirectory();
+        private readonly CapturingSink _sink = new CapturingSink();
+        private readonly TimelineEventStream _stream = new TimelineEventStream();
+        private GatherRuleExecutorHost? _host;
+
+        public void Dispose()
+        {
+            _host?.Dispose();
+            _tmp.Dispose();
+        }
+
+        private sealed class CapturingSink : ISignalIngressSink
+        {
+            private readonly List<string> _eventTypes = new List<string>();
+            private readonly object _gate = new object();
+
+            public int CountOf(string eventType)
+            {
+                lock (_gate)
+                {
+                    var n = 0;
+                    foreach (var t in _eventTypes)
+                        if (string.Equals(t, eventType, StringComparison.Ordinal)) n++;
+                    return n;
+                }
+            }
+
+            public void Post(
+                DecisionSignalKind kind,
+                DateTime occurredAtUtc,
+                string sourceOrigin,
+                Evidence evidence,
+                IReadOnlyDictionary<string, string>? payload = null,
+                int kindSchemaVersion = 1,
+                object? typedPayload = null)
+            {
+                if (kind != DecisionSignalKind.InformationalEvent || payload == null) return;
+                if (!payload.TryGetValue(SignalPayloadKeys.EventType, out var eventType)) return;
+                lock (_gate) _eventTypes.Add(eventType);
+            }
+        }
+
+        private void BuildHost(params GatherRule[] rules)
+        {
+            var logger = new AgentLogger(_tmp.Path, AgentLogLevel.Info);
+            _host = new GatherRuleExecutorHost(
+                sessionId: "sess",
+                tenantId: "tenant",
+                ingress: _sink,
+                clock: new SystemClock(),
+                logger: logger,
+                rules: new List<GatherRule>(rules),
+                imeLogPathOverride: null,
+                unrestrictedMode: true,
+                gatherDebugLogPath: null,
+                timelineEvents: _stream);
+            _host.Start();
+        }
+
+        private bool WaitForCount(string eventType, int count, int timeoutMs = 10000)
+        {
+            var sw = Stopwatch.StartNew();
+            while (sw.ElapsedMilliseconds < timeoutMs)
+            {
+                if (_sink.CountOf(eventType) >= count) return true;
+                Thread.Sleep(25);
+            }
+            return _sink.CountOf(eventType) >= count;
+        }
+
+        private static GatherRule Rule(string id, string trigger, string? triggerPhase = null, string? triggerEventType = null)
+            => new GatherRule
+            {
+                RuleId = id,
+                Title = id,
+                CollectorType = "registry",
+                Target = AbsentPath,
+                Trigger = trigger,
+                TriggerPhase = triggerPhase ?? string.Empty,
+                TriggerEventType = triggerEventType ?? string.Empty,
+                OutputEventType = "gather_host_test",
+                Enabled = true,
+            };
+
+        [Fact]
+        public void PhaseChangeRule_FiresOnEmittedPhaseDeclaration_NotOnPhaselessEvents()
+        {
+            BuildHost(Rule("GATHER-HOST-001", "phase_change", triggerPhase: "FinalizingSetup"));
+
+            // The raw-world sequence of session 32312a32 as it reaches the emitted timeline:
+            // esp_exiting and hello_wizard_started are emitted WITHOUT a phase declaration
+            // (the engine holds FinalizingSetup back behind the RealmJoin gate) — no fire.
+            _stream.Publish("esp_exiting", EnrollmentPhase.Unknown);
+            _stream.Publish("hello_wizard_started", EnrollmentPhase.Unknown);
+            Thread.Sleep(300);
+            Assert.Equal(0, _sink.CountOf("gather_host_test"));
+
+            // Only the engine's actual phase declaration fires the rule.
+            _stream.Publish("phase_transition", EnrollmentPhase.FinalizingSetup);
+            Assert.True(WaitForCount("gather_host_test", 1));
+        }
+
+        [Fact]
+        public void OnEventRule_FiresForEngineEmittedEventTypes()
+        {
+            // enrollment_complete is an engine-emitted effect event; it never existed on the raw
+            // InformationalEvent signal stream, so the docs-promised "On Event with
+            // enrollment_complete" trigger was dead under the previous SignalPosted feed.
+            BuildHost(Rule("GATHER-HOST-002", "on_event", triggerEventType: "enrollment_complete"));
+
+            _stream.Publish("enrollment_complete", EnrollmentPhase.Unknown);
+            Assert.True(WaitForCount("gather_host_test", 1));
+        }
+
+        [Fact]
+        public void PhaseFeed_DedupsConsecutiveSamePhaseDeclarations()
+        {
+            // "Any phase" phase_change rule fires on every phase TRANSITION — a re-declared
+            // identical phase (e.g. duplicate esp_phase_changed) must not count as one.
+            BuildHost(Rule("GATHER-HOST-003", "phase_change", triggerPhase: ""));
+
+            _stream.Publish("esp_phase_changed", EnrollmentPhase.DeviceSetup);
+            Assert.True(WaitForCount("gather_host_test", 1));
+
+            _stream.Publish("esp_phase_changed", EnrollmentPhase.DeviceSetup);
+            Thread.Sleep(300);
+            Assert.Equal(1, _sink.CountOf("gather_host_test"));
+
+            _stream.Publish("esp_phase_changed", EnrollmentPhase.AccountSetup);
+            Assert.True(WaitForCount("gather_host_test", 2));
+        }
+
+        [Fact]
+        public void PhaseExitRule_FiresWhenEmittedTimelineLeavesThePhase()
+        {
+            BuildHost(Rule("GATHER-HOST-004", "phase_exit", triggerPhase: "AccountSetup"));
+
+            _stream.Publish("esp_phase_changed", EnrollmentPhase.AccountSetup);
+            Thread.Sleep(300);
+            Assert.Equal(0, _sink.CountOf("gather_host_test"));
+
+            _stream.Publish("phase_transition", EnrollmentPhase.FinalizingSetup);
+            Assert.True(WaitForCount("gather_host_test", 1));
+        }
+
+        [Fact]
+        public void StoppedHost_NoLongerReactsToTheStream()
+        {
+            BuildHost(Rule("GATHER-HOST-005", "on_event", triggerEventType: "enrollment_complete"));
+
+            _host!.Stop();
+            _stream.Publish("enrollment_complete", EnrollmentPhase.Unknown);
+            Thread.Sleep(300);
+            Assert.Equal(0, _sink.CountOf("gather_host_test"));
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Program/AgentBootstrapSelfUpdateRetryTests.cs

@@ -0,0 +1,124 @@
+using System;
+using System.IO;
+using System.Threading.Tasks;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime;
+using AutopilotMonitor.Agent.V2.Core.Tests.Harness;
+using AutopilotMonitor.Agent.V2.Runtime;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
+{
+    /// <summary>
+    /// Contract tests for <see cref="AgentBootstrap.RetrySelfUpdateAfterEnrollment"/> —
+    /// the post-cert one-shot self-update retry (field case sits-d.cloud, 2026-08-09):
+    /// guard on <see cref="SelfUpdater.LastVersionCheckSucceeded"/>, the relaxed
+    /// timeouts/trigger it passes to the updater, and the swallow-everything exception
+    /// contract (bootstrap must continue on any updater failure). Uses the
+    /// <see cref="AgentBootstrap.UpdateInvokerOverride"/> seam — no network, no process
+    /// side effects.
+    /// <para>
+    /// Static-hook state: each test saves/restores both statics in ctor/Dispose so
+    /// parallel-running test classes never observe a leaked value (idiom of
+    /// SelfUpdaterGracefulShutdownTests).
+    /// </para>
+    /// </summary>
+    public sealed class AgentBootstrapSelfUpdateRetryTests : IDisposable
+    {
+        private readonly AgentBootstrap.SelfUpdateInvoker _savedInvoker;
+        private readonly bool _savedVersionCheckFlag;
+
+        public AgentBootstrapSelfUpdateRetryTests()
+        {
+            _savedInvoker = AgentBootstrap.UpdateInvokerOverride;
+            _savedVersionCheckFlag = SelfUpdater.LastVersionCheckSucceeded;
+            AgentBootstrap.UpdateInvokerOverride = null;
+            SelfUpdater.LastVersionCheckSucceeded = false;
+        }
+
+        public void Dispose()
+        {
+            AgentBootstrap.UpdateInvokerOverride = _savedInvoker;
+            SelfUpdater.LastVersionCheckSucceeded = _savedVersionCheckFlag;
+        }
+
+        private static AgentLogger NewLogger(string path)
+            => new AgentLogger(Path.Combine(path, "logs"), AgentLogLevel.Info);
+
+        [Fact]
+        public void Skips_retry_when_startup_version_check_already_succeeded()
+        {
+            using var tmp = new TempDirectory();
+            var invoked = false;
+            SelfUpdater.LastVersionCheckSucceeded = true;
+            AgentBootstrap.UpdateInvokerOverride = (v, dir, console, reason, dl, downgrade, vc) =>
+            {
+                invoked = true;
+                return Task.CompletedTask;
+            };
+
+            AgentBootstrap.RetrySelfUpdateAfterEnrollment(NewLogger(tmp.Path), consoleMode: false);
+
+            Assert.False(invoked);
+        }
+
+        [Fact]
+        public void Retries_with_await_enrollment_trigger_and_relaxed_timeouts()
+        {
+            using var tmp = new TempDirectory();
+            string? capturedVersion = null, capturedDir = null, capturedReason = null;
+            bool? capturedConsole = null, capturedDowngrade = null;
+            int capturedDownloadMs = 0, capturedVersionCheckMs = 0;
+            AgentBootstrap.UpdateInvokerOverride = (v, dir, console, reason, dl, downgrade, vc) =>
+            {
+                capturedVersion = v;
+                capturedDir = dir;
+                capturedConsole = console;
+                capturedReason = reason;
+                capturedDownloadMs = dl;
+                capturedDowngrade = downgrade;
+                capturedVersionCheckMs = vc;
+                return Task.CompletedTask;
+            };
+
+            AgentBootstrap.RetrySelfUpdateAfterEnrollment(NewLogger(tmp.Path), consoleMode: true);
+
+            Assert.Equal("await_enrollment", capturedReason);
+            // Relaxed vs. the boot-speed-tuned startup check (10s/2.5s) — enrollment is
+            // already past OOBE's critical path here.
+            Assert.Equal(60000, capturedDownloadMs);
+            Assert.Equal(10000, capturedVersionCheckMs);
+            // No cached remote config on a fresh --await-enrollment install → no downgrade override.
+            Assert.False(capturedDowngrade);
+            Assert.True(capturedConsole);
+            Assert.False(string.IsNullOrEmpty(capturedVersion));
+            Assert.False(string.IsNullOrEmpty(capturedDir));
+        }
+
+        [Fact]
+        public void Synchronous_invoker_exception_is_swallowed()
+        {
+            using var tmp = new TempDirectory();
+            AgentBootstrap.UpdateInvokerOverride =
+                (v, dir, console, reason, dl, downgrade, vc) => throw new InvalidOperationException("boom");
+
+            var ex = Record.Exception(
+                () => AgentBootstrap.RetrySelfUpdateAfterEnrollment(NewLogger(tmp.Path), consoleMode: false));
+
+            Assert.Null(ex);
+        }
+
+        [Fact]
+        public void Faulted_update_task_is_swallowed()
+        {
+            using var tmp = new TempDirectory();
+            AgentBootstrap.UpdateInvokerOverride = (v, dir, console, reason, dl, downgrade, vc) =>
+                Task.FromException(new IOException("download interrupted"));
+
+            var ex = Record.Exception(
+                () => AgentBootstrap.RetrySelfUpdateAfterEnrollment(NewLogger(tmp.Path), consoleMode: false));
+
+            Assert.Null(ex);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Program/InstallModeMergeTests.cs

@@ -132,10 +132,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
         }
 
         [Fact]
-        public void First_install_without_wait_arg_uses_agent_default_of_600()
+        public void First_install_without_wait_arg_persists_null_so_runtime_default_applies()
         {
             // Generic bootstrap path: PS1 calls `--install` without --tenant-id-wait,
-            // and there is no persisted config yet. Agent owns the default (600 s).
+            // and there is no persisted config yet. "Not configured" is persisted as null
+            // so BuildAgentConfiguration applies the agent-side default (600 s) — freezing
+            // a number into the file would decouple deployed devices from default changes.
             var merged = AutopilotMonitor.Agent.V2.Program.MergeBootstrapConfig(
                 existing: null,
                 bootstrapTokenArg: null!, bootstrapTokenGiven: false,
@@ -144,20 +146,42 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
 
             Assert.Null(merged.BootstrapToken);
             Assert.Null(merged.TenantId);
-            Assert.Equal(600, merged.TenantIdWaitSeconds);
+            Assert.Null(merged.TenantIdWaitSeconds);
         }
 
         [Fact]
-        public void Existing_config_without_wait_field_treated_as_zero()
+        public void Legacy_config_without_wait_field_stays_null_on_plain_reinstall()
         {
-            // BackCompat: pre-fix bootstrap-config.json has no TenantIdWaitSeconds field;
-            // Newtonsoft deserialises that to 0. New install with --tenant-id-wait 600
-            // overrides cleanly; no extra migration logic required.
+            // BackCompat: pre-feature bootstrap-config.json has no TenantIdWaitSeconds
+            // property → nullable deserialisation yields null. A reinstall that does not
+            // pass --tenant-id-wait must NOT turn that into 0 (which would silently
+            // disable the wait); null carries through and the runtime default applies.
             var existing = new BootstrapConfigFile
             {
                 BootstrapToken = "tok-legacy",
                 TenantId = "tenant-legacy",
-                TenantIdWaitSeconds = 0,
+                TenantIdWaitSeconds = null,
+            };
+
+            var merged = AutopilotMonitor.Agent.V2.Program.MergeBootstrapConfig(
+                existing,
+                bootstrapTokenArg: null!, bootstrapTokenGiven: false,
+                tenantIdArg: null!, tenantIdGiven: false,
+                tenantIdWaitSeconds: 0, tenantIdWaitGiven: false);
+
+            Assert.Equal("tok-legacy", merged.BootstrapToken);
+            Assert.Equal("tenant-legacy", merged.TenantId);
+            Assert.Null(merged.TenantIdWaitSeconds);
+        }
+
+        [Fact]
+        public void Legacy_config_without_wait_field_takes_explicit_wait_arg()
+        {
+            var existing = new BootstrapConfigFile
+            {
+                BootstrapToken = "tok-legacy",
+                TenantId = "tenant-legacy",
+                TenantIdWaitSeconds = null,
             };
 
             var merged = AutopilotMonitor.Agent.V2.Program.MergeBootstrapConfig(
@@ -170,5 +194,26 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
             Assert.Equal("tenant-legacy", merged.TenantId);
             Assert.Equal(600, merged.TenantIdWaitSeconds);
         }
+
+        [Fact]
+        public void Explicit_zero_opt_out_survives_redeploy_without_wait_arg()
+        {
+            // An admin's deliberate `--tenant-id-wait 0` must not be resurrected to a
+            // wait by a later redeploy that omits the flag.
+            var existing = new BootstrapConfigFile
+            {
+                BootstrapToken = "tok-abc",
+                TenantId = "tenant-xyz",
+                TenantIdWaitSeconds = 0,
+            };
+
+            var merged = AutopilotMonitor.Agent.V2.Program.MergeBootstrapConfig(
+                existing,
+                bootstrapTokenArg: null!, bootstrapTokenGiven: false,
+                tenantIdArg: null!, tenantIdGiven: false,
+                tenantIdWaitSeconds: 0, tenantIdWaitGiven: false);
+
+            Assert.Equal(0, merged.TenantIdWaitSeconds);
+        }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Program/PostEnrollmentFactsObservedSignalTests.cs

@@ -66,6 +66,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
             // same facts signal (safe default "false" off-device).
             var selfDeploying = payload["isSelfDeployingProfile"];
             Assert.True(selfDeploying == "true" || selfDeploying == "false");
+            // W365 — the Cloud PC marker fact rides the same signal (safe default "false"
+            // off-device; a build host is not a Cloud PC).
+            Assert.Contains("isCloudPc", (IDictionary<string, string>)payload);
+            var cloudPc = payload["isCloudPc"];
+            Assert.True(cloudPc == "true" || cloudPc == "false");
         }
 
         [Fact]

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Program/TenantIdWaitResolutionTests.cs

@@ -0,0 +1,90 @@
+using AutopilotMonitor.Agent.V2;
+using AutopilotMonitor.Agent.V2.Core.Configuration;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Program
+{
+    /// <summary>
+    /// Pins the TenantIdWaitSeconds resolution order in
+    /// <see cref="AutopilotMonitor.Agent.V2.Program.BuildAgentConfiguration"/>:
+    /// CLI arg &gt; persisted bootstrap-config.json value &gt; agent default (600 s).
+    /// The regression this guards: a legacy bootstrap-config.json written before the
+    /// TenantIdWaitSeconds property existed deserialises to null — that must fall
+    /// through to the 600 s default, NOT be treated as an explicit 0 opt-out
+    /// (which silently disabled the wait and broke Hybrid-AAD-join devices whose
+    /// registry TenantId lands minutes after first boot).
+    /// </summary>
+    public sealed class TenantIdWaitResolutionTests
+    {
+        private static AgentConfiguration Build(BootstrapConfigFile? bootstrapConfig, params string[] args) =>
+            AutopilotMonitor.Agent.V2.Program.BuildAgentConfiguration(
+                args: args,
+                tenantId: "tenant-t",
+                sessionId: "session-s",
+                bootstrapConfig: bootstrapConfig,
+                awaitConfig: null);
+
+        [Fact]
+        public void No_cli_and_no_bootstrap_config_uses_default_600()
+        {
+            var cfg = Build(bootstrapConfig: null);
+
+            Assert.Equal(600, cfg.TenantIdWaitSeconds);
+        }
+
+        [Fact]
+        public void Legacy_bootstrap_config_with_null_wait_uses_default_600()
+        {
+            var legacy = new BootstrapConfigFile
+            {
+                BootstrapToken = "tok-legacy",
+                TenantId = "tenant-legacy",
+                TenantIdWaitSeconds = null,
+            };
+
+            var cfg = Build(legacy);
+
+            Assert.Equal(600, cfg.TenantIdWaitSeconds);
+        }
+
+        [Fact]
+        public void Explicit_zero_in_bootstrap_config_disables_wait()
+        {
+            var optedOut = new BootstrapConfigFile { TenantIdWaitSeconds = 0 };
+
+            var cfg = Build(optedOut);
+
+            Assert.Equal(0, cfg.TenantIdWaitSeconds);
+        }
+
+        [Fact]
+        public void Nonzero_bootstrap_config_value_wins_over_default()
+        {
+            var configured = new BootstrapConfigFile { TenantIdWaitSeconds = 1800 };
+
+            var cfg = Build(configured);
+
+            Assert.Equal(1800, cfg.TenantIdWaitSeconds);
+        }
+
+        [Fact]
+        public void Cli_arg_wins_over_bootstrap_config_value()
+        {
+            var configured = new BootstrapConfigFile { TenantIdWaitSeconds = 1800 };
+
+            var cfg = Build(configured, "--tenant-id-wait", "300");
+
+            Assert.Equal(300, cfg.TenantIdWaitSeconds);
+        }
+
+        [Fact]
+        public void Cli_zero_wins_over_bootstrap_config_value()
+        {
+            var configured = new BootstrapConfigFile { TenantIdWaitSeconds = 1800 };
+
+            var cfg = Build(configured, "--tenant-id-wait", "0");
+
+            Assert.Equal(0, cfg.TenantIdWaitSeconds);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Security/AuthFailureTrackerTests.cs

@@ -260,6 +260,60 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Security
             Assert.Contains("agent/config", fakeDistress.Calls[0].Message);
         }
 
+        [Fact]
+        public void RecordFailure_endpoint_unavailable_suppresses_distress_but_still_counts()
+        {
+            var clock = new FakeClock(new DateTime(2026, 4, 21, 10, 0, 0, DateTimeKind.Utc));
+            var fakeDistress = new FakeDistressReporter();
+            var tracker = new AuthFailureTracker(maxFailures: 2, timeoutMinutes: 0, clock, NewLogger(), fakeDistress);
+
+            int events = 0;
+            tracker.ThresholdExceeded += (_, _) => events++;
+
+            // Platform-403s from a stopped endpoint: a distress report cannot reach it and the
+            // DeviceNotRegistered classification would be wrong — nothing must be dispatched.
+            tracker.RecordFailure(403, "agent/config", endpointUnavailable: true);
+            tracker.RecordFailure(403, "agent/register-session", endpointUnavailable: true);
+
+            Assert.Empty(fakeDistress.Calls);
+            // The shutdown thresholds still apply — a dead endpoint must not retry forever.
+            Assert.Equal(2, tracker.ConsecutiveFailures);
+            Assert.Equal(1, events);
+        }
+
+        [Fact]
+        public void RecordFailure_endpoint_unavailable_does_not_consume_streak_report_slot()
+        {
+            var clock = new FakeClock(new DateTime(2026, 4, 21, 10, 0, 0, DateTimeKind.Utc));
+            var fakeDistress = new FakeDistressReporter();
+            var tracker = new AuthFailureTracker(maxFailures: 50, timeoutMinutes: 0, clock, NewLogger(), fakeDistress);
+
+            // The streak opens with a platform-403 (no dispatch), then a live backend answers
+            // with a genuine 403 — that one must still produce the streak's single report.
+            tracker.RecordFailure(403, "agent/config", endpointUnavailable: true);
+            tracker.RecordFailure(403, "agent/config");
+            tracker.RecordFailure(403, "agent/config");
+
+            Assert.Single(fakeDistress.Calls);
+            Assert.Equal(DistressErrorType.DeviceNotRegistered, fakeDistress.Calls[0].ErrorType);
+        }
+
+        [Fact]
+        public void RecordSuccess_rearms_distress_dispatch_for_the_next_streak()
+        {
+            var clock = new FakeClock(new DateTime(2026, 4, 21, 10, 0, 0, DateTimeKind.Utc));
+            var fakeDistress = new FakeDistressReporter();
+            var tracker = new AuthFailureTracker(maxFailures: 50, timeoutMinutes: 0, clock, NewLogger(), fakeDistress);
+
+            tracker.RecordFailure(401, "agent/config");
+            tracker.RecordSuccess();
+            tracker.RecordFailure(403, "agent/config");
+
+            Assert.Equal(2, fakeDistress.Calls.Count);
+            Assert.Equal(DistressErrorType.AuthCertificateRejected, fakeDistress.Calls[0].ErrorType);
+            Assert.Equal(DistressErrorType.DeviceNotRegistered, fakeDistress.Calls[1].ErrorType);
+        }
+
         [Fact]
         public void RecordFailure_without_distress_reporter_is_silent_but_still_tracks()
         {

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Security/CloudPcDetectorTests.cs

@@ -0,0 +1,74 @@
+using System;
+using System.Collections.Generic;
+using AutopilotMonitor.Agent.V2.Core.Security;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Security
+{
+    /// <summary>
+    /// Pins the marker-AND contract of <see cref="CloudPcDetector.ResolveIsCloudPc"/>: BOTH
+    /// the Windows365 registry key and the CloudManagedDesktopExtension service key must be
+    /// present — each alone has plausible look-alikes (W365-Boot physical clients carry
+    /// Windows365 policy state; the MCMD agent family served other managed-desktop
+    /// offerings). Mirrors the bootstrap script's field-verified <c>Test-IsCloudPc</c>.
+    /// </summary>
+    public sealed class CloudPcDetectorTests
+    {
+        private static Func<string, bool> Probe(params string[] existingKeys)
+        {
+            var set = new HashSet<string>(existingKeys, StringComparer.OrdinalIgnoreCase);
+            return path => set.Contains(path);
+        }
+
+        [Fact]
+        public void Both_markers_present_resolves_true()
+        {
+            Assert.True(CloudPcDetector.ResolveIsCloudPc(Probe(
+                CloudPcDetector.Windows365MarkerKey,
+                CloudPcDetector.CmdeServiceKey)));
+        }
+
+        [Fact]
+        public void Windows365_key_alone_resolves_false()
+        {
+            // W365-Boot physical client shape: policy state without the on-device MCMD agent.
+            Assert.False(CloudPcDetector.ResolveIsCloudPc(Probe(CloudPcDetector.Windows365MarkerKey)));
+        }
+
+        [Fact]
+        public void Cmde_service_alone_resolves_false()
+        {
+            // MCMD agent family also served other managed-desktop offerings.
+            Assert.False(CloudPcDetector.ResolveIsCloudPc(Probe(CloudPcDetector.CmdeServiceKey)));
+        }
+
+        [Fact]
+        public void No_markers_resolves_false()
+        {
+            Assert.False(CloudPcDetector.ResolveIsCloudPc(Probe()));
+        }
+
+        [Fact]
+        public void Null_probe_resolves_false()
+        {
+            Assert.False(CloudPcDetector.ResolveIsCloudPc(null));
+        }
+
+        [Fact]
+        public void Throwing_probe_degrades_to_false()
+        {
+            // SKIP-safe contract: a broken registry read must never classify, let alone throw.
+            Assert.False(CloudPcDetector.ResolveIsCloudPc(_ => throw new UnauthorizedAccessException("registry denied")));
+        }
+
+        [Fact]
+        public void DetectIsCloudPc_never_throws_on_build_host()
+        {
+            // Real-registry shell: exercises the exception-swallowing wrapper end to end.
+            // A build host is not a Cloud PC, but the contract under test is "no throw",
+            // not the detected value.
+            var ex = Record.Exception(() => CloudPcDetector.DetectIsCloudPc());
+            Assert.Null(ex);
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Security/SessionRegistrationHelperTests.cs

@@ -137,6 +137,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Security
             Assert.Equal(Environment.MachineName, captured.DeviceName);
             Assert.False(string.IsNullOrEmpty(captured.EnrollmentType));
             Assert.True(captured.IsUserDriven);
+            // W365 marker rides the registration body. A build host is not a Cloud PC
+            // (marker-AND: Windows365 key + CloudManagedDesktopExtension service), so the
+            // detector's SKIP-safe default is what must land here.
+            Assert.False(captured.IsCloudPc);
         }
 
         [Fact]

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

@@ -83,13 +83,36 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
             using var adapter = new ImeLogTrackerAdapter(f.Tracker, f.Ingress, f.Clock);
             var app = new AppPackageState("app-do", 0);
 
-            f.Tracker.LastMatchedLogTimestamp = ClockNow.AddDays(-7);
-            adapter.TriggerDoTelemetryFromTest(app);
+            // Line-grounded path: the [DO TEL] line's own timestamp travels with the callback.
+            adapter.TriggerDoTelemetryFromTest(app, ClockNow.AddDays(-7));
             Assert.Empty(f.InfoEvents(SharedEventTypes.DoTelemetry));
 
-            f.Tracker.LastMatchedLogTimestamp = ClockNow.AddMinutes(-1);
-            adapter.TriggerDoTelemetryFromTest(app);
-            Assert.Single(f.InfoEvents(SharedEventTypes.DoTelemetry));
+            adapter.TriggerDoTelemetryFromTest(app, ClockNow.AddMinutes(-1));
+            var info = Assert.Single(f.InfoEvents(SharedEventTypes.DoTelemetry));
+            Assert.Equal(ClockNow.AddMinutes(-1), info.OccurredAtUtc);
+        }
+
+        [Fact]
+        public void Poll_driven_do_telemetry_stamps_clock_ignoring_unrelated_last_matched_line()
+        {
+            // Session df1fcf47: the DO collector observed the completion live, but the event
+            // inherited LastMatchedLogTimestamp from an unrelated, tz-skewed log line 8h in
+            // the past — which dragged Sessions.StartedAt back and inflated the duration.
+            // Poll-driven telemetry (null source timestamp) must stamp the clock, never the
+            // last matched line.
+            using var f = new ImeLogTrackerAdapterFixture(ClockNow);
+            using var adapter = new ImeLogTrackerAdapter(f.Tracker, f.Ingress, f.Clock);
+            var app = new AppPackageState("app-do-poll", 0);
+
+            f.Tracker.LastMatchedLogTimestamp = ClockNow.AddHours(-8);
+            adapter.TriggerDoTelemetryFromTest(app, sourceTimestampUtc: null);
+
+            var info = Assert.Single(f.InfoEvents(SharedEventTypes.DoTelemetry));
+            Assert.Equal(ClockNow, info.OccurredAtUtc);
+            Assert.Equal("true", info.Payload!["derivedTimestamp"]);
+            // Not a replay — live observation must never trip the replay suppression,
+            // even with a stale unrelated line on the tracker.
+            Assert.Empty(f.InfoEvents(SharedEventTypes.HistoricImeReplayDetected));
         }
 
         [Fact]

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

@@ -647,13 +647,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
             int priorDoCalls = 0;
             int priorScriptCalls = 0;
             f.Tracker.OnImeAgentVersion = _ => priorVersionCalls++;
-            f.Tracker.OnDoTelemetryReceived = _ => priorDoCalls++;
+            f.Tracker.OnDoTelemetryReceived = (_, _) => priorDoCalls++;
             f.Tracker.OnScriptCompleted = _ => priorScriptCalls++;
 
             using var adapter = new ImeLogTrackerAdapter(f.Tracker, f.Ingress, f.Clock);
 
             f.Tracker.OnImeAgentVersion("1.0.0.0");
-            f.Tracker.OnDoTelemetryReceived(new AppPackageState("app-1", 0));
+            f.Tracker.OnDoTelemetryReceived(new AppPackageState("app-1", 0), null);
             f.Tracker.OnScriptCompleted(new ScriptExecutionState { PolicyId = "p", ScriptType = "platform" });
 
             Assert.Equal(1, priorVersionCalls);
@@ -667,7 +667,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
         {
             using var f = new ImeLogTrackerAdapterFixture();
             Action<string> priorVersion = _ => { };
-            Action<AppPackageState> priorDo = _ => { };
+            Action<AppPackageState, DateTime?> priorDo = (_, _) => { };
             Action<ScriptExecutionState> priorScript = _ => { };
             f.Tracker.OnImeAgentVersion = priorVersion;
             f.Tracker.OnDoTelemetryReceived = priorDo;

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Telemetry/DeviceInfo/DeviceInfoCollectorAutopilotProfileMissingTests.cs

@@ -1,5 +1,6 @@
 using System.Collections.Generic;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo;
+using AutopilotMonitor.Shared.Models;
 using Xunit;
 
 namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry.DeviceInfo;
@@ -109,4 +110,28 @@ public class DeviceInfoCollectorAutopilotProfileMissingTests
         Assert.False(DeviceInfoCollector.TryExtractZeroTouchTenantDomain(null, out var domain));
         Assert.Null(domain);
     }
+
+    [Fact]
+    public void ResolveAutopilotProfileMissingPresentation_PhysicalDevice_WarnsAboutAssignment()
+    {
+        var (message, severity) = DeviceInfoCollector.ResolveAutopilotProfileMissingPresentation(isCloudPc: false);
+
+        Assert.Equal(EventSeverity.Warning, severity);
+        Assert.Equal(
+            "No Autopilot profile was available during OOBE (ProfileAvailable=0) — most likely no deployment profile was assigned to the device, or the assignment had not finished propagating when OOBE ran. OOBE proceeded as a standard Entra ID join instead of an Autopilot deployment.",
+            message);
+    }
+
+    [Fact]
+    public void ResolveAutopilotProfileMissingPresentation_CloudPc_InformationalAndExpected()
+    {
+        // On a Windows 365 Cloud PC a missing Autopilot profile is the normal state —
+        // the event must not read as an alarm there.
+        var (message, severity) = DeviceInfoCollector.ResolveAutopilotProfileMissingPresentation(isCloudPc: true);
+
+        Assert.Equal(EventSeverity.Info, severity);
+        Assert.Contains("Windows 365 Cloud PC", message);
+        Assert.Contains("expected", message);
+        Assert.DoesNotContain("no deployment profile was assigned", message);
+    }
 }

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

@@ -153,6 +153,58 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Telemetry.Events
             Assert.Equal("Device Setup", (string?)parsed["PhaseName"]);
         }
 
+        [Fact]
+        public void Emit_publishes_eventType_and_parsed_phase_to_TimelineEventStream()
+        {
+            // Post-reduce observer surface: gather-rule phase/event triggers subscribe here so
+            // they fire in step with what the timeline shows (session 32312a32 regression).
+            using var r = new Rig();
+            var stream = new AutopilotMonitor.Agent.V2.Core.Orchestration.TimelineEventStream();
+            var published = new List<(string EventType, EnrollmentPhase Phase)>();
+            stream.EventEmitted += (eventType, phase) => published.Add((eventType, phase));
+            var sut = new EventTimelineEmitter(r.Inner, stream);
+
+            sut.Emit(
+                new Dictionary<string, string>
+                {
+                    ["eventType"] = "phase_transition",
+                    ["phase"] = "FinalizingSetup",
+                },
+                State(),
+                At);
+            sut.Emit(
+                new Dictionary<string, string> { ["eventType"] = "enrollment_complete" },
+                State(),
+                At);
+
+            Assert.Equal(2, published.Count);
+            Assert.Equal(("phase_transition", EnrollmentPhase.FinalizingSetup), published[0]);
+            Assert.Equal(("enrollment_complete", EnrollmentPhase.Unknown), published[1]);
+            // Publish happens AFTER the transport enqueue — wire ordering is authoritative.
+            Assert.Equal(2, r.Transport.EnqueueCount);
+        }
+
+        [Fact]
+        public void TimelineEventStream_subscriber_exception_does_not_break_the_emit_path()
+        {
+            using var r = new Rig();
+            var stream = new AutopilotMonitor.Agent.V2.Core.Orchestration.TimelineEventStream();
+            var secondSubscriberCalls = 0;
+            stream.EventEmitted += (_, _) => throw new InvalidOperationException("subscriber bug");
+            stream.EventEmitted += (_, _) => secondSubscriberCalls++;
+            var sut = new EventTimelineEmitter(r.Inner, stream);
+
+            sut.Emit(
+                new Dictionary<string, string> { ["eventType"] = "enrollment_complete" },
+                State(),
+                At);
+
+            // Emit neither threw (would surface as an EffectRunner retry = duplicated event)
+            // nor skipped the remaining subscribers.
+            Assert.Equal(1, r.Transport.EnqueueCount);
+            Assert.Equal(1, secondSubscriberCalls);
+        }
+
         [Fact]
         public void Phase_parameter_with_invalid_value_falls_back_to_Unknown()
         {

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Termination/EnrollmentTerminationHandlerTests.cs

@@ -511,6 +511,88 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Termination
                 $"network_bandwidth_estimate (@{bandwidthIdx}) must precede whiteglove_part1_complete (@{part1CompleteIdx}) so the straggler stays in Part 1.");
         }
 
+        // ===================================================== WG Part-1 preprov diagnostics
+        // V1 parity (restored 2026-07-28): the seal exit uploads the diagnostics package as a
+        // pre-provisioning intermediate under the SAME mode gating as the terminal path — the
+        // seal counts as a success, so Always uploads, OnFailure skips (a Part-1 failure
+        // terminates via the regular Failed path, which uploads), Off does nothing.
+
+        [Theory]
+        [InlineData("Always", true, 1)]
+        [InlineData("OnFailure", true, 0)]
+        [InlineData("Off", true, 0)]
+        [InlineData("Always", false, 0)]
+        public void Handle_whiteglove_part1_diagnostics_upload_respects_mode(
+            string mode, bool enabled, int expected)
+        {
+            using var rig = new Rig();
+            rig.State = new DecisionStateBuilder(DecisionState.CreateInitial("S1", "T1")) { Stage = SessionStage.WhiteGloveSealed }.Build();
+            var cfg = rig.BuildConfig(diagEnabled: enabled, diagMode: mode);
+
+            rig.Build(cfg).Handle(sender: null!,
+                Args(EnrollmentTerminationReason.DecisionTerminalStage, EnrollmentTerminationOutcome.Succeeded, SessionStage.WhiteGloveSealed));
+
+            Assert.Equal(expected, rig.DiagnosticsUploads);
+        }
+
+        [Fact]
+        public void Handle_whiteglove_part1_diagnostics_upload_uses_preprov_suffix_and_succeeded_flag()
+        {
+            using var rig = new Rig();
+            rig.State = new DecisionStateBuilder(DecisionState.CreateInitial("S1", "T1")) { Stage = SessionStage.WhiteGloveSealed }.Build();
+            var cfg = rig.BuildConfig(diagEnabled: true, diagMode: "Always");
+
+            rig.Build(cfg).Handle(sender: null!,
+                Args(EnrollmentTerminationReason.DecisionTerminalStage, EnrollmentTerminationOutcome.Succeeded, SessionStage.WhiteGloveSealed));
+
+            Assert.Equal(1, rig.DiagnosticsUploads);
+            Assert.Equal("preprov", rig.LastDiagnosticsSuffix);
+            Assert.Equal(true, rig.LastDiagnosticsSucceededFlag);
+        }
+
+        [Fact]
+        public void Handle_whiteglove_part1_diagnostics_events_precede_part1_complete_marker()
+        {
+            // whiteglove_part1_complete is the authoritative Part-1/Part-2 boundary for the
+            // web split (computeWhiteGloveSplitSequence) — diagnostics_collecting/uploaded
+            // must sequence BEFORE it or they get mis-filed into the resumed Part-2 block.
+            using var rig = new Rig();
+            rig.State = new DecisionStateBuilder(DecisionState.CreateInitial("S1", "T1")) { Stage = SessionStage.WhiteGloveSealed }.Build();
+            rig.DiagnosticsResult = new DiagnosticsUploadResult { BlobName = "diag-preprov.zip" };
+            var cfg = rig.BuildConfig(diagEnabled: true, diagMode: "Always");
+
+            rig.Build(cfg).Handle(sender: null!,
+                Args(EnrollmentTerminationReason.DecisionTerminalStage, EnrollmentTerminationOutcome.Succeeded, SessionStage.WhiteGloveSealed));
+
+            var emitted = rig.EmittedEventTypes.ToList();
+            var collectingIdx = emitted.IndexOf("diagnostics_collecting");
+            var uploadedIdx = emitted.IndexOf("diagnostics_uploaded");
+            var part1CompleteIdx = emitted.IndexOf(Constants.EventTypes.WhiteGlovePart1Complete);
+
+            Assert.True(collectingIdx >= 0, "diagnostics_collecting must have been emitted.");
+            Assert.True(uploadedIdx >= 0, "diagnostics_uploaded must have been emitted.");
+            Assert.True(part1CompleteIdx >= 0, "whiteglove_part1_complete must have been emitted.");
+            Assert.True(uploadedIdx < part1CompleteIdx,
+                $"diagnostics_uploaded (@{uploadedIdx}) must precede whiteglove_part1_complete (@{part1CompleteIdx}) so the upload stays in Part 1.");
+        }
+
+        [Fact]
+        public void Handle_whiteglove_part1_still_skips_cleanup_and_marker_when_diagnostics_enabled()
+        {
+            // The preprov upload must not change the Part-1 exit contract: no self-destruct,
+            // no enrollment-complete.marker, whiteglove.complete still written.
+            using var rig = new Rig();
+            rig.State = new DecisionStateBuilder(DecisionState.CreateInitial("S1", "T1")) { Stage = SessionStage.WhiteGloveSealed }.Build();
+            var cfg = rig.BuildConfig(diagEnabled: true, diagMode: "Always");
+
+            rig.Build(cfg).Handle(sender: null!,
+                Args(EnrollmentTerminationReason.DecisionTerminalStage, EnrollmentTerminationOutcome.Succeeded, SessionStage.WhiteGloveSealed));
+
+            Assert.Equal(0, rig.CleanupService.Invocations);
+            Assert.False(File.Exists(Path.Combine(rig.StateDir, "enrollment-complete.marker")));
+            Assert.True(rig.SessionPersistence.IsWhiteGloveResume());
+        }
+
         [Fact]
         public void Handle_standalone_reboot_fires_when_reboot_enabled_and_no_self_destruct()
         {

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Termination/ObservationCoverageTests.cs

@@ -1,5 +1,7 @@
 using System;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
 using AutopilotMonitor.Agent.V2.Core.Termination;
+using AutopilotMonitor.Shared.Models;
 using Xunit;
 
 namespace AutopilotMonitor.Agent.V2.Core.Tests.Termination
@@ -70,5 +72,82 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Termination
             Assert.Equal(0, bootToStart, 0);
             Assert.Equal(10, uptime, 0);
         }
+
+        // --- DescribeLateStart: outcome-calibrated severity + phrasing (fleet 2026-07-28) ---
+
+        private static void Describe(
+            EnrollmentTerminationOutcome outcome, string oobeState,
+            out EventSeverity severity, out string message, out string note)
+            => ObservationCoverage.DescribeLateStart(
+                outcome, oobeState, bootToStartSeconds: 34 * 60, uptimeSeconds: 30,
+                out severity, out message, out note);
+
+        [Fact]
+        public void Failed_outcome_is_a_warning_with_the_hung_script_post_mortem_note()
+        {
+            Describe(EnrollmentTerminationOutcome.Failed, "in_progress",
+                out var severity, out var message, out var note);
+
+            Assert.Equal(EventSeverity.Warning, severity);
+            Assert.Contains("low coverage of the enrollment window", message);
+            Assert.Contains("post-mortem", note);
+            Assert.Contains("hung ahead of the bootstrap", note);
+        }
+
+        [Fact]
+        public void TimedOut_outcome_is_a_warning_like_a_failure()
+        {
+            Describe(EnrollmentTerminationOutcome.TimedOut, "in_progress",
+                out var severity, out _, out var note);
+
+            Assert.Equal(EventSeverity.Warning, severity);
+            Assert.Contains("post-mortem", note);
+        }
+
+        [Fact]
+        public void Succeeded_outcome_is_an_info_about_tail_only_coverage_without_alarm_framing()
+        {
+            // The 659c3a90 shape: healthy enrollment, bootstrap merely ran late in the ESP queue.
+            Describe(EnrollmentTerminationOutcome.Succeeded, "in_progress",
+                out var severity, out _, out var note);
+
+            Assert.Equal(EventSeverity.Info, severity);
+            Assert.Contains("succeeded", note);
+            Assert.Contains("IME log replay", note);
+            Assert.DoesNotContain("post-mortem", note);
+            Assert.DoesNotContain("hung", note);
+        }
+
+        [Fact]
+        public void Oobe_completed_at_start_phrases_a_pure_post_mortem()
+        {
+            Describe(EnrollmentTerminationOutcome.Failed, "completed",
+                out _, out var message, out _);
+
+            Assert.Contains("OOBE was already completed when the agent started", message);
+        }
+
+        [Fact]
+        public void Oobe_in_progress_at_start_phrases_the_live_tail()
+        {
+            Describe(EnrollmentTerminationOutcome.Failed, "in_progress",
+                out _, out var message, out _);
+
+            Assert.Contains("OOBE was still in progress at agent start", message);
+            Assert.Contains("final 30s live", message);
+        }
+
+        [Theory]
+        [InlineData("not_started")]  // flips in after a mid-OOBE reboot — not interpretable
+        [InlineData("unavailable")]  // WinRT contract absent / read failed
+        [InlineData("unknown_3")]    // unexpected enum value
+        public void Uninterpretable_oobe_states_add_no_claim_to_the_message(string oobeState)
+        {
+            Describe(EnrollmentTerminationOutcome.Failed, oobeState,
+                out _, out var message, out _);
+
+            Assert.DoesNotContain("OOBE", message);
+            Assert.EndsWith("low coverage of the enrollment window.", message);
+        }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Transport/BackendApiClientAuthClassificationTests.cs

@@ -0,0 +1,110 @@
+#nullable enable
+using System;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Transport;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Transport
+{
+    /// <summary>
+    /// 401/403 classification in <see cref="BackendApiClient"/>: a backend JSON 403 is a real
+    /// device-authorization verdict, while an HTML body means the response came from the Azure
+    /// platform / an edge proxy (stopped or retired app) and must NOT be reported as
+    /// "device is not authorized". Field case sits-d.cloud 2026-08-09: a pre-cutover agent hit
+    /// the stopped legacy Function App and support chased a non-existent authorization problem.
+    /// </summary>
+    public sealed class BackendApiClientAuthClassificationTests
+    {
+        private sealed class StubHandler : HttpMessageHandler
+        {
+            private readonly Func<HttpRequestMessage, HttpResponseMessage> _responder;
+            public StubHandler(Func<HttpRequestMessage, HttpResponseMessage> responder) => _responder = responder;
+
+            protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+                => Task.FromResult(_responder(request));
+        }
+
+        private static BackendApiClient BuildClient(HttpStatusCode status, string body, string mediaType)
+        {
+            var handler = new StubHandler(_ => new HttpResponseMessage(status)
+            {
+                Content = new StringContent(body, Encoding.UTF8, mediaType)
+            });
+            return new BackendApiClient(
+                new HttpClient(handler),
+                baseUrl: "https://backend.example",
+                manufacturer: "Contoso",
+                model: "TestBox",
+                serialNumber: "SN123",
+                useBootstrapTokenAuth: false,
+                bootstrapToken: null,
+                agentVersion: "2.0.0",
+                logger: null);
+        }
+
+        [Fact]
+        public async Task Backend_json_403_is_reported_as_device_not_authorized()
+        {
+            using var client = BuildClient(
+                HttpStatusCode.Forbidden,
+                "{\"success\":false,\"message\":\"Device validation failed\"}",
+                "application/json");
+
+            var ex = await Assert.ThrowsAsync<BackendAuthException>(() => client.GetAgentConfigAsync("tenant-1"));
+
+            Assert.Equal(403, ex.StatusCode);
+            Assert.False(ex.EndpointUnavailable);
+            Assert.Contains("The device is not authorized", ex.Message);
+        }
+
+        [Fact]
+        public async Task Platform_html_403_is_reported_as_endpoint_unavailable_with_page_title()
+        {
+            using var client = BuildClient(
+                HttpStatusCode.Forbidden,
+                "<!DOCTYPE html><html><head><title>Web App - Unavailable</title></head><body>stopped</body></html>",
+                "text/html");
+
+            var ex = await Assert.ThrowsAsync<BackendAuthException>(() => client.GetAgentConfigAsync("tenant-1"));
+
+            Assert.Equal(403, ex.StatusCode);
+            Assert.True(ex.EndpointUnavailable);
+            Assert.Contains("Web App - Unavailable", ex.Message);
+            Assert.Contains("NOT a device-authorization failure", ex.Message);
+            Assert.DoesNotContain("Check client certificate", ex.Message);
+        }
+
+        [Fact]
+        public async Task Html_body_with_generic_content_type_is_still_sniffed_as_platform_page()
+        {
+            using var client = BuildClient(
+                HttpStatusCode.Forbidden,
+                "  <html><body>Error 403 - This web app is stopped.</body></html>",
+                "text/plain");
+
+            var ex = await Assert.ThrowsAsync<BackendAuthException>(() => client.GetAgentConfigAsync("tenant-1"));
+
+            Assert.True(ex.EndpointUnavailable);
+            Assert.Contains("HTML platform error page", ex.Message);
+        }
+
+        [Fact]
+        public async Task Backend_401_keeps_authorization_message_and_status()
+        {
+            using var client = BuildClient(
+                HttpStatusCode.Unauthorized,
+                "{\"success\":false,\"message\":\"certificate rejected\"}",
+                "application/json");
+
+            var ex = await Assert.ThrowsAsync<BackendAuthException>(() => client.GetAgentConfigAsync("tenant-1"));
+
+            Assert.Equal(401, ex.StatusCode);
+            Assert.False(ex.EndpointUnavailable);
+            Assert.Contains("The device is not authorized", ex.Message);
+        }
+    }
+}

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

@@ -109,6 +109,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
         /// </summary>
         public bool EnableTimezoneAutoSet { get; set; } = false;
 
+        /// <summary>
+        /// Continue-Anyway observation mode (operator-set tenant opt-in, delivered via
+        /// remote config): stamped into the esp_config_detected decision-signal payload so
+        /// the DecisionEngine defangs a Device-phase ESP terminal failure into a bounded
+        /// 60-min observation instead of failing immediately. Default: false.
+        /// </summary>
+        public bool EnableEspContinueAnywayObservation { get; set; } = false;
+
         /// <summary>
         /// Optional custom path to IME logs directory for testing.
         /// If set, overrides the default %ProgramData%\Microsoft\IntuneManagementExtension\Logs path.
@@ -121,6 +129,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
         /// </summary>
         public string ImeMatchLogPath { get; set; }
 
+        /// <summary>
+        /// Optional path to write a gather-rule evaluation trace (for debugging).
+        /// If empty, no trace is written. Set from remote config (EnableGatherRuleDebugLog)
+        /// or the --gather-debug-log CLI override.
+        /// </summary>
+        public string GatherRuleDebugLogPath { get; set; }
+
         /// <summary>
         /// Path to directory with real IME log files for log replay.
         /// When set, the agent replays these logs with time compression instead of reading live logs.
@@ -265,9 +280,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
         /// CloudDomainJoin keys and re-probes on every change until either resolution
         /// or this timeout. 0 = no wait, fast-fail on miss (legacy behaviour).
         /// <para>
-        /// Set via the install-time CLI flag <c>--tenant-id-wait &lt;sec&gt;</c>, persisted
-        /// to <c>bootstrap-config.json</c>. The PS1 bootstrap script owns the production
-        /// default; the agent itself never assumes one.
+        /// Set via the CLI flag <c>--tenant-id-wait &lt;sec&gt;</c> or a persisted
+        /// <c>bootstrap-config.json</c> value; when neither supplies a value the agent
+        /// applies its own default of 600 s in BuildAgentConfiguration. The 0 default
+        /// here is only the POCO baseline, not the effective runtime default.
         /// </para>
         /// </summary>
         public int TenantIdWaitSeconds { get; set; } = 0;

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

@@ -16,8 +16,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
         /// <summary>
         /// TenantId-wait timeout in seconds, persisted from the <c>--tenant-id-wait</c>
         /// install-time arg. Read by AgentBootstrap when the registry probe finds no
-        /// TenantId on first try. 0 / missing = no wait, legacy fast-fail.
+        /// TenantId on first try. 0 = explicit opt-out (legacy fast-fail).
+        /// Null / missing (files written before this property existed) = not configured —
+        /// the agent-side default (600 s) applies. Nullable so a legacy file without the
+        /// property cannot masquerade as an explicit 0 and silently disable the wait.
         /// </summary>
-        public int TenantIdWaitSeconds { get; set; }
+        public int? TenantIdWaitSeconds { get; set; }
     }
 }

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

@@ -103,6 +103,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
 
             agentConfig.SendTraceEvents = remoteConfig.SendTraceEvents;
 
+            // ---------------- Continue-Anyway observation — remote wins (operator-set tenant
+            //                  opt-in; false must clear a stale cached true).
+            agentConfig.EnableEspContinueAnywayObservation = remoteConfig.EnableEspContinueAnywayObservation;
+
             // ---------------- UnrestrictedMode audit — track old/new for the caller so the
             //                  agent_unrestricted_mode_changed event can fire AFTER the
             //                  orchestrator emitter is alive (V1 parity with
@@ -135,6 +139,24 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                 }
             }
 
+            // ---------------- GatherRuleDebugLog: same bool→path projection as ImeMatchLog
+            //                  above. `true` expands Constants.GatherRuleDebugLogPath, `false`
+            //                  nulls the runtime path unless a --gather-debug-log CLI override
+            //                  supplied a non-default path.
+            if (remoteConfig.EnableGatherRuleDebugLog)
+            {
+                agentConfig.GatherRuleDebugLogPath = Environment.ExpandEnvironmentVariables(Constants.GatherRuleDebugLogPath);
+            }
+            else
+            {
+                var defaultGatherDebugPath = Environment.ExpandEnvironmentVariables(Constants.GatherRuleDebugLogPath);
+                if (string.IsNullOrEmpty(agentConfig.GatherRuleDebugLogPath)
+                    || string.Equals(agentConfig.GatherRuleDebugLogPath, defaultGatherDebugPath, StringComparison.OrdinalIgnoreCase))
+                {
+                    agentConfig.GatherRuleDebugLogPath = null;
+                }
+            }
+
             // ---------------- Upload interval / batch — direct, V1 parity (no > 0 gate so a
             //                  misconfigured tenant can in theory break uploads, but this
             //                  surfaces the config bug instead of silently masking it).

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

@@ -155,7 +155,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                     // see the AuthCertificateRejected/DeviceNotRegistered distress signal
                     // without 100 s of needless retry delay.
                     _logger.Warning($"Config fetch authentication failed: {ex.Message}");
-                    _authFailureTracker?.RecordFailure(ex.StatusCode, "agent/config");
+                    _authFailureTracker?.RecordFailure(ex.StatusCode, "agent/config", ex.EndpointUnavailable);
                     lastException = ex;
                     LastFetchAuthStatusCode = ex.StatusCode;
                     break;
@@ -327,6 +327,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                 KeepLogFile = false,
                 EnableGeoLocation = true,
                 EnableImeMatchLog = false,
+                EnableGatherRuleDebugLog = false,
+                EnableEspContinueAnywayObservation = false,
                 Collectors = CollectorConfiguration.CreateDefault(),
                 GatherRules = new System.Collections.Generic.List<GatherRule>(),
                 ImeLogPatterns = new System.Collections.Generic.List<ImeLogPattern>()

src/Agent/AutopilotMonitor.Agent.V2.Core/Logging/AgentLogger.cs

@@ -197,7 +197,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Logging
         /// <summary>
         /// Sanitizes log messages to prevent log injection attacks.
         /// Escapes control characters that could forge log entries.
-        /// Redaction patterns can be added here later as needed.
+        /// Transliterates typographic punctuation to ASCII: the log file is written as
+        /// UTF-8 without BOM, and customer-side viewers (e.g. Outlook web attachment
+        /// preview) guess cp1252 and render an em dash as mojibake ("—"). Only our own
+        /// punctuation is mapped — genuine non-ASCII payload (device names, paths) is
+        /// kept verbatim. Redaction patterns can be added here later as needed.
         /// </summary>
         private static string SanitizeLogMessage(string message)
         {
@@ -206,6 +210,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Logging
             // Escape newlines and carriage returns to prevent log injection
             message = message.Replace("\r", "\\r").Replace("\n", "\\n");
 
+            message = message
+                .Replace('\u2014', '-')      // — em dash
+                .Replace('\u2013', '-')      // – en dash
+                .Replace("\u2192", "->")     // → arrow
+                .Replace("\u2026", "...")    // … ellipsis
+                .Replace('\u2018', '\'')     // ' left single quote
+                .Replace('\u2019', '\'')     // ' right single quote
+                .Replace('\u201C', '"')      // " left double quote
+                .Replace('\u201D', '"')      // " right double quote
+                .Replace('\u00A0', ' ');     // non-breaking space
+
             return message;
         }
     }

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/Ime/ImeLogTracker.Handlers.cs

@@ -112,7 +112,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
                     $"size={fileSize}, peers={bytesFromPeers} ({peerCachingPct}%), " +
                     $"http={bytesFromHttp}, cache={bytesFromCacheServer}, mode={downloadMode}, duration={downloadDuration}");
 
-                OnDoTelemetryReceived?.Invoke(pkg);
+                OnDoTelemetryReceived?.Invoke(pkg, LastMatchedLogTimestamp);
                 _stateDirty = true;
             }
             catch (Exception ex)

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/Ime/ImeLogTracker.LogProcessing.cs

@@ -7,6 +7,7 @@ using System.Text.RegularExpressions;
 using System.Threading;
 using System.Threading.Tasks;
 using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Shared.Logging;
 using AutopilotMonitor.Shared.Models;
 
 namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/Ime/ImeLogTracker.cs

@@ -194,7 +194,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
         public Action OnAllAppsCompleted { get; set; }
         public Action OnUserSessionCompleted { get; set; }
         public Action<string> OnImeSessionChange { get; set; }
-        public Action<AppPackageState> OnDoTelemetryReceived { get; set; }
+        // Second arg: the [DO TEL] source log line's timestamp when the DO data came from a
+        // log line, null when the DO collector observed the completion live via polling. The
+        // consumer must stamp poll-driven telemetry with the clock — inheriting an unrelated
+        // line's LastMatchedLogTimestamp put a tz-skewed time on the event (session df1fcf47).
+        public Action<AppPackageState, DateTime?> OnDoTelemetryReceived { get; set; }
         public Action<ScriptExecutionState> OnScriptCompleted { get; set; }
 
         /// <summary>

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

@@ -631,10 +631,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals
         /// the regular <see cref="ProcessRecord"/> pipeline with isBackfill=true, so they arrive
         /// as modern_deployment_error events carrying backfilled=true plus the original
         /// timeCreated; the event's own timestamp is emission time, so session StartedAt is not
-        /// dragged backwards. Newest-first, capped, watermark-deduped across restarts.
+        /// dragged backwards. The scan reads newest-first (the cap keeps the newest records),
+        /// but replay is buffered so an Info summary event announces the block BEFORE the errors
+        /// hit the timeline (customer feedback 2026-07-28: an unannounced wall of pre-agent
+        /// Error events reads like a live failure) and the records emit oldest-first, giving the
+        /// timeline sequence the original event-log chronology. Watermark-deduped across restarts.
         /// </summary>
         private void BackfillAutopilotErrors()
         {
+            var buffered = new List<EventRecord>();
             try
             {
                 long watermark;
@@ -649,7 +654,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals
                     ReverseDirection = true
                 };
 
-                int processed = 0, skippedWatermark = 0, droppedOverCap = 0;
+                int skippedWatermark = 0, droppedOverCap = 0;
                 long maxSeen = watermark;
 
                 using (var reader = new EventLogReader(query))
@@ -657,37 +662,48 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals
                     EventRecord record;
                     while ((record = reader.ReadEvent()) != null)
                     {
-                        using (record)
+                        var recordId = record.RecordId ?? 0;
+                        if (recordId > maxSeen) maxSeen = recordId;
+
+                        if (recordId != 0 && recordId <= watermark)
                         {
-                            var recordId = record.RecordId ?? 0;
-                            if (recordId > maxSeen) maxSeen = recordId;
-
-                            if (recordId != 0 && recordId <= watermark)
-                            {
-                                skippedWatermark++;
-                                continue;
-                            }
-
-                            if (processed >= ErrorBackfillMaxRecords)
-                            {
-                                droppedOverCap++;
-                                continue;
-                            }
-
-                            processed++;
-                            ProcessRecord(record, "Autopilot", AutopilotChannel, isBackfill: true);
+                            skippedWatermark++;
+                            record.Dispose();
+                            continue;
                         }
+
+                        if (buffered.Count >= ErrorBackfillMaxRecords)
+                        {
+                            droppedOverCap++;
+                            record.Dispose();
+                            continue;
+                        }
+
+                        buffered.Add(record);
                     }
                 }
 
                 if (maxSeen > watermark)
                     AdvanceAutopilotErrorWatermark(maxSeen);
 
-                if (processed == 0 && droppedOverCap == 0)
+                if (buffered.Count == 0 && droppedOverCap == 0)
+                {
                     _logger.Debug($"ModernDeployment error backfill: nothing new (skippedByWatermark={skippedWatermark})");
+                }
                 else
-                    _logger.Info($"ModernDeployment error backfill: forwarded {processed} record(s) " +
+                {
+                    EmitErrorBackfillSummary(buffered.Count, droppedOverCap);
+
+                    // Scan buffered newest-first — replay in reverse so the emitted sequence
+                    // follows the original event-log chronology.
+                    for (var i = buffered.Count - 1; i >= 0; i--)
+                    {
+                        ProcessRecord(buffered[i], "Autopilot", AutopilotChannel, isBackfill: true);
+                    }
+
+                    _logger.Info($"ModernDeployment error backfill: forwarded {buffered.Count} record(s) " +
                         $"(skippedByWatermark={skippedWatermark}, droppedOverCap={droppedOverCap})");
+                }
             }
             catch (EventLogNotFoundException)
             {
@@ -701,6 +717,49 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals
             {
                 _logger.Warning($"ModernDeployment error backfill failed: {ex.Message}");
             }
+            finally
+            {
+                foreach (var record in buffered)
+                {
+                    try { record.Dispose(); } catch { }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Announces the error-backfill block on the session timeline BEFORE the replayed
+        /// errors, so pre-agent Error events are readable as history rather than a live
+        /// failure. The web timeline additionally badges each replayed event via its
+        /// backfilled=true payload marker; this summary carries backfillSummary=true instead —
+        /// it is a live emission, not a replayed record.
+        /// </summary>
+        internal void EmitErrorBackfillSummary(int replayedCount, int droppedOverCap)
+        {
+            var message = $"[Autopilot] Replaying {replayedCount} error event(s) recorded in the Autopilot event log " +
+                $"before the agent started (lookback {ErrorBackfillLookbackMinutes / 60}h). " +
+                "These predate monitoring — if enrollment progressed afterwards, they were already resolved by a retry.";
+            if (droppedOverCap > 0)
+            {
+                message += $" {droppedOverCap} older record(s) beyond the {ErrorBackfillMaxRecords}-record cap were not replayed.";
+            }
+
+            _post.Emit(new EnrollmentEvent
+            {
+                SessionId = _sessionId,
+                TenantId = _tenantId,
+                EventType = Constants.EventTypes.ModernDeploymentLog,
+                Severity = EventSeverity.Info,
+                Source = "ModernDeploymentWatcher",
+                Phase = EnrollmentPhase.Unknown,
+                Message = message,
+                Data = new Dictionary<string, object>
+                {
+                    { "backfillSummary", true },
+                    { "replayedCount", replayedCount },
+                    { "droppedOverCap", droppedOverCap },
+                    { "lookbackMinutes", ErrorBackfillLookbackMinutes }
+                }
+            });
         }
 
         /// <summary>

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

@@ -10,6 +10,7 @@ using AutopilotMonitor.Agent.V2.Core.Logging;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
 using AutopilotMonitor.Agent.V2.Core.Orchestration;
 using AutopilotMonitor.Shared;
+using AutopilotMonitor.Shared.Logging;
 using AutopilotMonitor.Shared.Models;
 using Microsoft.Win32;
 

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/NetshWifiFallback.cs

@@ -0,0 +1,221 @@
+using System;
+using System.Diagnostics;
+using AutopilotMonitor.Agent.V2.Core.Security;
+
+namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
+{
+    /// <summary>
+    /// Fallback WiFi reader via <c>netsh wlan show interfaces</c> output parsing, used ONLY
+    /// when <see cref="WifiInfoReader"/> (native WLAN API) yields nothing on a WiFi-connected
+    /// device. Field evidence 2026-07-28: the WLAN API can return nothing in the OOBE/SYSTEM
+    /// context on builds where inbox netsh still reports the connection — until that is fully
+    /// root-caused (suspect: Wi-Fi location gating, 24H2+), netsh stays as the safety net.
+    /// <para>
+    /// netsh labels follow the OS UI language, so the parser matches the label variants of
+    /// every language implied by the enrollment geography seen to date (see the comment on
+    /// the key arrays for the country→language derivation). Unknown-language labels fall
+    /// through harmlessly — the affected field is simply absent, same as before. "SSID"
+    /// itself is untranslated in all known locales.
+    /// </para>
+    /// </summary>
+    internal static class NetshWifiFallback
+    {
+        private const int NetshTimeoutMs = 5000;
+
+        // Label variants per field, by OS UI language. Matched case-insensitively against the
+        // full text left of the colon, so acronym-suffixed keys ("AP BSSID") never collide.
+        // Language set derived from enrollment geography (get_geographic_metrics, 365d):
+        // US/GB/AU/CA/IE/SG/IN/ZA/NG/PH en · DE/AT/CH de · BE/NL nl · BE/FR/CH fr · DK da ·
+        // SE sv · PL pl · TR tr · CN zh-CN · HK zh-TW · ES/MX/PE/PY es · CZ cs · SK sk ·
+        // IT/CH it · ID id · MY ms · FI fi · LT lt · LV lv · HU hu · BR/PT pt · JP ja ·
+        // KR ko · TH th · VN vi · RO/MD ro · BG bg · BA/HR hr · AE/SA/EG/JO ar ·
+        // MN/GE/AZ usually en/ru images → ru.
+        private static readonly string[] SignalKeys =
+        {
+            "Signal",     // en, de, fr, sv, da, nb, hr
+            "Señal",      // es
+            "Sinal",      // pt
+            "Segnale",    // it
+            "Signaal",    // nl
+            "Sygnał",     // pl
+            "Signál",     // cs, sk
+            "Sinyal",     // tr, id
+            "Isyarat",    // ms
+            "Signaali",   // fi
+            "Signalas",   // lt
+            "Signāls",    // lv
+            "Jel",        // hu
+            "Semnal",     // ro
+            "Tín hiệu",   // vi
+            "สัญญาณ",     // th
+            "الإشارة",    // ar
+            "إشارة",      // ar (variant without article)
+            "Сигнал",     // ru, bg
+            "シグナル",    // ja
+            "信号",        // zh-CN
+            "訊號",        // zh-TW
+            "신호",        // ko
+        };
+
+        private static readonly string[] RadioTypeKeys =
+        {
+            "Radio type",      // en
+            "Funktyp",         // de
+            "Type de radio",   // fr
+            "Tipo de radio",   // es
+            "Tipo de rádio",   // pt
+            "Tipo di radio",   // it
+            "Radiotype",       // nl, da
+            "Radiotyp",        // sv
+            "Typ radia",       // pl
+            "Typ rádia",       // cs, sk
+            "Radyo türü",      // tr
+            "Jenis radio",     // id, ms
+            "Radiotyyppi",     // fi
+            "Radijo tipas",    // lt
+            "Radio tips",      // lv
+            "Rádió típusa",    // hu
+            "Tip radio",       // ro
+            "Vrsta radija",    // hr, bs
+            "Loại radio",      // vi
+            "ชนิดวิทยุ",        // th
+            "نوع الراديو",     // ar
+            "Тип радио",       // ru
+            "Тип на радиото",  // bg
+            "無線の種類",       // ja
+            "无线电类型",       // zh-CN
+            "無線電類型",       // zh-TW
+            "라디오 종류",      // ko
+            "무선 종류",        // ko (variant)
+        };
+
+        private static readonly string[] ChannelKeys =
+        {
+            "Channel",     // en
+            "Kanal",       // de, sv, da, nb, tr, hr
+            "Canal",       // fr, es, pt, ro
+            "Canale",      // it
+            "Kanaal",      // nl
+            "Kanał",       // pl
+            "Kanál",       // cs, sk
+            "Saluran",     // id, ms
+            "Kanava",      // fi
+            "Kanalas",     // lt
+            "Kanāls",      // lv
+            "Csatorna",    // hu
+            "Kênh",        // vi
+            "ช่องสัญญาณ",   // th
+            "ช่อง",         // th (variant)
+            "القناة",      // ar
+            "قناة",        // ar (variant without article)
+            "Канал",       // ru, bg
+            "チャネル",     // ja
+            "信道",         // zh-CN
+            "通道",         // zh-TW / zh-CN (variant)
+            "채널",         // ko
+        };
+
+        /// <summary>
+        /// Runs <c>netsh wlan show interfaces</c> and parses its output. Returns a
+        /// <see cref="WifiConnectionInfo"/> with the fields that could be parsed, or null when
+        /// nothing was found (no WLAN, netsh failure, timeout, or unrecognized localized
+        /// labels). Never throws.
+        /// </summary>
+        internal static WifiConnectionInfo TryRead()
+        {
+            try
+            {
+                var psi = new ProcessStartInfo
+                {
+                    FileName = SystemPaths.Netsh,
+                    Arguments = "wlan show interfaces",
+                    UseShellExecute = false,
+                    RedirectStandardOutput = true,
+                    RedirectStandardError = true,
+                    CreateNoWindow = true
+                };
+
+                string output;
+                using (var process = Process.Start(psi))
+                {
+                    output = process.StandardOutput.ReadToEnd();
+                    if (!process.WaitForExit(NetshTimeoutMs))
+                    {
+                        try { process.Kill(); } catch { }
+                        return null;
+                    }
+                }
+
+                return Parse(output);
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        /// <summary>
+        /// Pure parser over the netsh output text. Internal for direct unit-testing via
+        /// InternalsVisibleTo (TryRead itself spawns a process and stays untested).
+        /// </summary>
+        internal static WifiConnectionInfo Parse(string output)
+        {
+            if (string.IsNullOrEmpty(output))
+                return null;
+
+            string ssid = null, radioType = null;
+            int? signal = null, channel = null;
+
+            foreach (var line in output.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries))
+            {
+                var trimmed = line.Trim();
+                var colonIndex = trimmed.IndexOf(':');
+                if (colonIndex < 0) continue;
+
+                var key = trimmed.Substring(0, colonIndex).Trim();
+                var value = trimmed.Substring(colonIndex + 1).Trim();
+
+                if (key.Equals("SSID", StringComparison.OrdinalIgnoreCase))
+                {
+                    ssid = value;
+                }
+                else if (MatchesAny(key, SignalKeys))
+                {
+                    // Value formats seen: "94%", "94% " (trailing space), "94 %".
+                    if (int.TryParse(value.TrimEnd('%', ' '), out var sig))
+                        signal = sig;
+                }
+                else if (MatchesAny(key, RadioTypeKeys))
+                {
+                    radioType = value;
+                }
+                else if (MatchesAny(key, ChannelKeys))
+                {
+                    if (int.TryParse(value, out var ch))
+                        channel = ch;
+                }
+            }
+
+            if (ssid == null && signal == null && radioType == null && channel == null)
+                return null;
+
+            return new WifiConnectionInfo
+            {
+                Ssid = ssid,
+                SignalPercent = signal,
+                RadioType = radioType,
+                Channel = channel,
+            };
+        }
+
+        private static bool MatchesAny(string key, string[] candidates)
+        {
+            foreach (var candidate in candidates)
+            {
+                if (key.Equals(candidate, StringComparison.OrdinalIgnoreCase))
+                    return true;
+            }
+            return false;
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/WifiInfoReader.cs

@@ -0,0 +1,234 @@
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+using static AutopilotMonitor.Agent.V2.Core.Monitoring.Interop.WlanNativeMethods;
+
+namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
+{
+    /// <summary>
+    /// Current WiFi connection details as read from the native WLAN API.
+    /// </summary>
+    public sealed class WifiConnectionInfo
+    {
+        /// <summary>SSID of the connected network; null when the AP broadcasts an empty SSID.</summary>
+        public string Ssid { get; internal set; }
+
+        /// <summary>
+        /// Signal quality 0–100 (same semantics as the netsh "Signal" percentage). Always set
+        /// on the native WLAN API path; null only when the netsh fallback could not parse it.
+        /// </summary>
+        public int? SignalPercent { get; internal set; }
+
+        /// <summary>Human-readable PHY generation ("802.11ax" …); null for exotic/unknown PHYs.</summary>
+        public string RadioType { get; internal set; }
+
+        /// <summary>Current 802.11 channel number; null when the channel query fails.</summary>
+        public int? Channel { get; internal set; }
+    }
+
+    /// <summary>
+    /// Fail-soft reader over <see cref="WlanNativeMethods"/>: returns the current WiFi
+    /// connection or null — never throws, never blocks on a child process. Machines without
+    /// the WLAN AutoConfig service (VMs, wired-only devices) simply return null.
+    /// </summary>
+    public static class WifiInfoReader
+    {
+        /// <summary>
+        /// Reads the current WiFi connection. When <paramref name="preferredInterfaceId"/> is
+        /// given (the adapter GUID from <c>NetworkInterface.Id</c>), that interface is queried
+        /// first; otherwise — or when it is not connected — the first connected WLAN interface
+        /// wins. Returns null when no interface has an active connection.
+        /// </summary>
+        public static WifiConnectionInfo TryGetCurrentConnection(Guid? preferredInterfaceId = null)
+            => TryGetCurrentConnection(preferredInterfaceId, out _);
+
+        /// <summary>
+        /// Same as <see cref="TryGetCurrentConnection(Guid?)"/> but reports WHY the read
+        /// yielded nothing via <paramref name="diagnostics"/> (native return codes per step).
+        /// The WLAN API can fail in ways that are invisible from the outside (e.g. per-process
+        /// access gating on newer Windows builds) — callers log this at Debug so field issues
+        /// are explainable from the agent log instead of a silent missing event.
+        /// </summary>
+        public static WifiConnectionInfo TryGetCurrentConnection(Guid? preferredInterfaceId, out string diagnostics)
+        {
+            var diag = new StringBuilder();
+            var clientHandle = IntPtr.Zero;
+            try
+            {
+                var rc = WlanOpenHandle(WLAN_CLIENT_VERSION, IntPtr.Zero, out _, out clientHandle);
+                if (rc != ERROR_SUCCESS)
+                {
+                    diagnostics = $"WlanOpenHandle rc={rc}";
+                    return null;
+                }
+
+                var interfaceList = IntPtr.Zero;
+                try
+                {
+                    rc = WlanEnumInterfaces(clientHandle, IntPtr.Zero, out interfaceList);
+                    if (rc != ERROR_SUCCESS)
+                    {
+                        diagnostics = $"WlanEnumInterfaces rc={rc}";
+                        return null;
+                    }
+
+                    var count = (uint)Marshal.ReadInt32(interfaceList);
+                    if (count == 0)
+                    {
+                        diagnostics = "no WLAN interfaces";
+                        return null;
+                    }
+
+                    var infoSize = Marshal.SizeOf(typeof(WLAN_INTERFACE_INFO));
+                    // List header: DWORD dwNumberOfItems + DWORD dwIndex, then the info array.
+                    var firstEntry = new IntPtr(interfaceList.ToInt64() + 8);
+
+                    WifiConnectionInfo fallback = null;
+                    for (var i = 0; i < count; i++)
+                    {
+                        var entryPtr = new IntPtr(firstEntry.ToInt64() + i * infoSize);
+                        var info = (WLAN_INTERFACE_INFO)Marshal.PtrToStructure(entryPtr, typeof(WLAN_INTERFACE_INFO));
+
+                        var connection = QueryCurrentConnection(clientHandle, info.InterfaceGuid, diag);
+                        if (connection == null)
+                            continue;
+
+                        if (preferredInterfaceId.HasValue && info.InterfaceGuid == preferredInterfaceId.Value)
+                        {
+                            diagnostics = null;
+                            return connection;
+                        }
+
+                        if (fallback == null)
+                            fallback = connection;
+                    }
+
+                    diagnostics = fallback == null ? diag.ToString() : null;
+                    return fallback;
+                }
+                finally
+                {
+                    if (interfaceList != IntPtr.Zero)
+                        WlanFreeMemory(interfaceList);
+                }
+            }
+            catch (Exception ex)
+            {
+                diagnostics = $"exception {ex.GetType().Name}: {ex.Message}";
+                return null;
+            }
+            finally
+            {
+                if (clientHandle != IntPtr.Zero)
+                    WlanCloseHandle(clientHandle, IntPtr.Zero);
+            }
+        }
+
+        private static WifiConnectionInfo QueryCurrentConnection(IntPtr clientHandle, Guid interfaceGuid, StringBuilder diag)
+        {
+            var dataPtr = IntPtr.Zero;
+            try
+            {
+                var rc = WlanQueryInterface(clientHandle, ref interfaceGuid,
+                        WLAN_INTF_OPCODE.wlan_intf_opcode_current_connection,
+                        IntPtr.Zero, out _, out dataPtr, IntPtr.Zero);
+                if (rc != ERROR_SUCCESS)
+                {
+                    diag.Append($"[{interfaceGuid:D}] query(current_connection) rc={rc}; ");
+                    return null;
+                }
+
+                var attributes = (WLAN_CONNECTION_ATTRIBUTES)Marshal.PtrToStructure(
+                    dataPtr, typeof(WLAN_CONNECTION_ATTRIBUTES));
+
+                if (attributes.isState != WLAN_INTERFACE_STATE.wlan_interface_state_connected)
+                {
+                    diag.Append($"[{interfaceGuid:D}] state={attributes.isState}; ");
+                    return null;
+                }
+
+                var assoc = attributes.wlanAssociationAttributes;
+                return new WifiConnectionInfo
+                {
+                    Ssid = DecodeSsid(assoc.dot11Ssid.ucSSID, assoc.dot11Ssid.uSSIDLength),
+                    SignalPercent = (int)Math.Min(assoc.wlanSignalQuality, 100),
+                    RadioType = PhyTypeToRadioType(assoc.dot11PhyType),
+                    Channel = QueryChannel(clientHandle, interfaceGuid),
+                };
+            }
+            finally
+            {
+                if (dataPtr != IntPtr.Zero)
+                    WlanFreeMemory(dataPtr);
+            }
+        }
+
+        private static int? QueryChannel(IntPtr clientHandle, Guid interfaceGuid)
+        {
+            var dataPtr = IntPtr.Zero;
+            try
+            {
+                if (WlanQueryInterface(clientHandle, ref interfaceGuid,
+                        WLAN_INTF_OPCODE.wlan_intf_opcode_channel_number,
+                        IntPtr.Zero, out var dataSize, out dataPtr, IntPtr.Zero) != ERROR_SUCCESS)
+                    return null;
+
+                if (dataSize < sizeof(uint) || dataPtr == IntPtr.Zero)
+                    return null;
+
+                return Marshal.ReadInt32(dataPtr);
+            }
+            catch
+            {
+                return null;
+            }
+            finally
+            {
+                if (dataPtr != IntPtr.Zero)
+                    WlanFreeMemory(dataPtr);
+            }
+        }
+
+        /// <summary>
+        /// Decodes a raw DOT11_SSID (UTF-8 by convention) into a string; null for empty SSIDs.
+        /// Internal for direct unit-testing via InternalsVisibleTo.
+        /// </summary>
+        internal static string DecodeSsid(byte[] raw, uint length)
+        {
+            if (raw == null || length == 0)
+                return null;
+
+            var byteCount = (int)Math.Min(length, (uint)raw.Length);
+            try
+            {
+                var ssid = Encoding.UTF8.GetString(raw, 0, byteCount);
+                return string.IsNullOrEmpty(ssid) ? null : ssid;
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        /// <summary>
+        /// Maps a DOT11 PHY type to the same strings netsh historically reported as
+        /// "Radio type" — keeps event payloads consistent across the netsh→WLAN-API switch.
+        /// Internal for direct unit-testing via InternalsVisibleTo.
+        /// </summary>
+        internal static string PhyTypeToRadioType(DOT11_PHY_TYPE phyType)
+        {
+            switch (phyType)
+            {
+                case DOT11_PHY_TYPE.dot11_phy_type_ofdm: return "802.11a";
+                case DOT11_PHY_TYPE.dot11_phy_type_hrdsss: return "802.11b";
+                case DOT11_PHY_TYPE.dot11_phy_type_erp: return "802.11g";
+                case DOT11_PHY_TYPE.dot11_phy_type_ht: return "802.11n";
+                case DOT11_PHY_TYPE.dot11_phy_type_vht: return "802.11ac";
+                case DOT11_PHY_TYPE.dot11_phy_type_dmg: return "802.11ad";
+                case DOT11_PHY_TYPE.dot11_phy_type_he: return "802.11ax";
+                case DOT11_PHY_TYPE.dot11_phy_type_eht: return "802.11be";
+                default: return null;
+            }
+        }
+    }
+}

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/WlanNativeMethods.cs

@@ -0,0 +1,142 @@
+using System;
+using System.Runtime.InteropServices;
+
+namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
+{
+    /// <summary>
+    /// Native WLAN API interop (<c>wlanapi.dll</c>) used to read the current WiFi connection
+    /// (SSID, signal quality, PHY type, channel) without spawning <c>netsh</c>.
+    /// <para>
+    /// The WLAN API is language-neutral — unlike parsing <c>netsh wlan show interfaces</c>
+    /// output, whose labels follow the OS UI language and silently drop fields on
+    /// non-English images. On machines without the WLAN AutoConfig service (VMs, servers,
+    /// wired-only devices) <c>WlanOpenHandle</c>/<c>WlanEnumInterfaces</c> fail with a
+    /// non-zero error code; callers treat that as "no WiFi" (see <see cref="WifiInfoReader"/>).
+    /// </para>
+    /// </summary>
+    internal static class WlanNativeMethods
+    {
+        internal const uint ERROR_SUCCESS = 0;
+
+        /// <summary>Client version 2 = Vista and later (the only relevant range).</summary>
+        internal const uint WLAN_CLIENT_VERSION = 2;
+
+        internal enum WLAN_INTF_OPCODE : uint
+        {
+            wlan_intf_opcode_current_connection = 7,
+            wlan_intf_opcode_channel_number = 8,
+        }
+
+        internal enum WLAN_INTERFACE_STATE
+        {
+            wlan_interface_state_not_ready = 0,
+            wlan_interface_state_connected = 1,
+            wlan_interface_state_ad_hoc_network_formed = 2,
+            wlan_interface_state_disconnecting = 3,
+            wlan_interface_state_disconnected = 4,
+            wlan_interface_state_associating = 5,
+            wlan_interface_state_discovering = 6,
+            wlan_interface_state_authenticating = 7,
+        }
+
+        internal enum DOT11_PHY_TYPE : uint
+        {
+            dot11_phy_type_unknown = 0,
+            dot11_phy_type_fhss = 1,
+            dot11_phy_type_dsss = 2,
+            dot11_phy_type_irbaseband = 3,
+            dot11_phy_type_ofdm = 4,    // 802.11a
+            dot11_phy_type_hrdsss = 5,  // 802.11b
+            dot11_phy_type_erp = 6,     // 802.11g
+            dot11_phy_type_ht = 7,      // 802.11n
+            dot11_phy_type_vht = 8,     // 802.11ac
+            dot11_phy_type_dmg = 9,     // 802.11ad
+            dot11_phy_type_he = 10,     // 802.11ax
+            dot11_phy_type_eht = 11,    // 802.11be
+        }
+
+        [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+        internal struct WLAN_INTERFACE_INFO
+        {
+            public Guid InterfaceGuid;
+            [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
+            public string strInterfaceDescription;
+            public WLAN_INTERFACE_STATE isState;
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        internal struct DOT11_SSID
+        {
+            public uint uSSIDLength;
+            [MarshalAs(UnmanagedType.ByValArray, SizeConst = 32)]
+            public byte[] ucSSID;
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        internal struct WLAN_ASSOCIATION_ATTRIBUTES
+        {
+            public DOT11_SSID dot11Ssid;
+            public int dot11BssType;
+            [MarshalAs(UnmanagedType.ByValArray, SizeConst = 6)]
+            public byte[] dot11Bssid;
+            public DOT11_PHY_TYPE dot11PhyType;
+            public uint uDot11PhyIndex;
+            public uint wlanSignalQuality; // 0..100, same semantics as netsh "Signal"
+            public uint ulRxRate;
+            public uint ulTxRate;
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        internal struct WLAN_SECURITY_ATTRIBUTES
+        {
+            [MarshalAs(UnmanagedType.Bool)]
+            public bool bSecurityEnabled;
+            [MarshalAs(UnmanagedType.Bool)]
+            public bool bOneXEnabled;
+            public int dot11AuthAlgorithm;
+            public int dot11CipherAlgorithm;
+        }
+
+        [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+        internal struct WLAN_CONNECTION_ATTRIBUTES
+        {
+            public WLAN_INTERFACE_STATE isState;
+            public int wlanConnectionMode;
+            [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
+            public string strProfileName;
+            public WLAN_ASSOCIATION_ATTRIBUTES wlanAssociationAttributes;
+            public WLAN_SECURITY_ATTRIBUTES wlanSecurityAttributes;
+        }
+
+        [DllImport("wlanapi.dll")]
+        internal static extern uint WlanOpenHandle(
+            uint dwClientVersion,
+            IntPtr pReserved,
+            out uint pdwNegotiatedVersion,
+            out IntPtr phClientHandle);
+
+        [DllImport("wlanapi.dll")]
+        internal static extern uint WlanCloseHandle(
+            IntPtr hClientHandle,
+            IntPtr pReserved);
+
+        [DllImport("wlanapi.dll")]
+        internal static extern uint WlanEnumInterfaces(
+            IntPtr hClientHandle,
+            IntPtr pReserved,
+            out IntPtr ppInterfaceList);
+
+        [DllImport("wlanapi.dll")]
+        internal static extern uint WlanQueryInterface(
+            IntPtr hClientHandle,
+            [In] ref Guid pInterfaceGuid,
+            WLAN_INTF_OPCODE OpCode,
+            IntPtr pReserved,
+            out uint pdwDataSize,
+            out IntPtr ppData,
+            IntPtr pWlanOpcodeValueType);
+
+        [DllImport("wlanapi.dll")]
+        internal static extern void WlanFreeMemory(IntPtr pMemory);
+    }
+}

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

@@ -218,15 +218,18 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
         /// This method is non-fatal: all exceptions are caught and logged.
         /// </summary>
         /// <param name="enrollmentSucceeded">
-        /// True for a successful enrollment (affects OnFailure mode check and sessioninfo.txt content).
-        /// Pass true for WhiteGlove pre-provisioning (it succeeded up to this point).
+        /// True for a successful enrollment, false for a failed one (drives the OnFailure mode
+        /// check and sessioninfo.txt content). Pass true for WhiteGlove pre-provisioning (it
+        /// succeeded up to this point). Pass <b>null</b> when the session has no outcome yet
+        /// (on-demand server-requested collection mid-enrollment): the OnFailure gate does not
+        /// apply — there is no success to skip on — and sessioninfo.txt records "In Progress".
         /// </param>
         /// <param name="fileNameSuffix">
         /// Optional suffix inserted before the .zip extension.
         /// Example: "preprov" → AgentDiagnostics-{sessionId}-{timestamp}-preprov.zip
         /// Null (default) → AgentDiagnostics-{sessionId}-{timestamp}.zip
         /// </param>
-        public virtual async Task<DiagnosticsUploadResult> CreateAndUploadAsync(bool enrollmentSucceeded, string fileNameSuffix = null)
+        public virtual async Task<DiagnosticsUploadResult> CreateAndUploadAsync(bool? enrollmentSucceeded, string fileNameSuffix = null)
         {
             try
             {
@@ -244,13 +247,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                     return null;
                 }
 
-                if (string.Equals(mode, "OnFailure", StringComparison.OrdinalIgnoreCase) && enrollmentSucceeded)
+                // Null outcome (on-demand mid-session) passes through: the OnFailure gate only
+                // skips a KNOWN success — an in-flight session has nothing to skip on.
+                if (string.Equals(mode, "OnFailure", StringComparison.OrdinalIgnoreCase) && enrollmentSucceeded == true)
                 {
                     _logger.Info("Diagnostics upload skipped: enrollment succeeded and mode=OnFailure");
                     return null;
                 }
 
-                _logger.Info($"Creating diagnostics package (mode={mode}, enrollmentSucceeded={enrollmentSucceeded}{(fileNameSuffix != null ? $", suffix={fileNameSuffix}" : "")})...");
+                _logger.Info($"Creating diagnostics package (mode={mode}, enrollmentSucceeded={(enrollmentSucceeded.HasValue ? enrollmentSucceeded.ToString() : "n/a")}{(fileNameSuffix != null ? $", suffix={fileNameSuffix}" : "")})...");
 
                 // Build ZIP in memory
                 var timestamp = DateTime.UtcNow.ToString("yyyyMMddHHmmss");
@@ -343,7 +348,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
 
         // Builds the diagnostics ZIP body in-memory. Extracted from CreateAndUploadAsync so
         // tests can assert archive contents without going through the upload path.
-        internal virtual byte[] BuildArchiveBytes(bool enrollmentSucceeded)
+        internal virtual byte[] BuildArchiveBytes(bool? enrollmentSucceeded)
         {
             var tracker = new BudgetTracker(Budget);
             using (var ms = new MemoryStream())
@@ -414,14 +419,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
             }
         }
 
-        private void AddSessionInfo(ZipArchive archive, bool enrollmentSucceeded)
+        private void AddSessionInfo(ZipArchive archive, bool? enrollmentSucceeded)
         {
             var sb = new StringBuilder();
             sb.AppendLine($"Session ID: {_configuration.SessionId}");
             sb.AppendLine($"Tenant ID: {_configuration.TenantId}");
             sb.AppendLine($"Device Name: {Environment.MachineName}");
             sb.AppendLine($"Timestamp: {DateTime.UtcNow:O}");
-            sb.AppendLine($"Enrollment Result: {(enrollmentSucceeded ? "Succeeded" : "Failed")}");
+            sb.AppendLine($"Enrollment Result: {(enrollmentSucceeded == null ? "In Progress" : enrollmentSucceeded.Value ? "Succeeded" : "Failed")}");
 
             // Hardware info via existing DeviceInfoProvider (WMI)
             sb.AppendLine($"Manufacturer: {DeviceInfoProvider.GetManufacturer()}");

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

@@ -88,6 +88,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
         /// </summary>
         public static string BackendExpectedSha256 { get; set; }
 
+        /// <summary>
+        /// True once a <see cref="CheckAndApplyUpdateAsync"/> run actually obtained a version
+        /// from the manifest (regardless of whether an update was then needed/applied).
+        /// <para>
+        /// Consumed by the <c>--await-enrollment</c> path: the startup check runs pre-enrollment
+        /// where OOBE frequently has no network yet, so a failed check there says nothing about
+        /// the latest version. Once the MDM certificate appears the device provably has
+        /// connectivity — the bootstrap retries the check exactly when this is still false.
+        /// </para>
+        /// </summary>
+        /// <remarks>
+        /// Setter is internal solely as a test seam (InternalsVisibleTo): the bootstrap-retry
+        /// tests arm/reset the guard without running the real network check. Production code
+        /// writes it only from <see cref="CheckAndApplyUpdateAsync"/>.
+        /// </remarks>
+        public static bool LastVersionCheckSucceeded { get; internal set; }
+
         /// <summary>
         /// Optional: graceful-shutdown request hook, set by the runtime host once its
         /// shutdown machinery is armed (before the orchestrator starts) and cleared in its
@@ -130,14 +147,21 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
         /// to cover hotfixes that reuse the same version number.
         /// </param>
         /// <param name="triggerReason">
-        /// "startup" (default) or "runtime_hash_mismatch". Recorded in the marker file so the
-        /// agent_version_check event (outcome=updated) can distinguish the two paths.
+        /// "startup" (default), "await_enrollment" (post-cert retry in the bootstrap), or
+        /// "runtime_hash_mismatch". Recorded in the marker file so the agent_version_check
+        /// event (outcome=updated) can distinguish the paths.
         /// </param>
         /// <param name="downloadTimeoutMsOverride">
         /// Overrides the ZIP download timeout. Startup path leaves null (fast-fail, 10s) to preserve
         /// Autopilot boot speed. Runtime trigger passes 60000 because monitoring is already running
         /// and we know an update is required.
         /// </param>
+        /// <param name="versionCheckTimeoutMsOverride">
+        /// Overrides the version-v2.json fetch timeout (default 2500ms, tuned for boot speed).
+        /// The await-enrollment retry passes a relaxed value: enrollment just completed, the
+        /// device provably has network, and a stranded old build's last self-rescue chance is
+        /// worth a few extra seconds before session registration.
+        /// </param>
         /// <param name="allowDowngrade">
         /// When false (default), a latest version strictly lower than <paramref name="currentVersion"/>
         /// is rejected even when <paramref name="forceUpdate"/> is true — prevents the production
@@ -151,7 +175,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
             bool forceUpdate = false,
             string triggerReason = "startup",
             int? downloadTimeoutMsOverride = null,
-            bool allowDowngrade = false)
+            bool allowDowngrade = false,
+            int? versionCheckTimeoutMsOverride = null)
         {
             Action<string> log = msg =>
             {
@@ -160,7 +185,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
             };
 
             var isStartupTrigger = string.Equals(triggerReason, "startup", StringComparison.Ordinal);
+            // The await-enrollment retry replaces the startup verdict — its markers must win so
+            // the agent_version_check event reflects the LATEST check, not the pre-network one.
+            var writeMarkers = isStartupTrigger || string.Equals(triggerReason, "await_enrollment", StringComparison.Ordinal);
             var downloadTimeoutMs = downloadTimeoutMsOverride ?? DownloadTimeoutMs;
+            var versionCheckTimeoutMs = versionCheckTimeoutMsOverride ?? VersionCheckTimeoutMs;
             var totalSw = Stopwatch.StartNew();
             long versionCheckMs = 0, downloadMs = 0, verifyMs = 0, extractMs = 0, swapMs = 0;
             long zipSizeBytes = 0;
@@ -174,16 +203,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
 
             try
             {
-                // Step 1: Fetch version-v2.json (2.5s timeout)
+                // Step 1: Fetch version-v2.json (default 2.5s timeout, relaxed on retry triggers)
                 var versionSw = Stopwatch.StartNew();
                 string manifestSha256;
-                (latestVersion, manifestSha256) = await GetLatestVersionAsync(log);
+                (latestVersion, manifestSha256) = await GetLatestVersionAsync(log, versionCheckTimeoutMs);
                 versionSw.Stop();
                 versionCheckMs = versionSw.ElapsedMilliseconds;
+                LastVersionCheckSucceeded = latestVersion != null;
 
                 if (latestVersion == null)
                 {
-                    if (isStartupTrigger)
+                    if (writeMarkers)
                         WriteSkipMarker("version_check_failed", currentVersion, null, "version-v2.json fetch failed or timed out", log);
                     return; // Could not determine latest version — continue with current
                 }
@@ -213,7 +243,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                     if (!forceUpdate)
                     {
                         log($"Self-update: current version {currentVersion} is up to date (latest: {latestVersion})");
-                        if (isStartupTrigger)
+                        if (writeMarkers)
                             WriteCheckedMarker(currentVersion, latestVersion, versionCheckMs, log);
                         return;
                     }
@@ -230,7 +260,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                     if (!forceUpdate)
                     {
                         log($"Self-update: cannot compare versions (current={currentVersion}, latest={latestVersion}) — skipping");
-                        if (isStartupTrigger)
+                        if (writeMarkers)
                             WriteSkipMarker("version_compare_failed", currentVersion, latestVersion, "version parse failed", log);
                         return;
                     }
@@ -249,7 +279,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                 downloadMs = downloadTimerSw.ElapsedMilliseconds;
                 if (!downloadOk)
                 {
-                    if (isStartupTrigger)
+                    if (writeMarkers)
                         WriteSkipMarker("download_failed", currentVersion, latestVersion, $"ZIP download failed within {downloadTimeoutMs}ms", log);
                     return;
                 }
@@ -282,7 +312,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                 if (!integrityOk)
                 {
                     CleanupStaging(null, zipPath);
-                    if (isStartupTrigger)
+                    if (writeMarkers)
                         WriteSkipMarker("integrity_mismatch", currentVersion, latestVersion, "SHA-256 mismatch on downloaded ZIP", log);
                     return;
                 }
@@ -297,7 +327,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                 extractMs = extractSw.ElapsedMilliseconds;
                 if (!extractOk)
                 {
-                    if (isStartupTrigger)
+                    if (writeMarkers)
                         WriteSkipMarker("extract_failed", currentVersion, latestVersion, "ZIP extraction failed", log);
                     return;
                 }
@@ -310,7 +340,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                 {
                     log("Self-update: staging validation failed — AutopilotMonitor.Agent.exe not found in ZIP");
                     CleanupStaging(stagingDir, zipPath);
-                    if (isStartupTrigger)
+                    if (writeMarkers)
                         WriteSkipMarker("extract_failed", currentVersion, latestVersion, "AutopilotMonitor.Agent.exe not found in ZIP", log);
                     return;
                 }
@@ -323,7 +353,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                 if (!swapOk)
                 {
                     CleanupStaging(stagingDir, zipPath);
-                    if (isStartupTrigger)
+                    if (writeMarkers)
                         WriteSkipMarker("swap_failed", currentVersion, latestVersion, "file swap failed", log);
                     return;
                 }
@@ -355,7 +385,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
             catch (Exception ex)
             {
                 log($"Self-update: unexpected error — {ex.Message}. Continuing with current version.");
-                if (isStartupTrigger)
+                if (writeMarkers)
                 {
                     try { WriteSkipMarker("unexpected_error", currentVersion, latestVersion, ex.Message, log); } catch { }
                 }
@@ -366,7 +396,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
         /// Fetches version-v2.json from blob storage and returns the version string and optional SHA-256 hash.
         /// Returns (null, null) if the check fails or times out.
         /// </summary>
-        private static async Task<(string version, string sha256)> GetLatestVersionAsync(Action<string> log)
+        private static async Task<(string version, string sha256)> GetLatestVersionAsync(Action<string> log, int timeoutMs)
         {
             try
             {
@@ -375,7 +405,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
                 var versionUrl = $"{Constants.AgentDownloadBaseUrl}/{Constants.AgentVersionFileNameForLine(2)}";
 
                 using (var handler = new HttpClientHandler())
-                using (var client = new HttpClient(handler) { Timeout = TimeSpan.FromMilliseconds(VersionCheckTimeoutMs) })
+                using (var client = new HttpClient(handler) { Timeout = TimeSpan.FromMilliseconds(timeoutMs) })
                 {
                     var json = await client.GetStringAsync(versionUrl);
                     var obj = JObject.Parse(json);
@@ -396,7 +426,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime
             }
             catch (TaskCanceledException)
             {
-                log($"Self-update: version check timed out ({VersionCheckTimeoutMs}ms) — skipping update");
+                log($"Self-update: version check timed out ({timeoutMs}ms) — skipping update");
                 return (null, null);
             }
             catch (HttpRequestException ex) when (ex.Message.Contains("404"))

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/DeviceInfo/DeviceInfoCollector.NetworkAndSecurity.cs

@@ -305,10 +305,16 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
                 // (see docs/agent/autopilot-ztd-diagnostics.md for the evidence model).
                 if (IsAutopilotProfileMissing(data))
                 {
+                    // On Windows 365 Cloud PCs a missing profile is the expected state — Cloud PCs
+                    // are provisioned by the Windows 365 service, not by Autopilot — so the event
+                    // is demoted to Info there instead of raising a misleading warning.
+                    var isCloudPc = CloudPcDetector.DetectIsCloudPc();
+
                     var missingData = new Dictionary<string, object>
                     {
                         { "profileAvailable", "0" },
-                        { "likelyCauses", "profile_not_assigned,profile_assignment_not_propagated" }
+                        { "likelyCauses", "profile_not_assigned,profile_assignment_not_propagated" },
+                        { "isCloudPc", isCloudPc }
                     };
                     if (TryExtractZeroTouchTenantDomain(data, out var ztdTenantDomain))
                     {
@@ -347,12 +353,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
                     missingData["ztdEndpointLatencyMs"] = probe.LatencyMs;
                     missingData["ztdEndpointDetail"] = probe.Detail;
 
+                    var presentation = ResolveAutopilotProfileMissingPresentation(isCloudPc);
                     EmitDeviceInfoEvent(Constants.EventTypes.AutopilotProfileMissing,
-                        "No Autopilot profile was available during OOBE (ProfileAvailable=0) — most likely no deployment profile was assigned to the device, or the assignment had not finished propagating when OOBE ran. OOBE proceeded as a standard Entra ID join instead of an Autopilot deployment.",
+                        presentation.Message,
                         missingData,
-                        EventSeverity.Warning);
+                        presentation.Severity);
 
-                    _logger.Warning($"EnrollmentTracker: no Autopilot profile available during OOBE (ProfileAvailable=0) — ztdVerdict={missingData["ztdVerdict"]}, endpointReachable={probe.Reachable}");
+                    var logLine = $"EnrollmentTracker: no Autopilot profile available during OOBE (ProfileAvailable=0) — isCloudPc={isCloudPc}, ztdVerdict={missingData["ztdVerdict"]}, endpointReachable={probe.Reachable}";
+                    if (isCloudPc)
+                        _logger.Info(logLine);
+                    else
+                        _logger.Warning(logLine);
                 }
 
                 // Emit dedicated enrollment_type_detected event for easy filtering. Routed through
@@ -396,6 +407,26 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
                 && profileAvailable?.ToString() == "0";
         }
 
+        /// <summary>
+        /// Message and severity for the autopilot_profile_missing event. On Windows 365
+        /// Cloud PCs the missing profile is expected (Cloud PCs are provisioned by the
+        /// Windows 365 service, not by Autopilot), so the event is informational there;
+        /// on physical devices it stays a warning about a missing profile ASSIGNMENT.
+        /// </summary>
+        internal static (string Message, EventSeverity Severity) ResolveAutopilotProfileMissingPresentation(bool isCloudPc)
+        {
+            if (isCloudPc)
+            {
+                return (
+                    "No Autopilot profile was available during OOBE (ProfileAvailable=0). This device is a Windows 365 Cloud PC — Cloud PCs are provisioned by the Windows 365 service and do not use Autopilot deployment profiles, so this is expected. OOBE ran as a standard Entra ID join, which is the normal path for Cloud PCs.",
+                    EventSeverity.Info);
+            }
+
+            return (
+                "No Autopilot profile was available during OOBE (ProfileAvailable=0) — most likely no deployment profile was assigned to the device, or the assignment had not finished propagating when OOBE ran. OOBE proceeded as a standard Entra ID join instead of an Autopilot deployment.",
+                EventSeverity.Warning);
+        }
+
         /// <summary>
         /// Extracts ZeroTouchConfig.CloudAssignedTenantDomain from the cached profile data.
         /// The value lives in the CloudAssignedAadServerData JSON — either as a top-level
@@ -815,7 +846,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
         /// Collects active network interface details (name, type, link speed, MAC) using
         /// System.Net.NetworkInformation — instant, no process spawn.
         /// If the active interface is WiFi, fires off a separate async task to collect
-        /// WiFi signal info via netsh (fire-and-forget, never blocks).
+        /// WiFi signal info via the native WLAN API (fire-and-forget, never blocks).
         /// </summary>
         private void CollectActiveNetworkInterfaceInfo()
         {
@@ -858,7 +889,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
                 // Fire-and-forget WiFi signal collection — separate event, never blocks
                 if (isWifi)
                 {
-                    Task.Run(() => CollectWiFiSignalInfo());
+                    Guid? nicGuid = Guid.TryParse(activeNic.Id, out var parsedGuid) ? parsedGuid : (Guid?)null;
+                    Task.Run(() => CollectWiFiSignalInfo(nicGuid));
                 }
             }
             catch (Exception ex)
@@ -899,78 +931,41 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
         }
 
         /// <summary>
-        /// Collects WiFi signal info via netsh wlan show interfaces and emits a separate
-        /// wifi_signal_info event. Designed to run as fire-and-forget via Task.Run —
-        /// never blocks other collection. VMs without WiFi service simply get no event.
+        /// Collects WiFi signal info via the native WLAN API (<see cref="WifiInfoReader"/>,
+        /// language-neutral, no process spawn) and emits a separate wifi_signal_info event.
+        /// Designed to run as fire-and-forget via Task.Run — never blocks other collection.
+        /// VMs without WiFi service simply get no event.
         /// </summary>
-        private void CollectWiFiSignalInfo()
+        private void CollectWiFiSignalInfo(Guid? interfaceGuid)
         {
             try
             {
-                var psi = new ProcessStartInfo
+                var wifi = WifiInfoReader.TryGetCurrentConnection(interfaceGuid, out var wifiDiag);
+                if (wifi == null)
                 {
-                    FileName = SystemPaths.Netsh,
-                    Arguments = "wlan show interfaces",
-                    UseShellExecute = false,
-                    RedirectStandardOutput = true,
-                    RedirectStandardError = true,
-                    CreateNoWindow = true
-                };
-
-                string output;
-                using (var process = Process.Start(psi))
-                {
-                    output = process.StandardOutput.ReadToEnd();
-                    process.WaitForExit(5000);
+                    _logger.Debug($"EnrollmentTracker: native WLAN API returned no WiFi info ({wifiDiag ?? "no connected WLAN interface"}) — trying netsh fallback");
+                    wifi = NetshWifiFallback.TryRead();
+                    if (wifi == null)
+                        return;
                 }
 
-                if (string.IsNullOrEmpty(output))
-                    return;
-
                 var data = new Dictionary<string, object>();
+                if (wifi.Ssid != null)
+                    data["wifiSsid"] = wifi.Ssid;
+                if (wifi.SignalPercent.HasValue)
+                    data["wifiSignalPercent"] = wifi.SignalPercent.Value;
+                if (wifi.RadioType != null)
+                    data["wifiRadioType"] = wifi.RadioType;
+                if (wifi.Channel.HasValue)
+                    data["wifiChannel"] = wifi.Channel.Value;
 
-                foreach (var line in output.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries))
-                {
-                    var trimmed = line.Trim();
-                    var colonIndex = trimmed.IndexOf(':');
-                    if (colonIndex < 0) continue;
+                var message = wifi.Ssid != null ? $"WiFi: {wifi.Ssid}" : "WiFi signal info";
+                if (wifi.SignalPercent.HasValue)
+                    message += $", Signal: {wifi.SignalPercent.Value}%";
+                if (wifi.RadioType != null)
+                    message += $" ({wifi.RadioType})";
 
-                    var key = trimmed.Substring(0, colonIndex).Trim();
-                    var value = trimmed.Substring(colonIndex + 1).Trim();
-
-                    if (key.Equals("SSID", StringComparison.OrdinalIgnoreCase) &&
-                        !key.Equals("BSSID", StringComparison.OrdinalIgnoreCase))
-                    {
-                        data["wifiSsid"] = value;
-                    }
-                    else if (key.Equals("Signal", StringComparison.OrdinalIgnoreCase))
-                    {
-                        if (int.TryParse(value.TrimEnd('%'), out var signal))
-                            data["wifiSignalPercent"] = signal;
-                    }
-                    else if (key.Equals("Radio type", StringComparison.OrdinalIgnoreCase))
-                    {
-                        data["wifiRadioType"] = value;
-                    }
-                    else if (key.Equals("Channel", StringComparison.OrdinalIgnoreCase))
-                    {
-                        if (int.TryParse(value, out var channel))
-                            data["wifiChannel"] = channel;
-                    }
-                }
-
-                if (data.Count > 0)
-                {
-                    var message = data.ContainsKey("wifiSsid")
-                        ? $"WiFi: {data["wifiSsid"]}"
-                        : "WiFi signal info";
-                    if (data.ContainsKey("wifiSignalPercent"))
-                        message += $", Signal: {data["wifiSignalPercent"]}%";
-                    if (data.ContainsKey("wifiRadioType"))
-                        message += $" ({data["wifiRadioType"]})";
-
-                    EmitDeviceInfoEvent(Constants.EventTypes.WifiSignalInfo, message, data);
-                }
+                EmitDeviceInfoEvent(Constants.EventTypes.WifiSignalInfo, message, data);
             }
             catch (Exception ex)
             {
@@ -1057,6 +1052,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
                     .ToString(System.Globalization.CultureInfo.InvariantCulture);
             if (snapshot.AllowContinueAnyway.HasValue)
                 payload[SignalPayloadKeys.EspAllowContinueAnyway] = snapshot.AllowContinueAnyway.Value ? "true" : "false";
+            // Tenant opt-in (remote config, not a registry fact) — only stamped when
+            // enabled; absent = default hard-fail semantics in the engine.
+            if (_espContinueAnywayObservationEnabled?.Invoke() == true)
+                payload[SignalPayloadKeys.EspContinueAnywayObservationEnabled] = "true";
 
             var derivationInputs = new Dictionary<string, string>(payload, StringComparer.Ordinal)
             {

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/DeviceInfo/DeviceInfoCollector.cs

@@ -35,6 +35,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
         private readonly IClock _clock;
         private readonly Persistence.StartupEventGate _startupGate;
 
+        // Live accessor for AgentConfiguration.EnableEspContinueAnywayObservation — read at
+        // esp_config_detected stamping time so a late remote-config merge takes effect on
+        // the phase-triggered re-emissions. Null (tests / legacy callers) means disabled.
+        private readonly Func<bool> _espContinueAnywayObservationEnabled;
+
         private const string RegKeyWindowsCurrentVersion = @"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion";
 
         // Restart dedup (StartupEventGate) — exemptions. boot_time is genuinely new per boot
@@ -65,7 +70,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
             AgentLogger logger,
             ISignalIngressSink signalIngress = null,
             IClock clock = null,
-            Persistence.StartupEventGate startupGate = null)
+            Persistence.StartupEventGate startupGate = null,
+            Func<bool> espContinueAnywayObservationEnabled = null)
         {
             _sessionId = sessionId ?? throw new ArgumentNullException(nameof(sessionId));
             _tenantId  = tenantId  ?? throw new ArgumentNullException(nameof(tenantId));
@@ -74,6 +80,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
             _signalIngress = signalIngress;
             _clock = clock;
             _startupGate = startupGate;
+            _espContinueAnywayObservationEnabled = espContinueAnywayObservationEnabled;
         }
 
         /// <summary>

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

@@ -10,6 +10,7 @@ using AutopilotMonitor.Agent.V2.Core.Monitoring.Runtime;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime;
 using AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.SystemSignals;
+using AutopilotMonitor.Shared.Logging;
 
 namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
 {
@@ -25,14 +26,21 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
         {
             var filePath = rule.Target;
             if (string.IsNullOrEmpty(filePath))
+            {
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser, "empty target — nothing to parse");
                 return null;
+            }
 
             // Expand custom tokens (%LOGGED_ON_USER_PROFILE%) and standard environment variables
             var userProfilePath = UserProfileResolver.ContainsUserProfileToken(filePath)
                 ? UserProfileResolver.GetLoggedOnUserProfilePath() : null;
             filePath = UserProfileResolver.ExpandCustomTokens(filePath);
             if (filePath == null)
+            {
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                    "target contains %LOGGED_ON_USER_PROFILE% but no user is logged on — skipped this run");
                 return null; // Token present but no user logged on — skip silently
+            }
 
             // 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
@@ -66,6 +74,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                 string.IsNullOrEmpty(patternStr))
             {
                 context.Logger.Warning($"LogParser rule {rule.RuleId} has no 'pattern' parameter");
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageError,
+                    "missing 'pattern' parameter — rule can never match");
                 return null;
             }
 
@@ -93,6 +103,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             catch (Exception ex)
             {
                 context.Logger.Warning($"LogParser rule {rule.RuleId} has invalid regex: {ex.Message}");
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageError,
+                    $"invalid regex pattern '{patternStr}' — rule can never match: {ex.Message}");
                 return null;
             }
 
@@ -101,6 +113,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             if (resolvedPaths.Count == 0)
             {
                 context.Logger.Debug($"LogParser rule {rule.RuleId}: no files found for: {filePath}");
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                    $"no files matched target {filePath}" + (HasWildcard(Path.GetFileName(filePath)) ? " (wildcard)" : "") + " — nothing to parse");
                 return null;
             }
 
@@ -120,6 +134,44 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             return null;
         }
 
+        // Per-match trace lines are capped per file per run — the per-file summary line
+        // still carries the full match count, this only bounds the per-match detail.
+        private const int MaxTracedMatchesPerFile = 10;
+
+        /// <summary>
+        /// Writes one debug-trace line per regex match: the line number, the matched text,
+        /// and every capture group that will land in the emitted event (same "0" exclusion
+        /// as the event data). Stops after <see cref="MaxTracedMatchesPerFile"/> matches.
+        /// </summary>
+        private static void TraceMatch(GatherRuleContext context, GatherRule rule, string fileName,
+            int lineNumber, Match match, Regex pattern, int matchNumber)
+        {
+            if (matchNumber > MaxTracedMatchesPerFile)
+            {
+                if (matchNumber == MaxTracedMatchesPerFile + 1)
+                    context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                        $"{fileName}: further matches not traced individually (cap {MaxTracedMatchesPerFile}/file/run) — see the per-file summary for the total");
+                return;
+            }
+
+            var sb = new StringBuilder();
+            sb.Append(fileName).Append(": line ").Append(lineNumber)
+              .Append(" matched \"").Append(TruncateMessage(match.Value, 200)).Append('"');
+
+            var first = true;
+            foreach (var groupName in pattern.GetGroupNames())
+            {
+                if (groupName == "0") continue;
+                var group = match.Groups[groupName];
+                if (!group.Success) continue;
+                sb.Append(first ? " — groups: " : ", ");
+                first = false;
+                sb.Append(groupName).Append("=\"").Append(TruncateMessage(group.Value, 100)).Append('"');
+            }
+
+            context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser, sb.ToString());
+        }
+
         private static bool HasWildcard(string fileNamePart)
             => !string.IsNullOrEmpty(fileNamePart) &&
                (fileNamePart.Contains("*") || fileNamePart.Contains("?"));
@@ -144,7 +196,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             try
             {
                 // Return matched files sorted by last write time (newest first), capped at 20
-                return Directory.GetFiles(directory, fileNamePart)
+                var allMatches = Directory.GetFiles(directory, fileNamePart);
+                if (allMatches.Length > 20)
+                    context.DebugLog(ruleId, GatherRuleDebugLog.StageLogParser,
+                        $"wildcard matched {allMatches.Length} files — capped to the 20 newest");
+                return allMatches
                     .OrderByDescending(f => new FileInfo(f).LastWriteTimeUtc)
                     .Take(20)
                     .ToList();
@@ -152,6 +208,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
             catch (Exception ex)
             {
                 context.Logger.Warning($"LogParser rule {ruleId}: wildcard expansion failed for {filePath}: {ex.Message}");
+                context.DebugLog(ruleId, GatherRuleDebugLog.StageError, $"wildcard expansion failed for {filePath}: {ex.Message}");
                 return new List<string>();
             }
         }
@@ -168,10 +225,16 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
 
                 // Nothing new to read
                 if (startPosition >= fileInfo.Length)
+                {
+                    context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                        $"{Path.GetFileName(filePath)}: no new content (position {startPosition} >= length {fileInfo.Length}) — trackPosition=true, nothing re-read");
                     return;
+                }
 
                 int matchCount = 0;
                 int linesRead = 0;
+                int parseFailCount = 0;
+                int timeoutCount = 0;
                 long endPosition = startPosition;
 
                 using (var stream = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite))
@@ -195,6 +258,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 }
                                 catch (RegexMatchTimeoutException)
                                 {
+                                    timeoutCount++;
                                     continue;
                                 }
                                 if (!match.Success)
@@ -233,13 +297,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 });
 
                                 matchCount++;
+                                TraceMatch(context, rule, Path.GetFileName(filePath), linesRead, match, pattern, matchCount);
                             }
                             else
                             {
                                 // CMTrace mode: parse line as CMTrace format, match regex against message
                                 CmTraceLogEntry entry;
                                 if (!CmTraceLogParser.TryParseLine(line, out entry))
+                                {
+                                    parseFailCount++;
                                     continue;
+                                }
 
                                 Match match;
                                 try
@@ -248,6 +316,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 }
                                 catch (RegexMatchTimeoutException)
                                 {
+                                    timeoutCount++;
                                     continue;
                                 }
                                 if (!match.Success)
@@ -288,6 +357,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 });
 
                                 matchCount++;
+                                TraceMatch(context, rule, Path.GetFileName(filePath), linesRead, match, pattern, matchCount);
                             }
                         }
 
@@ -301,10 +371,24 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
 
                 if (matchCount > 0)
                     context.Logger.Debug($"LogParser rule {rule.RuleId}: {matchCount} matches from {linesRead} lines in {Path.GetFileName(filePath)}");
+
+                // Per-file outcome — always written so a "matched 0" run is visible too.
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                    $"{Path.GetFileName(filePath)}: read {linesRead} lines from position {startPosition}->{endPosition}, " +
+                    $"matched {matchCount}, parseFailures={parseFailCount}, regexTimeouts={timeoutCount}, mode={(isTextMode ? "text" : "cmtrace")}");
+
+                if (!isTextMode && linesRead > 0 && parseFailCount == linesRead)
+                    context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                        "every line failed CMTrace parsing — if this is a plain-text log, set parameter format=text");
+
+                if (linesRead == maxLines)
+                    context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageLogParser,
+                        $"stopped at maxLines={maxLines} — remaining content is deferred to the next run");
             }
             catch (Exception ex)
             {
                 context.Logger.Warning($"LogParser rule {rule.RuleId} failed reading {filePath}: {ex.Message}");
+                context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageError, $"failed reading {filePath}: {ex}");
             }
         }
 

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

@@ -113,7 +113,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
 
                         // Suppress the "not found" event when the rule only wants a positive signal.
                         if (emitOnlyIfExists)
+                        {
+                            context.DebugLog(rule.RuleId, GatherRuleDebugLog.StageCollector,
+                                $"registry key/value not found: {path} — emitOnlyIfExists=true, empty result");
                             return new Dictionary<string, object>(); // empty → executor emits nothing
+                        }
 
                         data["exists"] = false;
                         data["path"] = path;

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

@@ -22,13 +22,20 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         public LogFilePositionTracker FilePositionTracker { get; }
         public bool UnrestrictedMode { get; set; }
 
+        /// <summary>
+        /// Optional gather-rule debug trace writer (EnableGatherRuleDebugLog). Null when
+        /// tracing is disabled — use <see cref="DebugLog"/> for null-safe writes.
+        /// </summary>
+        public GatherRuleDebugLog DebugWriter { get; }
+
         public GatherRuleContext(
             AgentLogger logger,
             string sessionId,
             string tenantId,
             Action<EnrollmentEvent> onEventCollected,
             string imeLogPathOverride,
-            LogFilePositionTracker filePositionTracker)
+            LogFilePositionTracker filePositionTracker,
+            GatherRuleDebugLog debugLog = null)
         {
             Logger = logger ?? throw new ArgumentNullException(nameof(logger));
             SessionId = sessionId ?? throw new ArgumentNullException(nameof(sessionId));
@@ -36,8 +43,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             OnEventCollected = onEventCollected ?? throw new ArgumentNullException(nameof(onEventCollected));
             ImeLogPathOverride = imeLogPathOverride;
             FilePositionTracker = filePositionTracker ?? throw new ArgumentNullException(nameof(filePositionTracker));
+            DebugWriter = debugLog;
         }
 
+        /// <summary>
+        /// Null-safe write to the gather-rule debug trace. No-op when tracing is disabled.
+        /// </summary>
+        public void DebugLog(string ruleId, string stage, string message) => DebugWriter?.Write(ruleId, stage, message);
+
         /// <summary>
         /// Emits a security_warning event and returns an empty result dictionary.
         /// Called when a gather rule targets a path/query not on the allowlist.
@@ -45,6 +58,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         public Dictionary<string, object> EmitSecurityWarning(GatherRule rule, string collectorType, string target)
         {
             Logger.Warning($"SECURITY: {collectorType} path blocked by guard: {target} (Rule: {rule.RuleId})");
+            DebugLog(rule.RuleId, GatherRuleDebugLog.StageGuard,
+                $"{collectorType} target blocked by allowlist guard: {target} — security_warning emitted, rule produced no data");
 
             var data = new Dictionary<string, object>
             {

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

@@ -0,0 +1,116 @@
+using System;
+using System.IO;
+using AutopilotMonitor.Agent.V2.Core.Logging;
+
+namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
+{
+    /// <summary>
+    /// Append-only trace file for gather-rule evaluation, enabled per tenant via
+    /// EnableGatherRuleDebugLog (or --gather-debug-log). Explains every evaluation
+    /// decision — including the outcomes that produce no event — so customers can
+    /// diagnose rules that never show up in the timeline. Every write failure is
+    /// swallowed: tracing must never break gathering.
+    /// </summary>
+    public sealed class GatherRuleDebugLog
+    {
+        public const string StageConfig = "config";
+        public const string StagePhase = "phase";
+        public const string StageTrigger = "trigger";
+        public const string StageScope = "scope";
+        public const string StageExec = "exec";
+        public const string StageCollector = "collector";
+        public const string StageGuard = "guard";
+        public const string StageEmit = "emit";
+        public const string StageSuppress = "suppress";
+        public const string StageLogParser = "logparser";
+        public const string StageError = "error";
+
+        private const long DefaultMaxBytes = 10 * 1024 * 1024;
+
+        private readonly string _path;
+        private readonly long _maxBytes;
+        private readonly Action<string> _echo;
+        private readonly object _lock = new object();
+        private bool _headerWritten;
+
+        public GatherRuleDebugLog(string path, AgentLogger logger, Action<string> echo = null, long maxBytes = DefaultMaxBytes)
+        {
+            if (string.IsNullOrEmpty(path)) throw new ArgumentNullException(nameof(path));
+            _path = path;
+            _maxBytes = maxBytes;
+            _echo = echo;
+            logger?.Info($"GatherRuleDebugLog: enabled -> {path}");
+        }
+
+        /// <summary>
+        /// Writes one trace line: <c>{utc} | {ruleId} | {stage} | {message}</c>.
+        /// Newlines in <paramref name="message"/> are flattened except for the error
+        /// stage, where exception stack traces stay multi-line.
+        /// </summary>
+        public void Write(string ruleId, string stage, string message)
+        {
+            try
+            {
+                if (stage != StageError && message != null && message.IndexOf('\n') >= 0)
+                    message = message.Replace("\r", "").Replace('\n', ' ');
+
+                var line = $"{DateTime.UtcNow:yyyy-MM-ddTHH:mm:ss.fffZ} | {ruleId ?? "-"} | {stage} | {message}";
+
+                lock (_lock)
+                {
+                    EnsureFileReadyLocked();
+                    File.AppendAllText(_path, line + Environment.NewLine);
+                }
+
+                _echo?.Invoke(line);
+            }
+            catch { }
+        }
+
+        /// <summary>
+        /// One-shot helper for callers that have no executor (e.g. the flag is on but the
+        /// backend delivered zero gather rules) — the customer's trace file should explain
+        /// that too instead of silently not existing.
+        /// </summary>
+        public static void WriteStandalone(string path, string message, AgentLogger logger)
+        {
+            if (string.IsNullOrEmpty(path)) return;
+            try
+            {
+                new GatherRuleDebugLog(path, logger).Write(null, StageConfig, message);
+            }
+            catch { }
+        }
+
+        // Lazy on first write: create the directory and emit a header line. Before every
+        // append, rotate when the file exceeds maxBytes — keeping exactly one .old
+        // generation (worst case ~2x maxBytes on disk).
+        private void EnsureFileReadyLocked()
+        {
+            if (!_headerWritten)
+            {
+                var dir = Path.GetDirectoryName(_path);
+                if (!string.IsNullOrEmpty(dir))
+                    Directory.CreateDirectory(dir);
+            }
+
+            var info = new FileInfo(_path);
+            if (info.Exists && info.Length > _maxBytes)
+            {
+                var oldPath = Path.ChangeExtension(_path, null) + ".old.log";
+                if (File.Exists(oldPath))
+                    File.Delete(oldPath);
+                File.Move(_path, oldPath);
+                File.AppendAllText(_path,
+                    $"{DateTime.UtcNow:yyyy-MM-ddTHH:mm:ss.fffZ} | - | {StageConfig} | -- rotated (previous file exceeded {_maxBytes} bytes) --" + Environment.NewLine);
+            }
+
+            if (!_headerWritten)
+            {
+                File.AppendAllText(_path,
+                    $"{DateTime.UtcNow:yyyy-MM-ddTHH:mm:ss.fffZ} | - | {StageConfig} | -- gather rule debug log started --" + Environment.NewLine);
+                _headerWritten = true;
+            }
+        }
+    }
+}

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

@@ -22,6 +22,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
     public class GatherRuleExecutor : IDisposable
     {
         private readonly AgentLogger _logger;
+        private readonly GatherRuleDebugLog _debug;   // null unless EnableGatherRuleDebugLog / --gather-debug-log
         private readonly GatherRuleContext _context;
         private readonly Dictionary<string, IGatherRuleCollector> _collectors;
 
@@ -61,7 +62,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         }
 
         public GatherRuleExecutor(string sessionId, string tenantId, Action<EnrollmentEvent> onEventCollected,
-            AgentLogger logger, string imeLogPathOverride = null)
+            AgentLogger logger, string imeLogPathOverride = null, string debugLogPath = null,
+            Action<string> debugEcho = null)
         {
             if (sessionId == null) throw new ArgumentNullException(nameof(sessionId));
             if (tenantId == null) throw new ArgumentNullException(nameof(tenantId));
@@ -69,9 +71,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             if (logger == null) throw new ArgumentNullException(nameof(logger));
 
             _logger = logger;
+            _debug = string.IsNullOrEmpty(debugLogPath) ? null : new GatherRuleDebugLog(debugLogPath, logger, debugEcho);
 
             var filePositionTracker = new LogFilePositionTracker();
-            _context = new GatherRuleContext(logger, sessionId, tenantId, onEventCollected, imeLogPathOverride, filePositionTracker);
+            _context = new GatherRuleContext(logger, sessionId, tenantId, onEventCollected, imeLogPathOverride, filePositionTracker, _debug);
 
             // Register all collector strategies
             var collectorList = new IGatherRuleCollector[]
@@ -96,6 +99,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             _collectors["command"] = _collectors["command_allowlisted"];
         }
 
+        /// <summary>
+        /// Null-safe write to the gather-rule debug trace. Never call while holding
+        /// <see cref="_scopeLock"/> — capture the message under the lock, write after release.
+        /// </summary>
+        private void DebugLog(string ruleId, string stage, string message) => _debug?.Write(ruleId, stage, message);
+
         /// <summary>
         /// Updates the active rules and starts/stops execution accordingly
         /// </summary>
@@ -111,11 +120,43 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
             _activeRules = rules.Where(r => r.Enabled).ToList();
 
+            // Registration summary for the debug trace: one line per delivered rule so the
+            // customer can see exactly what the agent received and how it will be triggered.
+            if (_debug != null)
+            {
+                foreach (var rule in rules)
+                {
+                    if (!rule.Enabled)
+                    {
+                        DebugLog(rule.RuleId, GatherRuleDebugLog.StageConfig, "rule disabled — will never run");
+                        continue;
+                    }
+
+                    var scope = rule.ActivePhases != null && rule.ActivePhases.Count > 0
+                        ? $"activePhases=[{string.Join(",", rule.ActivePhases)}]"
+                        : !string.IsNullOrEmpty(rule.ActiveFromPhase)
+                            ? $"activeFromPhase={rule.ActiveFromPhase}"
+                            : "unscoped";
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageConfig,
+                        $"registered: trigger={rule.Trigger}" +
+                        (string.IsNullOrEmpty(rule.TriggerPhase) ? "" : $" triggerPhase={rule.TriggerPhase}") +
+                        (string.IsNullOrEmpty(rule.TriggerEventType) ? "" : $" triggerEventType={rule.TriggerEventType}") +
+                        $", collector={rule.CollectorType}, target={rule.Target}, {scope}" +
+                        $", emitMode={(string.IsNullOrEmpty(rule.EmitMode) ? "always" : rule.EmitMode)}" +
+                        (rule.IntervalSeconds.HasValue ? $", interval={rule.IntervalSeconds}s" : ""));
+
+                    if (rule.Trigger == "interval" && !rule.IntervalSeconds.HasValue)
+                        DebugLog(rule.RuleId, GatherRuleDebugLog.StageError,
+                            "trigger=interval but intervalSeconds is missing — rule will NEVER run");
+                }
+            }
+
             // 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;
+            var deferredTraces = _debug != null ? new List<KeyValuePair<string, string>>() : null;
             lock (_scopeLock)
             {
                 // A config refresh may deliver new from-phase rules after their phase was
@@ -124,7 +165,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
                 pendingStartup = _activeRules
                     .Where(r => r.Trigger == "startup" && !_startupRulesExecuted.Contains(r.RuleId))
-                    .Where(r => IsRuleInScopeLocked(r))
+                    .Where(r =>
+                    {
+                        string reason;
+                        var inScope = IsRuleInScopeLocked(r, out reason);
+                        if (!inScope && deferredTraces != null)
+                            deferredTraces.Add(new KeyValuePair<string, string>(r.RuleId,
+                                $"startup rule deferred — {reason}; runs once when its scope activates"));
+                        return inScope;
+                    })
                     .ToList();
 
                 foreach (var rule in pendingStartup)
@@ -133,6 +182,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 }
             }
 
+            if (deferredTraces != null)
+            {
+                foreach (var trace in deferredTraces)
+                    DebugLog(trace.Key, GatherRuleDebugLog.StageScope, trace.Value);
+            }
+
             if (pendingStartup.Count > 0)
             {
                 _startupRulesLatch?.Dispose();
@@ -158,8 +213,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 var timer = new Timer(
                     _ =>
                     {
-                        if (!IsRuleInScope(intervalRule))
+                        string skipReason;
+                        if (!IsRuleInScope(intervalRule, out skipReason))
+                        {
+                            DebugLog(intervalRule.RuleId, GatherRuleDebugLog.StageScope, $"interval tick skipped: {skipReason}");
                             return;
+                        }
                         ExecuteRule(intervalRule);
                     },
                     null,
@@ -168,6 +227,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 );
                 _intervalTimers[intervalRule.RuleId] = timer;
                 _logger.Info($"  Interval rule {intervalRule.RuleId} scheduled every {intervalRule.IntervalSeconds}s");
+                DebugLog(intervalRule.RuleId, GatherRuleDebugLog.StageTrigger,
+                    $"interval timer scheduled every {intervalRule.IntervalSeconds}s (first run after one full interval — no immediate execution)");
             }
 
             _logger.Info($"GatherRuleExecutor: {_activeRules.Count(r => r.Trigger == "startup")} startup, " +
@@ -187,9 +248,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             // _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;
+            EnrollmentPhase previousPhase;
+            var exitTraces = _debug != null ? new List<KeyValuePair<string, string>>() : null;
             lock (_scopeLock)
             {
-                var previousPhase = _currentPhase;
+                previousPhase = _currentPhase;
                 if (previousPhase != EnrollmentPhase.Unknown && previousPhase != newPhase)
                 {
                     var previousPhaseName = previousPhase.ToString();
@@ -204,12 +267,22 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
                         // 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;
+                        string scopeReason;
+                        if (!IsRuleInScopeLocked(rule, out scopeReason))
+                        {
+                            if (exitTraces != null)
+                                exitTraces.Add(new KeyValuePair<string, string>(rule.RuleId,
+                                    $"phase_exit of {previousPhaseName} skipped: {scopeReason}"));
+                            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");
+                            if (exitTraces != null)
+                                exitTraces.Add(new KeyValuePair<string, string>(rule.RuleId,
+                                    $"phase_exit already executed for exit of {previousPhaseName} — once per (rule, phase)"));
                             continue;
                         }
 
@@ -219,6 +292,21 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 }
             }
 
+            // Transition marker first, so every rule-level line below reads against it.
+            // Written outside _scopeLock like all trace lines.
+            if (previousPhase != newPhase)
+                DebugLog(null, GatherRuleDebugLog.StagePhase,
+                    $"phase change: {previousPhase} -> {phaseName}" +
+                    (previousPhase == EnrollmentPhase.Unknown
+                        ? " (first phase signal — scoped rules now evaluate against this phase)"
+                        : ""));
+
+            if (exitTraces != null)
+            {
+                foreach (var trace in exitTraces)
+                    DebugLog(trace.Key, GatherRuleDebugLog.StageScope, trace.Value);
+            }
+
             if (exitRules != null)
             {
                 foreach (var rule in exitRules)
@@ -252,6 +340,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             {
                 var deferredRule = rule;
                 _logger.Info($"Phase {phaseName} activated deferred startup rule {deferredRule.RuleId}");
+                DebugLog(deferredRule.RuleId, GatherRuleDebugLog.StageTrigger,
+                    $"phase {phaseName} activated deferred startup rule");
                 ThreadPool.QueueUserWorkItem(_ => ExecuteRule(deferredRule));
             }
 
@@ -262,18 +352,26 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 {
                     // Scope gate BEFORE the dedup add — an out-of-scope pass must not consume
                     // the once-per-(rule, phase) execution slot.
-                    if (!IsRuleInScope(rule))
+                    string scopeReason;
+                    if (!IsRuleInScope(rule, out scopeReason))
+                    {
+                        DebugLog(rule.RuleId, GatherRuleDebugLog.StageScope,
+                            $"phase_change to {phaseName} skipped: {scopeReason}");
                         continue;
+                    }
 
                     // Deduplicate: only fire once per (ruleId, phase) combination
                     var deduplicationKey = $"{rule.RuleId}|{phaseName}";
                     if (!_phaseRulesExecuted.Add(deduplicationKey))
                     {
                         _logger.Debug($"Phase rule {rule.RuleId} already executed for phase {phaseName}, skipping");
+                        DebugLog(rule.RuleId, GatherRuleDebugLog.StageTrigger,
+                            $"phase_change already executed for phase {phaseName} — once per (rule, phase)");
                         continue;
                     }
 
                     _logger.Info($"Phase change triggered rule {rule.RuleId} (phase: {phaseName})");
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageTrigger, $"phase_change to {phaseName} fired");
                     ThreadPool.QueueUserWorkItem(_ => ExecuteRule(rule));
                 }
             }
@@ -288,10 +386,16 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             {
                 if (string.Equals(rule.TriggerEventType, eventType, StringComparison.OrdinalIgnoreCase))
                 {
-                    if (!IsRuleInScope(rule))
+                    string scopeReason;
+                    if (!IsRuleInScope(rule, out scopeReason))
+                    {
+                        DebugLog(rule.RuleId, GatherRuleDebugLog.StageScope,
+                            $"on_event {eventType} skipped: {scopeReason}");
                         continue;
+                    }
 
                     _logger.Info($"Event triggered rule {rule.RuleId} (event: {eventType})");
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageTrigger, $"on_event {eventType} fired");
                     ThreadPool.QueueUserWorkItem(_ => ExecuteRule(rule));
                 }
             }
@@ -302,6 +406,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             try
             {
                 _logger.Info($"Executing gather rule: {rule.RuleId} ({rule.Title})");
+                DebugLog(rule.RuleId, GatherRuleDebugLog.StageExec, $"executing: collector={rule.CollectorType}, target={rule.Target}");
 
                 var collectorType = rule.CollectorType?.ToLower();
 
@@ -309,6 +414,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 if (collectorType == null || !_collectors.TryGetValue(collectorType, out collector))
                 {
                     _logger.Warning($"Unknown collector type: {rule.CollectorType} for rule {rule.RuleId}");
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageError, $"unknown collector type '{rule.CollectorType}' — nothing emitted");
                     return;
                 }
 
@@ -316,7 +422,19 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
                 // LogParser (and potentially others) emit events directly and return null
                 if (result == null)
+                {
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageCollector,
+                        collectorType == "logparser"
+                            ? "logparser emits per-match events directly — see logparser lines above for the per-file outcome"
+                            : "collector returned null — nothing emitted");
                     return;
+                }
+
+                if (result.Count == 0)
+                {
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageCollector,
+                        "collector returned EMPTY result — nothing emitted (typical causes: target not found with emitOnlyIfExists, or guard block — see guard line if present)");
+                }
 
                 if (result.Count > 0)
                 {
@@ -325,8 +443,19 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                     // 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;
+                    if (IsOnChangeMode(rule))
+                    {
+                        string hashPrefix;
+                        int suppressedStreak;
+                        if (!ShouldEmitOnChange(rule, result, out hashPrefix, out suppressedStreak))
+                        {
+                            DebugLog(rule.RuleId, GatherRuleDebugLog.StageSuppress,
+                                $"result unchanged (hash {hashPrefix}) — emit suppressed (on_change), suppressed streak={suppressedStreak}");
+                            return;
+                        }
+                        DebugLog(rule.RuleId, GatherRuleDebugLog.StageEmit,
+                            $"result changed (hash {hashPrefix})" + (suppressedStreak > 0 ? $" after {suppressedStreak} suppressed polls" : ""));
+                    }
 
                     result["ruleId"] = rule.RuleId;
                     result["ruleTitle"] = rule.Title;
@@ -357,11 +486,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                         Message = $"Gather: {rule.Title}",
                         Data = result
                     });
+                    DebugLog(rule.RuleId, GatherRuleDebugLog.StageEmit,
+                        $"emitted {eventType} (severity={severity}, {result.Count} fields)");
                 }
             }
             catch (Exception ex)
             {
                 _logger.Warning($"Gather rule {rule.RuleId} failed: {ex.Message}");
+                // Full exception incl. stack trace only in the debug trace — the agent log stays terse.
+                DebugLog(rule.RuleId, GatherRuleDebugLog.StageError, $"rule execution failed: {ex}");
             }
         }
 
@@ -375,15 +508,33 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
         // Internal so the scope matrix is testable synchronously (no timer/ThreadPool races).
         internal bool IsRuleInScope(GatherRule rule)
+        {
+            string reason;
+            return IsRuleInScope(rule, out reason);
+        }
+
+        /// <summary>
+        /// Scope gate with a human-readable skip reason for the debug trace. The reason is
+        /// captured under the lock but must be WRITTEN outside it (never trace under _scopeLock).
+        /// </summary>
+        internal bool IsRuleInScope(GatherRule rule, out string reason)
         {
             lock (_scopeLock)
             {
-                return IsRuleInScopeLocked(rule);
+                return IsRuleInScopeLocked(rule, out reason);
             }
         }
 
         private bool IsRuleInScopeLocked(GatherRule rule)
         {
+            string reason;
+            return IsRuleInScopeLocked(rule, out reason);
+        }
+
+        private bool IsRuleInScopeLocked(GatherRule rule, out string reason)
+        {
+            reason = null;
+
             if (!HasPhaseScope(rule))
                 return true; // unscoped — legacy behavior
 
@@ -400,7 +551,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 // No phase signal yet (or scope tokens that never match, e.g. "Unknown"):
                 // scoped rules stay inactive.
                 if (_currentPhase == EnrollmentPhase.Unknown)
+                {
+                    reason = "currentPhase=Unknown — scoped rules stay inactive until the first phase signal";
                     return false;
+                }
 
                 var phaseName = _currentPhase.ToString();
                 foreach (var phase in rule.ActivePhases)
@@ -408,10 +562,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                     if (string.Equals(phase, phaseName, StringComparison.OrdinalIgnoreCase))
                         return true;
                 }
+                reason = $"out of scope (currentPhase={phaseName}, activePhases=[{string.Join(",", rule.ActivePhases)}])";
                 return false;
             }
 
-            return _fromPhaseLatched.Contains(rule.RuleId);
+            if (_fromPhaseLatched.Contains(rule.RuleId))
+                return true;
+
+            reason = $"activeFromPhase={rule.ActiveFromPhase} not latched yet (currentPhase={_currentPhase})";
+            return false;
         }
 
         /// <summary>
@@ -457,8 +616,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         /// Internal so the state machine is testable synchronously (no timer/ThreadPool races).
         /// </summary>
         internal bool ShouldEmitOnChange(GatherRule rule, Dictionary<string, object> result)
+        {
+            string hashPrefix;
+            int suppressedStreak;
+            return ShouldEmitOnChange(rule, result, out hashPrefix, out suppressedStreak);
+        }
+
+        /// <summary>
+        /// Overload exposing the hash prefix and suppression streak for the debug trace:
+        /// on suppress, <paramref name="suppressedStreak"/> is the updated streak count;
+        /// on emit, it is the streak that just ended (0 when none).
+        /// </summary>
+        internal bool ShouldEmitOnChange(GatherRule rule, Dictionary<string, object> result,
+            out string hashPrefix, out int suppressedStreak)
         {
             var hash = ComputeCanonicalHash(result);
+            hashPrefix = hash.Length > 8 ? hash.Substring(0, 8) : hash;
+            suppressedStreak = 0;
             bool emit;
             lock (_scopeLock)
             {
@@ -469,6 +643,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                     _suppressed[rule.RuleId] = _suppressed.TryGetValue(rule.RuleId, out streak)
                         ? (streak.Count + 1, streak.SinceUtc)
                         : (1, DateTime.UtcNow);
+                    suppressedStreak = _suppressed[rule.RuleId].Count;
                     emit = false;
                 }
                 else
@@ -479,6 +654,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                     {
                         result["suppressedPolls"] = streak.Count;
                         result["suppressedSinceUtc"] = streak.SinceUtc.ToString("o", CultureInfo.InvariantCulture);
+                        suppressedStreak = streak.Count;
                     }
                     _suppressed.Remove(rule.RuleId);
                     emit = true;

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

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using System.Reflection;
+using System.Text.RegularExpressions;
 using Newtonsoft.Json.Linq;
 
 namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
@@ -35,9 +36,29 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         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");
-        private static readonly string[] AdditionalHardBlockedPathPrefixes = new[]
+        // Derived from AllowedWmiQueryPrefixes: entries of the canonical form
+        // "SELECT * FROM <class>" contribute their class name; any other entry
+        // (none today) stays on the legacy literal-prefix path.
+        private static readonly HashSet<string> AllowedWmiClasses;
+        private static readonly List<string> ResidualWmiPrefixes;
+
+        // Canonical allowlist entry: exactly "SELECT * FROM <class>".
+        private static readonly Regex CanonicalWmiEntryRegex = new Regex(
+            @"^SELECT\s+\*\s+FROM\s+([A-Za-z_][A-Za-z0-9_]*)$",
+            RegexOptions.IgnoreCase | RegexOptions.Compiled);
+
+        // WQL shape "SELECT <* | property-list> FROM <class>", class token bounded
+        // by whitespace or end of string (a trailing WHERE clause is permitted,
+        // "Win32_BIOSX" cannot pass as "Win32_BIOS").
+        private static readonly Regex WmiQueryRegex = new Regex(
+            @"^SELECT\s+(?:\*|[A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*)*)\s+FROM\s+([A-Za-z_][A-Za-z0-9_]*)(?=\s|$)",
+            RegexOptions.IgnoreCase | RegexOptions.Compiled);
+
+        // Hard blocks: never allowed, even in unrestricted mode. Internal (not private)
+        // so GuardrailsParityTests can pin the guardrails.json display mirror to these
+        // constants — enforcement stays code-only by design.
+        internal static readonly string BlockedUsersPrefix = Path.GetFullPath(@"C:\Users");
+        internal static readonly string[] AdditionalHardBlockedPathPrefixes = new[]
         {
             Path.GetFullPath(@"C:\Windows\System32\config"),  // SAM, SECURITY, SYSTEM hives
         };
@@ -50,14 +71,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         };
 
         // Hard limit: maximum command length (even in unrestricted mode)
-        private const int MaxCommandLength = 2000;
+        internal 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[]
+        internal static readonly string[] HardBlockedEventLogChannels = new[]
         {
             "Security",
             "Microsoft-Windows-PowerShell",
@@ -67,7 +88,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
 
         // Hard-blocked command patterns: never allowed, even in unrestricted mode.
         // These prevent privilege escalation, persistence, and data exfiltration.
-        private static readonly string[] HardBlockedCommandPatterns = new[]
+        // Mirrored in rules/guardrails.json ("blockedCommandPatterns") for portal/MCP
+        // pre-flight display — enforcement lives here so a parse error cannot lift it.
+        internal static readonly string[] HardBlockedCommandPatterns = new[]
         {
             // Download / exfiltration
             "Invoke-WebRequest", "Invoke-RestMethod", "Start-BitsTransfer",
@@ -101,6 +124,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                     AllowedCommands = new HashSet<string>(commands, StringComparer.OrdinalIgnoreCase);
 
                     AllowedEventLogChannels = FlattenCategorized(obj, "eventLogChannels", "channels");
+                    DeriveWmiClassAllowlist(AllowedWmiQueryPrefixes, out AllowedWmiClasses, out ResidualWmiPrefixes);
                     return;
                 }
             }
@@ -115,6 +139,26 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
             AllowedWmiQueryPrefixes = new List<string>();
             AllowedCommands = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
             AllowedEventLogChannels = new List<string>();
+            AllowedWmiClasses = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            ResidualWmiPrefixes = new List<string>();
+        }
+
+        private static void DeriveWmiClassAllowlist(
+            IReadOnlyList<string> entries,
+            out HashSet<string> classes,
+            out List<string> residual)
+        {
+            classes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            residual = new List<string>();
+
+            foreach (var entry in entries)
+            {
+                var match = CanonicalWmiEntryRegex.Match(entry.Trim());
+                if (match.Success)
+                    classes.Add(match.Groups[1].Value);
+                else
+                    residual.Add(entry);
+            }
         }
 
         private static string LoadEmbeddedGuardrails()
@@ -250,8 +294,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
         }
 
         /// <summary>
-        /// Returns true if the WMI query (trimmed) matches an allowed prefix
-        /// with boundary matching (next char must be whitespace or end of string).
+        /// Returns true if the WMI query (trimmed) is "SELECT &lt;* | property-list&gt; FROM &lt;class&gt;"
+        /// (optionally followed by a WHERE clause) against a class on the allowlist.
+        /// A property projection exposes a strict subset of the allowed "SELECT *".
         /// </summary>
         public static bool IsWmiQueryAllowed(string query)
             => IsWmiQueryAllowed(query, unrestrictedMode: false);
@@ -269,7 +314,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather
                 return true;
 
             var trimmed = query.Trim();
-            return AllowedWmiQueryPrefixes.Any(prefix =>
+
+            var match = WmiQueryRegex.Match(trimmed);
+            if (match.Success && AllowedWmiClasses.Contains(match.Groups[1].Value))
+                return true;
+
+            // Non-canonical allowlist entries keep the legacy literal-prefix match.
+            return ResidualWmiPrefixes.Any(prefix =>
                 trimmed.StartsWith(prefix, StringComparison.OrdinalIgnoreCase) &&
                 (trimmed.Length == prefix.Length || char.IsWhiteSpace(trimmed[prefix.Length])));
         }

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

@@ -77,11 +77,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic
 
         protected override void Collect()
         {
-            // Full path writes 18 keys: agent_version + process metrics (5: cpu, ws, private,
-            // threads, handles) + spool stats (4) + network delta (8: requests, failures,
-            // bytes_up/down, avg_latency, total_up/down/requests). cap=18 → HashHelpers.GetPrime(18)=23
-            // buckets → no resize on the 18th key (cap=16 would land at 17 buckets and resize).
-            var data = new Dictionary<string, object>(capacity: 18, StringComparer.Ordinal)
+            // Full path writes 19 keys: agent_version + process metrics (5: cpu, ws, private,
+            // threads, handles) + spool stats (4) + network delta (9: requests, failures,
+            // bytes_up/down, avg_latency, total_up/down/requests/latency). cap=19 →
+            // HashHelpers.GetPrime(19)=23 buckets → no resize on the 19th key.
+            var data = new Dictionary<string, object>(capacity: 19, StringComparer.Ordinal)
             {
                 { "agent_version", _agentVersion }
             };
@@ -164,6 +164,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic
                 data["net_total_bytes_up"] = currentNet.TotalBytesUp;
                 data["net_total_bytes_down"] = currentNet.TotalBytesDown;
                 data["net_total_requests"] = currentNet.RequestCount;
+                // Cumulative latency sum: total/requests = session-wide average HTTP
+                // round-trip. The backend projects that average onto the Session row
+                // (AvgApiLatencyMs) — cumulative counters make the write idempotent.
+                data["net_total_latency_ms"] = currentNet.TotalLatencyMs;
             }
             catch (Exception ex)
             {

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

@@ -8,8 +8,8 @@ using System.Net.Sockets;
 using System.Threading;
 using System.Threading.Tasks;
 using AutopilotMonitor.Agent.V2.Core.Logging;
+using AutopilotMonitor.Agent.V2.Core.Monitoring.Interop;
 using AutopilotMonitor.Agent.V2.Core.Orchestration;
-using AutopilotMonitor.Agent.V2.Core.Security;
 using AutopilotMonitor.Shared;
 using AutopilotMonitor.Shared.Models;
 
@@ -37,7 +37,6 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic
         private const int DebounceDelayMs = 3000;
         private const int ConnectivityCheckDelayMs = 5000;
         private const int ConnectivityCheckTimeoutMs = 8000;
-        private const int WifiCollectTimeoutMs = 3000;
         private const string Source = "NetworkChangeDetector";
 
         /// <summary>
@@ -374,7 +373,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic
                 // Collect WiFi SSID synchronously (needed for before/after comparison)
                 if (isWifi)
                 {
-                    var wifiInfo = CollectWiFiInfo();
+                    Guid? nicGuid = Guid.TryParse(activeNic.Id, out var parsedGuid) ? parsedGuid : (Guid?)null;
+                    var wifiInfo = CollectWiFiInfo(nicGuid);
                     snapshot.WifiSsid = wifiInfo.ssid;
                     snapshot.WifiSignalPercent = wifiInfo.signal;
                     snapshot.WifiRadioType = wifiInfo.radioType;
@@ -390,73 +390,30 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Periodic
         }
 
         /// <summary>
-        /// Collects WiFi SSID, signal, and radio type via netsh wlan show interfaces.
-        /// Synchronous with timeout — needed before emitting the event.
+        /// Collects WiFi SSID, signal, and radio type via the native WLAN API
+        /// (<see cref="WifiInfoReader"/> — language-neutral, no process spawn).
+        /// Synchronous — needed before emitting the event.
         /// </summary>
-        private (string ssid, int? signal, string radioType) CollectWiFiInfo()
+        private (string ssid, int? signal, string radioType) CollectWiFiInfo(Guid? interfaceGuid)
         {
-            string ssid = null;
-            int? signal = null;
-            string radioType = null;
-
             try
             {
-                var psi = new ProcessStartInfo
+                var wifi = WifiInfoReader.TryGetCurrentConnection(interfaceGuid, out var wifiDiag);
+                if (wifi == null)
                 {
-                    FileName = SystemPaths.Netsh,
-                    Arguments = "wlan show interfaces",
-                    UseShellExecute = false,
-                    RedirectStandardOutput = true,
-                    RedirectStandardError = true,
-                    CreateNoWindow = true
-                };
-
-                string output;
-                using (var process = Process.Start(psi))
-                {
-                    output = process.StandardOutput.ReadToEnd();
-                    if (!process.WaitForExit(WifiCollectTimeoutMs))
-                    {
-                        try { process.Kill(); } catch { }
-                        _logger.Debug("NetworkChangeDetector: netsh timed out");
-                        return (null, null, null);
-                    }
+                    _logger.Debug($"NetworkChangeDetector: native WLAN API returned no WiFi info ({wifiDiag ?? "no connected WLAN interface"}) — trying netsh fallback");
+                    wifi = NetshWifiFallback.TryRead();
                 }
 
-                if (string.IsNullOrEmpty(output))
-                    return (null, null, null);
-
-                foreach (var line in output.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries))
-                {
-                    var trimmed = line.Trim();
-                    var colonIndex = trimmed.IndexOf(':');
-                    if (colonIndex < 0) continue;
-
-                    var key = trimmed.Substring(0, colonIndex).Trim();
-                    var value = trimmed.Substring(colonIndex + 1).Trim();
-
-                    if (key.Equals("SSID", StringComparison.OrdinalIgnoreCase) &&
-                        !key.Equals("BSSID", StringComparison.OrdinalIgnoreCase))
-                    {
-                        ssid = value;
-                    }
-                    else if (key.Equals("Signal", StringComparison.OrdinalIgnoreCase))
-                    {
-                        if (int.TryParse(value.TrimEnd('%'), out var sig))
-                            signal = sig;
-                    }
-                    else if (key.Equals("Radio type", StringComparison.OrdinalIgnoreCase))
-                    {
-                        radioType = value;
-                    }
-                }
+                if (wifi != null)
+                    return (wifi.Ssid, wifi.SignalPercent, wifi.RadioType);
             }
             catch (Exception ex)
             {
                 _logger.Debug($"NetworkChangeDetector: WiFi info collection failed: {ex.Message}");
             }
 
-            return (ssid, signal, radioType);
+            return (null, null, null);
         }
 
         // -------------------------------------------------------------------

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Transport/BackendApiClient.cs

@@ -137,7 +137,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
                             continue;
                         }
 
-                        ThrowOnAuthFailure(response);
+                        await ThrowOnAuthFailureAsync(response).ConfigureAwait(false);
                         response.EnsureSuccessStatusCode();
 
                         var responseJson = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
@@ -236,7 +236,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
 
                 using (response)
                 {
-                    ThrowOnAuthFailure(response);
+                    await ThrowOnAuthFailureAsync(response).ConfigureAwait(false);
                     response.EnsureSuccessStatusCode();
 
                     var responseJson = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
@@ -282,16 +282,97 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
         /// <summary>
         /// Throws <see cref="BackendAuthException"/> for 401/403 responses so callers can
         /// distinguish authentication failures from transient server errors.
+        /// <para>
+        /// Field case (sits-d.cloud, 2026-08-09): a pre-cutover agent build pointed at a
+        /// retired Function App; Azure answers for a stopped app with a platform-level 403
+        /// carrying an HTML error page ("Web App - Unavailable"). Our backend never returns
+        /// HTML on 401/403 — an HTML body therefore means the response did not come from the
+        /// backend's auth layer at all (stopped/retired app, edge proxy, WAF). Reporting that
+        /// as "device is not authorized" sends troubleshooting down the wrong path, so the
+        /// two cases get distinct messages and the exception carries a flag.
+        /// </para>
         /// </summary>
-        private static void ThrowOnAuthFailure(HttpResponseMessage response)
+        private static async Task ThrowOnAuthFailureAsync(HttpResponseMessage response)
         {
-            if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized ||
-                response.StatusCode == System.Net.HttpStatusCode.Forbidden)
+            if (response.StatusCode != System.Net.HttpStatusCode.Unauthorized &&
+                response.StatusCode != System.Net.HttpStatusCode.Forbidden)
             {
+                return;
+            }
+
+            var statusText = $"{(int)response.StatusCode} {response.StatusCode}";
+
+            string body = null;
+            try
+            {
+                body = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
+            }
+            catch
+            {
+                // Body is diagnostic-only; classification below treats null as non-HTML.
+            }
+
+            if (LooksLikeHtmlErrorPage(response, body))
+            {
+                var title = TryExtractHtmlTitle(body);
+                var titleText = title != null ? $" (\"{title}\")" : string.Empty;
+                var host = response.RequestMessage?.RequestUri?.Host ?? "(unknown host)";
                 throw new BackendAuthException(
-                    $"Backend returned {(int)response.StatusCode} {response.StatusCode}. " +
-                    "The device is not authorized. Check client certificate and Autopilot device validation.",
-                    (int)response.StatusCode);
+                    $"Backend returned {statusText} with an HTML platform error page{titleText} from '{host}'. " +
+                    "This response did not come from the Autopilot Monitor backend — the endpoint appears stopped, " +
+                    "retired, or intercepted by a proxy. This is NOT a device-authorization failure; an outdated " +
+                    "agent build pointing at a stale ApiBaseUrl is the most likely cause.",
+                    (int)response.StatusCode,
+                    endpointUnavailable: true);
+            }
+
+            throw new BackendAuthException(
+                $"Backend returned {statusText}. " +
+                "The device is not authorized. Check client certificate and Autopilot device validation.",
+                (int)response.StatusCode);
+        }
+
+        /// <summary>
+        /// True when a 401/403 response is an HTML page rather than a backend JSON/plain-text
+        /// reply. Checks the declared Content-Type first, then falls back to sniffing the body
+        /// prefix so a platform page served with a generic Content-Type is still recognized.
+        /// </summary>
+        private static bool LooksLikeHtmlErrorPage(HttpResponseMessage response, string body)
+        {
+            var mediaType = response.Content?.Headers?.ContentType?.MediaType;
+            if (string.Equals(mediaType, "text/html", StringComparison.OrdinalIgnoreCase))
+                return true;
+
+            if (string.IsNullOrWhiteSpace(body))
+                return false;
+
+            var head = body.TrimStart();
+            return head.StartsWith("<!DOCTYPE", StringComparison.OrdinalIgnoreCase) ||
+                   head.StartsWith("<html", StringComparison.OrdinalIgnoreCase);
+        }
+
+        /// <summary>
+        /// Best-effort extraction of the HTML &lt;title&gt; (e.g. "Web App - Unavailable") so the
+        /// log line names the platform page without dumping markup. Null when absent/oversized.
+        /// </summary>
+        private static string TryExtractHtmlTitle(string body)
+        {
+            if (string.IsNullOrEmpty(body)) return null;
+            try
+            {
+                var match = System.Text.RegularExpressions.Regex.Match(
+                    body, @"<title[^>]*>\s*(.*?)\s*</title>",
+                    System.Text.RegularExpressions.RegexOptions.IgnoreCase |
+                    System.Text.RegularExpressions.RegexOptions.Singleline,
+                    TimeSpan.FromMilliseconds(250));
+                if (!match.Success) return null;
+
+                var title = match.Groups[1].Value;
+                return title.Length == 0 ? null : (title.Length > 80 ? title.Substring(0, 80) : title);
+            }
+            catch
+            {
+                return null;
             }
         }
 
@@ -330,7 +411,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
     }
 
     /// <summary>
-    /// Thrown when the backend returns 401 or 403, indicating the device is not authorized.
+    /// Thrown when the backend returns 401 or 403, indicating the device is not authorized —
+    /// or, when <see cref="EndpointUnavailable"/> is set, that the 401/403 was a platform-level
+    /// HTML response (stopped/retired app, edge proxy) rather than a backend auth verdict.
     /// </summary>
     public class BackendAuthException : Exception
     {
@@ -340,9 +423,16 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
         /// </summary>
         public int StatusCode { get; }
 
-        public BackendAuthException(string message, int statusCode = 0) : base(message)
+        /// <summary>
+        /// True when the 401/403 carried an HTML platform error page — the endpoint itself is
+        /// stopped/retired/proxied and the status says nothing about this device's authorization.
+        /// </summary>
+        public bool EndpointUnavailable { get; }
+
+        public BackendAuthException(string message, int statusCode = 0, bool endpointUnavailable = false) : base(message)
         {
             StatusCode = statusCode;
+            EndpointUnavailable = endpointUnavailable;
         }
     }
 }

src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Transport/DistressReporter.cs

@@ -56,6 +56,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
         private DateTime? _lastReportTime;
         private int _reportCount;
 
+        // Local W365 marker verdict, captured once at construction (same UNVERIFIED contract
+        // as the hardware fields). Optional ctor arg so test fakes stay source-compatible.
+        private readonly bool _isCloudPc;
+
         public DistressReporter(
             string baseUrl,
             string tenantId,
@@ -64,7 +68,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
             string serialNumber,
             string agentVersion,
             AgentLogger logger,
-            X509Certificate2 clientCertificate = null)
+            X509Certificate2 clientCertificate = null,
+            bool isCloudPc = false)
         {
             _tenantId = tenantId;
             _manufacturer = manufacturer;
@@ -72,6 +77,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
             _serialNumber = serialNumber;
             _agentVersion = agentVersion;
             _logger = logger;
+            _isCloudPc = isCloudPc;
 
             // Capture cert context. Each field is independently nullable so the backend can tell
             // "agent had no cert at all" (NoCertInStore + all-null fields) from "agent had a cert
@@ -169,6 +175,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Transport
                 HttpStatusCode = httpStatusCode,
                 Message = Truncate(message, 256),
                 Timestamp = DateTime.UtcNow,
+                IsCloudPc = _isCloudPc,
                 CertSourceState = _capturedCertState,
                 CertThumbprint = _capturedCertThumbprint,
                 CertSubject = Truncate(_capturedCertSubject, 96),

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

@@ -97,7 +97,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             IReadOnlyCollection<string> whiteGloveSealingPatternIds,
             ISignalIngressSink ingress,
             IClock clock,
-            Transport.Telemetry.ITelemetrySpool? telemetrySpool)
+            Transport.Telemetry.ITelemetrySpool? telemetrySpool,
+            TimelineEventStream? timelineEvents = null)
         {
             if (string.IsNullOrEmpty(sessionId)) throw new ArgumentException("SessionId required.", nameof(sessionId));
             if (string.IsNullOrEmpty(tenantId)) throw new ArgumentException("TenantId required.", nameof(tenantId));
@@ -126,7 +127,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                 ingress: ingress,
                 clock: clock,
                 logger: logger,
-                startupGate: _startupEventGate));
+                startupGate: _startupEventGate,
+                // Live accessor (not the current value): a remote-config merge landing after
+                // factory construction must still reach the phase-triggered re-emissions.
+                espContinueAnywayObservationEnabled: () => _agentConfig.EnableEspContinueAnywayObservation));
 
             // Session caa6cf50 gate-starvation fix: the EspAndHelloTracker's user-ESP-apps-settled
             // probe reads the IME log host, which is constructed further down. Same closure-over-
@@ -471,8 +475,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             if (officeHost != null) hosts.Add(officeHost);
 
             // M4.6.δ — Gather-rules runtime executor. Runs "startup" rules once the agent is up
-            // and "interval" rules on their timers; "phase_change" / "on_event" rules are driven
-            // by the host's SignalIngress.SignalPosted subscription (MON-A1).
+            // and "interval" rules on their timers; "phase_change" / "phase_exit" / "on_event"
+            // rules are driven by the post-reduce TimelineEventStream (emitted timeline events),
+            // NOT the raw SignalPosted stream — the raw phase can run minutes ahead of the
+            // engine-declared one (RealmJoin gate, session 32312a32). See TimelineEventStream doc.
             if (_remoteConfig.GatherRules != null && _remoteConfig.GatherRules.Count > 0)
             {
                 hosts.Add(new GatherRuleExecutorHost(
@@ -483,7 +489,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                     logger: logger,
                     rules: _remoteConfig.GatherRules,
                     imeLogPathOverride: _agentConfig.ImeLogPathOverride,
-                    unrestrictedMode: _agentConfig.UnrestrictedMode));
+                    unrestrictedMode: _agentConfig.UnrestrictedMode,
+                    gatherDebugLogPath: _agentConfig.GatherRuleDebugLogPath,
+                    timelineEvents: timelineEvents));
+            }
+            else if (!string.IsNullOrEmpty(_agentConfig.GatherRuleDebugLogPath))
+            {
+                // Debug trace is on but the backend delivered zero gather rules — the trace
+                // file must say so instead of silently not existing.
+                Monitoring.Telemetry.Gather.GatherRuleDebugLog.WriteStandalone(
+                    _agentConfig.GatherRuleDebugLogPath,
+                    "no gather rules delivered by backend — nothing to execute", logger);
             }
 
             return new CollectorSurfaces(hosts, imeLogHost, espAndHelloHost, aadJoinHost);

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

@@ -91,6 +91,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
         // (tests / legacy callers) means trace events always flow.
         private readonly Func<bool>? _traceEventsEnabled;
 
+        // Live accessor for AgentConfiguration.EnableEspContinueAnywayObservation — read at
+        // esp_config_detected stamping time so a remote-config merge that lands after
+        // construction still takes effect. Null (tests / legacy callers) means disabled.
+        private readonly Func<bool>? _espContinueAnywayObservationEnabled;
+
         // Max-lifetime watchdog (M4.6.α). Timer is armed in Start() when _agentMaxLifetime != null.
         private System.Threading.Timer? _maxLifetimeTimer;
         private int _terminatedFired;
@@ -107,6 +112,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
         private TelemetrySignalEmitter? _signalEmitter;
         private TelemetryTransitionEmitter? _transitionEmitter;
         private EventTimelineEmitter? _timelineEmitter;
+        private TimelineEventStream? _timelineEvents;
         private BackPressureEventObserver? _backPressureObserver;
         private IDeadlineScheduler? _scheduler;
         private ClassifierRegistry? _classifierRegistry;
@@ -172,7 +178,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             TimeSpan? agentMaxLifetime = null,
             int uploadBatchSize = 100,
             IDeadlineScheduler? schedulerOverride = null,
-            Func<bool>? traceEventsEnabled = null)
+            Func<bool>? traceEventsEnabled = null,
+            Func<bool>? espContinueAnywayObservationEnabled = 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));
@@ -213,6 +220,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
 
             _schedulerOverride = schedulerOverride;
             _traceEventsEnabled = traceEventsEnabled;
+            _espContinueAnywayObservationEnabled = espContinueAnywayObservationEnabled;
         }
 
         /// <summary>
@@ -413,7 +421,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                 _transport, _eventSequenceCounter, _sessionId, _tenantId, _traceEventsEnabled);
             _signalEmitter = new TelemetrySignalEmitter(_transport, _sessionId, _tenantId);
             _transitionEmitter = new TelemetryTransitionEmitter(_transport, _sessionId, _tenantId);
-            _timelineEmitter = new EventTimelineEmitter(eventEmitter);
+            // Post-reduce timeline observer: EventTimelineEmitter publishes every emitted event's
+            // (eventType, phase) here. Fed to the collector-host factory at step 14 so gather-rule
+            // phase_change/on_event triggers key off the ENGINE-REDUCED timeline (RealmJoin gate
+            // et al. respected) instead of raw pre-reduce signals — see TimelineEventStream doc.
+            _timelineEvents = new TimelineEventStream();
+            _timelineEmitter = new EventTimelineEmitter(eventEmitter, _timelineEvents);
             _backPressureObserver = new BackPressureEventObserver(eventEmitter, _clock);
 
             // 5) Deadlines + Classifiers.
@@ -653,7 +666,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             {
                 var surfaces = _componentFactory.CreateCollectorHosts(
                     _sessionId, _tenantId, _logger, _whiteGloveSealingPatternIds,
-                    ingress: _ingress, clock: _clock, telemetrySpool: _spool);
+                    ingress: _ingress, clock: _clock, telemetrySpool: _spool,
+                    timelineEvents: _timelineEvents);
                 CollectorSurfaces = surfaces;
                 _collectorHosts = surfaces.Hosts;
                 foreach (var host in _collectorHosts)
@@ -766,6 +780,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                         .ToString(System.Globalization.CultureInfo.InvariantCulture);
                 if (snapshot.AllowContinueAnyway.HasValue)
                     payload[SignalPayloadKeys.EspAllowContinueAnyway] = snapshot.AllowContinueAnyway.Value ? "true" : "false";
+                // Tenant opt-in (remote config, not a registry fact) — only stamped when
+                // enabled; absent = default hard-fail semantics in the engine.
+                if (_espContinueAnywayObservationEnabled?.Invoke() == true)
+                    payload[SignalPayloadKeys.EspContinueAnywayObservationEnabled] = "true";
 
                 _ingress!.Post(
                     kind: DecisionSignalKind.EspConfigDetected,

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

@@ -51,7 +51,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                 getPackageStates: () => imeHost.PackageStates,
                 onDoTelemetryReceived: pkg =>
                 {
-                    try { imeHost.Tracker.OnDoTelemetryReceived?.Invoke(pkg); }
+                    // null source timestamp: poll-driven completion, no log line backs it —
+                    // the adapter stamps the clock instead of LastMatchedLogTimestamp.
+                    try { imeHost.Tracker.OnDoTelemetryReceived?.Invoke(pkg, null); }
                     catch (Exception ex) { logger.Warning($"DeliveryOptimizationHost: OnDoTelemetryReceived invocation threw: {ex.Message}"); }
                 },
                 logDirectory: Environment.ExpandEnvironmentVariables(Constants.LogDirectory),

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

@@ -82,7 +82,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             ISignalIngressSink ingress,
             IClock clock,
             AgentLogger logger,
-            Persistence.StartupEventGate? startupGate = null)
+            Persistence.StartupEventGate? startupGate = null,
+            Func<bool>? espContinueAnywayObservationEnabled = null)
         {
             if (ingress == null) throw new ArgumentNullException(nameof(ingress));
             if (clock == null) throw new ArgumentNullException(nameof(clock));
@@ -92,7 +93,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             // when it reads the FirstSync SkipUser/SkipDevice registry values, so that Fix 8's
             // reducer guards have the SkipUserEsp/SkipDeviceEsp state facts to read.
             _collector = new Monitoring.Telemetry.DeviceInfo.DeviceInfoCollector(
-                sessionId, tenantId, post, logger, ingress, clock, startupGate);
+                sessionId, tenantId, post, logger, ingress, clock, startupGate,
+                espContinueAnywayObservationEnabled);
             _observableIngress = ingress as SignalIngress;
         }
 

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

@@ -4,7 +4,6 @@ using System.Collections.Generic;
 using System.Threading;
 using AutopilotMonitor.Agent.V2.Core.Logging;
 using AutopilotMonitor.DecisionCore.Engine;
-using AutopilotMonitor.DecisionCore.Signals;
 using AutopilotMonitor.Shared.Models;
 
 namespace AutopilotMonitor.Agent.V2.Core.Orchestration
@@ -19,17 +18,24 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
         private readonly bool _unrestrictedMode;
         private int _disposed;
 
-        // MON-A1: drive phase_change / on_event gather triggers from the central signal stream.
-        // V1 fired these from MonitoringService on every EnrollmentEvent (OnPhaseChanged(evt.Phase)
-        // on phase change + OnEvent(evt.EventType) per event); the V2 host previously only called
-        // UpdateRules, so 5 of 10 shipped rules (incl. the only enabled one, dsregcmd at
-        // FinalizingSetup) silently never fired. In V2 every event is an InformationalEvent signal
-        // carrying eventType + (optional) phase in its payload. Null on test fakes / non-SignalIngress
-        // sinks — then signal-triggers degrade off (startup + interval rules still run).
-        private readonly SignalIngress? _observableIngress;
-        private Action<DecisionSignalKind, IReadOnlyDictionary<string, string>?>? _signalPostedHandler;
+        // MON-A1 (revised): drive phase_change / phase_exit / on_event gather triggers from the
+        // POST-REDUCE emitted timeline (TimelineEventStream), not from the raw signal stream.
+        // V1 fired these from MonitoringService on every emitted EnrollmentEvent; the first V2
+        // wiring subscribed to SignalIngress.SignalPosted instead, which fires at enqueue time
+        // with the RAW collector payload — before the reducer has applied gates like the
+        // RealmJoin completion gate. Consequence (session 32312a32, rsneuffen.de): a phase_change
+        // rule on FinalizingSetup fired at the raw EspPhaseChanged(FinalizingSetup) signal (ESP
+        // exit / Hello wizard), 7 minutes before the engine declared phase_transition(FinalizingSetup)
+        // on the timeline — and before the RealmJoin package wrote the registry key the rule was
+        // built to read. The raw feed also never carried engine-emitted event types at all, so
+        // on_event rules on enrollment_complete (documented) could never fire. The emitted-event
+        // feed restores V1 semantics and matches what the UI timeline shows ("collect once when
+        // the enrollment reaches this phase"). Null on test fakes / standalone configurations —
+        // then phase/event triggers degrade off (startup + interval rules still run).
+        private readonly TimelineEventStream? _timelineEvents;
+        private Action<string, EnrollmentPhase>? _timelineHandler;
         private readonly object _sync = new object();
-        private string? _lastPhaseName;
+        private EnrollmentPhase _lastPhase = EnrollmentPhase.Unknown;
 
         public GatherRuleExecutorHost(
             string sessionId,
@@ -39,7 +45,9 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             AgentLogger logger,
             List<GatherRule> rules,
             string? imeLogPathOverride,
-            bool unrestrictedMode = false)
+            bool unrestrictedMode = false,
+            string? gatherDebugLogPath = null,
+            TimelineEventStream? timelineEvents = null)
         {
             if (ingress == null) throw new ArgumentNullException(nameof(ingress));
             if (clock == null) throw new ArgumentNullException(nameof(clock));
@@ -55,10 +63,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             // session mode we wrap post.Emit so every session-mode gather event still
             // flows through the InformationalEvent ingress pipe before hitting the
             // telemetry spool — Rail-A semantics for ordering / replay determinism.
-            var post = new InformationalEventPost(ingress, clock);
+            var post = new InformationalEventPost(ingress, clock, logger);
             _executor = new Monitoring.Telemetry.Gather.GatherRuleExecutor(
-                sessionId, tenantId, evt => post.Emit(evt), logger, imeLogPathOverride);
-            _observableIngress = ingress as SignalIngress;
+                sessionId, tenantId, evt => post.Emit(evt), logger, imeLogPathOverride,
+                debugLogPath: gatherDebugLogPath);
+            _timelineEvents = timelineEvents;
         }
 
         public void Start()
@@ -69,46 +78,43 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             _executor.UnrestrictedMode = _unrestrictedMode;
             _executor.UpdateRules(_rules);
 
-            // MON-A1: observe the central signal stream so phase_change / on_event rules fire.
-            if (_observableIngress != null && _signalPostedHandler == null)
+            // MON-A1 (revised): observe the emitted timeline so phase/event triggers fire in
+            // step with what the timeline actually shows.
+            if (_timelineEvents != null && _timelineHandler == null)
             {
-                _signalPostedHandler = OnSignalPosted;
-                _observableIngress.SignalPosted += _signalPostedHandler;
+                _timelineHandler = OnTimelineEventEmitted;
+                _timelineEvents.EventEmitted += _timelineHandler;
             }
 
             _logger.Info(
-                $"GatherRuleExecutorHost: started with {_rules.Count} rule(s), unrestrictedMode={_unrestrictedMode}, signalTriggers={(_observableIngress != null)}.");
+                $"GatherRuleExecutorHost: started with {_rules.Count} rule(s), unrestrictedMode={_unrestrictedMode}, timelineTriggers={(_timelineEvents != null)}.");
         }
 
         /// <summary>
-        /// Translates posted signals into the executor's phase_change / on_event triggers (MON-A1).
-        /// Phase: fire <see cref="Monitoring.Telemetry.Gather.GatherRuleExecutor.OnPhaseChanged"/> when
-        /// the observed phase changes and parses to an <see cref="EnrollmentPhase"/> (raw collector
-        /// phase strings that aren't enum names are ignored — they carry no gather-rule meaning).
-        /// Event: fire <see cref="Monitoring.Telemetry.Gather.GatherRuleExecutor.OnEvent"/> for every
-        /// InformationalEvent's eventType. The executor dispatches rule execution on the ThreadPool,
-        /// so this stays off the signal-posting hot path; it also dedups phase rules per (rule, phase).
+        /// Translates emitted timeline events into the executor's triggers. Phase: fire
+        /// <see cref="Monitoring.Telemetry.Gather.GatherRuleExecutor.OnPhaseChanged"/> when a
+        /// phase-declaration event (Phase != Unknown) moves the timeline to a new phase — this
+        /// is by construction the engine-reduced phase, so deferred transitions (RealmJoin gate)
+        /// fire the rules exactly when the timeline shows them. Event: fire
+        /// <see cref="Monitoring.Telemetry.Gather.GatherRuleExecutor.OnEvent"/> for every emitted
+        /// event's type — including engine-emitted types (enrollment_complete, phase_transition,
+        /// realmjoin_resolved, …) that never existed on the raw signal stream. The executor
+        /// dispatches rule execution on the ThreadPool, so this stays off the ingress worker's
+        /// effect path; it also dedups phase rules per (rule, phase).
         /// </summary>
-        private void OnSignalPosted(DecisionSignalKind kind, IReadOnlyDictionary<string, string>? payload)
+        private void OnTimelineEventEmitted(string eventType, EnrollmentPhase phase)
         {
-            if (payload == null) return;
-
             try
             {
                 lock (_sync)
                 {
-                    if (payload.TryGetValue(SignalPayloadKeys.EspPhase, out var phaseName)
-                        && !string.IsNullOrEmpty(phaseName)
-                        && !string.Equals(phaseName, _lastPhaseName, StringComparison.OrdinalIgnoreCase)
-                        && Enum.TryParse<EnrollmentPhase>(phaseName, ignoreCase: true, out var phase))
+                    if (phase != EnrollmentPhase.Unknown && phase != _lastPhase)
                     {
-                        _lastPhaseName = phaseName;
+                        _lastPhase = phase;
                         _executor.OnPhaseChanged(phase);
                     }
 
-                    if (kind == DecisionSignalKind.InformationalEvent
-                        && payload.TryGetValue(SignalPayloadKeys.EventType, out var eventType)
-                        && !string.IsNullOrEmpty(eventType))
+                    if (!string.IsNullOrEmpty(eventType))
                     {
                         _executor.OnEvent(eventType);
                     }
@@ -116,17 +122,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             }
             catch (Exception ex)
             {
-                _logger.Verbose($"GatherRuleExecutorHost: signal-trigger dispatch failed: {ex.Message}");
+                _logger.Verbose($"GatherRuleExecutorHost: timeline-trigger dispatch failed: {ex.Message}");
             }
         }
 
         public void Stop()
         {
-            if (_observableIngress != null && _signalPostedHandler != null)
+            if (_timelineEvents != null && _timelineHandler != null)
             {
-                try { _observableIngress.SignalPosted -= _signalPostedHandler; }
+                try { _timelineEvents.EventEmitted -= _timelineHandler; }
                 catch { /* best-effort unsubscribe during shutdown */ }
-                _signalPostedHandler = null;
+                _timelineHandler = null;
             }
             // GatherRuleExecutor is IDisposable; no explicit Stop beyond unsubscribe. Rely on Dispose.
         }

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

@@ -39,6 +39,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
         /// <c>spool.pendingItemCount</c> / <c>spool.fileSizeBytes</c>. Nullable — fakes and
         /// spool-less configurations pass null and the metrics fields are simply absent.
         /// </para>
+        /// <para>
+        /// <paramref name="timelineEvents"/> flows into the <c>GatherRuleExecutorHost</c> so
+        /// <c>phase_change</c> / <c>phase_exit</c> / <c>on_event</c> gather triggers key off the
+        /// ENGINE-REDUCED emitted timeline (post-reduce, RealmJoin gate respected) instead of raw
+        /// pre-reduce signals — see <see cref="TimelineEventStream"/>. Nullable — fakes pass null
+        /// and the host's phase/event triggers degrade off (startup + interval rules still run).
+        /// </para>
         /// </summary>
         CollectorSurfaces CreateCollectorHosts(
             string sessionId,
@@ -47,6 +54,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             IReadOnlyCollection<string> whiteGloveSealingPatternIds,
             ISignalIngressSink ingress,
             IClock clock,
-            Transport.Telemetry.ITelemetrySpool? telemetrySpool);
+            Transport.Telemetry.ITelemetrySpool? telemetrySpool,
+            TimelineEventStream? timelineEvents = null);
     }
 }