fix(quickfiler): observe InitializeWebViewAsync faults at a boundary (#670)

[drmoisan]

fix(quickfiler): observe InitializeWebViewAsync faults at a boundary (#670)

Summary

• Adds a fault boundary over QfcItemController.InitializeWebViewAsync, whose returned task was discarded at three of its four production call sites, so any exception it raised became an unobserved task exception with no diagnostic.
• Introduces InitializeWebViewGuardedAsync, an async Task member that contains the fault rather than returning it: the task it returns never transitions to Faulted.
• Introduces WebViewInitializationErrorSink, an injectable seam over the static log4net logger, so the fault path is assertable in a unit test without a live WebView2 runtime.
• Substitutes the guard at the three discarding call sites in QfcItemController.Initialization.cs (lines 192, 288 and 324). Line 256 is deliberately left calling the unguarded member, because it is already awaited and routing it through the guard would swallow a fault an existing test asserts.
• Adds four tests, including a mutation-discriminated pair that proves the new test observes the fix rather than passing regardless of it.
• New file coverage is 92.31% against the 90% new-module floor; repository-wide covered lines rise by 5 with no regression.

Why

On .NET Framework 4.5 and later, an unobserved task exception no longer terminates the process by default, so a discarded faulted task is finalized away with no observable effect at all. InitializeWebViewAsync is the sole entry point for WebView2 environment creation and core initialization, and at ViewerSetup.cs:112 it calls EnsureBreadcrumbPipeline(). Issue #488's D5 change made that path newly capable of throwing ObjectDisposedException when the pipeline is built against a viewer whose teardown has begun, which converted a previously silent leak into a fault that was itself silently swallowed.

The practical consequence was a diagnostic gap rather than a crash: a WebView2 initialization failure — a missing runtime, a locked cache directory, a disposed viewer — produced no log entry on three of four paths, so the breadcrumb surface simply never appeared and the cause was unavailable to anyone triaging it.

The fire-and-forget intent at those three sites is sound; not blocking initialization on a WebView2 round trip is deliberate. Discarding the fault is the part that was not.

What Changed

Core fix

• QuickFiler/Controllers/QfcItemController.WebViewFaultBoundary.cs (new, 41 lines) — a new partial of QfcItemController carrying the sink and the guard. A new file rather than an edit to QfcItemController.ViewerSetup.cs because that file measures 499 lines against the repository's 500-line ceiling.
  • WebViewInitializationErrorSink defaults to (message, exception) => logger.Error(message, exception), matching the log4net message-first, exception-second signature.
  • InitializeWebViewGuardedAsync awaits InitializeWebViewAsync, swallows OperationCanceledException as expected cooperative cancellation during teardown, and routes any other Exception to the sink with a subsystem-identifying message.
• QuickFiler/Controllers/QfcItemController.Initialization.cs — three call-site substitutions, net zero lines added or removed. The file remains 489 lines.
• QuickFiler/QuickFiler.csproj — one added <Compile Include> entry. That project enumerates the QfcItemController partials explicitly with no wildcard.

Tests

• QuickFiler.Test/Controllers/QfcItemController.InitializationTests.Part3.cs — three tests: the seam-fault-reaches-the-sink test, the default-delegate smoke test, and a pump-hosted test that drives Initialize(async: false) through WinFormsPumpHost and observes the fault through a signalling sink.
• QuickFiler.Test/Controllers/QfcItemController.InitializationTests.cs — the shared arrange helper and a fourth test covering the guard's cancellation arm, placed here because Part3.cs had no room under the 500-line ceiling.

Docs and evidence

The feature folder carries the issue, spec, research note, atomic plan, the three feature-review audit artifacts, and the per-task evidence artifacts for every baseline, regression and QA gate.

Architecture / How It Fits Together

The boundary sits between the three fire-and-forget dispatch sites and the existing initialization member. Control flow is unchanged on the success path: the guard awaits the same member the sites previously called, so initialization is neither serialized nor delayed. On the failure path the exception is caught inside the guard instead of escaping into a discarded task, and is handed to the sink.

The sink is the testability seam. In production it is the default lambda over the static log4net logger; in a test it is replaced with a delegate that captures the exception or completes a TaskCompletionSource. This mirrors the ratified EfcFormController.BoundaryErrorSink shape already in the codebase, and is named distinctly so no shared contract between the two types is implied.

The broad catch (Exception) is deliberate and qualifies under .claude/rules/csharp.md as a defined boundary with added context: the file and member are purpose-named, the contract is documented, and the handler routes to the sink with a subsystem-identifying message plus the exception instance rather than swallowing it.

Verification

Completed

Full four-stage C# toolchain, one clean pass with no restart:

Stage	Command	Result
Format	dotnet tool run csharpier format . then check .	exit 0, 1567 files, no file under QuickFiler/ or QuickFiler.Test/ rewritten
Lint	msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true	exit 0, 0 errors
Type-check	msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU" /p:TreatWarningsAsErrors=true	exit 0, 0 errors
Test + coverage	Invoke-MSTestWithCoverage.ps1 -SearchRoot . -Configuration Debug	6934 tests, baseline failure set NONE, post-change failure set NONE

Coverage:

Figure	Value	Gate	Result
Baseline repository-wide line	85.3866% (54983/64393)	—	—
Post-change repository-wide line	85.3771% (54988/64406)	no regression	PASS
Covered-line delta	+5	>= 0	PASS
New file QfcItemController.WebViewFaultBoundary.cs	92.3077% (12/13)	>= 90%	PASS

The post-change figure clears both repository floors: the 80% floor in CLAUDE.md and the 85% floor in .claude/rules/general-unit-test.md. The sole uncovered line in the new file is the try block's closing brace.

Mutation discrimination for the primary regression test — the same command, filter and assembly, differing only by the presence of the sink invocation:

• sink invocation present: exit 0
• sink invocation replaced with a discard: exit 1, failing on but found <null>
• sink invocation restored: exit 0

A test that passed in both states would not observe the fix.

Acceptance criteria: 14 of 14 in spec.md delivered and verified, 0 remaining. Feature review returned 0 blocking findings across policy-audit, code-review and feature-audit.

Recommended

• Re-run the four toolchain stages above against the merge result.
• Exercise a real WebView2 initialization failure (rename the runtime, or lock the cache directory) and confirm a log entry now appears where previously none did.

Backward Compatibility / Migration Notes

No breaking changes. No public API is altered, no member is removed or renamed, and no signature changes. InitializeWebViewAsync itself is untouched, so any existing caller keeps its current behavior; only the three previously-discarding sites now route through the guard. QfcItemController.ViewerSetup.cs receives zero changed lines.

Risks and Mitigations

• Risk: the guard converts a previously-propagating fault into a logged one at the three substituted sites, so an automated caller that relied on observing the task would no longer see it. Mitigation: none of the three sites observed the task — that is the defect being addressed — and line 256, the one site that does observe it, is deliberately unchanged and covered by an existing test.
• Risk: the broad catch (Exception) could mask an unrelated programming error thrown from deep inside initialization. Mitigation: the handler logs rather than swallows, with the exception instance preserved, so the diagnostic is strictly better than the discarded-task behavior it replaces.
• Rollback: revert the single implementation commit. The three call-site substitutions are net-zero-line replacements and the new file is additive, so the revert is mechanical.

Review Guide

Suggested order:

1. QuickFiler/Controllers/QfcItemController.WebViewFaultBoundary.cs — 41 lines, the whole fix.
2. QuickFiler/Controllers/QfcItemController.Initialization.cs — three one-line substitutions.
3. QuickFiler.Test/Controllers/QfcItemController.InitializationTests.Part3.cs and .cs — the four tests.
4. QuickFiler/QuickFiler.csproj — one added line.

Large mechanical diffs to skip: the two Cobertura coverage documents under the feature folder total roughly 388,000 added lines and are machine-generated evidence. The remaining feature-folder files are documentation and per-task evidence artifacts.

Note for reviewers using the generated PR-context bundle: it reports "Core logic changes: 0 files" for this branch and buckets all 61 changed paths as documentation. That classification is wrong — five of them are C# source. See Follow-ups.

Follow-ups

None of the following is delivered here, and none is filed from this branch; they are recorded for consolidated filing.

• Boundary error sinks are settable and unguarded against null or throwing delegates. Affects both the WebViewInitializationErrorSink added here and the existing EfcFormController.BoundaryErrorSink precedent. A null or throwing sink would fault the guard's task and reinstate the unobserved-fault behavior. LATENT — no production code assigns either sink today. Should be addressed for both types together rather than under this issue.
• EfcItemController fire-and-forget sites at EfcItemController.cs:97 and :153 use Task.Run(() => InitializeWebViewAsync()) against that class's own same-named member and discard the result. LIVE, but the class carries a class-level [ExcludeFromCodeCoverage] and has no injectable initializer seam, so extracting that seam is the real prerequisite.
• TaskScheduler.UnobservedTaskException backstop at the add-in boundary. Optional hardening; finalization-timed, process-global, and not deterministically testable.
• PR-context bundle disables the C# coverage gate. validate-feature-review-coverage.ps1 derives its changed-language set by parsing churn-annotated lines out of artifacts/pr_context.summary.txt, and returns success when that set is empty. On this branch the bundle classifies every changed path as documentation and truncates the enumeration to the top ten by churn, which this item's two large Cobertura evidence files dominate. No .cs path survives, so the language set is empty and C# coverage enforcement is skipped without any message saying so. Both mechanisms are independently sufficient to disable the gate.
• Coverage-floor divergence between CLAUDE.md / .claude/rules/csharp.md (80% and 90%) and .claude/rules/general-unit-test.md / .claude/rules/quality-tiers.md (85% and 75%) remains unsettled. Already tracked in issue Coverage threshold contradiction remains: CLAUDE.md/csharp.md say 80%, general-unit-test.md/quality-tiers.md say 85%/75%, and two live gates disagree #563; this change sidesteps it by clearing both floors.

GitHub Auto-close

• Closes Bug: qfc-initializewebviewasync-fault-is-unobserved #670

Issues #488, #563 and #464 appear above as context and precedent only. They remain open and this pull request does not act on them.