Diagnostics: add secret-safe WorkManager failure observation hooks

[MrFr3di]

Objective

Use the stable WorkManager 2.11.2 failure callbacks that MuxTV already depends on so background refresh/startup failures become typed, bounded and exportable without exposing secrets or changing WorkManager semantics.

Owner under modernization umbrella #179; Doctor integration must remain compatible with #30 and the user-unlocked lifecycle contract from #118.

Current gap

app/tv/src/main/kotlin/app/muxtv/MuxTvApplication.kt currently builds Configuration with only setWorkerFactory(workerFactory).

The current stable API already exposes:

• setInitializationExceptionHandler;
• setSchedulingExceptionHandler;
• setWorkerInitializationExceptionHandler;
• setWorkerExecutionExceptionHandler.

This means MuxTV currently has a blind spot when WorkManager itself cannot initialize/schedule a request or cannot initialize/execute a worker.

Architecture

Introduce a narrow WorkManager-specific diagnostic boundary rather than reusing PlaybackObservation or creating a generic raw telemetry event bus.

Suggested model:

• WorkFailureKind: stable enum/code for the four callback families;
• WorkFailureObservation: kind + timestamp + optional bounded safe worker identity/category only;
• WorkFailureRecorder / WorkFailureReader: bounded process/local diagnostic owner;
• WorkManager callbacks translate framework failures into this typed model and never propagate exceptions;
• Doctor/export receives a coarse projection through an explicit read boundary.

Initialization failures are special: the observation path must not depend on Room/WorkManager being healthy. Do not introduce a diagnostic write path that can recursively fail during WorkManager initialization.

Security / privacy contract

Never persist or export:

• raw Throwable.message or full stack trace;
• playlist/source URL, path or query;
• Authorization/Cookie/custom headers;
• provider credentials/tokens;
• arbitrary worker input/output Data;
• user/channel titles.

Tests must use deliberately secret-bearing exception text and prove it cannot cross the diagnostic boundary.

Required behavior

• all four stable callbacks are installed;
• callback handling is non-throwing and observational only;
• WorkManager retry/failure/scheduling semantics remain owned by WorkManager/Worker code;
• repeated failures are bounded; no unbounded in-memory or durable list;
• Doctor uses stable user-facing categories, not raw exception strings;
• no custom setWorkerCoroutineContext() in this issue;
• no WorkManager 2.12 RC upgrade solely for newer event-listener APIs.

TDD / acceptance

1. RED pure unit tests define four typed callback categories and secret stripping;
2. RED test proves recorder failure cannot escape into a callback;
3. bounded retention/deduplication behavior is deterministic;
4. wire all four Configuration.Builder callbacks after the pure boundary is GREEN;
5. app unit tests prove the configuration contains the expected handlers where framework inspection allows it; otherwise keep wiring behind a small testable factory;
6. Doctor/report tests prove only stable safe fields are formatted/exported;
7. host validation GREEN on exact head;
8. later API26 + API36 canonical-device smoke verifies startup/refresh behavior without creating any additional AVD.

Non-goals

• generic telemetry platform;
• remote telemetry upload;
• storing raw WorkManager internals;
• changing Worker retry/backoff policy;
• changing worker dispatcher/coroutine context;
• adding another Android TV AVD.

Official references

• https://developer.android.com/reference/androidx/work/Configuration.Builder

Dependencies / ordering

Can be implemented host-first before device runner returns. Device acceptance is deferred until the canonical API26/API36 runner is available. Keep this separate from #189 U0 UI characterization and from the combined stack staging #190.

[MrFr3di]

Execution design and task-level TDD steps are staged on docs/observability-modernization-20260824:

• docs/superpowers/specs/2026-08-24-observability-modernization-design.md
• docs/superpowers/plans/2026-08-24-observability-modernization-implementation-plan.md

#191 is O1 and is the first production implementation candidate once an executable host gate is available. Do not commit GREEN wiring before the pure diagnostic RED contract is actually observed.

[MrFr3di]

Runner-free secret-boundary audit prepared at docs/security/2026-08-24-secret-bearing-data-boundary-audit.md. For #191 specifically: WorkManager input/progress/output and durable failure diagnostics must use stable source/run/access refs plus typed failure codes; raw source/stream URLs, headers, credentials and unrestricted Throwable.message/stack text must not be persisted. First implementation should be a focused negative redaction contract before wiring handlers.

[MrFr3di]

O1 TDD execution update (2026-08-25):

• created isolated branch feat/workmanager-failure-observation-191 from accepted main@5aa9c108cc63187d8066494fb30c73b82f4e0f97;
• RED contract commit: 2516d8120c4c8535382c79654585b948b29daae2;
• test-only diff adds BackgroundWorkFailureTest.kt; no production WorkManager/Doctor code yet;
• contract strengthens safeWorkerCategory to a closed BackgroundWorkerCategory vocabulary (SOURCE_REFRESH, EPG_REFRESH, UNKNOWN) so arbitrary URL/token/title strings cannot enter the observation model by type;
• official WorkManager API was rechecked: initialization/scheduling callbacks are stable since 2.8.0, worker initialization/execution callbacks and WorkerExceptionInfo since 2.10.0, so existing 2.11.2 is sufficient and no upgrade is needed;
• draft PR feat(diagnostics): observe WorkManager framework failures safely #207 was opened only to request executable RED evidence, then closed while runner capacity is unavailable so subsequent planning commits do not keep generating self-hosted jobs;
• self-hosted RED validation run 32812782314, job 97695231419, remains queued with labels [self-hosted, Windows, X64, muxtv-android] on exact test-only SHA 2516d812...;
• a temporary ubuntu-latest RED workflow was attempted without artifacts, but GitHub did not allocate a hosted runner either: run 32812833506 / job 97695374747 completed with steps=[], runner_id=0. This is infrastructure no verdict, not the expected RED. The temporary workflow was removed immediately; branch effective diff remains test-only.

Per the approved observability plan, GREEN production code is intentionally not committed until :core:common:test --tests "*BackgroundWorkFailureTest" produces the expected missing-contract failure. U0/#189 remains higher priority on the single device runner; do not create another AVD or duplicate U0 run.

[MrFr3di]

2026-08-26 execution update — O1.1 RED is now genuinely observed; minimal GREEN staged

The earlier note that O1 had no executable RED verdict is superseded by self-hosted run 32812782314, job 97695231419, which finally acquired DESKTOP-0N5KM3T while the runner was briefly online.

Verified RED

Exact checkout: 2516d8120c4c8535382c79654585b948b29daae2.

Before the target test, runner preflight, Android/CI harness syntax, build-logic tests and configuration-cache checks passed. :core:common:compileTestKotlin then failed for the intended contract reason:

• unresolved BackgroundWorkFailureKind;
• unresolved BackgroundWorkerCategory;
• unresolved BackgroundWorkFailureObservation.

This is the required O1.1 RED, not an infrastructure/no-verdict failure. The workflow later also failed evidence upload because the repository Actions artifact storage quota is exhausted; that transport failure is independent of the RED result.

Minimal GREEN staged

Branch: feat/workmanager-failure-observation-191
Commit: 24b33931ce4ee09044e5ae467748de696d95a263

Added only core/common/src/main/kotlin/app/muxtv/common/diagnostics/BackgroundWorkFailure.kt with:

• the four closed failure kinds;
• closed safe worker categories SOURCE_REFRESH, EPG_REFRESH, UNKNOWN;
• typed observation fields only (kind, non-negative wall-clock timestamp, enum worker category);
• no arbitrary String, Throwable, URL/header/token or WorkManager Data field.

The existing generic DiagnosticEvent is deliberately not reused for this boundary because it exposes arbitrary string category/message fields and therefore cannot enforce #191's secret-safe model by type.

The new source was also checked with a standalone Kotlin compile, but O1.1 exact module GREEN is not claimed yet: :core:common:test --tests "*BackgroundWorkFailureTest" must still execute on the exact new head when an executable runner is available.

Do not advance to O1.2 production store code before that GREEN verification. The next cycle remains: O1.1 exact-head GREEN -> O1.2 store RED -> observed RED -> minimal store GREEN.