fix: session duration inflated by inherited tz-skewed IME log timestamps (#123)

Session df1fcf47 (WG Part 1, real ~1h16m) reported 8h15m: one do_telemetry
event inherited an unrelated, 8h-shifted IME log line timestamp via
LastMatchedLogTimestamp, and the backend re-anchored StartedAt on it.

Three layers:
- Agent: OnDoTelemetryReceived now carries the source-line timestamp; the
  DO-collector poll path passes null and the adapter stamps the clock
  instead of inheriting whatever line matched last.
- Backend: StartedAt alignment and duration-start selection reject
  earliest-event timestamps more than 2h before the current anchor
  (MaxStartedAtBackwardShift), on all four mutation sites incl. the
  SessionsIndex dual-write decision.
- Parser: CMTrace time fields with a UTC-bias suffix ("+480") now parse
  and honor the writer-declared offset instead of failing to match.

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"'
 

.github/workflows/ci.yml

@@ -69,9 +69,21 @@ 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. Warnings are ratcheted: the cap is the current
+      # count of accepted warnings (React-Compiler hooks-rule findings demoted
+      # in eslint.config.mjs + exhaustive-deps) — when you fix warnings, lower
+      # the cap to match; never raise it.
+      - name: Lint
+        run: npm run lint -- --max-warnings 115
+
       - name: Tests
         run: npm test
 

.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:

.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"]
     }
   }
 }

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

@@ -119,6 +119,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/gather-rule-debug-log.md

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

docs/agent/secureboot-ca2023-detection.md

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

docs/backend/device-journeys.md

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

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

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

docs/backend/rule-regression-radar.md

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

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

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

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

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

docs/backend/time-attribution.md

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

docs/index.md

@@ -20,6 +20,7 @@ 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.
 * [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.
@@ -32,11 +33,21 @@ https://docs.autopilotmonitor.com (separate repository).
 # 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.
+* [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.
 
 # 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.
 
+# 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
 
 * [MCP OAuth Flow](mcp-oauth-flow.md) - Who authenticates where when connecting an AI client to the MCP server; two identities, three parties plus Entra ID.

docs/log.md

@@ -1,7 +1,39 @@
 # Log
 
+## 2026-08-02
+
+* **Creation**: Added `backend/tenant-activation-welcome-mail.md` — triggered by the first production auto-approve (activation at signup+64 s, notification address saved at +69 s → welcome mail silently skipped, since the approval path is the only sender and reads the address once). Fix documented in the doc: the notification-email save path now also triggers the send (`PUT /api/preview/notification-email` → fresh approval check `IsApprovedFreshAsync`, bypassing the 30 s negative cache), and a conditional-insert `welcome-email-sent` marker in `PreviewWhitelist` makes the send once-only across both racing paths (marker consumed strictly after the address check; revoke clears it, offboarding wipes the partition, the GA resend endpoint sends unconditionally and consumes it best-effort).
+
+## 2026-07-29
+
+* **Update**: `agent/gather-rule-debug-log.md` — three trace enrichments: (1) new `phase` stage writing an enrollment-phase transition marker (`phase change: Old -> New`, ruleId `-`) so every rule-level line reads against the current phase; (2) logparser now writes one line per regex match — line number, matched text, capture groups — capped at 10 per file per run (the per-file summary keeps the full count); (3) the invalid-regex `error` line includes the offending pattern string.
+
+* **Update**: `url-registry.md` (+ `web/portal-navigation-prefetch.md` context) — the portal is now a **full static export** (`output: 'export'`, `trailingSlash: true`): the SWA serves plain files, the managed SSR runtime — the portal's last cold-start source ("Backend call failure" > 45 s) — no longer exists. Detail routes moved from path params to query strings (`/sessions?id=`, `/sessions/inspector?id=`, `/diagnosis?id=`, `/apps/detail?name=`, `/admin/backups/detail?id=`, `/admin/customs-archive/detail?tenantId=&rowKey=`) with all 21 link sites going through the new single-definition builders in `lib/routes.ts`; the 9 `[section]` families prerender via `generateStaticParams` server shells (37 pages, `dynamicParams=false`), server `redirect()` index pages became `ClientRedirect` shells. Legacy PATH-shaped deep links (sent Teams/Slack/webhook notifications hold `/sessions/{id}` forever) are preserved permanently: SWA wildcard rewrites serve the family page and the globally mounted `LegacyPathRedirect` rewrites to the canonical query URL (hash + query preserved; mapping pinned by `lib/__tests__/legacyPathRedirect.test.ts`). `middleware.ts` host routing became the client-side `HostRoutingGuard` (prefix list moved to `lib/hostRouting.ts`); the legacy `/go/[code]` route + `bootstrapValidation.ts` are deleted (BootstrapSessions table verified free of pre-cutover active sessions). `staticwebapp.config.json` now carries the 19 docs/marketing redirects (order-sensitive), the legacy rewrites, `404.html` override and ALL security headers incl. the literalized prod CSP — guarded by the new `swaConfig.guard.test.ts`; maintenance mode changed from whole-file swap to a first-routes-entry insert (README rewritten). Backend notification deep links go through the new `Constants.PortalSessionUrl` (query shape, pinned). Deploy: `deploy-web.yml` uploads `out/` with `is_static_export: true`.
+
+* **Creation**: Added `backend/oobe-bootstrap-go-flow.md` (and a `Bootstrap go-URL` section + web-registry update in `url-registry.md`) — the OOBE bootstrap script endpoint moved from the portal's Next.js `/go/[code]` SSR route into the Function App (`GET /api/bootstrap/go/{code}`, `GetBootstrapScriptFunction`), unblocking the portal's static export; the customer URL became **`go.autopilotmonitor.com/{code}`** (Front Door custom domain, `/*` route with origin-path rewrite, caching disabled — the script inlines the bearer token). New `Constants.BootstrapGoBaseUrl` (single producer via `CreateBootstrapSessionFunction`) + web `BOOTSTRAP_GO_URL` (display only); both guard host lists extended. Security invariants ported to C#: `BootstrapScriptValueValidator` (exact-GUID tenantId/token, https + host-allowlist + `/agent/….zip` path, expiry ≤ 14 d) and `OobeBootstrapScriptGenerator` (Replace-token raw-string template, single-quoted PS literals, 200-char error cap before quote-doubling; always-HTTP-200 text/plain contract for `irm | iex`). Endpoint is `PublicAnonymous` in the catalog, `NoStoreCacheMiddleware`-covered, self-rate-limited `bootstrap-script:{ip}` 20/min (rate-limit reply is also a 200 error script). Tests: golden byte-parity against the TS template, validator invariants incl. hostile-URL cases, format-gate table, and the previously missing BootstrapUrl shape pin. Transition: the legacy www route + `middleware.ts` `/go` prefix stay alive for pre-migration URLs (validity ≤ 168 h) and are removed in the static-export PR no earlier than 168 h after the last www URL was issued. Customer docs `network-endpoints.md` gained the `go.` host (device-facing, Bootstrap-Sessions-only).
+
+* **Update**: `agent/autopilot-ztd-diagnostics.md` — presentation layer for the startup error backfill (customer feedback: an unannounced wall of pre-agent Error events with a single identical timestamp read like a live failure). Agent: the backfill scan now buffers the capped record set, emits an Info summary event first (`modern_deployment_log`, `backfillSummary: true` + `replayedCount`/`droppedOverCap`/`lookbackMinutes`), then replays oldest-first so the timeline sequence follows event-log chronology. Web: `EventTimeline.tsx` badges `backfilled: true` events („⟲ Backfilled", tooltip) and renders the original `timeCreated` as the row time with a "(reported …)" suffix plus a `Recorded` metadata line — works retroactively for already-stored events. Severity is deliberately not downgraded.
+
+* **Creation**: Added `agent/gather-rule-debug-log.md` — the new per-tenant setting `EnableGatherRuleDebugLog` (ConfigVersion 35 → 36, portal toggle under Settings → Agent, `EnableImeMatchLog`-style bool→path projection in `RemoteConfigMerger`). When enabled, the agent writes `%ProgramData%\AutopilotMonitor\Logs\gather_rules_debug.log`: one pipe-delimited line per evaluation decision across ten previously silent "produced nothing" exits — disabled rules, `interval` without `intervalSeconds` (never runs), the first-tick-after-one-full-interval window, phase-scope skips incl. `currentPhase=Unknown`, per-(rule, phase) dedup, empty collector results (`emitOnlyIfExists`), `on_change` hash suppression (hash prefix + streak), guard blocks, logparser per-file outcomes (position skips, parse failures with a `format=text` hint when every line fails CMTrace parsing, `maxLines`/wildcard caps), and full exception stacks that the agent log drops. 10 MB cap + one `.old` generation; no hot-reload (per-enrollment lifecycle); flag survives the offline config cache; `--run-gather-rules` always traces and echoes under `--console`; zero-rules delivery leaves a one-line file instead of nothing. Side fix: `GatherRuleExecutorHost` now passes the logger into `InformationalEventPost`, so gather-event emissions appear in the agent DEBUG log.
+
+* **Correction + Update**: `web/portal-navigation-prefetch.md`. The HTTP/1.1 claim in the 2026-07-27 entry below is **wrong** and has been struck from the document: `portal.autopilotmonitor.com` negotiates **h2**, verified by `openssl s_client -alpn h2,http/1.1` and a .NET `HttpClient` returning `HTTP/2.0`. The false reading came from the Windows/Schannel curl build in this environment, which has no HTTP/2 support and therefore always reports `1.1` — do not use it to determine HTTP versions. There is no six-connection cap in play; the queue is server-side in the SWA SSR runtime, which does not change the fix or the evidence, only the mechanism. Added an `Outcome` section with 20 h of post-change telemetry: the Free → Standard plan change (16:02:44 UTC) produced **no measurable latency gain** once stratified by the gap to the previous request (p50 Free → Standard: `<10s` 85 → 95 ms, `5-30min` 429 → 441 ms; tail rates 1.64 %/0.374 % over 2 s/10 s vs 6 and 1 events at n = 258 against 4.2 and 1.0 expected; `browserTimings` Mann-Whitney z = −0.24, p = 0.81). The freezes were removed by `prefetch={false}` (16:34:13 UTC): worst `browserTimings.totalDuration` 225,277 → 4,856 ms. The prefetch storm was also an **accidental keep-alive** — requests under 10 s apart fell from 85 % to 46 %, and on the identical never-cacheable `/sessions/{id}` route the median rose 87 → 211 ms and p90 465 → 1,480 ms, with one 11,441 ms abandoned request (`resultCode 0`) after 517 minutes idle. Synthetic bursts warm the runtime and must not be used to benchmark this (round 1 p50 288 ms vs rounds 4–25 p50 113 ms).
+
+## 2026-07-27
+
+* **Creation**: Added `web/portal-navigation-prefetch.md` (and a `Web Portal` section to the index) — root cause of the minute-long portal freezes. `GlobalSidebar` and `Navbar` render the whole navigation on every page, so the App Router's default viewport prefetch issued one `?_rsc=` request per visible link against `portal.autopilotmonitor.com` (~10,400 in 14 days). *(The original entry attributed the freeze to HTTP/1.1 and a six-connection-per-origin cap — see the 2026-07-28 correction; the queue is server-side.)* When the Static Web Apps managed runtime queued the prefetches (p50 91 ms, p95 896 ms, but max 234 s / 21 samples over 30 s), the navigation the user wanted was stuck behind that queue. Measured on the 2026-07-27 17:25 CEST incident: `/admin/presence?_rsc=` 151 s, three siblings finishing within 340 ms of each other at ~37.5 s, all `200`, while the backend API answered in 1.6–2.2 s and `browserTimings` showed `networkDuration` 16 ms against `processingDuration` 225 s. Every navigation Link now sets `prefetch={false}` — these routes are client components behind `ProtectedRoute` that fetch their own data, so the prefetched RSC payload carried no benefit. The doc also records that browser telemetry lives in a **separate** App Insights resource (`AUTOPILOT_MONITOR_WEB_APPINSIGHTS_ID`) that the MCP `query_backend_logs` tool cannot reach, which is why the freezes left no trace in the backend logs.
+
+* **Creation**: Added `backend/rule-regression-radar.md` — F3 regression radar (analyze rules only; gather rules wait for their per-batch stats dedup fix): per (tenant, rule) daily hit rate from `RuleStats`, firing only when the trailing 7-day window has ≥5 hit sessions and ≥20 evaluated sessions, the rate is ≥2× the prior 28-day baseline AND the Wilson 95 % intervals are disjoint (deterministic `MetricsMath` primitive with hand-computed test vectors). Suppressed for deleted rules, rules younger than baseline+window (`CreatedAt` grace), rules edited inside the window (`UpdatedAt`), empty baselines, and the `RuleRegressionRadarDisabled` app-setting kill switch. Alert episodes live as `ruleregression|{ruleId}` tracker rows (one bell + one `RuleFrequencyRegression` ops event per episode; numbers refreshed while active; re-armed under 1.5× baseline, on fire-stop, or by the 30-day tracker retention). On-fire dimension correlation over osBuild/model/agentVersion/imeVersion with the "correlated, not necessarily causal" wording contract. Surfaces: `regressions[]` in the rule-stats response (MCP inherits), the analyze-rules page's 30-day sparkline and regression badge.
+
+* **Creation**: Added `backend/device-journeys.md` — F2 device history / First-Time-Right: the device key (trim + case-fold serial, junk/placeholder exclusion incl. the agent's `Unknown` WMI sentinel), journey grouping over the terminal set Succeeded/Failed/Incomplete (first success ends a journey, a >30-day gap from the previous attempt's CompletedAt starts one, WhiteGlove's single session row is ONE attempt, open sessions are never attempts), the `DeviceHistories` chain (cap 20, written inline at the terminal seam, healed by the sweep, deleted-session refs pruned tombstone-driven, deliberately not in the per-session deletion manifest) and the additive `DeviceJourneyAggregates` daily rows (window rate = ratio of sums — no rolling row needed, 180-day retention). Surfaces: the session-detail "Attempt N" banner with server-computed attempt numbers (virtual-attempt rule for live sessions), the Fleet Health First-time-right section (≥20-journey gate, attempt histogram, repeat-devices violator list), and the MCP `get_device_history` tool (serial mode / fleet FTR mode).
+
+## 2026-07-25
+
+* **Update**: `agent/secureboot-ca2023-detection.md` — review follow-up on 90012d9 hardened the privilege scope, the repo's only privilege-adjustment code and therefore the precedent for any future one. The process token moved from a raw `IntPtr` to a `SafeHandle` assigned by the P/Invoke marshaler, so the CLR owns it from the moment `OpenProcessToken` returns and the critical finalizer releases it even when `Dispose` never runs — previously an async exception between the successful open and the caller's `using` leaked the handle *with the privilege enabled and no owner left to restore it*. `Dispose` became idempotent and now releases the handle in a `finally`, so a throwing restore cannot strand it; the restore obligation is recorded immediately after the successful `AdjustTokenPrivileges` with nothing throwable in between. The whole enable → read → restore sequence runs under a static gate because the privilege is adjusted on the *process* token: a concurrent reader would see "already enabled", correctly skip its own restore, and then lose the privilege mid-read when the first reader disposed, reporting `privilege_denied` on a machine that holds it.
+
 ## 2026-07-24
 
+* **Creation**: Added `backend/server-actions-on-demand-diagnostics.md` — the ServerAction channel (queue on `Sessions.PendingActionsJson`, deliver piggy-backed on the next ingest response, at-least-once with `Type|RuleId|QueuedAt` dedup and sequential dispatch) and the on-demand log collection built on it: the portal's always-visible **Collect Logs** button, the new `EndpointPolicy.TenantAdminOrOperator` tier with the mandatory in-function per-type re-gate (Operators queue only `request_diagnostics`), the member-readable `diagnosticsUploadConfigured` feature flag, the admin quick-config path that must queue `rotate_config` before `request_diagnostics` (works against the deployed fleet — a one-time override would not, the mode gate is agent-side), sequence-based progress matching immune to agent clock skew, and the offboarding cascade's hosted-prefix sweep closing the latest-wins orphan-blob gap.
+
 * **Update**: `agent/esp-policy-provider-stall.md` — the customer's follow-up on issue #106 corrected the field-case mechanics: `TrackingPoliciesCreated=1` WAS set under the foreign `ConfigMgr` provider, so the ESP ignores a foreign provider's completion values and waits on the Intune-registered `Sidecar` provider by name (the rename to `Sidecar` creates no tracking entries yet unblocks instantly). The completeness-keyed detector would have missed exactly this — the incident it was built for. The tripwire is now two-armed under one event type discriminated by `reason`: `provider_incomplete` (unchanged dwell on continuously-incomplete providers) and `sidecar_provider_missing` (≥ 1 Setup/Apps provider registered without `Sidecar`, completeness deliberately ignored, clock reset when Sidecar registers later). Sidecar-missing wins the `reason` when both arms cross in one round; the cross-restart fingerprint gains a `sidecarMissing` sentinel; payload adds `reason` and `sidecarMissingForMinutes`. Evidence for the name-keyed wait: Niehaus' documented Intune WAP payload always registers `Sidecar` (ConfigMgr only via a co-management settings policy) and Microsoft's ESP troubleshooting models app tracking exclusively through the Sidecar subkey.
 
 * **Creation**: Added `agent/esp-policy-provider-stall.md` — a customer diagnosed that pre-provisioned devices with the ConfigMgr client as a blocking app occasionally park the user ESP at "Apps (Identifying)" for days: only a `ConfigMgr` provider is registered under `EnrollmentStatusTracking\Device\Setup\Apps\PolicyProviders` (no `Sidecar` = IME) and `TrackingPoliciesCreated` never becomes 1 — a wait the CSP defines without any timeout; renaming the key to `Sidecar` unblocks immediately. The agent now ships the always-on `esp_policy_provider_stalled` tripwire (60-s tick, 15-min continuous-incompleteness dwell, one-shot per provider, `StartupEventGate` fingerprint across restarts, purely observational via the InformationalEvent rail — no toggle, no ConfigVersion bump), generalized to any provider in both `Setup/Apps` and `DevicePreparation` kinds rather than hardcoding the ConfigMgr case. Companion change: `SOFTWARE\Microsoft\Windows\Autopilot` joins the gather-rule registry allowlist so tenants can target the subtree with custom rules (e.g. `not_exists` on the Sidecar key).
@@ -46,6 +78,10 @@
 
 * **Creation**: Added `agent/endpoint-migration.md` — config-channel agent re-home (`MigrateToApiBaseUrl` on `GET agent/config`, ConfigVersion 33): backend or per-tenant API-URL moves without DNS indirection (impossible due to mTLS/Flex-TLS). Live-fetch-only with cache strip, `AgentEndpointMigrationRules` allowlist validated on both sides, one hop, kill-switch wins. Built as the lesson from the 2026-07-18 WEU→GWC cutover, which hard-cut all in-flight agents.
 
+## 2026-07-26
+
+* **Creation**: Added `backend/time-attribution.md` — the F1 enrollment time attribution: exact-partition invariant against the session's authoritative DurationSeconds, two-window WhiteGlove model, segment mapping from phase-declaration events, positive-evidence ESP-blocking join with "up to" what-if bounds, reboot spans from event gaps around `lastBootUtc`, and the SessionTimeBreakdowns / TimeAttributionAggregates tables with their terminal-seam + maintenance-sweep compute paths and read surfaces (web lane, fleet panel, MCP `get_time_attribution`).
+
 ## 2026-07-17
 
 * **Creation**: Added `agent/build-counter-blob.md` — agent build numbers now come from a shared public counter blob (`buildcounter-v{N}.txt`, reserve-before-build with ETag-CAS) so local `build.ps1` and CI `build-agent.yml` builds can never mint the same number. Documents the CI parity fixes (SummaryDialog.exe.config in the ZIP, EXE-vs-manifest version check, hash-oracle update gated on stable cutover) and the Sigstore provenance attestation on CI-built ZIPs.

docs/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')

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.ps1

@@ -5,18 +5,28 @@
 .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.
+         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
-         (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.
 
+    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.
+    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.
@@ -27,16 +37,35 @@
     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.
@@ -55,17 +84,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.2"
 
 # Configuration - Everything in ProgramData for easy cleanup
 $AgentBasePath = "$env:ProgramData\AutopilotMonitor"
@@ -85,26 +117,19 @@ function Write-Log {
     Add-Content -Path $LogFile -Value $logMessage -ErrorAction SilentlyContinue
 }
 
-function Get-FileMd5Base64 {
-    param(
-        [Parameter(Mandatory = $true)]
-        [string]$Path
-    )
-
-    $md5 = [System.Security.Cryptography.MD5]::Create()
+# 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 {
-        $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() -eq 'InProgress'
     }
-    finally {
-        $md5.Dispose()
+    catch {
+        return $false
     }
 }
 
@@ -119,30 +144,65 @@ try {
         exit 0
     }
 
-    # 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)$'
+    # Collect real (non-special) user profiles as full paths (WMI Special flag + filesystem).
+    $excludePattern = '^(defaultuser\d*|Public|Default( User)?|All Users|WDAGUtilityAccount)$'
 
-    $profileNames = @(
+    # 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 {
-            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." }
+            $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)
+    }
 
-        (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."
+    # 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.
+    # 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*') {
+    if ($lastLoggedOnUser -and $lastLoggedOnUser -notmatch 'defaultuser\d*' -and -not $oobeRelax) {
         Write-Log "SKIP: LastLoggedOnUser found ($lastLoggedOnUser). Device appears productive."
         exit 0
     }
@@ -166,7 +226,7 @@ try {
         }
     }
 
-    Write-Log "Pre-flight checks passed -- no prior deployment, no real user profiles, no logged-on user, within bootstrap window"
+    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"
@@ -181,38 +241,47 @@ 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
 
-            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)"
+            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]
+                    }
                 }
-            }
-            catch {
-                Write-Log "WARNING: Could not fetch manifest - falling back to legacy MD5 check: $($_.Exception.Message)"
             }
 
             $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 `
+                    $downloadStopwatch = [System.Diagnostics.Stopwatch]::StartNew()
+                    Invoke-WebRequest `
                         -Uri $AgentDownloadUrl `
                         -OutFile $zipPath `
                         -UseBasicParsing `
                         -TimeoutSec 30 `
-                        -ErrorAction Stop `
-                        -PassThru
-                    Write-Log "Downloaded agent to $zipPath"
+                        -ErrorAction Stop
+                    $downloadStopwatch.Stop()
+                    $downloadSeconds = [math]::Round($downloadStopwatch.Elapsed.TotalSeconds, 1)
+                    Write-Log "Downloaded agent to $zipPath (took ${downloadSeconds}s)"
                     break
                 }
                 catch {
@@ -227,29 +296,17 @@ try {
                 }
             } while ($downloadAttempt -lt $maxDownloadAttempts)
 
-            if ($expectedSha256) {
-                $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"
+            # 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."
             }
-            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"
-                }
+            $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"

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,11 @@
 # Autopilot Monitor Bootstrap Guard Test
 # Dry-run only: does not exit, does not install, only reports what WOULD happen.
+# Mirrors Install-AutopilotMonitor.ps1 incl. the OOBE-relax exemption for the
+# "Windows Backup for Organizations" restore case (guards 2+3).
 
 param(
-    [string]$AgentBinPath = 'C:\ProgramData\AutopilotMonitor\Agent'
+    [string]$AgentBinPath = 'C:\ProgramData\AutopilotMonitor\Agent',
+    [int]$OobeProfileMaxAgeMinutes = 15
 )
 
 $ErrorActionPreference = 'SilentlyContinue'
@@ -38,6 +41,19 @@ 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
+    }
+}
+
 $AgentExePath = Join-Path $AgentBinPath 'AutopilotMonitor.Agent.exe'
 $MaxBootstrapWindowHours = 12
 
@@ -58,63 +74,79 @@ 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 }
+
+# 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 -- 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 OOBE-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
 
@@ -134,7 +166,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 +200,11 @@ 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"

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/DeviceInfo/DeviceInfoCollectorEspRefreshTests.cs

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

src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/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

@@ -92,6 +92,27 @@ 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.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/UefiSecureBootCertReaderTests.cs

@@ -161,6 +161,40 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.Monitoring
             Assert.False(string.IsNullOrEmpty(snapshot.KekStatus));
         }
 
+        /// <summary>
+        /// SeSystemEnvironmentPrivilege is adjusted on the PROCESS token, so the enable →
+        /// read → restore sequence is a process-wide side effect. Unserialized, a second
+        /// reader observes "already enabled", skips its own restore, and then loses the
+        /// privilege mid-read when the first reader disposes — surfacing as a privilege_denied
+        /// that disagrees with the other readers. The machine's actual privilege state does
+        /// not matter here: whatever it is, every reader must report the SAME status.
+        /// </summary>
+        [Fact]
+        public void Read_is_serialized_across_concurrent_callers()
+        {
+            const int readers = 8;
+            var snapshots = new UefiSecureBootCertSnapshot[readers];
+            var failures = new System.Exception[readers];
+
+            var threads = new System.Threading.Thread[readers];
+            for (var i = 0; i < readers; i++)
+            {
+                var index = i;
+                threads[i] = new System.Threading.Thread(() =>
+                {
+                    try { snapshots[index] = UefiSecureBootCertReader.Read(); }
+                    catch (System.Exception ex) { failures[index] = ex; }
+                });
+                threads[i].Start();
+            }
+            foreach (var thread in threads) thread.Join();
+
+            Assert.All(failures, Assert.Null);
+            Assert.All(snapshots, s => Assert.False(string.IsNullOrEmpty(s.DbStatus)));
+            Assert.All(snapshots, s => Assert.Equal(snapshots[0].DbStatus, s.DbStatus));
+            Assert.All(snapshots, s => Assert.Equal(snapshots[0].KekStatus, s.KekStatus));
+        }
+
         private static byte[] Concat(params byte[][] parts)
         {
             var total = 0;

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

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

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

@@ -0,0 +1,33 @@
+using AutopilotMonitor.Agent.V2.Core.Security;
+using Xunit;
+
+namespace AutopilotMonitor.Agent.V2.Core.Tests.Security
+{
+    /// <summary>
+    /// Audit Q5 — WMI hardware values are trimmed at the source. BIOS serials become device
+    /// identity keys downstream (F2 device history joins on TenantId + serial), so padding
+    /// must never leave the agent; whitespace-only values collapse to the "Unknown" sentinel
+    /// the retry logic already treats as unresolved.
+    /// </summary>
+    public sealed class HardwareInfoNormalizeTests
+    {
+        [Theory]
+        [InlineData(" PF60H941 ", "PF60H941")]
+        [InlineData("PF60H941", "PF60H941")]
+        [InlineData("\tLENOVO \r\n", "LENOVO")]
+        [InlineData("Unknown", "Unknown")]
+        public void Trims_whitespace_at_the_source(string raw, string expected)
+            => Assert.Equal(expected, HardwareInfo.NormalizeWmiValue(raw));
+
+        [Theory]
+        [InlineData("")]
+        [InlineData("   ")]
+        [InlineData("\t\r\n")]
+        public void Empty_and_whitespace_only_collapse_to_the_Unknown_sentinel(string raw)
+            => Assert.Equal("Unknown", HardwareInfo.NormalizeWmiValue(raw));
+
+        [Fact]
+        public void Null_collapses_to_the_Unknown_sentinel()
+            => Assert.Equal("Unknown", HardwareInfo.NormalizeWmiValue(null));
+    }
+}

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/SignalAdapters/ImeLogTrackerAdapterTimingTests.cs

@@ -243,5 +243,87 @@ namespace AutopilotMonitor.Agent.V2.Core.Tests.SignalAdapters
 
             Assert.Equal(firstStamp, adapter.AppTimings["app-P"].StartedAtUtc);
         }
+
+        [Fact]
+        public void Terminal_to_active_retry_rearms_CompletedAt_and_final_terminal_covers_total_occupancy()
+        {
+            // Audit Q1: the IME retry path (Error -> Downloading -> Installed is permitted by
+            // AppPackageState.UpdateState). Pre-fix, CompletedAt froze at the first Error, so
+            // the final Installed payload carried the first failure's completedAt/duration.
+            using var f = new ImeLogTrackerAdapterFixture(T0);
+            using var adapter = new ImeLogTrackerAdapter(f.Tracker, f.Ingress, f.Clock);
+            var app = new AppPackageState("app-R", 0);
+
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Unknown, AppInstallationState.Installing);
+            f.Clock.Advance(TimeSpan.FromSeconds(5));
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Installing, AppInstallationState.Error);
+            f.Clock.Advance(TimeSpan.FromSeconds(10));
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Error, AppInstallationState.Downloading);
+
+            // Re-armed while active again: the retry's download event carries no completedAt,
+            // and the FIRST start stamp is kept.
+            Assert.Null(adapter.AppTimings["app-R"].CompletedAtUtc);
+            var retryDownload = f.InfoEvent(SharedEventTypes.AppDownloadStarted);
+            Assert.False(retryDownload.Payload!.ContainsKey("completedAt"));
+            Assert.False(retryDownload.Payload.ContainsKey("durationSeconds"));
+            Assert.Equal(T0.ToString("o"), retryDownload.Payload["startedAt"]);
+
+            f.Clock.Advance(TimeSpan.FromSeconds(20));
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Downloading, AppInstallationState.Installed);
+
+            var timing = adapter.AppTimings["app-R"];
+            Assert.Equal(T0, timing.StartedAtUtc);
+            Assert.Equal(T0.AddSeconds(35), timing.CompletedAtUtc);
+            Assert.Equal(35.0, timing.DurationSeconds);
+
+            var completed = Assert.Single(f.InfoEvents(SharedEventTypes.AppInstallComplete));
+            Assert.Equal("35.00", completed.Payload!["durationSeconds"]);
+            Assert.Equal(T0.AddSeconds(35).ToString("o"), completed.Payload["completedAt"]);
+        }
+
+        [Fact]
+        public void Skipped_then_retried_app_emits_positive_duration_from_retry_start()
+        {
+            // Production regression (session 66f1c5e1, audit Q1): a user-scope app evaluated
+            // Skipped during DeviceSetup (terminal, no start observed), retried after sign-in
+            // (Skipped -> Downloading is permitted), Installed later. Pre-fix payload:
+            // completedAt frozen at the early Skip + startedAt from the retry ->
+            // durationSeconds=-2342. Post-fix: retry re-arms, duration covers retry-start ->
+            // final terminal.
+            using var f = new ImeLogTrackerAdapterFixture(T0);
+            using var adapter = new ImeLogTrackerAdapter(f.Tracker, f.Ingress, f.Clock);
+            var app = new AppPackageState("app-S", 0);
+
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Unknown, AppInstallationState.Skipped);
+            Assert.Null(adapter.AppTimings["app-S"].StartedAtUtc);
+            Assert.Equal(T0, adapter.AppTimings["app-S"].CompletedAtUtc);
+
+            f.Clock.Advance(TimeSpan.FromSeconds(60));
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Skipped, AppInstallationState.Downloading);
+            f.Clock.Advance(TimeSpan.FromSeconds(30));
+            adapter.TriggerAppStateFromTest(app, AppInstallationState.Downloading, AppInstallationState.Installed);
+
+            var timing = adapter.AppTimings["app-S"];
+            Assert.Equal(T0.AddSeconds(60), timing.StartedAtUtc);
+            Assert.Equal(T0.AddSeconds(90), timing.CompletedAtUtc);
+            Assert.Equal(30.0, timing.DurationSeconds);
+
+            var completedEvents = f.InfoEvents(SharedEventTypes.AppInstallComplete);
+            Assert.Equal(2, completedEvents.Count);
+            Assert.Equal("30.00", completedEvents[1].Payload!["durationSeconds"]);
+        }
+
+        [Fact]
+        public void Inverted_endpoints_yield_null_DurationSeconds()
+        {
+            // Negative guard (audit Q1): endpoints stamped from out-of-order source lines must
+            // never surface as a negative durationSeconds (observed -2342s in production). The
+            // payload emitter omits the field when DurationSeconds is null.
+            var inverted = new AppInstallTiming(startedAtUtc: T0.AddSeconds(100), completedAtUtc: T0);
+            Assert.Null(inverted.DurationSeconds);
+
+            var wellOrdered = new AppInstallTiming(startedAtUtc: T0, completedAtUtc: T0.AddSeconds(100));
+            Assert.Equal(100.0, wellOrdered.DurationSeconds);
+        }
     }
 }

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/Configuration/AgentConfiguration.cs

@@ -121,6 +121,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.

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

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

@@ -327,6 +327,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Configuration
                 KeepLogFile = false,
                 EnableGeoLocation = true,
                 EnableImeMatchLog = false,
+                EnableGatherRuleDebugLog = false,
                 Collectors = CollectorConfiguration.CreateDefault(),
                 GatherRules = new System.Collections.Generic.List<GatherRule>(),
                 ImeLogPatterns = new System.Collections.Generic.List<ImeLogPattern>()

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

@@ -10,9 +10,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
     /// the <c>app_tracking_summary</c> terminal event.
     /// <para>
     /// <b>StartedAtUtc</b> is recorded on the first lifecycle transition into Downloading /
-    /// Installing / InProgress. <b>CompletedAtUtc</b> is recorded on the first transition to a
-    /// terminal state (Installed / Skipped / Postponed / Error). Both are "set-once" — subsequent
-    /// identical-state events do not overwrite an earlier stamp.
+    /// Installing / InProgress and never overwritten. <b>CompletedAtUtc</b> is recorded on a
+    /// transition to a terminal state (Installed / Skipped / Postponed / Error) and re-armed
+    /// to <c>null</c> when the app goes terminal → active again (IME retry / re-evaluation,
+    /// audit Q1) — so the final terminal event carries first-start → last-terminal.
     /// </para>
     /// </summary>
     public sealed class AppInstallTiming
@@ -30,10 +31,14 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
         /// <summary>
         /// Elapsed time from first Downloading/Installing transition to terminal state, in
         /// seconds. <c>null</c> when either endpoint is missing (e.g. app still installing,
-        /// or the adapter missed the start event because it came online mid-install).
+        /// or the adapter missed the start event because it came online mid-install) — and
+        /// <c>null</c> when the endpoints are inverted (CompletedAt before StartedAt: log lines
+        /// from different source files can be processed out of chronological order; observed in
+        /// production as durationSeconds=-2342 on a Skipped-then-retried user-scope app,
+        /// audit Q1). A negative duration is never a real measurement, so it is not emitted.
         /// </summary>
         public double? DurationSeconds =>
-            StartedAtUtc.HasValue && CompletedAtUtc.HasValue
+            StartedAtUtc.HasValue && CompletedAtUtc.HasValue && CompletedAtUtc.Value >= StartedAtUtc.Value
                 ? (CompletedAtUtc.Value - StartedAtUtc.Value).TotalSeconds
                 : (double?)null;
     }

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

@@ -22,9 +22,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
     /// </summary>
     public static class CmTraceLogParser
     {
-        // Pre-compiled regex for the CMTrace format
+        // Pre-compiled regex for the CMTrace format. The time field may carry a UTC-bias
+        // suffix in minutes ("06:08:04.8834397+480", GetTimeZoneInformation convention:
+        // UTC = local + bias) — without the optional bias group such lines would not match
+        // at all and their content would be invisible to every pattern.
         private static readonly Regex CmTraceRegex = new Regex(
-            @"<!\[LOG\[(?<message>.*)\]LOG\]!><time=""(?<time>[\d:.]+)""\s+date=""(?<date>[\d-]+)""\s+component=""(?<component>[^""]*)""\s+context=""[^""]*""\s+type=""(?<type>\d+)""\s+thread=""(?<thread>\d+)""\s+file=""[^""]*"">",
+            @"<!\[LOG\[(?<message>.*)\]LOG\]!><time=""(?<time>[\d:.]+)(?<bias>[+-]\d{1,4})?""\s+date=""(?<date>[\d-]+)""\s+component=""(?<component>[^""]*)""\s+context=""[^""]*""\s+type=""(?<type>\d+)""\s+thread=""(?<thread>\d+)""\s+file=""[^""]*"">",
             RegexOptions.Compiled | RegexOptions.Singleline
         );
 
@@ -45,6 +48,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
 
             var message = match.Groups["message"].Value;
             var timeStr = match.Groups["time"].Value;
+            var biasStr = match.Groups["bias"].Value;
             var dateStr = match.Groups["date"].Value;
             var component = match.Groups["component"].Value;
             var typeStr = match.Groups["type"].Value;
@@ -52,7 +56,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
 
             // Parse timestamp: date is "M-d-yyyy", time is "HH:mm:ss.ticks"
             DateTime timestamp;
-            if (!TryParseTimestamp(dateStr, timeStr, out timestamp))
+            if (!TryParseTimestamp(dateStr, timeStr, biasStr, out timestamp))
             {
                 timestamp = DateTime.UtcNow;
             }
@@ -72,7 +76,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
             return true;
         }
 
-        private static bool TryParseTimestamp(string dateStr, string timeStr, out DateTime result)
+        private static bool TryParseTimestamp(string dateStr, string timeStr, string biasStr, out DateTime result)
         {
             result = DateTime.MinValue;
 
@@ -116,7 +120,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Enrollment.Ime
                 "M-d-yyyy HH:mm:ss"
             };
 
-            // CMTrace timestamps are always in LOCAL time. Parse as local, then convert to UTC.
+            // Bias-suffixed time ("+480"): the writer declared its own UTC offset in minutes
+            // (GetTimeZoneInformation convention: UTC = written time + bias). Honor it instead
+            // of assuming the agent's local timezone — writer and agent can disagree (mixed
+            // components, mid-enrollment timezone change; session df1fcf47).
+            if (!string.IsNullOrEmpty(biasStr)
+                && int.TryParse(biasStr, NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture, out var biasMinutes))
+            {
+                if (DateTime.TryParseExact(combined, formats, CultureInfo.InvariantCulture,
+                    DateTimeStyles.None, out result))
+                {
+                    result = DateTime.SpecifyKind(result.AddMinutes(biasMinutes), DateTimeKind.Utc);
+                    return true;
+                }
+                return false;
+            }
+
+            // No bias: CMTrace timestamps are in LOCAL time. Parse as local, then convert to UTC.
             if (DateTime.TryParseExact(combined, formats, CultureInfo.InvariantCulture,
                 DateTimeStyles.AssumeLocal, out result))
             {

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.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/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/UefiSecureBootCertReader.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Runtime.InteropServices;
+using Microsoft.Win32.SafeHandles;
 
 namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
 {
@@ -56,6 +57,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
         private const int InitialBufferSize = 64 * 1024;
         private const int RetryBufferSize = 256 * 1024;
 
+        // SeSystemEnvironmentPrivilege is adjusted on the PROCESS token, so enable → read →
+        // restore is a process-wide side effect and must run as one atomic sequence. Without
+        // this gate a second reader would observe "already enabled", correctly skip its own
+        // restore, and then have the privilege disabled underneath it when the first reader
+        // finishes — a spurious privilege_denied on a machine that actually holds it.
+        private static readonly object FirmwareReadGate = new object();
+
         /// <summary>
         /// Reads db and KEK and evaluates the certificate presence flags. Never throws;
         /// per-variable failures surface as <see cref="UefiSecureBootCertSnapshot.DbStatus"/> /
@@ -67,6 +75,10 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
             var snapshot = new UefiSecureBootCertSnapshot();
             try
             {
+                // The critical section covers the whole privileged window, not just the
+                // adjustment — see FirmwareReadGate. Only synchronous kernel calls and byte
+                // scans run inside it, so it cannot block on anything else the agent does.
+                lock (FirmwareReadGate)
                 using (var privilege = SystemEnvironmentPrivilege.TryEnable())
                 {
                     if (!privilege.Enabled)
@@ -168,23 +180,42 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
         /// of the instance and restores the previous privilege state on dispose. SYSTEM holds
         /// the privilege (default-disabled); without elevation <see cref="Enabled"/> stays
         /// false and the caller reports <see cref="StatusPrivilegeDenied"/>.
+        /// <para>
+        /// <b>Crash-safety.</b> This is the repo's only privilege-adjustment code, so the
+        /// ownership rules are spelled out: the token is held in a <see cref="SafeHandle"/>
+        /// assigned by the P/Invoke marshaler, so the CLR owns it from the moment
+        /// <c>OpenProcessToken</c> returns — it is released by the critical finalizer even if
+        /// this instance never reaches the caller's <c>using</c> (async exception between the
+        /// call and the assignment). <see cref="Dispose"/> is idempotent, never throws, and
+        /// releases the handle in a <c>finally</c> so a failed restore cannot leak it. The
+        /// restore obligation is recorded immediately after the successful adjustment, so no
+        /// throw in between can strand the process with the privilege left enabled.
+        /// </para>
         /// </summary>
         private sealed class SystemEnvironmentPrivilege : IDisposable
         {
             public bool Enabled { get; private set; }
 
-            private IntPtr _token = IntPtr.Zero;
+            private SafeTokenHandle _token;
             private NativeMethods.TOKEN_PRIVILEGES _previousState;
             private bool _restoreNeeded;
+            private bool _disposed;
 
             public static SystemEnvironmentPrivilege TryEnable()
             {
                 var instance = new SystemEnvironmentPrivilege();
                 try
                 {
+                    SafeTokenHandle token;
                     if (!NativeMethods.OpenProcessToken(NativeMethods.GetCurrentProcess(),
-                            NativeMethods.TOKEN_ADJUST_PRIVILEGES | NativeMethods.TOKEN_QUERY, out instance._token))
+                            NativeMethods.TOKEN_ADJUST_PRIVILEGES | NativeMethods.TOKEN_QUERY, out token))
+                    {
+                        // Failed open still yields a (closed/invalid) SafeHandle instance.
+                        if (token != null) token.Dispose();
                         return instance;
+                    }
+
+                    instance._token = token;
 
                     NativeMethods.LUID luid;
                     if (!NativeMethods.LookupPrivilegeValueW(null, "SeSystemEnvironmentPrivilege", out luid))
@@ -197,52 +228,80 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
                         Attributes = NativeMethods.SE_PRIVILEGE_ENABLED
                     };
 
+                    NativeMethods.TOKEN_PRIVILEGES previousState;
                     uint returnLength;
-                    if (!NativeMethods.AdjustTokenPrivileges(instance._token, false, ref newState,
+                    if (!NativeMethods.AdjustTokenPrivileges(token, false, ref newState,
                             (uint)Marshal.SizeOf(typeof(NativeMethods.TOKEN_PRIVILEGES)),
-                            out instance._previousState, out returnLength))
+                            out previousState, out returnLength))
                         return instance;
 
                     // AdjustTokenPrivileges returns TRUE even when the privilege is not held —
-                    // the real verdict is ERROR_NOT_ALL_ASSIGNED in the last error.
+                    // the real verdict is ERROR_NOT_ALL_ASSIGNED in the last error. Nothing was
+                    // adjusted in that case, so there is nothing to restore.
                     if (Marshal.GetLastWin32Error() == ErrorNotAllAssigned)
                         return instance;
 
-                    // Restore only when the privilege was not already enabled before.
-                    instance._restoreNeeded = instance._previousState.PrivilegeCount > 0
-                        && (instance._previousState.Attributes & NativeMethods.SE_PRIVILEGE_ENABLED) == 0;
+                    // The token is now modified: record the restore obligation before anything
+                    // else can throw. Restore only when the privilege was not already enabled.
+                    instance._previousState = previousState;
+                    instance._restoreNeeded = previousState.PrivilegeCount > 0
+                        && (previousState.Attributes & NativeMethods.SE_PRIVILEGE_ENABLED) == 0;
                     instance.Enabled = true;
                 }
                 catch
                 {
-                    // Fail-soft: Enabled stays false.
+                    // Fail-soft: Enabled stays false. Whatever was acquired before the failure
+                    // is already tracked on the instance and released by Dispose.
                 }
                 return instance;
             }
 
             public void Dispose()
             {
-                if (_token != IntPtr.Zero)
+                if (_disposed) return;
+                _disposed = true;
+                Enabled = false;
+
+                var token = _token;
+                _token = null;
+                if (token == null) return;
+
+                try
                 {
-                    try
+                    if (_restoreNeeded)
                     {
-                        if (_restoreNeeded)
-                        {
-                            NativeMethods.TOKEN_PRIVILEGES ignored;
-                            uint returnLength;
-                            NativeMethods.AdjustTokenPrivileges(_token, false, ref _previousState,
-                                (uint)Marshal.SizeOf(typeof(NativeMethods.TOKEN_PRIVILEGES)),
-                                out ignored, out returnLength);
-                        }
+                        _restoreNeeded = false;
+                        NativeMethods.TOKEN_PRIVILEGES ignored;
+                        uint returnLength;
+                        NativeMethods.AdjustTokenPrivileges(token, false, ref _previousState,
+                            (uint)Marshal.SizeOf(typeof(NativeMethods.TOKEN_PRIVILEGES)),
+                            out ignored, out returnLength);
                     }
-                    catch
-                    {
-                        // Best effort — the process token privilege state is not load-bearing
-                        // for anything else the agent does.
-                    }
-                    NativeMethods.CloseHandle(_token);
-                    _token = IntPtr.Zero;
                 }
+                catch
+                {
+                    // Best effort — the process token privilege state is not load-bearing for
+                    // anything else the agent does, and Dispose must never throw.
+                }
+                finally
+                {
+                    token.Dispose();
+                }
+            }
+        }
+
+        /// <summary>
+        /// Owns a process-token handle. <c>ReleaseHandle</c> runs on the finalizer thread when
+        /// <see cref="SystemEnvironmentPrivilege.Dispose"/> is skipped, so it must not throw —
+        /// a single <c>CloseHandle</c> P/Invoke satisfies that.
+        /// </summary>
+        private sealed class SafeTokenHandle : SafeHandleZeroOrMinusOneIsInvalid
+        {
+            public SafeTokenHandle() : base(true) { }
+
+            protected override bool ReleaseHandle()
+            {
+                return NativeMethods.CloseHandle(handle);
             }
         }
 
@@ -278,7 +337,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
 
             [DllImport("advapi32.dll", SetLastError = true)]
             [return: MarshalAs(UnmanagedType.Bool)]
-            public static extern bool OpenProcessToken(IntPtr processHandle, uint desiredAccess, out IntPtr tokenHandle);
+            public static extern bool OpenProcessToken(IntPtr processHandle, uint desiredAccess, out SafeTokenHandle tokenHandle);
 
             [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
             [return: MarshalAs(UnmanagedType.Bool)]
@@ -286,7 +345,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Interop
 
             [DllImport("advapi32.dll", SetLastError = true)]
             [return: MarshalAs(UnmanagedType.Bool)]
-            public static extern bool AdjustTokenPrivileges(IntPtr tokenHandle, bool disableAllPrivileges,
+            public static extern bool AdjustTokenPrivileges(SafeTokenHandle tokenHandle, bool disableAllPrivileges,
                 ref TOKEN_PRIVILEGES newState, uint bufferLength, out TOKEN_PRIVILEGES previousState, out uint returnLength);
 
             [DllImport("kernel32.dll", SetLastError = true)]

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/Telemetry/DeviceInfo/DeviceInfoCollector.NetworkAndSecurity.cs

@@ -706,10 +706,27 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
         /// the desktop via "Continue anyway".
         /// </para>
         /// </summary>
+        // Serializes the ESP-config read+emit across ALL callers (CollectAll on the startup
+        // ThreadPool task, CollectAtEnrollmentStart and RefreshEspConfiguration on their own
+        // Task.Run) — without it, two concurrent collects can interleave read-before-emit and
+        // the LATER emission can carry the OLDER (smaller) registry snapshot. The backend keeps
+        // the latest list-bearing emission as positive blocking evidence, so an out-of-order
+        // emission would silently shrink it (Codex review). Inside the lock each collect is
+        // read→emit atomic: a later emission always carries an equal-or-newer snapshot.
+        private readonly object _espConfigCollectLock = new object();
+
         // Internal (not private) as a test seam: unlike CollectAll/CollectAtEnrollmentStart this
         // method touches no live system state once both probes are overridden, so tests can
         // drive the esp_config_detected event surface in isolation (InternalsVisibleTo).
         internal (bool? skipUserStatusPage, bool? skipDeviceStatusPage) CollectEspConfiguration()
+        {
+            lock (_espConfigCollectLock)
+            {
+                return CollectEspConfigurationLocked();
+            }
+        }
+
+        private (bool? skipUserStatusPage, bool? skipDeviceStatusPage) CollectEspConfigurationLocked()
         {
             bool? skipUser = null;
             bool? skipDevice = null;
@@ -798,7 +815,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()
         {
@@ -841,7 +858,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)
@@ -882,78 +900,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)
             {

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

@@ -114,6 +114,23 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.DeviceInfo
             CollectTpmStatus();
         }
 
+        /// <summary>
+        /// Re-reads the ESP configuration (skip flags + ESPTrackingInfo blocking lists) and
+        /// re-emits <c>esp_config_detected</c> when the payload changed. Audit Q2: the earlier
+        /// emissions (agent start, DeviceSetup detection) fire before the registry lists are
+        /// complete — the ESP writes one timestamped subkey per CSP status write, so the
+        /// device-scope list grows progressively and the user-scope <c>S-&lt;SID&gt;</c> lists
+        /// appear only after sign-in. Called by <see cref="Orchestration.DeviceInfoHost"/> as
+        /// phase-driven one-shots (apps sub-phase opened, AccountSetup detected) — never on a
+        /// timer. The StartupEventGate keeps an unchanged payload silent, so a re-collect that
+        /// found nothing new emits nothing.
+        /// </summary>
+        public void RefreshEspConfiguration(string trigger)
+        {
+            _logger.Info($"EnrollmentTracker: re-collecting ESP configuration (trigger={trigger})");
+            CollectEspConfiguration();
+        }
+
         /// <summary>
         /// Re-collects device info that may change during enrollment (e.g. BitLocker enabled via policy).
         /// Called at enrollment complete / FinalizingSetup transition to capture final state.

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

@@ -25,14 +25,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 +73,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 +102,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 +112,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 +133,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 +195,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 +207,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 +224,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 +257,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 }
                                 catch (RegexMatchTimeoutException)
                                 {
+                                    timeoutCount++;
                                     continue;
                                 }
                                 if (!match.Success)
@@ -233,13 +296,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 +315,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 }
                                 catch (RegexMatchTimeoutException)
                                 {
+                                    timeoutCount++;
                                     continue;
                                 }
                                 if (!match.Success)
@@ -288,6 +356,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Monitoring.Telemetry.Gather.Collectors
                                 });
 
                                 matchCount++;
+                                TraceMatch(context, rule, Path.GetFileName(filePath), linesRead, match, pattern, matchCount);
                             }
                         }
 
@@ -301,10 +370,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/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/Orchestration/DefaultComponentFactory.cs

@@ -483,7 +483,16 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                     logger: logger,
                     rules: _remoteConfig.GatherRules,
                     imeLogPathOverride: _agentConfig.ImeLogPathOverride,
-                    unrestrictedMode: _agentConfig.UnrestrictedMode));
+                    unrestrictedMode: _agentConfig.UnrestrictedMode,
+                    gatherDebugLogPath: _agentConfig.GatherRuleDebugLogPath));
+            }
+            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/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

@@ -36,6 +36,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
     ///   <item><c>CollectAtEnd</c> — once, on <c>FinalizingSetup</c> or desktop arrival
     ///   (whichever comes first; desktop arrival also covers no-ESP / WDP v2). Re-fetches
     ///   BitLocker (commonly enabled via policy DURING enrollment) + the active NIC.</item>
+    ///   <item><c>RefreshEspConfiguration</c> — audit Q2, one-shot per trigger: the ESP
+    ///   blocking lists in the registry grow progressively (device scope) and the user-scope
+    ///   lists appear only after sign-in, so the early emissions are structurally partial.
+    ///   Re-collected when the apps sub-phase opens (first app activity in DeviceSetup /
+    ///   AccountSetup — the adapter's <c>phase_transition</c> declaration) and when the
+    ///   AccountSetup ESP phase itself is detected. Phase-driven one-shots, never a timer
+    ///   (no-heartbeat policy).</item>
     /// </list>
     /// <para>
     /// Duplicate-event cost is zero: every re-collected event runs through the collector's
@@ -46,6 +53,12 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
     {
         public string Name => "DeviceInfoCollector";
 
+        // ESP-config refresh trigger labels (audit Q2) — also the values passed to
+        // DeviceInfoCollector.RefreshEspConfiguration for the agent-log line.
+        internal const string EspConfigTriggerAppsDevice = "apps_phase_device";
+        internal const string EspConfigTriggerAppsUser = "apps_phase_user";
+        internal const string EspConfigTriggerAccountSetup = "account_setup_detected";
+
         private readonly Monitoring.Telemetry.DeviceInfo.DeviceInfoCollector _collector;
         private readonly AgentLogger _logger;
 
@@ -58,6 +71,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
         private int _endCollected;
         private int _disposed;
 
+        // Audit Q2 — fire-once latches per ESP-config refresh trigger. Guarded by _espConfigLock
+        // instead of three Interlocked ints so the membership test + add stays one atomic step.
+        private readonly object _espConfigLock = new object();
+        private readonly HashSet<string> _espConfigRefreshesFired = new HashSet<string>(StringComparer.Ordinal);
+
         public DeviceInfoHost(
             string sessionId,
             string tenantId,
@@ -100,6 +118,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
 
         private void OnSignalPosted(DecisionSignalKind kind, IReadOnlyDictionary<string, string>? payload)
         {
+            HandleEspConfigRefreshTrigger(kind, payload);
+
             var startTrigger = IsEnrollmentStartTrigger(kind, payload);
             var endTrigger = IsEndTrigger(kind, payload);
             if (!startTrigger && !endTrigger) return;
@@ -111,10 +131,6 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             var runEndCollect = endTrigger && Interlocked.Exchange(ref _endCollected, 1) == 0;
             if (!runStartRefresh && !runEndCollect) return;
 
-            // Both one-shots done → nothing left to observe.
-            if (Volatile.Read(ref _enrollmentStartCollected) == 1 && Volatile.Read(ref _endCollected) == 1)
-                Unsubscribe();
-
             var trigger = kind == DecisionSignalKind.DesktopArrived ? "desktop_arrived" : "esp_phase_changed";
             _logger.Info($"DeviceInfoHost: trigger '{trigger}' — scheduling re-collect (enrollmentStart={runStartRefresh}, end={runEndCollect}).");
 
@@ -134,6 +150,32 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             });
         }
 
+        /// <summary>
+        /// Audit Q2 — ESP-config refresh one-shots. Each trigger label fires at most once per
+        /// agent run; the collector's StartupEventGate keeps an unchanged payload silent, so
+        /// the worst case is one silent registry re-read per trigger. The subscription stays
+        /// armed for the host's lifetime (unlike the start/end pair there is no "all triggers
+        /// seen" point that is guaranteed to arrive — SkipUser enrollments never enter
+        /// AccountSetup); the per-signal cost is a few dictionary lookups.
+        /// </summary>
+        private void HandleEspConfigRefreshTrigger(DecisionSignalKind kind, IReadOnlyDictionary<string, string>? payload)
+        {
+            var trigger = ClassifyEspConfigRefreshTrigger(kind, payload);
+            if (trigger == null) return;
+
+            lock (_espConfigLock)
+            {
+                if (!_espConfigRefreshesFired.Add(trigger)) return;
+            }
+
+            _logger.Info($"DeviceInfoHost: ESP-config refresh trigger '{trigger}' — scheduling re-collect.");
+            Task.Run(() =>
+            {
+                try { _collector.RefreshEspConfiguration(trigger); }
+                catch (Exception ex) { _logger.Warning($"DeviceInfoHost: ESP-config refresh threw: {ex.Message}"); }
+            });
+        }
+
         /// <summary>First DeviceSetup phase signal — MDM enrollment has populated the registry surface.</summary>
         internal static bool IsEnrollmentStartTrigger(DecisionSignalKind kind, IReadOnlyDictionary<string, string>? payload)
         {
@@ -156,6 +198,45 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
                 && string.Equals(phase, nameof(EnrollmentPhase.FinalizingSetup), StringComparison.Ordinal);
         }
 
+        /// <summary>
+        /// Audit Q2 — maps a posted signal to an ESP-config refresh trigger label, or
+        /// <c>null</c> when the signal is not one. Two trigger families:
+        /// <list type="bullet">
+        ///   <item>The adapter's apps sub-phase declaration (<c>phase_transition</c>
+        ///   InformationalEvent with phase AppsDevice/AppsUser — fired on the first app
+        ///   activity in an ESP phase): by then IME is actively processing the blocking set,
+        ///   so the device-scope ESPTrackingInfo lists are as complete as they get.</item>
+        ///   <item>The AccountSetup ESP phase (UserSetup detection): sign-in has happened, so
+        ///   the user-scope <c>S-&lt;SID&gt;</c> lists exist now — production showed 88 of 89
+        ///   sessions with an EMPTY user list at the last pre-fix emission.</item>
+        /// </list>
+        /// </summary>
+        internal static string? ClassifyEspConfigRefreshTrigger(DecisionSignalKind kind, IReadOnlyDictionary<string, string>? payload)
+        {
+            if (payload == null) return null;
+
+            if (kind == DecisionSignalKind.InformationalEvent
+                && payload.TryGetValue(SignalPayloadKeys.EventType, out var eventType)
+                && string.Equals(eventType, AutopilotMonitor.Shared.Constants.EventTypes.PhaseTransition, StringComparison.Ordinal)
+                && payload.TryGetValue(Telemetry.Events.EventTimelineEmitter.PhaseParamKey, out var declaredPhase))
+            {
+                if (string.Equals(declaredPhase, nameof(EnrollmentPhase.AppsDevice), StringComparison.Ordinal))
+                    return EspConfigTriggerAppsDevice;
+                if (string.Equals(declaredPhase, nameof(EnrollmentPhase.AppsUser), StringComparison.Ordinal))
+                    return EspConfigTriggerAppsUser;
+                return null;
+            }
+
+            if (kind == DecisionSignalKind.EspPhaseChanged
+                && payload.TryGetValue(SignalPayloadKeys.EspPhase, out var espPhase)
+                && string.Equals(espPhase, nameof(EnrollmentPhase.AccountSetup), StringComparison.Ordinal))
+            {
+                return EspConfigTriggerAccountSetup;
+            }
+
+            return null;
+        }
+
         public void Stop() => Unsubscribe();
 
         public void Dispose()

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

@@ -39,7 +39,8 @@ namespace AutopilotMonitor.Agent.V2.Core.Orchestration
             AgentLogger logger,
             List<GatherRule> rules,
             string? imeLogPathOverride,
-            bool unrestrictedMode = false)
+            bool unrestrictedMode = false,
+            string? gatherDebugLogPath = null)
         {
             if (ingress == null) throw new ArgumentNullException(nameof(ingress));
             if (clock == null) throw new ArgumentNullException(nameof(clock));
@@ -55,9 +56,10 @@ 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);
+                sessionId, tenantId, evt => post.Emit(evt), logger, imeLogPathOverride,
+                debugLogPath: gatherDebugLogPath);
             _observableIngress = ingress as SignalIngress;
         }
 

src/Agent/AutopilotMonitor.Agent.V2.Core/Security/HardwareInfo.cs

@@ -93,7 +93,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Security
                     {
                         using (obj)
                         {
-                            manufacturer = obj["Manufacturer"]?.ToString() ?? Unknown;
+                            manufacturer = NormalizeWmiValue(obj["Manufacturer"]?.ToString());
                             if (manufacturer.IndexOf("lenovo", StringComparison.OrdinalIgnoreCase) >= 0)
                             {
                                 using (var lenovoSearcher = new ManagementObjectSearcher("SELECT Version FROM Win32_ComputerSystemProduct"))
@@ -103,7 +103,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Security
                                     {
                                         using (lenovoObj)
                                         {
-                                            model = lenovoObj["Version"]?.ToString() ?? Unknown;
+                                            model = NormalizeWmiValue(lenovoObj["Version"]?.ToString());
                                         }
                                         break;
                                     }
@@ -111,7 +111,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Security
                             }
                             else
                             {
-                                model = obj["Model"]?.ToString() ?? Unknown;
+                                model = NormalizeWmiValue(obj["Model"]?.ToString());
                             }
                         }
                     }
@@ -132,7 +132,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Security
                     {
                         using (obj)
                         {
-                            serialNumber = obj["SerialNumber"]?.ToString() ?? Unknown;
+                            serialNumber = NormalizeWmiValue(obj["SerialNumber"]?.ToString());
                         }
                     }
                 }
@@ -154,5 +154,17 @@ namespace AutopilotMonitor.Agent.V2.Core.Security
         private static bool IsResolved(string value)
             => !string.IsNullOrWhiteSpace(value)
                && !string.Equals(value, Unknown, StringComparison.OrdinalIgnoreCase);
+
+        /// <summary>
+        /// Trims a raw WMI string value at the source (audit Q5: BIOS serials are used as device
+        /// identity keys downstream — F2 device history joins on them — so padding must never
+        /// leave the agent). Whitespace-only and empty values collapse to the "Unknown" sentinel,
+        /// matching the null fallback so the retry logic treats them as unresolved.
+        /// </summary>
+        internal static string NormalizeWmiValue(string raw)
+        {
+            if (string.IsNullOrWhiteSpace(raw)) return Unknown;
+            return raw.Trim();
+        }
     }
 }

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

@@ -72,7 +72,7 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
         private readonly Action<AppPackageState, AppInstallationState, AppInstallationState>? _prevOnAppStateChanged;
         private readonly Action<string>? _prevOnPatternMatched;
         private readonly Action<string>? _prevOnImeAgentVersion;
-        private readonly Action<AppPackageState>? _prevOnDoTelemetryReceived;
+        private readonly Action<AppPackageState, DateTime?>? _prevOnDoTelemetryReceived;
         private readonly Action<ScriptExecutionState>? _prevOnScriptCompleted;
         private readonly Action<ScriptStartedInfo>? _prevOnScriptStarted;
 
@@ -82,7 +82,7 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
         private readonly Action<AppPackageState, AppInstallationState, AppInstallationState> _ourOnAppStateChanged;
         private readonly Action<string> _ourOnPatternMatched;
         private readonly Action<string> _ourOnImeAgentVersion;
-        private readonly Action<AppPackageState> _ourOnDoTelemetryReceived;
+        private readonly Action<AppPackageState, DateTime?> _ourOnDoTelemetryReceived;
         private readonly Action<ScriptExecutionState> _ourOnScriptCompleted;
         private readonly Action<ScriptStartedInfo> _ourOnScriptStarted;
 
@@ -132,7 +132,9 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
 
         // Plan §5 Fix 4c — per-app install-lifecycle timing captured from state transitions.
         // StartedAtUtc on first Downloading/Installing/InProgress transition (set-once);
-        // CompletedAtUtc on first terminal transition (Installed/Skipped/Postponed/Error).
+        // CompletedAtUtc on terminal transition (Installed/Skipped/Postponed/Error), re-armed
+        // to null on a terminal→active transition (IME retry, audit Q1) so the final terminal
+        // stamp reflects the last outcome instead of freezing at the first one.
         // Surfaced via <see cref="AppTimings"/> to peripheral consumers (FinalStatusBuilder,
         // app_tracking_summary emission in EnrollmentTerminationHandler).
         private readonly Dictionary<string, (DateTime? Started, DateTime? Completed)> _appTimings =
@@ -240,10 +242,10 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
             EmitImeAgentVersion(version);
         }
 
-        private void OnDoTelemetryReceived(AppPackageState app)
+        private void OnDoTelemetryReceived(AppPackageState app, DateTime? sourceTimestampUtc)
         {
-            _prevOnDoTelemetryReceived?.Invoke(app);
-            EmitDoTelemetry(app);
+            _prevOnDoTelemetryReceived?.Invoke(app, sourceTimestampUtc);
+            EmitDoTelemetry(app, sourceTimestampUtc);
         }
 
         private void OnScriptCompleted(ScriptExecutionState script)
@@ -264,7 +266,8 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
             EmitAppState(app, oldState, newState);
         internal void TriggerPatternMatchedFromTest(string patternId) => MaybeEmitWhiteGloveSealingPattern(patternId);
         internal void TriggerImeAgentVersionFromTest(string version) => EmitImeAgentVersion(version);
-        internal void TriggerDoTelemetryFromTest(AppPackageState app) => EmitDoTelemetry(app);
+        internal void TriggerDoTelemetryFromTest(AppPackageState app, DateTime? sourceTimestampUtc = null) =>
+            EmitDoTelemetry(app, sourceTimestampUtc);
         internal void TriggerScriptCompletedFromTest(ScriptExecutionState script) => EmitScriptCompleted(script);
         internal void TriggerScriptStartedFromTest(ScriptStartedInfo info) => EmitScriptStarted(info);
 
@@ -691,10 +694,20 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
         }
 
         /// <summary>
-        /// Plan §5 Fix 4c — set-once per-app install-lifecycle timing. Called for every
-        /// state transition, no-op for duplicate stamps. Returns the up-to-date
+        /// Plan §5 Fix 4c — per-app install-lifecycle timing. Called for every state
+        /// transition, no-op for duplicate stamps. Returns the up-to-date
         /// <see cref="AppInstallTiming"/> so the emitter can inline the values on the
         /// current event's payload without a second dictionary lookup.
+        /// <para>
+        /// Audit Q1: a terminal→active transition (the IME retry path — <see
+        /// cref="AppPackageState.UpdateState"/> permits e.g. Error→Downloading and
+        /// Skipped→Downloading) re-arms <c>Completed</c> to <c>null</c>, so the NEXT terminal
+        /// transition stamps a fresh CompletedAt. StartedAt keeps its first value — the final
+        /// terminal payload then covers first-start → last-terminal (total occupancy across
+        /// attempts) instead of freezing at the first failure. Observed pre-fix: a user-scope
+        /// app Skipped early in DeviceSetup, retried after sign-in, emitted its final
+        /// Installed event with the stale early CompletedAt (durationSeconds=-2342).
+        /// </para>
         /// </summary>
         private AppInstallTiming UpdateAppTiming(string appId, AppInstallationState newState, DateTime now)
         {
@@ -702,13 +715,20 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
             {
                 _appTimings.TryGetValue(appId, out var current);
 
+                // Terminal→active (retry): the earlier terminal stamp no longer describes this
+                // app's outcome — re-arm so the next terminal transition stamps fresh.
+                if (current.Completed != null && IsLifecycleActive(newState))
+                {
+                    current.Completed = null;
+                }
+
                 // First lifecycle-active transition → record StartedAt.
                 if (current.Started == null && IsLifecycleActive(newState))
                 {
                     current.Started = now;
                 }
 
-                // First terminal transition → record CompletedAt.
+                // Terminal transition → record CompletedAt (fresh after a re-arm).
                 if (current.Completed == null && IsCompletedState(newState))
                 {
                     current.Completed = now;
@@ -857,7 +877,7 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
             _logger?.Info($"ImeAdapter: IME agent version detected: {version}");
         }
 
-        private void EmitDoTelemetry(AppPackageState app)
+        private void EmitDoTelemetry(AppPackageState app, DateTime? sourceTimestampUtc)
         {
             if (app == null || string.IsNullOrEmpty(app.Id)) return;
 
@@ -893,11 +913,31 @@ namespace AutopilotMonitor.Agent.V2.Core.SignalAdapters
             var patternId = _tracker.LastMatchedPatternId;
             if (!string.IsNullOrEmpty(patternId)) data["patternId"] = patternId!;
 
-            var now = ResolveOccurredAt(out var derivedFromClock, out var rawSourceTs);
+            // Two trigger paths with different time grounding (session df1fcf47: a single
+            // tz-skewed unrelated log line inherited via LastMatchedLogTimestamp dragged the
+            // session StartedAt back 7h and inflated the reported duration):
+            //  - [DO TEL] log line (sourceTimestampUtc set): the line's own timestamp is the
+            //    event time — resolve/clamp it and apply historic-replay suppression.
+            //  - DO collector poll (sourceTimestampUtc null): the completion was observed live
+            //    via Get-DeliveryOptimizationStatus; no log line is involved, so the clock is
+            //    the only honest source. LastMatchedLogTimestamp must NOT be consulted here.
+            DateTime now;
+            bool derivedFromClock;
+            DateTime? rawSourceTs;
+            if (sourceTimestampUtc.HasValue)
+            {
+                now = ResolveOccurredAt(sourceTimestampUtc, out derivedFromClock, out rawSourceTs);
 
-            // Historic replay — a week-old DO summary is not this enrollment's download.
-            if (SuppressIfHistoricReplay(derivedFromClock, rawSourceTs, SharedEventTypes.DoTelemetry, app.Id))
-                return;
+                // Historic replay — a week-old DO summary is not this enrollment's download.
+                if (SuppressIfHistoricReplay(derivedFromClock, rawSourceTs, SharedEventTypes.DoTelemetry, app.Id))
+                    return;
+            }
+            else
+            {
+                now = _clock.UtcNow;
+                derivedFromClock = true;
+                rawSourceTs = null;
+            }
 
             TagDerivedTimestamp(data, derivedFromClock, rawSourceTs);
 

src/Agent/AutopilotMonitor.Agent.V2.Core/Termination/EnrollmentTerminationHandler.cs

@@ -39,8 +39,11 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
     ///     <see cref="SessionStage.WhiteGloveSealed"/> (Part-1 exit, session resumes Part 2).</item>
     ///   <item>WhiteGlove Part-1 path: stop peripheral collectors first (so their stop-time
     ///     stragglers — e.g. <c>network_bandwidth_estimate</c> — sequence BEFORE the marker),
-    ///     then emit <c>whiteglove_part1_complete</c>, drain spool, and write
-    ///     <c>whiteglove.complete</c> marker via <see cref="SessionIdPersistence.SaveWhiteGloveComplete"/>
+    ///     upload the diagnostics package as a pre-provisioning intermediate (suffix
+    ///     <c>preprov</c>, same mode gating as the terminal path — the seal counts as a
+    ///     success, so <c>OnFailure</c> skips), then emit <c>whiteglove_part1_complete</c>,
+    ///     drain spool, and write <c>whiteglove.complete</c> marker via
+    ///     <see cref="SessionIdPersistence.SaveWhiteGloveComplete"/>
     ///     so Part-2 resume is detected on the next boot.</item>
     ///   <item>Signal the caller-owned shutdown <see cref="ManualResetEventSlim"/>.</item>
     /// </list>
@@ -241,6 +244,18 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
                     // the full Stop() later is a no-op for the hosts.
                     StopPeripheralCollectorsBestEffort();
 
+                    // V1 parity (restored 2026-07-28) — upload the diagnostics package as a
+                    // pre-provisioning intermediate. Between reseal and user OOBE the device
+                    // may sit boxed for weeks, and if Part 2 never uploads (never runs, or
+                    // OnFailure + success) the Part-1 forensics would be lost to self-destruct.
+                    // No dedicated flag: the existing mode semantics apply — Always uploads,
+                    // OnFailure skips (the seal is a success; a Part-1 failure terminates via
+                    // the regular Failed path below, which uploads), Off does nothing. Must run
+                    // BEFORE the whiteglove_part1_complete emit so diagnostics_* events keep a
+                    // lower sequence than the Part-1/Part-2 boundary marker. Best-effort: a
+                    // reseal-reboot racing the upload just loses the intermediate package.
+                    RunUploadDiagnosticsWithEvents(args, suffixOverride: "preprov");
+
                     EmitEventSafe(new EnrollmentEvent
                     {
                         SessionId = _configuration.SessionId,
@@ -623,12 +638,15 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
         }
 
         /// <summary>
-        /// Emits a one-shot <c>agent_late_start</c> Warning when the agent had low observation
+        /// Emits a one-shot <c>agent_late_start</c> event when the agent had low observation
         /// coverage: it started a long time after device boot AND lived only briefly before this
         /// terminal outcome (gate in <see cref="ObservationCoverage"/>). Such a session looks like a
         /// normal multi-minute failure in the list (StartedAt is back-dated to the earliest replayed
-        /// IME-log event) but the agent actually observed only the end-state — so the operator should
-        /// read the diagnosis as a post-mortem reconstruction, not live evidence. No state mutation.
+        /// IME-log event) but the agent actually observed only the end-state. Severity and phrasing
+        /// are outcome-calibrated via <see cref="ObservationCoverage.DescribeLateStart"/>: a failure
+        /// stays a Warning with the post-mortem/hung-script note, a success is an Info about
+        /// tail-only coverage (fleet 2026-07-28: tenant 659c3a90 collected 12 Warnings on healthy
+        /// enrollments whose bootstrap merely ran late). No state mutation.
         /// </summary>
         private void MaybeEmitAgentLateStart(EnrollmentTerminatedEventArgs args)
         {
@@ -642,21 +660,24 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
                         out var bootToStartSeconds, out var uptimeSeconds))
                     return;
 
+                ObservationCoverage.DescribeLateStart(
+                    args.Outcome, _oobeStateAtAgentStart, bootToStartSeconds, uptimeSeconds,
+                    out var severity, out var message, out var note);
+
                 _logger.Info(
                     $"EnrollmentTerminationHandler: low observation coverage — agent started " +
                     $"{bootToStartSeconds / 60.0:F1} min after boot and lived {uptimeSeconds:F0}s; " +
-                    $"emitting agent_late_start.");
+                    $"emitting agent_late_start ({severity}, outcome {args.Outcome}).");
 
                 _post.Emit(new EnrollmentEvent
                 {
                     SessionId = _configuration.SessionId,
                     TenantId = _configuration.TenantId,
                     EventType = Constants.EventTypes.AgentLateStart,
-                    Severity = EventSeverity.Warning,
+                    Severity = severity,
                     Source = "EnrollmentTerminationHandler",
                     Phase = EnrollmentPhase.Unknown,
-                    Message = $"Agent started {bootToStartSeconds / 60.0:F0} min after boot and observed only " +
-                              $"{uptimeSeconds:F0}s before terminating ({args.Outcome}) — low coverage of the enrollment window.",
+                    Message = message,
                     Data = new Dictionary<string, object>
                     {
                         { "bootToAgentStartSeconds", Math.Round(bootToStartSeconds, 1) },
@@ -665,7 +686,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
                         { "agentStartUtc", _agentStartTimeUtc.ToString("o") },
                         { "oobeStateAtAgentStart", _oobeStateAtAgentStart },
                         { "outcome", args.Outcome.ToString() },
-                        { "note", "The agent's bootstrap (an Intune platform script) ran only near the end of the enrollment, so the agent observed the already-decided end-state rather than the failure window. Treat the diagnosis as a post-mortem; check for a platform/remediation script that hung ahead of the bootstrap (see script_timeout_suspected)." },
+                        { "note", note },
                     },
                     ImmediateUpload = true,
                 });
@@ -771,7 +792,13 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
                 StringComparison.Ordinal);
         }
 
-        private void RunUploadDiagnosticsWithEvents(EnrollmentTerminatedEventArgs args)
+        /// <param name="args">Termination payload — outcome drives the OnFailure gate.</param>
+        /// <param name="suffixOverride">
+        /// Blob-name suffix override. Null (terminal path) derives "success"/"failure" from
+        /// the outcome; the WhiteGlove Part-1 seal passes "preprov" so the intermediate
+        /// package is distinguishable from the later Part-2 terminal upload.
+        /// </param>
+        private void RunUploadDiagnosticsWithEvents(EnrollmentTerminatedEventArgs args, string suffixOverride = null)
         {
             var mode = _configuration.DiagnosticsUploadMode ?? "Off";
             if (!_configuration.DiagnosticsUploadEnabled || string.Equals(mode, "Off", StringComparison.OrdinalIgnoreCase))
@@ -807,7 +834,7 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
             DiagnosticsUploadResult result = null;
             try
             {
-                var suffix = enrollmentSucceeded ? "success" : "failure";
+                var suffix = suffixOverride ?? (enrollmentSucceeded ? "success" : "failure");
                 result = _uploadDiagnosticsAsync(enrollmentSucceeded, suffix).GetAwaiter().GetResult();
             }
             catch (Exception ex)

src/Agent/AutopilotMonitor.Agent.V2.Core/Termination/ObservationCoverage.cs

@@ -1,6 +1,8 @@
 #nullable enable
 using System;
 using System.Runtime.InteropServices;
+using AutopilotMonitor.Agent.V2.Core.Orchestration;
+using AutopilotMonitor.Shared.Models;
 
 namespace AutopilotMonitor.Agent.V2.Core.Termination
 {
@@ -76,5 +78,57 @@ namespace AutopilotMonitor.Agent.V2.Core.Termination
             uptimeSeconds = Math.Max(0, uptime.TotalSeconds);
             return bootToStart >= LateStartBootThreshold && uptime <= LowCoverageUptime;
         }
+
+        /// <summary>
+        /// Severity + operator-facing phrasing for the <c>agent_late_start</c> event, calibrated
+        /// by fleet data (2026-07-28): the gate alone is outcome-blind and attached a
+        /// "post-mortem / check for a hung script" Warning to sessions that in fact succeeded —
+        /// there the late bootstrap is deployment hygiene, not an alarm. The OOBE state refines
+        /// the phrasing but must never gate: the canonical hung-script failure terminates on the
+        /// still-shown ESP screen, i.e. with OOBE reading <c>in_progress</c>.
+        /// </summary>
+        /// <param name="outcome">Terminal outcome the enrollment reached.</param>
+        /// <param name="oobeStateAtAgentStart"><see cref="Monitoring.Interop.OobeStateReader"/>
+        /// sample taken at THIS process's start. Only <c>completed</c> / <c>in_progress</c> are
+        /// interpreted; <c>not_started</c> flips in after mid-OOBE reboots and <c>completed</c> is
+        /// routine for post-desktop restarts, so no claim is phrased from the other values.</param>
+        /// <param name="bootToStartSeconds">From <see cref="IsLowObservationCoverage"/>.</param>
+        /// <param name="uptimeSeconds">From <see cref="IsLowObservationCoverage"/>.</param>
+        internal static void DescribeLateStart(
+            EnrollmentTerminationOutcome outcome,
+            string oobeStateAtAgentStart,
+            double bootToStartSeconds,
+            double uptimeSeconds,
+            out EventSeverity severity,
+            out string message,
+            out string note)
+        {
+            var succeeded = outcome == EnrollmentTerminationOutcome.Succeeded;
+            severity = succeeded ? EventSeverity.Info : EventSeverity.Warning;
+
+            message = $"Agent started {bootToStartSeconds / 60.0:F0} min after boot and observed only " +
+                      $"{uptimeSeconds:F0}s before terminating ({outcome}) — low coverage of the enrollment window.";
+            switch (oobeStateAtAgentStart)
+            {
+                case "completed":
+                    message += " OOBE was already completed when the agent started — the diagnosis is a " +
+                               "post-mortem reconstruction, not live observation.";
+                    break;
+                case "in_progress":
+                    message += $" OOBE was still in progress at agent start — the agent did observe the " +
+                               $"final {uptimeSeconds:F0}s live.";
+                    break;
+            }
+
+            note = succeeded
+                ? "The agent's bootstrap (an Intune platform script) ran late in the enrollment, so only the " +
+                  "final stretch was observed live; earlier timeline entries are reconstructed from IME log " +
+                  "replay. The enrollment itself succeeded. If this recurs across sessions, review which " +
+                  "platform/remediation scripts run ahead of the bootstrap (see script_timeout_suspected)."
+                : "The agent's bootstrap (an Intune platform script) ran only near the end of the enrollment, " +
+                  "so the agent observed the already-decided end-state rather than the failure window. Treat " +
+                  "the diagnosis as a post-mortem; check for a platform/remediation script that hung ahead of " +
+                  "the bootstrap (see script_timeout_suspected).";
+        }
     }
 }

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

@@ -221,8 +221,18 @@ namespace AutopilotMonitor.Agent.V2
                         },
                     });
 
-                    // Step 4 — run the executor and wait.
-                    using (var executor = new GatherRuleExecutor(sessionId, tenantId, emitEvent, logger, config.ImeLogPathOverride))
+                    // Step 4 — run the executor and wait. Diagnostic mode always writes the
+                    // gather-rule debug trace (CLI override or default path) and mirrors it
+                    // to the console in --console mode.
+                    var gatherDebugLogPath = !string.IsNullOrEmpty(config.GatherRuleDebugLogPath)
+                        ? config.GatherRuleDebugLogPath
+                        : Environment.ExpandEnvironmentVariables(Constants.GatherRuleDebugLogPath);
+                    logger.Info($"--run-gather-rules: debug trace -> {gatherDebugLogPath}");
+                    if (consoleMode) Console.WriteLine($"Debug trace: {gatherDebugLogPath}");
+
+                    using (var executor = new GatherRuleExecutor(sessionId, tenantId, emitEvent, logger, config.ImeLogPathOverride,
+                        debugLogPath: gatherDebugLogPath,
+                        debugEcho: consoleMode ? (Action<string>)(line => Console.WriteLine($"  {line}")) : null))
                     {
                         // Diagnostic mode has no enrollment phase context — scoped rules
                         // (activePhases / activeFromPhase) execute unconditionally here.

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

@@ -303,6 +303,7 @@ namespace AutopilotMonitor.Agent.V2
             var apiBaseUrl = GetArgValue(args, "--api-url", "--backend-api") ?? Constants.ApiBaseUrl;
             var imeLogPathOverride = GetArgValue(args, "--ime-log-path");
             var imeMatchLogPath = GetArgValue(args, "--ime-match-log");
+            var gatherDebugLogPath = GetArgValue(args, "--gather-debug-log");
 
             // Dev / test — IME log replay (V1 compat mode). Feeds ImeLogTracker.SimulationMode
             // + SpeedFactor so recorded raw IME logs are replayed at an accelerated rate; signal
@@ -373,6 +374,7 @@ namespace AutopilotMonitor.Agent.V2
                 EnableGeoLocation = !disableGeoLocation,
                 ImeLogPathOverride = imeLogPathOverride,
                 ImeMatchLogPath = imeMatchLogPath,
+                GatherRuleDebugLogPath = gatherDebugLogPath,
                 KeepLogFile = keepLogFile,
                 SelfDestructOnComplete = !noCleanup,
                 CommandLineArgs = FormatArgsForLog(args),
@@ -485,6 +487,7 @@ namespace AutopilotMonitor.Agent.V2
             Console.Out.WriteLine("  --api-url <URL>                   Override backend API base URL (alias: --backend-api)");
             Console.Out.WriteLine("  --ime-log-path <PATH>             Override IME logs directory");
             Console.Out.WriteLine("  --ime-match-log <PATH>            Write matched IME log lines to file (debug)");
+            Console.Out.WriteLine("  --gather-debug-log <PATH>         Write gather-rule evaluation trace to file (debug)");
             Console.Out.WriteLine();
             Console.Out.WriteLine("Dev / Test:");
             Console.Out.WriteLine("  --replay-log-dir <PATH>           Replay IME logs from this directory (simulation mode)");

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

@@ -46,8 +46,12 @@ namespace AutopilotMonitor.Agent.V2.Runtime
                     try { var _ = await remoteConfigService.FetchConfigAsync(); return true; }
                     catch (Exception ex) { logger.Warning($"ServerAction rotate_config failed: {ex.Message}"); return false; }
                 },
+                // On-demand request mid-enrollment — the session has no outcome yet. Null keeps
+                // sessioninfo.txt honest ("In Progress") and passes the OnFailure gate by
+                // semantics (there is no success to skip on) instead of the former
+                // enrollmentSucceeded:false workaround that stamped in-flight packages "Failed".
                 uploadDiagnosticsAsync: async (suffix) =>
-                    await diagnosticsService.CreateAndUploadAsync(enrollmentSucceeded: false, fileNameSuffix: suffix),
+                    await diagnosticsService.CreateAndUploadAsync(enrollmentSucceeded: null, fileNameSuffix: suffix),
                 onTerminateRequested: action => OnTerminateRequested(
                     action, agentConfig, orchestrator, terminationHandler, shutdown, shutdownComplete, logger),
                 post: post);

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

@@ -0,0 +1,34 @@
+using AutopilotMonitor.Shared.Models;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Default-value + round-trip tests for <see cref="AdminConfiguration.AutoApproveNewTenants"/>.
+/// The flag gates the tenant auto-approve queue worker — defaulting to false keeps new tenant
+/// signups on manual Global Admin approval until the operator deliberately opts in.
+/// </summary>
+public class AdminConfigurationAutoApproveNewTenantsTests
+{
+    [Fact]
+    public void AutoApproveNewTenants_defaults_to_false_on_new_config()
+    {
+        var cfg = new AdminConfiguration();
+        Assert.False(cfg.AutoApproveNewTenants);
+    }
+
+    [Fact]
+    public void AutoApproveNewTenants_defaults_to_false_on_CreateDefault()
+    {
+        // CreateDefault() is called when no admin-config row exists yet — if it somehow
+        // enabled auto-approve, tenants would activate without any operator opt-in.
+        var cfg = AdminConfiguration.CreateDefault();
+        Assert.False(cfg.AutoApproveNewTenants);
+    }
+
+    [Fact]
+    public void AutoApproveNewTenants_true_persists_on_the_config()
+    {
+        var cfg = new AdminConfiguration { AutoApproveNewTenants = true };
+        Assert.True(cfg.AutoApproveNewTenants);
+    }
+}

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

@@ -51,5 +51,7 @@ public class AdminConfigurationRateLimitSyncTests
         // ...but NO tenant configuration is enumerated or mutated (sync removed).
         repo.Verify(r => r.GetAllTenantConfigurationsAsync(), Times.Never);
         repo.Verify(r => r.SaveTenantConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        repo.Verify(r => r.SaveTenantConfigurationAsync(
+            It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 }

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

@@ -0,0 +1,64 @@
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.DataAccess;
+using AutopilotMonitor.Shared.Models;
+using Microsoft.Extensions.Caching.Memory;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Default-value + fail-closed tests for <see cref="AdminConfiguration.SelfServiceAppHomingEnabled"/>.
+/// The flag is the kill switch of the dual app-reg self-service homing flip — defaulting to false
+/// keeps the consent funnel and auto-flip off until the operator deliberately opts in, and a
+/// storage error must read as "disabled" (kill switch wins over a blip).
+/// </summary>
+public class AdminConfigurationSelfServiceAppHomingTests
+{
+    [Fact]
+    public void SelfServiceAppHoming_defaults_to_false_on_new_config()
+    {
+        var cfg = new AdminConfiguration();
+        Assert.False(cfg.SelfServiceAppHomingEnabled);
+    }
+
+    [Fact]
+    public void SelfServiceAppHoming_defaults_to_false_on_CreateDefault()
+    {
+        var cfg = AdminConfiguration.CreateDefault();
+        Assert.False(cfg.SelfServiceAppHomingEnabled);
+    }
+
+    [Fact]
+    public void SelfServiceAppHoming_true_persists_on_the_config()
+    {
+        var cfg = new AdminConfiguration { SelfServiceAppHomingEnabled = true };
+        Assert.True(cfg.SelfServiceAppHomingEnabled);
+    }
+
+    [Fact]
+    public async Task Reader_returns_true_when_flag_enabled()
+    {
+        var repo = new Mock<IConfigRepository>();
+        repo.Setup(r => r.GetAdminConfigurationAsync())
+            .ReturnsAsync(new AdminConfiguration { SelfServiceAppHomingEnabled = true });
+        var svc = new AdminConfigurationService(
+            repo.Object, NullLogger<AdminConfigurationService>.Instance,
+            new MemoryCache(new MemoryCacheOptions()));
+
+        Assert.True(await svc.IsSelfServiceAppHomingEnabledAsync());
+    }
+
+    [Fact]
+    public async Task Reader_fails_closed_on_repository_error()
+    {
+        var repo = new Mock<IConfigRepository>();
+        repo.Setup(r => r.GetAdminConfigurationAsync())
+            .ThrowsAsync(new InvalidOperationException("storage down"));
+        var svc = new AdminConfigurationService(
+            repo.Object, NullLogger<AdminConfigurationService>.Instance,
+            new MemoryCache(new MemoryCacheOptions()));
+
+        Assert.False(await svc.IsSelfServiceAppHomingEnabledAsync());
+    }
+}

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

@@ -189,7 +189,7 @@ public class AnalyzeRuleNotifyTests
 
         var alert = NotificationAlertBuilder.BuildRuleFiredAlert(
             result, "DESKTOP-CONTOSO1", "SN-1234",
-            "https://portal.autopilotmonitor.com/sessions/abc");
+            "https://portal.autopilotmonitor.com/sessions?id=abc");
 
         Assert.Equal("analyze_rule_fired", alert.EventType);
         Assert.Contains("Proxy blocks enrollment endpoints", alert.Title);
@@ -197,7 +197,7 @@ public class AnalyzeRuleNotifyTests
         Assert.Contains(alert.Facts, f => f.Name == "Serial" && f.Value == "SN-1234");
         Assert.Contains(alert.Facts, f => f.Name == "Rule" && f.Value.Contains("ANALYZE-NET-001"));
         Assert.Contains(alert.Facts, f => f.Name == "Confidence" && f.Value == "85%");
-        Assert.Contains(alert.Actions, a => a.Type == "openUrl" && a.Url == "https://portal.autopilotmonitor.com/sessions/abc");
+        Assert.Contains(alert.Actions, a => a.Type == "openUrl" && a.Url == "https://portal.autopilotmonitor.com/sessions?id=abc");
         Assert.Contains(alert.Sections, s => s.Text.Contains("could not reach"));
     }
 

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

@@ -0,0 +1,135 @@
+using AutopilotMonitor.Functions.Services;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Authorization/validation matrix for <see cref="AppHomingService.EvaluateManualFlip"/> — the
+/// pure decision behind <c>POST config/{tenantId}/app-homing</c>. Contract: tenant admins may
+/// only flip TO primary, without force, with the self-service flag on, and only after a
+/// successful consent probe; Global Admins may flip both directions and force past the probe.
+/// </summary>
+public class AppHomingDecisionTests
+{
+    private static readonly AppHomingProbeResult ProbeOk = new(Succeeded: true, IsTransient: false);
+    private static readonly AppHomingProbeResult ProbeFail = new(Succeeded: false, IsTransient: false);
+    private static readonly AppHomingProbeResult ProbeTransient = new(Succeeded: false, IsTransient: true);
+
+    private static AppHomingDecision Evaluate(
+        bool isGlobalAdmin = false,
+        bool selfServiceEnabled = true,
+        bool legacyConfigured = true,
+        bool currentlyPrimary = false,
+        bool targetPrimary = true,
+        bool force = false,
+        AppHomingProbeResult? probe = null)
+        => AppHomingService.EvaluateManualFlip(
+            isGlobalAdmin, selfServiceEnabled, legacyConfigured, currentlyPrimary, targetPrimary, force, probe);
+
+    [Fact]
+    public void ParallelWindowInactive_denies_for_everyone()
+    {
+        var decision = Evaluate(isGlobalAdmin: true, legacyConfigured: false, force: true);
+        Assert.Equal(AppHomingDecisionKind.Deny, decision.Kind);
+        Assert.Equal("parallel-window-inactive", decision.ReasonCode);
+        Assert.Equal(409, decision.StatusCode);
+    }
+
+    [Theory]
+    [InlineData(false, false)] // legacy-homed, target legacy
+    [InlineData(true, true)]   // primary-homed, target primary
+    public void AlreadyAtTarget_is_a_noop(bool currentlyPrimary, bool targetPrimary)
+    {
+        var decision = Evaluate(currentlyPrimary: currentlyPrimary, targetPrimary: targetPrimary);
+        Assert.Equal(AppHomingDecisionKind.AllowNoOp, decision.Kind);
+    }
+
+    [Fact]
+    public void NonGa_revert_to_legacy_is_denied()
+    {
+        var decision = Evaluate(currentlyPrimary: true, targetPrimary: false);
+        Assert.Equal(AppHomingDecisionKind.Deny, decision.Kind);
+        Assert.Equal("revert-is-ga-only", decision.ReasonCode);
+        Assert.Equal(403, decision.StatusCode);
+    }
+
+    [Fact]
+    public void NonGa_force_is_denied()
+    {
+        var decision = Evaluate(force: true);
+        Assert.Equal(AppHomingDecisionKind.Deny, decision.Kind);
+        Assert.Equal("force-is-ga-only", decision.ReasonCode);
+        Assert.Equal(403, decision.StatusCode);
+    }
+
+    [Fact]
+    public void NonGa_with_flag_off_is_denied()
+    {
+        // The kill switch: turning the admin-config flag off must stop tenant-admin flips
+        // immediately, while the GA path below stays open (operator lever survives).
+        var decision = Evaluate(selfServiceEnabled: false);
+        Assert.Equal(AppHomingDecisionKind.Deny, decision.Kind);
+        Assert.Equal("self-service-disabled", decision.ReasonCode);
+        Assert.Equal(409, decision.StatusCode);
+    }
+
+    [Fact]
+    public void Ga_with_flag_off_still_requires_only_the_probe()
+    {
+        var decision = Evaluate(isGlobalAdmin: true, selfServiceEnabled: false);
+        Assert.Equal(AppHomingDecisionKind.RequireProbe, decision.Kind);
+    }
+
+    [Fact]
+    public void FlipToPrimary_without_probe_requires_probe()
+    {
+        var decision = Evaluate();
+        Assert.Equal(AppHomingDecisionKind.RequireProbe, decision.Kind);
+    }
+
+    [Fact]
+    public void FlipToPrimary_with_successful_probe_is_allowed()
+    {
+        var decision = Evaluate(probe: ProbeOk);
+        Assert.Equal(AppHomingDecisionKind.Allow, decision.Kind);
+    }
+
+    [Fact]
+    public void FlipToPrimary_with_failed_probe_is_denied()
+    {
+        var decision = Evaluate(probe: ProbeFail);
+        Assert.Equal(AppHomingDecisionKind.Deny, decision.Kind);
+        Assert.Equal("probe-failed", decision.ReasonCode);
+        Assert.Equal(409, decision.StatusCode);
+    }
+
+    [Fact]
+    public void FlipToPrimary_with_transient_probe_is_denied_as_retryable()
+    {
+        var decision = Evaluate(probe: ProbeTransient);
+        Assert.Equal(AppHomingDecisionKind.Deny, decision.Kind);
+        Assert.Equal("probe-transient", decision.ReasonCode);
+        Assert.Equal(503, decision.StatusCode);
+    }
+
+    [Fact]
+    public void Ga_flip_without_force_also_requires_probe()
+    {
+        var decision = Evaluate(isGlobalAdmin: true);
+        Assert.Equal(AppHomingDecisionKind.RequireProbe, decision.Kind);
+    }
+
+    [Fact]
+    public void Ga_force_skips_the_probe()
+    {
+        var decision = Evaluate(isGlobalAdmin: true, force: true);
+        Assert.Equal(AppHomingDecisionKind.Allow, decision.Kind);
+    }
+
+    [Fact]
+    public void Ga_revert_to_legacy_needs_no_probe()
+    {
+        // The legacy app is consented by construction — probing it would be meaningless.
+        var decision = Evaluate(isGlobalAdmin: true, currentlyPrimary: true, targetPrimary: false);
+        Assert.Equal(AppHomingDecisionKind.Allow, decision.Kind);
+    }
+}

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

@@ -0,0 +1,289 @@
+using AutopilotMonitor.Functions.Security;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Functions.Services.GraphResolution;
+using AutopilotMonitor.Functions.Services.Notifications;
+using AutopilotMonitor.Shared.DataAccess;
+using AutopilotMonitor.Shared.Models;
+using Microsoft.ApplicationInsights;
+using Microsoft.ApplicationInsights.Extensibility;
+using Microsoft.Extensions.Caching.Memory;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Unit tests for <see cref="AppHomingService"/> — funnel eligibility, the consent-driven
+/// auto-flip, and the flip persist side-effect chain (save + cache invalidation + audit +
+/// ops events). The consent probe and the kill-switch flag are mocked at their virtual seams.
+/// </summary>
+public class AppHomingServiceTests
+{
+    private const string TenantId = "11111111-1111-1111-1111-111111111111";
+    private const string PrimaryId = "aaaaaaaa-0000-0000-0000-000000000001";
+    private const string LegacyId = "bbbbbbbb-0000-0000-0000-000000000002";
+    private const string Actor = "admin@contoso.com";
+
+    private readonly Mock<AdminConfigurationService> _adminConfigMock;
+    private readonly Mock<TenantConfigurationService> _tenantConfigMock;
+    private readonly Mock<GraphTokenService> _graphTokenMock;
+    private readonly Mock<IGraphFeatureDetector> _detectorMock;
+    private readonly Mock<IMaintenanceRepository> _maintenanceMock;
+    private readonly List<OpsEventEntry> _savedOpsEvents = new();
+    private readonly EntraAppRegistry _registry;
+    private readonly AppHomingService _sut;
+
+    public AppHomingServiceTests() : this(legacyConfigured: true) { }
+
+    private AppHomingServiceTests(bool legacyConfigured)
+    {
+        var configValues = new Dictionary<string, string?>
+        {
+            ["EntraId:ClientId"] = PrimaryId,
+            ["EntraId:ClientSecret"] = "primary-secret",
+        };
+        if (legacyConfigured)
+        {
+            configValues["EntraId:LegacyClientId"] = LegacyId;
+            configValues["EntraId:LegacyClientSecret"] = "legacy-secret";
+        }
+        var configuration = new ConfigurationBuilder().AddInMemoryCollection(configValues).Build();
+        _registry = new EntraAppRegistry(configuration, NullLogger<EntraAppRegistry>.Instance);
+
+        var configRepo = Mock.Of<IConfigRepository>();
+        var cache = new MemoryCache(new MemoryCacheOptions());
+
+        _adminConfigMock = new Mock<AdminConfigurationService>(
+            configRepo, NullLogger<AdminConfigurationService>.Instance, cache)
+        { CallBase = false };
+        _tenantConfigMock = new Mock<TenantConfigurationService>(
+            configRepo, NullLogger<TenantConfigurationService>.Instance, cache)
+        { CallBase = false };
+        _graphTokenMock = new Mock<GraphTokenService>(
+            NullLogger<GraphTokenService>.Instance,
+            Mock.Of<System.Net.Http.IHttpClientFactory>(),
+            cache,
+            configuration,
+            _registry,
+            _tenantConfigMock.Object)
+        { CallBase = false };
+        _detectorMock = new Mock<IGraphFeatureDetector>();
+        _maintenanceMock = new Mock<IMaintenanceRepository>();
+        _maintenanceMock
+            .Setup(m => m.LogAuditEntryAsync(It.IsAny<string>(), It.IsAny<string>(), It.IsAny<string>(),
+                It.IsAny<string>(), It.IsAny<string>(), It.IsAny<Dictionary<string, string>?>()))
+            .ReturnsAsync(true);
+
+        var opsRepo = new Mock<IOpsEventRepository>();
+        opsRepo.Setup(r => r.SaveOpsEventAsync(It.IsAny<OpsEventEntry>()))
+            .Callback<OpsEventEntry>(e => { lock (_savedOpsEvents) _savedOpsEvents.Add(e); })
+            .Returns(Task.CompletedTask);
+        var alertDispatch = new OpsAlertDispatchService(
+            _adminConfigMock.Object,
+            new TelegramNotificationService(new HttpClient(), configRepo,
+                NullLogger<TelegramNotificationService>.Instance),
+            new WebhookNotificationService(new HttpClient(),
+                NullLogger<WebhookNotificationService>.Instance),
+            NullLogger<OpsAlertDispatchService>.Instance);
+        var opsService = new OpsEventService(opsRepo.Object, NullLogger<OpsEventService>.Instance, alertDispatch);
+
+        _sut = new AppHomingService(
+            NullLogger<AppHomingService>.Instance,
+            _adminConfigMock.Object,
+            _tenantConfigMock.Object,
+            _registry,
+            _graphTokenMock.Object,
+            _detectorMock.Object,
+            _maintenanceMock.Object,
+            opsService,
+            new TelemetryClient(new TelemetryConfiguration { DisableTelemetry = true }));
+
+        // Defaults: flag on, legacy-homed config exists, probe succeeds. FlipAsync reads via
+        // the cache-bypassing GetConfigurationFreshAsync (read-modify-write on the whole entity).
+        _adminConfigMock.Setup(x => x.IsSelfServiceAppHomingEnabledAsync()).ReturnsAsync(true);
+        var config = LegacyHomedConfig();
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId)).ReturnsAsync(config);
+        _tenantConfigMock.Setup(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()))
+            .Returns(Task.CompletedTask);
+        SetupProbe(GraphTokenResult.Success("tok"));
+    }
+
+    private static TenantConfiguration LegacyHomedConfig()
+    {
+        var config = TenantConfiguration.CreateDefault(TenantId);
+        config.HomedAppClientId = null;
+        return config;
+    }
+
+    private void SetupProbe(GraphTokenResult result) =>
+        _graphTokenMock
+            .Setup(x => x.GetAccessTokenForAppAsync(TenantId, It.Is<EntraAppCredentials>(c => !c.IsLegacy),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(result);
+
+    // ── IsFunnelEligibleAsync ───────────────────────────────────────────────
+
+    [Fact]
+    public async Task Funnel_is_eligible_for_legacy_homed_tenant_with_flag_on()
+    {
+        Assert.True(await _sut.IsFunnelEligibleAsync(LegacyHomedConfig()));
+    }
+
+    [Fact]
+    public async Task Funnel_is_not_eligible_when_legacy_pair_unconfigured()
+    {
+        var sut = new AppHomingServiceTests(legacyConfigured: false)._sut;
+        Assert.False(await sut.IsFunnelEligibleAsync(LegacyHomedConfig()));
+    }
+
+    [Fact]
+    public async Task Funnel_is_not_eligible_for_primary_homed_tenant()
+    {
+        var config = LegacyHomedConfig();
+        config.HomedAppClientId = PrimaryId;
+        Assert.False(await _sut.IsFunnelEligibleAsync(config));
+    }
+
+    [Fact]
+    public async Task Funnel_is_not_eligible_when_flag_off()
+    {
+        _adminConfigMock.Setup(x => x.IsSelfServiceAppHomingEnabledAsync()).ReturnsAsync(false);
+        Assert.False(await _sut.IsFunnelEligibleAsync(LegacyHomedConfig()));
+    }
+
+    [Fact]
+    public async Task Funnel_does_not_block_on_entra_app_roles()
+    {
+        // Deliberate: app-role tenants may flip (operator informs them personally); the
+        // reminder trail is asserted in the flip test below.
+        var config = LegacyHomedConfig();
+        config.EntraAppRolesEnabled = true;
+        Assert.True(await _sut.IsFunnelEligibleAsync(config));
+    }
+
+    // ── TryAutoFlipToPrimaryAsync ───────────────────────────────────────────
+
+    [Fact]
+    public async Task AutoFlip_flips_on_probe_success_with_full_side_effect_chain()
+    {
+        var outcome = await _sut.TryAutoFlipToPrimaryAsync(LegacyHomedConfig(), Actor);
+
+        Assert.Equal(AppHomingAutoFlipOutcome.Flipped, outcome);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.Is<TenantConfiguration>(c =>
+            string.Equals(c.HomedAppClientId, PrimaryId, StringComparison.OrdinalIgnoreCase)
+            && c.UpdatedBy == Actor), It.IsAny<string?>(), It.IsAny<string?>()), Times.Once);
+        _detectorMock.Verify(x => x.InvalidateTenant(TenantId), Times.Once);
+        _maintenanceMock.Verify(m => m.LogAuditEntryAsync(TenantId, "UPDATE", "TenantConfiguration",
+            TenantId, Actor, It.Is<Dictionary<string, string>?>(d =>
+                d != null && d.ContainsKey("HomedAppClientId"))), Times.Once);
+        Assert.Contains(_savedOpsEvents, e => e.EventType == "AppHomingFlipped");
+        Assert.DoesNotContain(_savedOpsEvents, e => e.EventType == "AppHomingFlippedWithEntraRoles");
+    }
+
+    [Fact]
+    public async Task AutoFlip_does_not_flip_on_permanent_probe_failure()
+    {
+        SetupProbe(GraphTokenResult.PermanentFailure());
+
+        var outcome = await _sut.TryAutoFlipToPrimaryAsync(LegacyHomedConfig(), Actor);
+
+        Assert.Equal(AppHomingAutoFlipOutcome.ProbeFailed, outcome);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task AutoFlip_does_not_flip_on_transient_probe()
+    {
+        SetupProbe(GraphTokenResult.TransientFailure());
+
+        var outcome = await _sut.TryAutoFlipToPrimaryAsync(LegacyHomedConfig(), Actor);
+
+        Assert.Equal(AppHomingAutoFlipOutcome.ProbeTransient, outcome);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task AutoFlip_is_not_eligible_for_primary_homed_tenant_and_never_probes()
+    {
+        var config = LegacyHomedConfig();
+        config.HomedAppClientId = PrimaryId;
+
+        var outcome = await _sut.TryAutoFlipToPrimaryAsync(config, Actor);
+
+        Assert.Equal(AppHomingAutoFlipOutcome.NotEligible, outcome);
+        _graphTokenMock.Verify(x => x.GetAccessTokenForAppAsync(It.IsAny<string>(),
+            It.IsAny<EntraAppCredentials>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task AutoFlip_is_not_eligible_when_flag_off()
+    {
+        _adminConfigMock.Setup(x => x.IsSelfServiceAppHomingEnabledAsync()).ReturnsAsync(false);
+
+        var outcome = await _sut.TryAutoFlipToPrimaryAsync(LegacyHomedConfig(), Actor);
+
+        Assert.Equal(AppHomingAutoFlipOutcome.NotEligible, outcome);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+    }
+
+    // ── FlipAsync ───────────────────────────────────────────────────────────
+
+    [Fact]
+    public async Task Flip_of_entra_app_roles_tenant_emits_reminder_ops_event()
+    {
+        var config = LegacyHomedConfig();
+        config.EntraAppRolesEnabled = true;
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId)).ReturnsAsync(config);
+
+        await _sut.FlipAsync(TenantId, PrimaryId, Actor, "manual-ga");
+
+        Assert.Contains(_savedOpsEvents, e => e.EventType == "AppHomingFlipped");
+        Assert.Contains(_savedOpsEvents, e => e.EventType == "AppHomingFlippedWithEntraRoles");
+    }
+
+    [Fact]
+    public async Task Flip_noops_when_already_at_target()
+    {
+        var config = LegacyHomedConfig();
+        config.HomedAppClientId = PrimaryId;
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId)).ReturnsAsync(config);
+
+        await _sut.FlipAsync(TenantId, PrimaryId, Actor, "manual-ga");
+
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+        _detectorMock.Verify(x => x.InvalidateTenant(It.IsAny<string>()), Times.Never);
+        Assert.Empty(_savedOpsEvents);
+    }
+
+    [Fact]
+    public async Task Flip_throws_when_config_row_missing_and_saves_nothing()
+    {
+        // A flip must never materialize a default row (e.g. resurrect an offboarded tenant);
+        // the fresh read returning null is a hard stop.
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId))
+            .ReturnsAsync((TenantConfiguration?)null);
+
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => _sut.FlipAsync(TenantId, PrimaryId, Actor, "manual-ga"));
+
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+        _detectorMock.Verify(x => x.InvalidateTenant(It.IsAny<string>()), Times.Never);
+        Assert.Empty(_savedOpsEvents);
+    }
+
+    [Fact]
+    public async Task Flip_back_to_legacy_persists_null_homing()
+    {
+        var config = LegacyHomedConfig();
+        config.HomedAppClientId = PrimaryId;
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId)).ReturnsAsync(config);
+
+        await _sut.FlipAsync(TenantId, null, Actor, "manual-ga");
+
+        // The null-homing invariant: legacy is represented as null, never as the legacy GUID.
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.Is<TenantConfiguration>(c =>
+            c.HomedAppClientId == null), It.IsAny<string?>(), It.IsAny<string?>()), Times.Once);
+        _detectorMock.Verify(x => x.InvalidateTenant(TenantId), Times.Once);
+    }
+}

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

@@ -0,0 +1,333 @@
+using System.Text.Json;
+using Azure.Data.Tables;
+using AutopilotMonitor.Functions.Functions.Apps;
+using AutopilotMonitor.Functions.Helpers;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.DataAccess;
+using AutopilotMonitor.Shared.Models;
+using Moq;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// F1 PR1 (insights spec §F1, source-data audit Q2/Q3): app identity on the name-keyed
+/// summary row and the ESP-blocking join.
+///
+/// Ingest side: <c>appId</c> is adopted from the app events; a second appId under the same
+/// name flags the row (<see cref="AppInstallSummary.AppIdCollision"/>) — in-batch and
+/// cross-batch. Store side: sentinel-gated columns + sticky collision. Join side:
+/// <see cref="EspBlockingSets"/> is positive evidence only, and
+/// <see cref="TableStorageService.ShouldStampEspBlocking"/> never stamps collision rows,
+/// id-less rows, or non-members. Aggregate side: collision rows leave every per-app fleet
+/// aggregate with a disclosed exclusion count.
+/// </summary>
+public class AppInstallIdentityAndEspBlockingTests
+{
+    private static readonly DateTime T0 = new(2026, 7, 26, 10, 0, 0, DateTimeKind.Utc);
+
+    private const string IdA = "aaaaaaaa-1111-2222-3333-444444444444";
+    private const string IdB = "bbbbbbbb-1111-2222-3333-444444444444";
+
+    // ── ingest fold: appId adoption + in-batch collision ────────────────────
+
+    private static Dictionary<string, AppInstallAggregationState> Aggregate(params EnrollmentEvent[] events)
+    {
+        var summaries = new Dictionary<string, AppInstallAggregationState>(StringComparer.OrdinalIgnoreCase);
+        foreach (var evt in events)
+            EventIngestProcessor.AggregateAppInstallEvent(evt, "tenant", "session", summaries);
+        return summaries;
+    }
+
+    private static EnrollmentEvent AppEvent(string eventType, string? appId = null, string appName = "App")
+    {
+        var evt = new EnrollmentEvent
+        {
+            EventType = eventType,
+            Timestamp = T0,
+            Data = new Dictionary<string, object> { ["appName"] = appName },
+        };
+        if (appId != null) evt.Data["appId"] = appId;
+        return evt;
+    }
+
+    [Fact]
+    public void Ingest_AdoptsAppId_FromFirstObservingEvent()
+    {
+        var s = Aggregate(
+            AppEvent("app_install_started", IdA),
+            AppEvent("app_install_completed", IdA))["App"].Summary;
+
+        Assert.Equal(IdA, s.AppId);
+        Assert.False(s.AppIdCollision);
+    }
+
+    [Fact]
+    public void Ingest_SameName_DifferentAppId_FlagsCollision_FirstSeenIdWins()
+    {
+        // Device- + user-scope assignment of the same display name in one batch (audit Q3:
+        // observed in production as two "Company Portal" appIds in one session).
+        var s = Aggregate(
+            AppEvent("app_install_started", IdA),
+            AppEvent("app_install_started", IdB))["App"].Summary;
+
+        Assert.True(s.AppIdCollision);
+        Assert.Equal(IdA, s.AppId);
+    }
+
+    [Fact]
+    public void Ingest_AppIdCaseDrift_IsNotACollision()
+    {
+        var s = Aggregate(
+            AppEvent("app_install_started", IdA),
+            AppEvent("app_install_completed", IdA.ToUpperInvariant()))["App"].Summary;
+
+        Assert.False(s.AppIdCollision);
+    }
+
+    [Fact]
+    public void Ingest_EventsWithoutAppId_LeaveSentinelEmpty()
+    {
+        var s = Aggregate(AppEvent("app_install_completed"))["App"].Summary;
+        Assert.Equal(string.Empty, s.AppId);
+        Assert.False(s.AppIdCollision);
+    }
+
+    // ── reconcile: cross-batch identity ─────────────────────────────────────
+
+    [Fact]
+    public void Reconcile_AdoptsStoredAppId_WhenIncomingBatchHasNone()
+    {
+        var existing = new TableEntity("tenant", "session_App") { ["AppId"] = IdA };
+        var summary = new AppInstallSummary { AppName = "App", StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.Equal(IdA, summary.AppId);
+        Assert.False(summary.AppIdCollision);
+    }
+
+    [Fact]
+    public void Reconcile_CrossBatchDifferentAppId_FlagsCollision_StoredIdWins()
+    {
+        var existing = new TableEntity("tenant", "session_App") { ["AppId"] = IdA };
+        var summary = new AppInstallSummary { AppName = "App", AppId = IdB, StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.True(summary.AppIdCollision);
+        Assert.Equal(IdA, summary.AppId); // first-seen (stored) identity wins, matching the fold rule
+    }
+
+    [Fact]
+    public void Reconcile_CollisionIsSticky_AndEspBlockingVerdictIsAdopted()
+    {
+        var existing = new TableEntity("tenant", "session_App")
+        {
+            ["AppId"] = IdA,
+            ["AppIdCollision"] = true,
+            ["EspBlocking"] = true,
+        };
+        var summary = new AppInstallSummary { AppName = "App", AppId = IdA, StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.True(summary.AppIdCollision);       // one-way sticky
+        Assert.True(summary.EspBlocking);          // terminal-path verdict survives late batches
+    }
+
+    // ── entity builder: sentinel gating ─────────────────────────────────────
+
+    [Fact]
+    public void EntityBuilder_IdentityColumns_AreSentinelGated()
+    {
+        var empty = TableStorageService.BuildAppInstallSummaryEntity(
+            new AppInstallSummary { AppName = "App" }, "rk");
+        // Absent columns → Merge-mode preserves prior values / stays unknown.
+        Assert.False(empty.ContainsKey("AppId"));
+        Assert.False(empty.ContainsKey("EspBlocking"));
+        Assert.False(empty.ContainsKey("AppIdCollision"));
+
+        var full = TableStorageService.BuildAppInstallSummaryEntity(
+            new AppInstallSummary { AppName = "App", AppId = IdA, EspBlocking = true, AppIdCollision = true }, "rk");
+        Assert.Equal(IdA, full.GetString("AppId"));
+        Assert.True(full.GetBoolean("EspBlocking"));
+        Assert.True(full.GetBoolean("AppIdCollision"));
+    }
+
+    // ── EspBlockingSets: positive-evidence parsing ──────────────────────────
+
+    private static Dictionary<string, object> Lists(
+        object? win32 = null, object? userWin32 = null, object? msi = null, object? pfn = null,
+        long? win32Count = null)
+    {
+        var d = new Dictionary<string, object> { ["source"] = "registry_firstsync" };
+        if (win32 != null) d["espTrackedWin32AppIds"] = win32;
+        if (userWin32 != null) d["espTrackedUserWin32AppIds"] = userWin32;
+        if (msi != null) d["espTrackedMsiProductCodes"] = msi;
+        if (pfn != null) d["espTrackedModernAppPfns"] = pfn;
+        if (win32Count.HasValue) d["espTrackedWin32Count"] = win32Count.Value;
+        return d;
+    }
+
+    [Fact]
+    public void Sets_PayloadWithoutListKeys_YieldsNull_NoListsIsNotEmptyLists()
+    {
+        Assert.Null(EspBlockingSets.FromEventData(null));
+        Assert.Null(EspBlockingSets.FromEventData(Lists())); // probe found no Diagnostics key
+    }
+
+    [Fact]
+    public void Sets_MembershipIsCaseInsensitive_AcrossAllFourLists()
+    {
+        // Storage rehydration shape: List<object> (EventDataNormalizer).
+        var sets = EspBlockingSets.FromEventData(Lists(
+            win32: new List<object> { IdA },
+            msi: new List<object> { "{11111111-2222-3333-4444-555555555555}" },
+            pfn: new List<object> { "Contoso.App_abc123" }))!;
+
+        Assert.True(sets.Contains(IdA.ToUpperInvariant()));
+        Assert.True(sets.Contains("{11111111-2222-3333-4444-555555555555}"));
+        Assert.True(sets.Contains("Contoso.App_abc123"));
+        Assert.False(sets.Contains(IdB));           // absent ⇒ unknown at the caller, never false here
+        Assert.False(sets.Contains(null));
+        Assert.Equal(3, sets.ListedCount);
+        Assert.False(sets.IsTruncated);
+    }
+
+    [Fact]
+    public void Sets_EmittedCountAboveListLength_MeansTruncated()
+    {
+        var sets = EspBlockingSets.FromEventData(Lists(
+            win32: new List<object> { IdA }, win32Count: 60))!;
+
+        Assert.True(sets.IsTruncated);
+    }
+
+    [Fact]
+    public void Sets_UserScopeSubset_IsExposedForCoverageLabeling()
+    {
+        var sets = EspBlockingSets.FromEventData(Lists(
+            win32: new List<object> { IdA, IdB },
+            userWin32: new List<object> { IdB }))!;
+
+        Assert.Contains(IdB, sets.UserWin32AppIds);
+        Assert.DoesNotContain(IdA, sets.UserWin32AppIds);
+    }
+
+    // ── terminal-path stamping predicate ────────────────────────────────────
+
+    private static TableEntity Row(string? appId = null, bool? collision = null, bool? espBlocking = null)
+    {
+        var row = new TableEntity("tenant", "session_App");
+        if (appId != null) row["AppId"] = appId;
+        if (collision.HasValue) row["AppIdCollision"] = collision.Value;
+        if (espBlocking.HasValue) row["EspBlocking"] = espBlocking.Value;
+        return row;
+    }
+
+    [Fact]
+    public void Stamp_OnlyPositiveMembers_NeverIdlessCollidedOrAlreadyStamped()
+    {
+        var sets = EspBlockingSets.FromEventData(Lists(win32: new List<object> { IdA }))!;
+
+        Assert.True(TableStorageService.ShouldStampEspBlocking(Row(IdA), sets));
+        Assert.False(TableStorageService.ShouldStampEspBlocking(Row(), sets));                    // no identity → unknown
+        Assert.False(TableStorageService.ShouldStampEspBlocking(Row(IdB), sets));                 // absent ⇒ unknown, never false
+        Assert.False(TableStorageService.ShouldStampEspBlocking(Row(IdA, collision: true), sets)); // ambiguous identity
+        Assert.False(TableStorageService.ShouldStampEspBlocking(Row(IdA, espBlocking: true), sets)); // idempotent
+    }
+
+    // ── per-app fleet aggregates: collision rows leave, disclosed ───────────
+
+    private static AppInstallSummary Summary(
+        string appName, string status = "Succeeded", bool collision = false, int duration = 30)
+        => new()
+        {
+            TenantId = "00000000-0000-0000-0000-000000000fa1",
+            SessionId = "s-1",
+            AppName = appName,
+            Status = status,
+            TerminalState = status == "Succeeded" ? "Installed" : "Error",
+            DurationSeconds = duration,
+            StartedAt = DateTime.UtcNow.AddHours(-2),
+            AppIdCollision = collision,
+        };
+
+    [Fact]
+    public void AppMetricsPayload_ExcludesCollisionRowsFromGroups_DisclosesCount()
+    {
+        var summaries = new List<AppInstallSummary>
+        {
+            Summary("Clean App"),
+            Summary("Clean App"),
+            Summary("Company Portal", collision: true),
+            Summary("Company Portal", status: "Failed", collision: true),
+        };
+
+        var root = JsonSerializer.SerializeToElement(MetricsMath.BuildAppMetricsPayload(summaries));
+
+        Assert.Equal(1, root.GetProperty("totalApps").GetInt32());          // collided name forms no group
+        Assert.Equal(4, root.GetProperty("totalInstalls").GetInt32());      // raw row count unchanged
+        Assert.Equal(2, root.GetProperty("totalCollisionExcluded").GetInt32());
+        Assert.Empty(root.GetProperty("topFailingApps").EnumerateArray());  // the collided Failed row ranks nowhere
+    }
+
+    [Fact]
+    public void AppsList_ExcludesCollisionRows_DisclosesCount()
+    {
+        var summaries = new List<AppInstallSummary>
+        {
+            Summary("Clean App"),
+            Summary("Company Portal", collision: true),
+        };
+
+        var root = JsonSerializer.SerializeToElement(
+            AppsAnalyticsHelper.BuildAppsListResponse(summaries, days: 30));
+
+        var apps = root.GetProperty("apps").EnumerateArray().ToList();
+        Assert.Single(apps);
+        Assert.Equal("Clean App", apps[0].GetProperty("appName").GetString());
+        Assert.Equal(2, root.GetProperty("totalInstalls").GetInt32());
+        Assert.Equal(1, root.GetProperty("collisionExcluded").GetInt32());
+    }
+
+    [Fact]
+    public async Task AppAnalytics_ExcludesCollisionRows_DisclosesCount()
+    {
+        var repo = new Mock<ISessionRepository>();
+        repo.Setup(r => r.GetSessionAsync(It.IsAny<string>(), It.IsAny<string>()))
+            .ReturnsAsync((SessionSummary?)null);
+
+        var summaries = new List<AppInstallSummary>
+        {
+            Summary("Company Portal"),
+            Summary("Company Portal", status: "Failed", collision: true), // the second identity's failure
+        };
+
+        var root = JsonSerializer.SerializeToElement(await AppsAnalyticsHelper.BuildAnalyticsResponseAsync(
+            summaries, repo.Object, "Company Portal", days: 30));
+
+        Assert.Equal(1, root.GetProperty("collisionExcluded").GetInt32());
+        var stats = root.GetProperty("summary");
+        Assert.Equal(1, stats.GetProperty("totalInstalls").GetInt32());
+        Assert.Equal(0, stats.GetProperty("failed").GetInt32());            // ambiguous failure not attributed
+        Assert.Equal(0d, stats.GetProperty("failureRate").GetDouble());
+    }
+
+    [Fact]
+    public async Task AppAnalytics_AllRowsCollided_ReturnsEmptyShape_WithDisclosure()
+    {
+        var repo = new Mock<ISessionRepository>();
+        repo.Setup(r => r.GetSessionAsync(It.IsAny<string>(), It.IsAny<string>()))
+            .ReturnsAsync((SessionSummary?)null);
+
+        var summaries = new List<AppInstallSummary> { Summary("Company Portal", collision: true) };
+
+        var root = JsonSerializer.SerializeToElement(await AppsAnalyticsHelper.BuildAnalyticsResponseAsync(
+            summaries, repo.Object, "Company Portal", days: 30));
+
+        Assert.Equal(1, root.GetProperty("collisionExcluded").GetInt32());
+        Assert.Equal(0, root.GetProperty("summary").GetProperty("totalInstalls").GetInt32());
+    }
+}

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

@@ -0,0 +1,201 @@
+using Azure.Data.Tables;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// PR0 (2026-07-26, source-data audit §0.5 of tasks/insights-expansion-spec.md).
+///
+/// Ingest side: the agent emits <c>app_install_completed</c> for EVERY terminal transition —
+/// including Skipped/Postponed no-ops (V1 wire parity; production: 78 % of zero-duration rows
+/// were skips). The payload's <c>state</c> field must be persisted as
+/// <see cref="AppInstallSummary.TerminalState"/> so metrics can exclude skips from durations
+/// and rates.
+///
+/// Store side: <see cref="TableStorageService.ReconcileAppInstallSummaryWithExisting"/> pins the
+/// cross-batch contract — earliest StartedAt wins, terminal status is sticky, and the Q4
+/// out-of-order case (terminal batch first, started batch later) recomputes the duration.
+/// </summary>
+public class AppInstallTerminalStateAndReconcileTests
+{
+    private static readonly DateTime T0 = new(2026, 7, 26, 10, 0, 0, DateTimeKind.Utc);
+
+    // ── ingest: TerminalState fold ──────────────────────────────────────────
+
+    private static Dictionary<string, AppInstallAggregationState> Aggregate(params EnrollmentEvent[] events)
+    {
+        var summaries = new Dictionary<string, AppInstallAggregationState>(StringComparer.OrdinalIgnoreCase);
+        foreach (var evt in events)
+            EventIngestProcessor.AggregateAppInstallEvent(evt, "tenant", "session", summaries);
+        return summaries;
+    }
+
+    private static EnrollmentEvent AppEvent(string eventType, DateTime ts, string? state = null, string appName = "App")
+    {
+        var evt = new EnrollmentEvent
+        {
+            EventType = eventType,
+            Timestamp = ts,
+            Data = new Dictionary<string, object> { ["appName"] = appName },
+        };
+        if (state != null) evt.Data["state"] = state;
+        return evt;
+    }
+
+    [Theory]
+    [InlineData("Installed")]
+    [InlineData("Skipped")]
+    [InlineData("Postponed")]
+    public void Completed_PersistsPayloadState(string state)
+    {
+        var s = Aggregate(AppEvent("app_install_completed", T0, state))["App"].Summary;
+
+        Assert.Equal("Succeeded", s.Status);          // backward-compatible status
+        Assert.Equal(state, s.TerminalState);          // new precision column
+    }
+
+    [Fact]
+    public void Completed_WithoutState_LeavesSentinelEmpty_NeverGuessed()
+    {
+        var s = Aggregate(AppEvent("app_install_completed", T0))["App"].Summary;
+        Assert.Equal(string.Empty, s.TerminalState);
+    }
+
+    [Fact]
+    public void Completed_WithNonTerminalOrGarbageState_LeavesSentinelEmpty()
+    {
+        // A payload state outside the terminal set (bug or drift) must not be persisted.
+        var s = Aggregate(AppEvent("app_install_completed", T0, "Downloading"))["App"].Summary;
+        Assert.Equal(string.Empty, s.TerminalState);
+    }
+
+    [Fact]
+    public void Failed_SetsError()
+    {
+        var s = Aggregate(AppEvent("app_install_failed", T0))["App"].Summary;
+        Assert.Equal("Failed", s.Status);
+        Assert.Equal("Error", s.TerminalState);
+    }
+
+    [Fact]
+    public void FailedThenCompleted_RetrySucceeds_LastTerminalWins()
+    {
+        // IME retry path (audit Q1): Error → retry → Installed. The later completed event is
+        // the authoritative outcome for Status AND TerminalState.
+        var s = Aggregate(
+            AppEvent("app_install_failed", T0),
+            AppEvent("app_install_completed", T0.AddMinutes(10), "Installed"))["App"].Summary;
+
+        Assert.Equal("Succeeded", s.Status);
+        Assert.Equal("Installed", s.TerminalState);
+    }
+
+    [Fact]
+    public void SkippedEvent_SetsSkipped_ButNeverOverridesStrongerTerminal()
+    {
+        var fresh = Aggregate(AppEvent("app_install_skipped", T0))["App"].Summary;
+        Assert.Equal("Succeeded", fresh.Status);
+        Assert.Equal("Skipped", fresh.TerminalState);
+
+        var afterFailure = Aggregate(
+            AppEvent("app_install_failed", T0),
+            AppEvent("app_install_skipped", T0.AddSeconds(5)))["App"].Summary;
+        Assert.Equal("Error", afterFailure.TerminalState);
+    }
+
+    // ── store: cross-batch reconcile ────────────────────────────────────────
+
+    [Fact]
+    public void Reconcile_Q4_OutOfOrder_RecomputesDurationFromStoredCompletedAt()
+    {
+        // Terminal batch landed first: row has CompletedAt but no usable duration.
+        var existing = new TableEntity("tenant", "session_App")
+        {
+            ["Status"] = "Succeeded",
+            ["StartedAt"] = new DateTimeOffset(T0.AddMinutes(5)),   // late (completed-event) stamp
+            ["CompletedAt"] = new DateTimeOffset(T0.AddMinutes(5)),
+        };
+        // Started batch arrives now with the true (earlier) start.
+        var summary = new AppInstallSummary
+        {
+            AppName = "App", SessionId = "session", TenantId = "tenant",
+            Status = "InProgress", StartedAt = T0,
+        };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.Equal(T0, summary.StartedAt);                        // earlier start kept
+        Assert.Equal(T0.AddMinutes(5), summary.CompletedAt);        // endpoint adopted from the row
+        Assert.Equal(300, summary.DurationSeconds);                 // recomputed — was permanently unset before PR0
+        Assert.Equal("Succeeded", summary.Status);                  // sticky terminal (below)
+    }
+
+    [Fact]
+    public void Reconcile_TerminalStatusIsSticky_AgainstLateInProgressBatch()
+    {
+        var existing = new TableEntity("tenant", "session_App") { ["Status"] = "Failed" };
+        var summary = new AppInstallSummary { AppName = "App", Status = "InProgress", StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.Equal("Failed", summary.Status);
+    }
+
+    [Fact]
+    public void Reconcile_TerminalToTerminal_StaysWithIncomingEvidence()
+    {
+        // Failed row + succeeded batch (successful retry) → the new terminal wins.
+        var existing = new TableEntity("tenant", "session_App") { ["Status"] = "Failed" };
+        var summary = new AppInstallSummary { AppName = "App", Status = "Succeeded", StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.Equal("Succeeded", summary.Status);
+    }
+
+    [Fact]
+    public void Reconcile_Q4Guard_DoesNotFireWithoutStoredCompletedAt()
+    {
+        var existing = new TableEntity("tenant", "session_App") { ["Status"] = "InProgress" };
+        var summary = new AppInstallSummary { AppName = "App", Status = "InProgress", StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.Null(summary.CompletedAt);
+        Assert.Equal(0, summary.DurationSeconds);
+    }
+
+    [Fact]
+    public void Reconcile_Q4Guard_IgnoresStoredCompletedAtBeforeIncomingStart()
+    {
+        // Negative interval (clock mess) must not produce a negative duration.
+        var existing = new TableEntity("tenant", "session_App")
+        {
+            ["Status"] = "Succeeded",
+            ["CompletedAt"] = new DateTimeOffset(T0.AddMinutes(-10)),
+        };
+        var summary = new AppInstallSummary { AppName = "App", Status = "InProgress", StartedAt = T0 };
+
+        TableStorageService.ReconcileAppInstallSummaryWithExisting(summary, existing);
+
+        Assert.Null(summary.CompletedAt);
+        Assert.Equal(0, summary.DurationSeconds);
+    }
+
+    // ── entity builder: sentinel gating for the new column ─────────────────
+
+    [Fact]
+    public void EntityBuilder_TerminalState_IsSentinelGated()
+    {
+        var withState = new AppInstallSummary { AppName = "App", TerminalState = "Skipped" };
+        var entity = TableStorageService.BuildAppInstallSummaryEntity(withState, "rk");
+        Assert.Equal("Skipped", entity.GetString("TerminalState"));
+
+        var withoutState = new AppInstallSummary { AppName = "App" };
+        var empty = TableStorageService.BuildAppInstallSummaryEntity(withoutState, "rk");
+        // Column absent → Merge-mode preserves a prior batch's terminal state.
+        Assert.False(empty.ContainsKey("TerminalState"));
+    }
+}

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

@@ -162,6 +162,58 @@ public class AppsAnalyticsFailureRateTests
         Assert.Equal(50d, todayBucket.GetProperty("failureRate").GetDouble());
     }
 
+    // ── PR0 (2026-07-26): skip / unmeasured classification ──────────────────
+
+    [Fact]
+    public void List_Skips_LeaveRateAndDurations_AndAreReportedSeparately()
+    {
+        var skip = A("Succeeded");
+        skip.TerminalState = "Skipped";
+        skip.DurationSeconds = 0;
+        var unmeasured = A("Succeeded");
+        unmeasured.TerminalState = "Installed";
+        unmeasured.DurationSeconds = 0;
+
+        var summaries = new List<AppInstallSummary> { A("Failed"), A("Succeeded"), skip, unmeasured };
+
+        var root = JsonSerializer.SerializeToElement(
+            AppsAnalyticsHelper.BuildAppsListResponse(summaries, days: 30));
+        var app = root.GetProperty("apps")[0];
+
+        Assert.Equal(4, app.GetProperty("totalInstalls").GetInt32());
+        Assert.Equal(2, app.GetProperty("succeeded").GetInt32());          // real install + unmeasured
+        Assert.Equal(1, app.GetProperty("skipped").GetInt32());
+        Assert.Equal(1, app.GetProperty("unmeasured").GetInt32());
+        // 1 / (1 + 2) — the skip is not an attempt.
+        Assert.Equal(33.3d, app.GetProperty("failureRate").GetDouble());
+        // avg over the single measured row (30s) — the zero must not drag it to 15.
+        Assert.Equal(30d, app.GetProperty("avgDurationSeconds").GetDouble());
+    }
+
+    [Fact]
+    public async Task Analytics_Summary_CarriesSkippedAndUnmeasured_AndP95OverMeasuredOnly()
+    {
+        var skip = A("Succeeded");
+        skip.TerminalState = "Skipped";
+        skip.DurationSeconds = 0;
+        var unmeasured = A("Succeeded");
+        unmeasured.TerminalState = "Installed";
+        unmeasured.DurationSeconds = 0;
+        var measured = A("Succeeded");
+        measured.TerminalState = "Installed";
+        measured.DurationSeconds = 100;
+
+        var root = await BuildAnalyticsAsync(new List<AppInstallSummary> { skip, unmeasured, measured });
+        var summary = root.GetProperty("summary");
+
+        Assert.Equal(2, summary.GetProperty("succeeded").GetInt32());
+        Assert.Equal(1, summary.GetProperty("skipped").GetInt32());
+        Assert.Equal(1, summary.GetProperty("unmeasured").GetInt32());
+        Assert.Equal(100d, summary.GetProperty("avgDurationSeconds").GetDouble());
+        Assert.Equal(100, summary.GetProperty("p95DurationSeconds").GetInt32());
+        Assert.Equal(0d, summary.GetProperty("failureRate").GetDouble());
+    }
+
     [Fact]
     public async Task Analytics_DeviceModelBreakdown_RatesAndSampleFloor_UseFinishedInstalls()
     {

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

@@ -34,6 +34,14 @@ public class AppsProjectionEquivalenceTests
             ["AppType"] = "Win32",
             ["AppVersion"] = "2.1.0",
             ["Status"] = "Failed",
+            // PR0/PR1 classification columns. The fixture MUST populate every column a Build*
+            // method reads: a column absent here passes the equivalence assert trivially (both
+            // sides map to default) — exactly how the missing TerminalState projection slipped
+            // through and zeroed totalSkipped in production (2026-07-27).
+            ["TerminalState"] = "Skipped",
+            ["AppId"] = "9e8d7c6b-5a49-4832-9182-736451234567",
+            ["EspBlocking"] = true,
+            ["AppIdCollision"] = true,
             ["StartedAt"] = new DateTimeOffset(DateTime.UtcNow.AddHours(-6)),
             ["CompletedAt"] = new DateTimeOffset(DateTime.UtcNow.AddHours(-5)),
             ["DurationSeconds"] = 340,
@@ -83,6 +91,9 @@ public class AppsProjectionEquivalenceTests
 
         Assert.Equal(fromFull.AppName, fromProjected.AppName);
         Assert.Equal(fromFull.Status, fromProjected.Status);
+        // IsSkipTerminalState / skip classification input — see the fixture comment.
+        Assert.Equal(fromFull.TerminalState, fromProjected.TerminalState);
+        Assert.Equal(fromFull.AppIdCollision, fromProjected.AppIdCollision);
         Assert.Equal(fromFull.StartedAt, fromProjected.StartedAt);
         Assert.Equal(fromFull.DurationSeconds, fromProjected.DurationSeconds);
         Assert.Equal(fromFull.DownloadBytes, fromProjected.DownloadBytes);
@@ -122,6 +133,10 @@ public class AppsProjectionEquivalenceTests
         Assert.Equal(fromFull.FailureMessage, fromProjected.FailureMessage);
         Assert.Equal(fromFull.ExitCode, fromProjected.ExitCode);
         Assert.Equal(fromFull.DetectionResult, fromProjected.DetectionResult);
+        Assert.Equal(fromFull.TerminalState, fromProjected.TerminalState);
+        Assert.Equal(fromFull.AppId, fromProjected.AppId);
+        Assert.Equal(fromFull.EspBlocking, fromProjected.EspBlocking);
+        Assert.Equal(fromFull.AppIdCollision, fromProjected.AppIdCollision);
     }
 
     [Fact]

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

@@ -24,6 +24,7 @@ public class AuthFunctionSideEffectTests
     private readonly Mock<TelegramNotificationService> _telegramMock;
     private readonly Mock<GlobalNotificationService> _globalNotificationMock;
     private readonly Mock<IMetricsRepository> _metricsRepoMock;
+    private readonly Mock<AutopilotMonitor.Functions.Services.Activation.ITenantAutoApproveEnqueuer> _autoApproveEnqueuerMock;
     private readonly AuthFunction _sut;
 
     public AuthFunctionSideEffectTests()
@@ -44,7 +45,7 @@ public class AuthFunctionSideEffectTests
 
         var delegatedAdminMock = new Mock<DelegatedAdminService>(
             adminRepo,
-            new StubTenantEntitlementService(AutopilotMonitor.Functions.Security.TenantEdition.Enterprise),
+            new StubTenantEntitlementService(AutopilotMonitor.Functions.Security.TenantEdition.Pro),
             cache, Mock.Of<ILogger<DelegatedAdminService>>())
         { CallBase = false };
         delegatedAdminMock.Setup(x => x.GetScopeAsync(It.IsAny<string>(), It.IsAny<string?>()))
@@ -76,6 +77,7 @@ public class AuthFunctionSideEffectTests
         { CallBase = false };
 
         _metricsRepoMock = new Mock<IMetricsRepository>();
+        _autoApproveEnqueuerMock = new Mock<AutopilotMonitor.Functions.Services.Activation.ITenantAutoApproveEnqueuer>();
 
         _sut = new AuthFunction(
             Mock.Of<ILogger<AuthFunction>>(),
@@ -87,11 +89,15 @@ public class AuthFunctionSideEffectTests
             previewMock.Object,
             _telegramMock.Object,
             _globalNotificationMock.Object,
-            mcpUserMock.Object);
+            mcpUserMock.Object,
+            _autoApproveEnqueuerMock.Object,
+            new AutopilotMonitor.Functions.Security.EntraAppRegistry(
+                new Microsoft.Extensions.Configuration.ConfigurationBuilder().Build(),
+                Mock.Of<ILogger<AutopilotMonitor.Functions.Security.EntraAppRegistry>>()));
 
         // Default: all fire-and-forget calls succeed
         _tenantConfigMock
-            .Setup(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()))
+            .Setup(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()))
             .Returns(Task.CompletedTask);
         _telegramMock
             .Setup(x => x.SendNewTenantSignupAsync(It.IsAny<string>(), It.IsAny<string>()))
@@ -126,12 +132,89 @@ public class AuthFunctionSideEffectTests
         // OnboardedBy is the immutable copy of the first-login UPN that auto-promote on
         // preview approval reads — UpdatedBy may later be clobbered by background syncs.
         Assert.Equal(Upn, config.OnboardedBy);
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(config), Times.Once);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(config, It.IsAny<string?>(), It.IsAny<string?>()), Times.Once);
         _telegramMock.Verify(x => x.SendNewTenantSignupAsync(TenantId, Upn), Times.Once);
         _globalNotificationMock.Verify(x => x.CreateNotificationAsync(
-            "preview_signup", "New Preview Signup",
+            "preview_signup", "New Tenant Signup",
             It.Is<string>(m => m.Contains(TenantId) && m.Contains("contoso.com") && m.Contains(Upn)),
-            null), Times.Once);
+            $"/admin/tenants/management?tenantId={TenantId}"), Times.Once);
+        // Signup enqueues the delayed auto-approve unconditionally — the worker is the
+        // decision point (flag check at processing time).
+        _autoApproveEnqueuerMock.Verify(x => x.EnqueueAsync(
+            It.Is<AutopilotMonitor.Functions.Services.Activation.TenantAutoApproveEnvelope>(
+                e => e.TenantId == TenantId && e.SignupUpn == Upn),
+            AutopilotMonitor.Functions.Services.Activation.TenantAutoApproveEnvelope.ActivationDelay,
+            It.IsAny<CancellationToken>()), Times.Once);
+    }
+
+    // -------------------------------------------------------------------------
+    // HandleAuthClientIdTrackingAsync — the write must mutate a cache-BYPASSING
+    // read, never the (possibly stale) cached view. Regression for the prod
+    // incident 2026-07-31: the login right after an app-homing flip carries the
+    // changed audience; blind-saving the stale cached entity reverted the flip.
+    // -------------------------------------------------------------------------
+
+    private const string LegacyAppId = "1a400946-62c1-4ab4-aa37-f730ac89704d";
+    private const string PrimaryAppId = "886ab5e2-6144-442c-80cc-9b28e0667731";
+
+    [Fact]
+    public async Task HandleAuthClientIdTracking_MutatesFreshConfig_PreservingConcurrentHomingFlip()
+    {
+        // Cached view: pre-flip (homing null, last-seen legacy). Fresh row: flipped meanwhile.
+        var cached = DefaultConfig();
+        cached.DomainName = "contoso.com";
+        cached.LastAuthClientId = LegacyAppId;
+        cached.HomedAppClientId = null;
+
+        var fresh = DefaultConfig();
+        fresh.DomainName = "contoso.com";
+        fresh.LastAuthClientId = LegacyAppId;
+        fresh.HomedAppClientId = PrimaryAppId; // the concurrent flip that must survive
+
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId)).ReturnsAsync(fresh);
+
+        await _sut.HandleAuthClientIdTrackingAsync(cached, TenantId, $"api://{PrimaryAppId}");
+
+        // The FRESH entity was mutated and saved — the flip survives, the stale view is discarded.
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(fresh, It.IsAny<string?>(), It.IsAny<string?>()), Times.Once);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(cached, It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+        Assert.Equal(PrimaryAppId, fresh.HomedAppClientId);
+        Assert.Equal(PrimaryAppId, fresh.LastAuthClientId);
+        Assert.NotNull(fresh.LastAuthClientIdSince);
+    }
+
+    [Fact]
+    public async Task HandleAuthClientIdTracking_FreshAlreadyCurrent_DoesNotWrite()
+    {
+        // Another instance already recorded the new client id — the fresh re-check must
+        // suppress the redundant write even though the cached view still looks outdated.
+        var cached = DefaultConfig();
+        cached.DomainName = "contoso.com";
+        cached.LastAuthClientId = LegacyAppId;
+
+        var fresh = DefaultConfig();
+        fresh.DomainName = "contoso.com";
+        fresh.LastAuthClientId = PrimaryAppId;
+
+        _tenantConfigMock.Setup(x => x.GetConfigurationFreshAsync(TenantId)).ReturnsAsync(fresh);
+
+        await _sut.HandleAuthClientIdTrackingAsync(cached, TenantId, PrimaryAppId);
+
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task HandleAuthClientIdTracking_UnchangedOnCachedView_SkipsFreshRead()
+    {
+        // Steady state (same app as last time) must stay a zero-I/O no-op.
+        var cached = DefaultConfig();
+        cached.DomainName = "contoso.com";
+        cached.LastAuthClientId = PrimaryAppId;
+
+        await _sut.HandleAuthClientIdTrackingAsync(cached, TenantId, $"api://{PrimaryAppId}");
+
+        _tenantConfigMock.Verify(x => x.GetConfigurationFreshAsync(It.IsAny<string>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     [Fact]
@@ -156,7 +239,7 @@ public class AuthFunctionSideEffectTests
 
         await _sut.HandleNewTenantDomainAsync(config, TenantId, Upn);
 
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
         _telegramMock.Verify(x => x.SendNewTenantSignupAsync(It.IsAny<string>(), It.IsAny<string>()), Times.Never);
     }
 
@@ -168,7 +251,7 @@ public class AuthFunctionSideEffectTests
 
         await _sut.HandleNewTenantDomainAsync(config, TenantId, "");
 
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     [Fact]
@@ -179,7 +262,7 @@ public class AuthFunctionSideEffectTests
 
         await _sut.HandleNewTenantDomainAsync(config, TenantId, "nodomain");
 
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     [Fact]
@@ -196,7 +279,7 @@ public class AuthFunctionSideEffectTests
         await _sut.HandleNewTenantDomainAsync(config, TenantId, Upn);
 
         // SaveConfig should still have been called before the fire-and-forget
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(config), Times.Once);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(config, It.IsAny<string?>(), It.IsAny<string?>()), Times.Once);
     }
 
     // -------------------------------------------------------------------------
@@ -217,7 +300,7 @@ public class AuthFunctionSideEffectTests
         Assert.Null(config.DisabledReason);
         Assert.Null(config.DisabledUntil);
         Assert.Equal("System (auto-re-enable)", config.UpdatedBy);
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(config), Times.Once);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(config, It.IsAny<string?>(), It.IsAny<string?>()), Times.Once);
     }
 
     [Fact]
@@ -230,7 +313,7 @@ public class AuthFunctionSideEffectTests
         await _sut.HandleAutoReEnableAsync(config, TenantId);
 
         Assert.True(config.Disabled);
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     [Fact]
@@ -241,7 +324,7 @@ public class AuthFunctionSideEffectTests
 
         await _sut.HandleAutoReEnableAsync(config, TenantId);
 
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     [Fact]
@@ -254,7 +337,7 @@ public class AuthFunctionSideEffectTests
         await _sut.HandleAutoReEnableAsync(config, TenantId);
 
         Assert.True(config.Disabled);
-        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>()), Times.Never);
+        _tenantConfigMock.Verify(x => x.SaveConfigurationAsync(It.IsAny<TenantConfiguration>(), It.IsAny<string?>(), It.IsAny<string?>()), Times.Never);
     }
 
     // -------------------------------------------------------------------------

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

@@ -223,11 +223,11 @@ public class AuthFunctionTests
     }
 
     // -------------------------------------------------------------------------
-    // Gate 2: Preview Gate
+    // Gate 2: Activation Gate
     // -------------------------------------------------------------------------
 
     [Fact]
-    public void PreviewGate_NotApproved_Returns403PrivatePreview()
+    public void PreviewGate_NotApproved_Returns403PendingActivation()
     {
         var result = AuthFunction.BuildAuthResult(
             DefaultConfig(), isGlobalAdmin: false, isGlobalReader: false, isPreviewApproved: false,
@@ -238,7 +238,7 @@ public class AuthFunctionTests
         Assert.False(result.IsSuccess);
         Assert.Equal(HttpStatusCode.Forbidden, result.StatusCode);
         var body = ToDynamic(result.Body);
-        Assert.Equal("PrivatePreview", (string)body.error);
+        Assert.Equal("PendingActivation", (string)body.error);
     }
 
     [Fact]

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

@@ -203,6 +203,38 @@ public class AuthenticationMiddlewareTokenValidationTests
             Mint(RsaCreds, audience: "api://some-third-app"), ClientId, SecondaryClientId));
     }
 
+    // ── Dual app-reg window (C4A8 move): primary=new app, legacy=old app via LegacyClientId ──
+    // The middleware folds EntraId:LegacyClientId into the additional-id set via
+    // CombineAdditionalClientIdSources, so both apps' tokens validate in bare AND api:// form.
+
+    private const string NewAppId = "886ab5e2-6144-442c-80cc-9b28e0667731";
+    private const string OldAppId = "1a400946-62c1-4ab4-aa37-f730ac89704d";
+
+    [Theory]
+    [InlineData(NewAppId)]
+    [InlineData("api://" + NewAppId)]
+    [InlineData(OldAppId)]
+    [InlineData("api://" + OldAppId)]
+    public void DualAppWindow_accepts_both_apps_tokens_in_both_audience_forms(string audience)
+    {
+        var clientIds = AuthenticationMiddleware.ResolveConfiguredClientIds(
+            NewAppId,
+            AuthenticationMiddleware.CombineAdditionalClientIdSources(OldAppId, null),
+            out _);
+
+        Assert.NotNull(ValidateWith(Mint(RsaCreds, audience: audience), clientIds));
+    }
+
+    [Fact]
+    public void CombineAdditionalClientIdSources_joins_and_skips_empty_sources()
+    {
+        Assert.Equal($"{OldAppId},{SecondaryClientId}",
+            AuthenticationMiddleware.CombineAdditionalClientIdSources(OldAppId, SecondaryClientId));
+        Assert.Equal(OldAppId,
+            AuthenticationMiddleware.CombineAdditionalClientIdSources($"  {OldAppId} ", null, ""));
+        Assert.Null(AuthenticationMiddleware.CombineAdditionalClientIdSources(null, "", "   "));
+    }
+
     // ── BuildValidAudiences: id → {id, api://id}, deduped, empties dropped ────────────────
 
     [Fact]

src/Backend/AutopilotMonitor.Functions.Tests/AutopilotMonitor.Functions.Tests.csproj

@@ -30,6 +30,9 @@
     <None Update="device-cert-sample.pem">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>
+    <None Update="TestData\oobe-bootstrap-golden.ps1">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
   </ItemGroup>
 
 </Project>

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

@@ -0,0 +1,172 @@
+using AutopilotMonitor.Functions.Functions.Infrastructure;
+using AutopilotMonitor.Shared.DataAccess;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Pins the pure helpers of <see cref="AzureMonitorAlertWebhookFunction"/> — the anonymous,
+/// secret-gated bridge that turns Azure Monitor Common Alert Schema notifications into ops
+/// events. Load-bearing bits: the secret gate is fail-closed (an unset app setting rejects
+/// everything), severity mapping can never escalate on schema drift (unknown → Info), and
+/// parsing is defensive (only the alert rule name is mandatory).
+/// </summary>
+public class AzureMonitorAlertWebhookFunctionTests
+{
+    // ── SecretMatches ──────────────────────────────────────────────────────
+
+    [Fact]
+    public void SecretMatches_accepts_equal_secrets()
+    {
+        Assert.True(AzureMonitorAlertWebhookFunction.SecretMatches("s3cret-value", "s3cret-value"));
+    }
+
+    [Theory]
+    [InlineData("wrong", "right")]
+    [InlineData("right-but-longer", "right")]
+    [InlineData("", "configured")]
+    [InlineData(null, "configured")]
+    public void SecretMatches_rejects_mismatch_or_missing_provided(string? provided, string configured)
+    {
+        Assert.False(AzureMonitorAlertWebhookFunction.SecretMatches(provided, configured));
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    public void SecretMatches_fails_closed_when_not_configured(string? configured)
+    {
+        // While the app setting is unset, NOTHING matches — not even an empty provided value.
+        Assert.False(AzureMonitorAlertWebhookFunction.SecretMatches("anything", configured));
+        Assert.False(AzureMonitorAlertWebhookFunction.SecretMatches("", configured));
+        Assert.False(AzureMonitorAlertWebhookFunction.SecretMatches(null, configured));
+    }
+
+    // ── MapSeverity ────────────────────────────────────────────────────────
+
+    [Theory]
+    [InlineData("Sev0", OpsEventSeverity.Critical)]
+    [InlineData("Sev1", OpsEventSeverity.Error)]
+    [InlineData("Sev2", OpsEventSeverity.Warning)]
+    [InlineData("Sev3", OpsEventSeverity.Info)]
+    [InlineData("Sev4", OpsEventSeverity.Info)]
+    public void MapSeverity_maps_azure_scale_to_ops_scale(string azure, string expected)
+    {
+        Assert.Equal(expected, AzureMonitorAlertWebhookFunction.MapSeverity(azure));
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("Sev5")]
+    [InlineData("Critical")] // someone posting the ops scale directly must not pass through
+    public void MapSeverity_falls_back_to_info_on_unknown_values(string? azure)
+    {
+        Assert.Equal(OpsEventSeverity.Info, AzureMonitorAlertWebhookFunction.MapSeverity(azure));
+    }
+
+    // ── TryParse ───────────────────────────────────────────────────────────
+
+    private const string FullPayload = """
+        {
+          "schemaId": "azureMonitorCommonAlertSchema",
+          "data": {
+            "essentials": {
+              "alertId": "/subscriptions/xxx/providers/Microsoft.AlertsManagement/alerts/abc",
+              "alertRule": "Portal RSC prefetch tail",
+              "severity": "Sev2",
+              "signalType": "Log",
+              "monitorCondition": "Fired",
+              "monitoringService": "Log Alerts V2",
+              "alertTargetIDs": [
+                "/subscriptions/xxx/resourcegroups/rg-autopilotmonitor-prd-gwc/providers/microsoft.insights/components/autopilotmonitorweb"
+              ],
+              "description": "RSC prefetches exceeding 10s",
+              "firedDateTime": "2026-07-27T15:30:00.000Z"
+            },
+            "alertContext": {
+              "condition": {
+                "windowSize": "PT1H",
+                "allOf": [
+                  {
+                    "searchQuery": "dependencies | where name contains '_rsc='",
+                    "metricValue": 18.0,
+                    "operator": "GreaterThan",
+                    "threshold": "0"
+                  }
+                ]
+              }
+            }
+          }
+        }
+        """;
+
+    [Fact]
+    public void TryParse_extracts_essentials_and_metric_value()
+    {
+        var alert = AzureMonitorAlertWebhookFunction.TryParse(FullPayload);
+
+        Assert.NotNull(alert);
+        Assert.Equal("Portal RSC prefetch tail", alert!.AlertRule);
+        Assert.Equal("Sev2", alert.Severity);
+        Assert.Equal("Fired", alert.MonitorCondition);
+        Assert.Equal("RSC prefetches exceeding 10s", alert.Description);
+        Assert.Equal("Log Alerts V2", alert.MonitoringService);
+        // No targetResourceName in the payload → resource name segment of the first target ID.
+        Assert.Equal("autopilotmonitorweb", alert.TargetResource);
+        Assert.Equal(18.0, alert.MetricValue);
+    }
+
+    [Fact]
+    public void TryParse_prefers_explicit_target_resource_name()
+    {
+        const string payload = """
+            {"data":{"essentials":{"alertRule":"r","targetResourceName":"explicit-name",
+            "alertTargetIDs":["/sub/x/other-name"]}}}
+            """;
+        var alert = AzureMonitorAlertWebhookFunction.TryParse(payload);
+        Assert.Equal("explicit-name", alert!.TargetResource);
+    }
+
+    [Fact]
+    public void TryParse_minimal_payload_needs_only_the_alert_rule()
+    {
+        var alert = AzureMonitorAlertWebhookFunction.TryParse(
+            """{"data":{"essentials":{"alertRule":"minimal"}}}""");
+
+        Assert.NotNull(alert);
+        Assert.Equal("minimal", alert!.AlertRule);
+        Assert.Null(alert.Severity);
+        Assert.Equal("Fired", alert.MonitorCondition); // default when absent
+        Assert.Null(alert.Description);
+        Assert.Null(alert.MetricValue);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData("not json at all")]
+    [InlineData("{}")]                                          // no data
+    [InlineData("""{"data":{}}""")]                             // no essentials
+    [InlineData("""{"data":{"essentials":{}}}""")]              // no alertRule
+    [InlineData("""{"data":{"essentials":{"alertRule":""}}}""")] // empty alertRule
+    [InlineData("""{"data":{"essentials":{"alertRule":123}}}""")] // wrong type
+    public void TryParse_rejects_unusable_payloads(string? body)
+    {
+        Assert.Null(AzureMonitorAlertWebhookFunction.TryParse(body!));
+    }
+
+    [Fact]
+    public void TryParse_tolerates_malformed_alert_context()
+    {
+        // alertContext with unexpected shapes must not break essentials extraction.
+        const string payload = """
+            {"data":{"essentials":{"alertRule":"r","severity":"Sev0"},
+            "alertContext":{"condition":{"allOf":"not-an-array"}}}}
+            """;
+        var alert = AzureMonitorAlertWebhookFunction.TryParse(payload);
+        Assert.NotNull(alert);
+        Assert.Equal("Sev0", alert!.Severity);
+        Assert.Null(alert.MetricValue);
+    }
+}

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

@@ -0,0 +1,120 @@
+using AutopilotMonitor.Functions.Security;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Pins the injection-defense invariants of <see cref="BootstrapScriptValueValidator"/>,
+/// ported from the portal's utils/bootstrapValidation.ts (and its vitest suite). The
+/// validated values are interpolated into a PowerShell script that runs as SYSTEM
+/// during OOBE — any relaxation here widens the injection surface.
+/// </summary>
+public class BootstrapScriptValueValidatorTests
+{
+    private const string GoodTenant = "11111111-1111-1111-1111-111111111111";
+    private const string GoodToken = "22222222-2222-2222-2222-222222222222";
+    private const string GoodUrl = "https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip";
+
+    private static DateTime FutureExpiry => DateTime.UtcNow.AddHours(24);
+
+    private static bool Validate(
+        string tenantId = GoodTenant,
+        string token = GoodToken,
+        string url = GoodUrl,
+        DateTime? expiresAt = null,
+        BootstrapScriptValueValidator.ValidationFailure? expectedFailure = null)
+    {
+        var ok = BootstrapScriptValueValidator.TryValidate(
+            tenantId, token, url, expiresAt ?? FutureExpiry, out _, out var failure);
+        if (!ok && expectedFailure.HasValue)
+            Assert.Equal(expectedFailure.Value, failure);
+        return ok;
+    }
+
+    [Fact]
+    public void Accepts_valid_values()
+    {
+        Assert.True(Validate());
+    }
+
+    // ── tenantId / token: exact canonical GUIDs only ──
+    [Theory]
+    [InlineData("")]
+    [InlineData("not-a-guid")]
+    [InlineData("11111111111111111111111111111111")]                  // "N" format — no hyphens
+    [InlineData("{11111111-1111-1111-1111-111111111111}")]            // "B" format
+    [InlineData(" 11111111-1111-1111-1111-111111111111")]             // leading space (TryParseExact would trim)
+    [InlineData("11111111-1111-1111-1111-11111111111$")]
+    public void Rejects_non_canonical_tenant_ids(string tenantId)
+    {
+        Assert.False(Validate(tenantId: tenantId,
+            expectedFailure: BootstrapScriptValueValidator.ValidationFailure.TenantId));
+    }
+
+    [Fact]
+    public void Rejects_non_guid_token()
+    {
+        Assert.False(Validate(token: "'; $(calc); '",
+            expectedFailure: BootstrapScriptValueValidator.ValidationFailure.Token));
+    }
+
+    // ── agentDownloadUrl: https + host allow-list + strict path ──
+    [Theory]
+    [InlineData("https://evil.example.com/x.zip'; $(calc); '")]        // hostile payload from the vitest suite
+    [InlineData("https://evil.example.com/agent/AutopilotMonitor-Agent.zip")]
+    [InlineData("http://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip")]   // not https
+    [InlineData("https://download.autopilotmonitor.com:8443/agent/AutopilotMonitor-Agent.zip")] // explicit port
+    [InlineData("https://user:pw@download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip")] // userinfo
+    [InlineData("https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip?x=1")]  // query
+    [InlineData("https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip#f")]    // fragment
+    [InlineData("https://download.autopilotmonitor.com/other/AutopilotMonitor-Agent.zip")]      // wrong prefix
+    [InlineData("https://download.autopilotmonitor.com/agent/.hidden.zip")]                     // leading dot
+    [InlineData("https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.exe")]      // not .zip
+    [InlineData("")]
+    public void Rejects_disallowed_download_urls(string url)
+    {
+        Assert.False(Validate(url: url,
+            expectedFailure: BootstrapScriptValueValidator.ValidationFailure.AgentDownloadUrl));
+    }
+
+    [Theory]
+    [InlineData("https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent.zip")]
+    [InlineData("https://autopilotmonitor.blob.core.windows.net/agent/AutopilotMonitor-Agent.zip")] // legacy blob host
+    [InlineData("https://download.autopilotmonitor.com/agent/AutopilotMonitor-Agent-v2.zip")]
+    public void Accepts_allowlisted_download_urls(string url)
+    {
+        Assert.True(Validate(url: url));
+    }
+
+    [Fact]
+    public void Rejects_filename_longer_than_80_chars()
+    {
+        // First char + 80 more before ".zip" exceeds the {0,79} tail bound.
+        var tooLong = "https://download.autopilotmonitor.com/agent/a" + new string('b', 80) + ".zip";
+        Assert.False(Validate(url: tooLong,
+            expectedFailure: BootstrapScriptValueValidator.ValidationFailure.AgentDownloadUrl));
+
+        var atLimit = "https://download.autopilotmonitor.com/agent/a" + new string('b', 75) + ".zip";
+        Assert.True(Validate(url: atLimit));
+    }
+
+    // ── expiresAt: strictly future, at most 14 days out ──
+    [Fact]
+    public void Rejects_past_expiry()
+    {
+        Assert.False(Validate(expiresAt: DateTime.UtcNow.AddMinutes(-1),
+            expectedFailure: BootstrapScriptValueValidator.ValidationFailure.ExpiresAt));
+    }
+
+    [Fact]
+    public void Rejects_expiry_beyond_14_days()
+    {
+        Assert.False(Validate(expiresAt: DateTime.UtcNow.AddDays(15),
+            expectedFailure: BootstrapScriptValueValidator.ValidationFailure.ExpiresAt));
+    }
+
+    [Fact]
+    public void Accepts_expiry_within_the_window()
+    {
+        Assert.True(Validate(expiresAt: DateTime.UtcNow.AddDays(7)));
+    }
+}

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

@@ -0,0 +1,244 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using AutopilotMonitor.Functions.DataAccess.TableStorage;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared;
+using AutopilotMonitor.Shared.DataAccess;
+using AutopilotMonitor.Shared.Models;
+using Azure;
+using Azure.Data.Tables;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// The universal pre-write snapshot hook in <see cref="TableConfigRepository"/>:
+/// every overwriting save of a TenantConfiguration/AdminConfiguration row must first
+/// snapshot the stored row into ConfigurationBackups — except row creations and
+/// noise-only changes — and a backup-storage failure must never break the save (fail-soft).
+/// </summary>
+public class ConfigBackupHookTests
+{
+    private const string TenantId = "11111111-1111-1111-1111-111111111111";
+
+    private sealed class Harness
+    {
+        public TableConfigRepository Sut { get; }
+        public Mock<TableClient> Table { get; } = new();
+        public Mock<IConfigBackupRepository> Backup { get; } = new();
+        public List<TableEntity> Upserts { get; } = new();
+
+        public Harness(TableEntity? stored)
+        {
+            if (stored == null)
+            {
+                Table.Setup(c => c.GetEntityAsync<TableEntity>(
+                        It.IsAny<string>(), It.IsAny<string>(),
+                        It.IsAny<IEnumerable<string>>(), It.IsAny<CancellationToken>()))
+                    .ThrowsAsync(new RequestFailedException(404, "Not Found", "ResourceNotFound", null));
+            }
+            else
+            {
+                Table.Setup(c => c.GetEntityAsync<TableEntity>(
+                        It.IsAny<string>(), It.IsAny<string>(),
+                        It.IsAny<IEnumerable<string>>(), It.IsAny<CancellationToken>()))
+                    .ReturnsAsync(Response.FromValue(stored, Mock.Of<Response>()));
+            }
+
+            Table.Setup(c => c.UpsertEntityAsync(
+                    It.IsAny<TableEntity>(), It.IsAny<TableUpdateMode>(), It.IsAny<CancellationToken>()))
+                .Returns<TableEntity, TableUpdateMode, CancellationToken>((e, _, _) =>
+                {
+                    Upserts.Add(e);
+                    return Task.FromResult(Mock.Of<Response>());
+                });
+
+            var serviceClient = new Mock<TableServiceClient>();
+            serviceClient.Setup(c => c.GetTableClient(It.IsAny<string>())).Returns(Table.Object);
+
+            Sut = new TableConfigRepository(
+                new TableStorageService(serviceClient.Object, NullLogger<TableStorageService>.Instance),
+                Backup.Object,
+                NullLogger<TableConfigRepository>.Instance);
+        }
+    }
+
+    private static TenantConfiguration StoredConfig()
+    {
+        var config = TenantConfiguration.CreateDefault(TenantId);
+        config.DomainName = "contoso.com";
+        config.UpdatedBy = "admin@contoso.com";
+        config.DataRetentionDays = 30;
+        config.TeamsWebhookUrl = "https://contoso.webhook.office.com/hook";
+        return config;
+    }
+
+    /// <summary>
+    /// Mirrors production: every real writer round-trips the STORED row (read-modify-write),
+    /// so time-stamped fields like OnboardedAt match the stored values exactly. Constructing
+    /// a second CreateDefault instead would fabricate an OnboardedAt diff that cannot occur.
+    /// </summary>
+    private static TenantConfiguration RoundtripClone(TenantConfiguration stored)
+        => TableConfigRepository.ConvertFromTenantTableEntity(
+            TableConfigRepository.ConvertToTenantTableEntity(stored));
+
+    [Fact]
+    public async Task RealChange_SnapshotsStoredRow_ThenSaves_ThenPrunes()
+    {
+        var stored = StoredConfig();
+        var harness = new Harness(TableConfigRepository.ConvertToTenantTableEntity(stored));
+
+        var incoming = RoundtripClone(stored);
+        incoming.DataRetentionDays = 90;
+        incoming.UpdatedBy = "ga@operator.example";
+
+        ConfigBackupEntry? snapshot = null;
+        harness.Backup
+            .Setup(b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()))
+            .Callback<ConfigBackupEntry, CancellationToken>((e, _) => snapshot = e)
+            .Returns(Task.CompletedTask);
+
+        var saved = await harness.Sut.SaveTenantConfigurationAsync(incoming, "portal-put", "test change");
+
+        Assert.True(saved);
+        Assert.Single(harness.Upserts); // the config row itself
+        Assert.NotNull(snapshot);
+        Assert.Equal(TenantId, snapshot!.PartitionKey);
+        Assert.Equal("portal-put", snapshot.Source);
+        Assert.Equal("test change", snapshot.Reason);
+        Assert.Equal("ga@operator.example", snapshot.ChangedBy); // identity about to write
+        // The snapshot holds the STORED row (retention 30), not the incoming one.
+        Assert.Contains("\"DataRetentionDays\":30", snapshot.EntityJson);
+        // Raw secrets ARE in EntityJson (full-fidelity restore source)…
+        Assert.Contains("contoso.webhook.office.com", snapshot.EntityJson);
+        // …but the advisory diff masks them by property-name heuristics (ConfigDiffHelper).
+        Assert.DoesNotContain("contoso.webhook.office.com", snapshot.DiffJson ?? string.Empty);
+        harness.Backup.Verify(
+            b => b.PruneAsync(TenantId, Constants.ConfigBackupKeepCount, It.IsAny<CancellationToken>()),
+            Times.Once);
+    }
+
+    [Fact]
+    public async Task RowCreation_NoExistingRow_NoSnapshot()
+    {
+        var harness = new Harness(stored: null);
+
+        var saved = await harness.Sut.SaveTenantConfigurationAsync(StoredConfig(), "portal-put", null);
+
+        Assert.True(saved);
+        Assert.Single(harness.Upserts);
+        harness.Backup.Verify(
+            b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()), Times.Never);
+        harness.Backup.Verify(
+            b => b.PruneAsync(It.IsAny<string>(), It.IsAny<int>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task NoiseOnlyChange_AuthClientIdFlip_NoSnapshot()
+    {
+        var stored = StoredConfig();
+        var harness = new Harness(TableConfigRepository.ConvertToTenantTableEntity(stored));
+
+        // The auth-side-effect write: only LastAuthClientId/Since + bookkeeping move.
+        var incoming = RoundtripClone(stored);
+        incoming.LastAuthClientId = "886ab5e2-6144-442c-80cc-9b28e0667731";
+        incoming.LastAuthClientIdSince = DateTime.UtcNow;
+        incoming.LastUpdated = DateTime.UtcNow;
+        incoming.UpdatedBy = "System (auth)";
+
+        var saved = await harness.Sut.SaveTenantConfigurationAsync(incoming, "auth", null);
+
+        Assert.True(saved); // the save itself still goes through
+        Assert.Single(harness.Upserts);
+        harness.Backup.Verify(
+            b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task NoOpSave_IdenticalContent_NoSnapshot()
+    {
+        var stored = StoredConfig();
+        var harness = new Harness(TableConfigRepository.ConvertToTenantTableEntity(stored));
+
+        var saved = await harness.Sut.SaveTenantConfigurationAsync(RoundtripClone(stored), "portal-put", null);
+
+        Assert.True(saved);
+        harness.Backup.Verify(
+            b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task BackupStorageFailure_IsFailSoft_SaveStillSucceeds()
+    {
+        var stored = StoredConfig();
+        var harness = new Harness(TableConfigRepository.ConvertToTenantTableEntity(stored));
+        harness.Backup
+            .Setup(b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()))
+            .ThrowsAsync(new RequestFailedException(503, "backup table throttled"));
+
+        var incoming = RoundtripClone(stored);
+        incoming.DataRetentionDays = 90;
+
+        var saved = await harness.Sut.SaveTenantConfigurationAsync(incoming, "portal-put", null);
+
+        Assert.True(saved);
+        Assert.Single(harness.Upserts); // the config write went through regardless
+    }
+
+    [Fact]
+    public async Task LegacyOneArgOverload_StillSnapshots_WithUnknownSource()
+    {
+        var stored = StoredConfig();
+        var harness = new Harness(TableConfigRepository.ConvertToTenantTableEntity(stored));
+
+        ConfigBackupEntry? snapshot = null;
+        harness.Backup
+            .Setup(b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()))
+            .Callback<ConfigBackupEntry, CancellationToken>((e, _) => snapshot = e)
+            .Returns(Task.CompletedTask);
+
+        var incoming = RoundtripClone(stored);
+        incoming.DataRetentionDays = 90;
+        await harness.Sut.SaveTenantConfigurationAsync(incoming);
+
+        Assert.NotNull(snapshot);
+        Assert.Equal("unknown", snapshot!.Source);
+    }
+
+    [Fact]
+    public async Task AdminConfigSave_SnapshotsUnderGlobalConfigPartition()
+    {
+        var stored = new AdminConfiguration
+        {
+            UpdatedBy = "ga@operator.example",
+            GlobalRateLimitRequestsPerMinute = 100,
+        };
+        var harness = new Harness(TableConfigRepository.ConvertToAdminTableEntity(stored));
+
+        ConfigBackupEntry? snapshot = null;
+        harness.Backup
+            .Setup(b => b.UpsertAsync(It.IsAny<ConfigBackupEntry>(), It.IsAny<CancellationToken>()))
+            .Callback<ConfigBackupEntry, CancellationToken>((e, _) => snapshot = e)
+            .Returns(Task.CompletedTask);
+
+        var incoming = new AdminConfiguration
+        {
+            UpdatedBy = "ga@operator.example",
+            GlobalRateLimitRequestsPerMinute = 200,
+        };
+
+        var saved = await harness.Sut.SaveAdminConfigurationAsync(incoming);
+
+        Assert.True(saved);
+        Assert.NotNull(snapshot);
+        Assert.Equal("GlobalConfig", snapshot!.PartitionKey);
+        Assert.Equal("admin-config", snapshot.Source);
+        harness.Backup.Verify(
+            b => b.PruneAsync("GlobalConfig", Constants.ConfigBackupKeepCount, It.IsAny<CancellationToken>()),
+            Times.Once);
+    }
+}

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

@@ -0,0 +1,172 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using AutopilotMonitor.Functions.DataAccess.TableStorage;
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.Models;
+using Azure;
+using Azure.Data.Tables;
+using Microsoft.Extensions.Logging.Abstractions;
+using Moq;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// TableConfigBackupRepository: Store↔Map roundtrip (project rule "table-serialization"),
+/// reverse-ticks RowKey ordering (newest-first), and prune-beyond-keep semantics.
+/// </summary>
+public class ConfigBackupRepositoryTests
+{
+    private const string TenantId = "11111111-1111-1111-1111-111111111111";
+
+    private sealed class Harness
+    {
+        public TableConfigBackupRepository Sut { get; }
+        public Mock<TableClient> Table { get; } = new();
+        public List<TableEntity> Upserts { get; } = new();
+        public List<(string Pk, string Rk)> Deletes { get; } = new();
+
+        public Harness()
+        {
+            Table.Setup(c => c.UpsertEntityAsync(
+                    It.IsAny<TableEntity>(), It.IsAny<TableUpdateMode>(), It.IsAny<CancellationToken>()))
+                .Returns<TableEntity, TableUpdateMode, CancellationToken>((e, _, _) =>
+                {
+                    Upserts.Add(e);
+                    return Task.FromResult(Mock.Of<Response>());
+                });
+            Table.Setup(c => c.DeleteEntityAsync(
+                    It.IsAny<string>(), It.IsAny<string>(), It.IsAny<ETag>(), It.IsAny<CancellationToken>()))
+                .Returns<string, string, ETag, CancellationToken>((pk, rk, _, _) =>
+                {
+                    Deletes.Add((pk, rk));
+                    return Task.FromResult(Mock.Of<Response>());
+                });
+
+            var serviceClient = new Mock<TableServiceClient>();
+            serviceClient.Setup(c => c.GetTableClient(It.IsAny<string>())).Returns(Table.Object);
+            Sut = new TableConfigBackupRepository(
+                new TableStorageService(serviceClient.Object, NullLogger<TableStorageService>.Instance),
+                NullLogger<TableConfigBackupRepository>.Instance);
+        }
+
+        public void SetupQuery(params TableEntity[] rows)
+        {
+            var page = Page<TableEntity>.FromValues(rows, continuationToken: null, Mock.Of<Response>());
+            Table.Setup(c => c.QueryAsync<TableEntity>(
+                    It.IsAny<string>(), It.IsAny<int?>(), It.IsAny<IEnumerable<string>>(), It.IsAny<CancellationToken>()))
+                .Returns(AsyncPageable<TableEntity>.FromPages(new[] { page }));
+        }
+    }
+
+    private static ConfigBackupEntry Entry(string rowKey = "0001_abc") => new()
+    {
+        PartitionKey = TenantId,
+        RowKey = rowKey,
+        TenantId = TenantId,
+        EntityJson = "{\"DomainName\":\"contoso.com\"}",
+        ChangedBy = "ga@operator.example",
+        Source = "mcp-patch",
+        Reason = "retention bump",
+        DiffJson = "{\"DataRetentionDays\":\"30 \\u2192 90\"}",
+        BackupTakenAt = new DateTime(2026, 8, 3, 12, 0, 0, DateTimeKind.Utc),
+    };
+
+    [Fact]
+    public async Task Roundtrip_StoreAndMap_PreservesEveryField()
+    {
+        var harness = new Harness();
+        var entry = Entry();
+
+        await harness.Sut.UpsertAsync(entry);
+        var stored = Assert.Single(harness.Upserts);
+
+        // Feed the stored entity back through the read path (TryGetAsync → Map).
+        harness.Table.Setup(c => c.GetEntityAsync<TableEntity>(
+                It.IsAny<string>(), It.IsAny<string>(),
+                It.IsAny<IEnumerable<string>>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(Response.FromValue(stored, Mock.Of<Response>()));
+        var mapped = await harness.Sut.TryGetAsync(TenantId, entry.RowKey);
+
+        Assert.NotNull(mapped);
+        Assert.Equal(entry.PartitionKey, mapped!.PartitionKey);
+        Assert.Equal(entry.RowKey, mapped.RowKey);
+        Assert.Equal(entry.TenantId, mapped.TenantId);
+        Assert.Equal(entry.EntityJson, mapped.EntityJson);
+        Assert.Equal(entry.ChangedBy, mapped.ChangedBy);
+        Assert.Equal(entry.Source, mapped.Source);
+        Assert.Equal(entry.Reason, mapped.Reason);
+        Assert.Equal(entry.DiffJson, mapped.DiffJson);
+        Assert.Equal(entry.BackupTakenAt, mapped.BackupTakenAt);
+    }
+
+    [Fact]
+    public void BuildRowKey_LaterTimestamps_SortFirst()
+    {
+        var earlier = TableConfigBackupRepository.BuildRowKey(new DateTime(2026, 8, 3, 12, 0, 0, DateTimeKind.Utc));
+        var later = TableConfigBackupRepository.BuildRowKey(new DateTime(2026, 8, 3, 12, 0, 1, DateTimeKind.Utc));
+
+        // Reverse ticks: the LATER backup gets the LEXICOGRAPHICALLY SMALLER RowKey, so
+        // Azure's RowKey-ascending partition scan returns newest-first.
+        Assert.True(string.CompareOrdinal(later, earlier) < 0);
+    }
+
+    [Fact]
+    public void BuildRowKey_SameTick_DistinctViaGuidSuffix()
+    {
+        var at = new DateTime(2026, 8, 3, 12, 0, 0, DateTimeKind.Utc);
+        Assert.NotEqual(
+            TableConfigBackupRepository.BuildRowKey(at),
+            TableConfigBackupRepository.BuildRowKey(at));
+    }
+
+    [Fact]
+    public async Task Prune_DeletesEverythingBeyondKeep_InScanOrder()
+    {
+        var harness = new Harness();
+        // Scan order = RowKey ascending = newest first (reverse ticks). keep=2 must
+        // delete rows 3 and 4, never the two newest.
+        harness.SetupQuery(
+            new TableEntity(TenantId, "0001_newest"),
+            new TableEntity(TenantId, "0002_second"),
+            new TableEntity(TenantId, "0003_old"),
+            new TableEntity(TenantId, "0004_oldest"));
+
+        var deleted = await harness.Sut.PruneAsync(TenantId, keep: 2);
+
+        Assert.Equal(2, deleted);
+        Assert.Equal(new[] { "0003_old", "0004_oldest" }, harness.Deletes.Select(d => d.Rk).ToArray());
+    }
+
+    [Fact]
+    public async Task Prune_WithinKeep_DeletesNothing()
+    {
+        var harness = new Harness();
+        harness.SetupQuery(
+            new TableEntity(TenantId, "0001_newest"),
+            new TableEntity(TenantId, "0002_second"));
+
+        var deleted = await harness.Sut.PruneAsync(TenantId, keep: 2);
+
+        Assert.Equal(0, deleted);
+        Assert.Empty(harness.Deletes);
+    }
+
+    [Fact]
+    public async Task ListByPartition_CapsAtMax()
+    {
+        var harness = new Harness();
+        harness.SetupQuery(
+            new TableEntity(TenantId, "0001"),
+            new TableEntity(TenantId, "0002"),
+            new TableEntity(TenantId, "0003"));
+
+        var listed = await harness.Sut.ListByPartitionAsync(TenantId, max: 2);
+
+        Assert.Equal(2, listed.Count);
+        Assert.Equal("0001", listed[0].RowKey);
+    }
+}

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

@@ -183,4 +183,46 @@ public class ConfigRedactionTests
     public void CanViewSecrets_PureDelegatedReader_False()
         => Assert.False(GetTenantConfigurationFunction.CanViewSecrets(
             new RequestContext { IsDelegatedReader = true, TenantId = TenantA, TargetTenantId = TenantB }));
+
+    [Theory]
+    [InlineData(Constants.TenantRoles.Operator)]
+    [InlineData(Constants.TenantRoles.Viewer)]
+    public void CanViewSecrets_OwnTenantOperatorOrViewer_False(string role)
+        // Member-tier read-only Settings view (config GET is MemberRead): an own-tenant
+        // Operator/Viewer arrives with IsTenantAdmin=false ⇒ always the redacted copy.
+        => Assert.False(GetTenantConfigurationFunction.CanViewSecrets(
+            new RequestContext { UserRole = role, TenantId = TenantA, TargetTenantId = TenantA }));
+
+    // ── ?view=redacted opt-in (MCP get_tenant_config): forces redaction even for GA ──
+
+    [Fact]
+    public void ShouldRedact_GlobalAdmin_ViewRedacted_True()
+        => Assert.True(GetTenantConfigurationFunction.ShouldRedact(
+            new RequestContext { IsGlobalAdmin = true, TenantId = TenantA, TargetTenantId = TenantB },
+            "?view=redacted"));
+
+    [Fact]
+    public void ShouldRedact_OwnTenantAdmin_ViewRedacted_True()
+        => Assert.True(GetTenantConfigurationFunction.ShouldRedact(
+            new RequestContext { IsTenantAdmin = true, TenantId = TenantA, TargetTenantId = TenantA },
+            "?view=redacted"));
+
+    [Fact]
+    public void ShouldRedact_GlobalAdmin_NoParam_False()
+        // Without the opt-in the GA clearance stands — the portal Settings UI depends on it.
+        => Assert.False(GetTenantConfigurationFunction.ShouldRedact(
+            new RequestContext { IsGlobalAdmin = true, TenantId = TenantA, TargetTenantId = TenantB },
+            ""));
+
+    [Fact]
+    public void ShouldRedact_GlobalAdmin_OtherViewValue_False()
+        => Assert.False(GetTenantConfigurationFunction.ShouldRedact(
+            new RequestContext { IsGlobalAdmin = true, TenantId = TenantA, TargetTenantId = TenantB },
+            "?view=full"));
+
+    [Fact]
+    public void ShouldRedact_ReaderWithoutClearance_AlwaysTrue_RegardlessOfParam()
+        => Assert.True(GetTenantConfigurationFunction.ShouldRedact(
+            new RequestContext { IsGlobalReader = true, TenantId = TenantA, TargetTenantId = TenantB },
+            "?view=full"));
 }

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

@@ -0,0 +1,48 @@
+using AutopilotMonitor.Functions.Services;
+using AutopilotMonitor.Shared.Models;
+using Xunit;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Cover for the ConnectionType predicate used on every search path that does NOT push the
+/// filter to OData — the deviceProperties batch-get (<c>ApplyBasicFilters</c>) and the legacy
+/// unpaged scan. Sessions that predate the projection (null ConnectionType) must never match
+/// a set filter; an unset filter matches everything.
+/// </summary>
+public class ConnectionTypeFilterTests
+{
+    private static SessionSummary Session(string? connectionType) =>
+        new() { SessionId = "s", TenantId = "t", ConnectionType = connectionType };
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("WiFi")]
+    [InlineData("Ethernet")]
+    public void NoFilter_AlwaysMatches(string? connectionType)
+    {
+        var filter = new SessionSearchFilter();
+        Assert.True(TableStorageService.MatchesConnectionType(Session(connectionType), filter));
+    }
+
+    [Theory]
+    [InlineData("Ethernet", true)]
+    [InlineData("ethernet", true)]  // case-insensitive, matching the other string filters
+    [InlineData("WiFi", false)]
+    [InlineData(null, false)]       // legacy session without the projected column
+    public void EthernetFilter_MatchesOnlyEthernet(string? connectionType, bool expected)
+    {
+        var filter = new SessionSearchFilter { ConnectionType = "Ethernet" };
+        Assert.Equal(expected, TableStorageService.MatchesConnectionType(Session(connectionType), filter));
+    }
+
+    [Theory]
+    [InlineData("WiFi", true)]
+    [InlineData("Ethernet", false)]
+    [InlineData(null, false)]
+    public void WiFiFilter_MatchesOnlyWiFi(string? connectionType, bool expected)
+    {
+        var filter = new SessionSearchFilter { ConnectionType = "WiFi" };
+        Assert.Equal(expected, TableStorageService.MatchesConnectionType(Session(connectionType), filter));
+    }
+}

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

@@ -47,7 +47,7 @@ public class CriticalTableBackupServiceTests
 
         Assert.Equal(BackupOutcome.Success, result.Outcome);
         Assert.True(store.ManifestWritten, "manifest must be written LAST");
-        Assert.Equal(16, result.Manifest.Tables.Count);   // critical-tables catalog count (incl. DelegatedAdmins)
+        Assert.Equal(17, result.Manifest.Tables.Count);   // critical-tables catalog count (incl. DelegatedAdmins + ConfigurationBackups)
         Assert.All(result.Manifest.Tables, t =>
             Assert.True(t.Status == TableBackupStatus.Ok || t.Status == TableBackupStatus.Empty));
     }

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

@@ -324,4 +324,42 @@ public class CrossTenantAccessTests
         Assert.NotNull(entry);
         Assert.Equal(TenantScoping.QueryParam, entry.TenantScoping);
     }
+
+    // ── Cross-tenant rule WRITES: global/rules/{gather,analyze}/{ruleId} ──
+    // Bug (2026-07-24): a Global Admin editing a foreign tenant's rule via the JWT-scoped
+    // rules/{type}/{ruleId} route silently upserted into the GA's OWN tenant (200 → false "saved");
+    // the reload re-read the foreign tenant and showed the unchanged rule. Fix: dedicated cross-tenant
+    // write routes. They MUST be GlobalAdminOnly (a write tier → no delegated-read rescue, so a
+    // tenant-admin / delegated caller can never cross into another tenant's rules) + QueryParam (the
+    // tenant is named by ?tenantId=, not the {ruleId} segment). A downgrade to a tenant tier, or a slip
+    // to TenantScoping.None (which would ignore ?tenantId= and re-introduce the home-tenant misroute),
+    // is caught here.
+
+    [Theory]
+    [InlineData("PUT",    "global/rules/gather/{ruleId}")]
+    [InlineData("DELETE", "global/rules/gather/{ruleId}")]
+    [InlineData("PUT",    "global/rules/analyze/{ruleId}")]
+    [InlineData("DELETE", "global/rules/analyze/{ruleId}")]
+    public void GlobalRuleWriteRoutes_AreGlobalAdminOnly_QueryParam(string httpMethod, string routeTemplate)
+    {
+        var entry = EndpointAccessPolicyCatalog.Entries
+            .FirstOrDefault(e => e.HttpMethod == httpMethod.ToUpperInvariant() && e.RouteTemplate == routeTemplate);
+
+        Assert.NotNull(entry);
+        Assert.Equal(EndpointPolicy.GlobalAdminOnly, entry!.Policy);
+        Assert.Equal(TenantScoping.QueryParam, entry.TenantScoping);
+    }
+
+    [Theory]
+    [InlineData("PUT",    "/api/global/rules/gather/rule-1")]
+    [InlineData("DELETE", "/api/global/rules/gather/rule-1")]
+    [InlineData("PUT",    "/api/global/rules/analyze/rule-1")]
+    [InlineData("DELETE", "/api/global/rules/analyze/rule-1")]
+    public void GlobalRuleWrite_CrossTenant_GlobalAdmin_IsAllowed(string httpMethod, string path)
+    {
+        var (isBlocked, targetTenantId) = SimulateQueryParamCheck(httpMethod, path, TenantA, hasGlobalScope: true, queryTenantId: TenantB);
+
+        Assert.False(isBlocked, $"Global Admin should reach the target tenant on the cross-tenant write route: {httpMethod} {path}");
+        Assert.Equal(TenantB, targetTenantId);
+    }
 }