# Incident: USB02 Stage 1B post-open session failure

Status: complete
Result: resolved
Type: incident
Updated: 2026-08-01
Next Action: none; retain the resolved session-handoff incident and current broad-baseline regression evidence
Campaign: 003-complete-bounded-hpt-slow-export-firmware-ticket
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Canonical Truth: docs/firmware-update-validation-and-recovery.md
Resolved By: work/wp/completed/wp-restore-broad-usb-compatibility-baseline.md

## Impact

The restored Stage 1 USB baseline did not provide reliable service for freshly
Windows-formatted `USB02_8G` on Controller A. A clean reinsertion briefly
established a valid FileX media handoff, but the USB application thread closed
the session while the drive remained attached. No customer workflow could run.

This is a Stage 1B gate failure. It is not media corruption and must not be
mitigated with a USB02 identity rule, fixed specimen delay, VBUS cycle, or an
approved-drive list.

## Observed boundary

- USB device attachment and the host port remained valid.
- USBX media lookup succeeded.
- The deferred handoff reached `FX_MEDIA_ID`, matching storage-instance
  identity, acceptance mask `15`, and generation `3`.
- The application then recorded one USB application error, cleared its
  effective FileX pointer, and remained unmounted with no pending instance.
- The exact error status was discarded by the inherited application logic.
- Independent read-only Pi checks found a clean, unchanged FAT32 filesystem
  and no publication artifacts.

## Current code comparison

Tag `v00.04.11` and the current Stage 1 thread share the same brittle outer
gate: after a short delay they call `fx_media_volume_get()`, accept only
`FX_SUCCESS` or `FX_NOT_FOUND`, and otherwise count an error before flushing
and closing the media. The outer loop cannot reacquire a still-attached device,
so one transient or diagnosable volume-query failure requires physical
reinsertion.

The current code improves on the original callback by deferring application
publication until USBX has established a valid FileX media identifier. That
guard is not the observed failure. The unresolved defect is that the next
FileX operation has neither exact-status telemetry nor bounded, state-driven
revalidation, and teardown destroys self-recovery.

## Required resolution properties

- Preserve the first exact FileX status and phase.
- Distinguish media-not-ready/transient state from permanent filesystem or
  pointer errors using protocol/FileX state, not drive identity.
- Do not close a valid still-attached media session merely because a
  nonessential volume-label lookup failed.
- If volume validation is actually required, use bounded revalidation and
  publish application readiness only after it succeeds.
- If the volume-label lookup is not required for any workflow, remove it as a
  mount gate and separately validate the default-directory behavior.
- Recover without VBUS cycling or physical reinsertion when the device and
  USBX/FileX session remain valid.
- Repeat the complete four-drive matrix and USB09 regression after correction;
  do not begin the 32 KiB experiment first.

## Implemented correction

Commit `96b8ab4b87e438c41370b24001a5ef00bcd93492` removes the unused
volume-label and nonexistent-default-directory probes from application
readiness, leaves USBX-owned FileX media close/deactivation to USBX, re-arms
deferred handoff when a published pointer becomes invalid, and adds exact
application-session telemetry. Static checks and canonical managed Debug and
Release rebuilds pass. Exact artifacts and hashes are in
`work/evidence/usb-session-recovery-software-candidate-20260731.md`.

The exact candidate was deployed B first and then A with full-flash readback
and fresh controller/SD identity gates. Recovery round 1 then repeated the
previously failing `USB02_8G`/Controller A allocation. USB02 mounted on first
insertion and passed WAV, playback, PID, image, HPT export, final live-session,
and independent Pi validation with zero errors and no reseat or VBUS action.
`USB03_32G` passed the paired Controller B path. Evidence is in
`work/evidence/usb-session-recovery-round1-usb02-usb03-20260731.md`.

At that checkpoint, the observed failing path was mitigated on target while
cross-controller and USB09 regression still remained.

The subsequent opposite-controller cross-check passed bounded WAV
load/playback and final session state on both drives. USB02/B mounted on first
insertion. USB03/A had one below-class first-insertion enumeration miss and
passed after the single allowed clean reseat; that separate observation is
preserved in
`work/evidence/usb-session-recovery-cross-check-usb03-usb02-20260731.md`.
At that later checkpoint, only USB09 regression remained for this incident.

## Next discriminator

Round 4 ran without firmware changes. `USB02_8G` mounted on Controller B on
its first insertion and passed WAV, playback, PID, image, and HPT publication.
Independent Pi validation found a clean FAT32 filesystem, exact output hashes,
and no temporary artifacts. `USB03_32G` passed the equivalent workflow on
Controller A without incrementing A's preserved round 3 error count.

The failure therefore does not follow USB02 and is not a specimen capability
limit. It is a transient application-session failure that current firmware
cannot recover. The exact discarded round 3 status can no longer be recovered
from the running target, but the failing operation's output is unused: the
application calls `fx_media_volume_get()` only as a gate and never consumes
the returned volume label. Removing that nonessential metadata query from the
readiness decision is narrower and more standards-led than inventing retry
status classes for an operation the product does not require.

Evidence:
`work/evidence/usb-stage1b-round3-usb02-usb03-20260731.md` and
`work/evidence/usb-stage1b-round4-usb03-usb02-20260731.md`.

## Resolution and Closeout

The completed four-drive matrix, USB09 correction, bounded enumeration
recovery, BOT validation, and representative delta regression close this
incident. Current evidence is in
`work/checklists/checklist-stage-1b-four-drive-usb-compatibility-baseline.md`,
`work/wp/completed/wp-restore-broad-usb-compatibility-baseline.md`, and
`work/evidence/usb-bot-representative-delta-regression-20260801.md`.

The correction removed a nonessential readiness query and preserved
state-driven session ownership. It added no USB02 rule, specimen delay, VBUS
cycle, or approved-drive list.
