Wire the end-of-session lifecycle on device: overtime, review and rest

[PurpleSentinel]

Objective

SessionController models six states. The device renders two of them, and the other
four resolve to the dashboard, so a driver gets no indication that a session has ended.

What happens today

ScreenRouter::service_session in firmware/main/screen_router.cpp reduces the whole
state machine to one boolean:

const auto active = snapshot.state == session::SessionState::running ||
                    snapshot.state == session::SessionState::overtime;
...
lv_screen_load(active ? trackday_root_ : home_screen());

The consequences:

State	Modelled	On device
running	yes	Track Day countdown
overtime	yes	the same screen as running, with no indication the session is over
review	yes	silently returns to the dashboard
rest	yes	silently returns to the dashboard

So the session simply vanishes when the clock expires. The driver is not told the
session ended, is not offered the review they were promised, and the rest period they
configured never appears — rest_duration_minutes is a live, editable setting that
currently has no observable effect on the device at all.

Overtime is the sharper problem of the two. It renders identically to running, so at
the moment the session ends the display gives no signal whatsoever. On a Track Day this
is exactly when the driver needs to know to come in.

Why this was not caught

These screens exist and are tested — #79 and #30 built rest, overtime, deliberate-stop
and post-session review, and #77 built the editors behind them. They were built against
the simulator, which has since been frozen (#134). The device never grew the routing to
reach them, and no test asserts that a device state maps to a screen, so nothing failed.

This is worth noting as a class of gap rather than a one-off: simulator-era screens
may be present, tested and unreachable on hardware. Other screens from the same
milestones should be audited the same way.

Scope

• Route every SessionState to a screen, with a test that fails when a state has
  no mapping — an exhaustive switch over the enum rather than a boolean
• Make overtime visually unmistakable and distinct from running; it currently shares
  the running layout, and the countdown's behaviour once remaining time reaches zero
  needs deciding (hold at 00:00, or count up)
• Present the end-of-session review, honouring the Track Day rule that lap times
  appear only once the session has finished (Add a top-level Mode selection: Track Day, Race and G-Only #132)
• Run the configured rest period and return to ready when it expires
• Wire the deliberate-stop confirmation, so a session cannot be ended by a stray touch

Depends on

Review content is thin until GNSS lands, but the routing, the overtime signal and the
rest period are all independent of it and are the driver-visible part.

[PurpleSentinel]

Agreed design, 2026-08-20

The overrun and rest halves of this issue are now specified. Track Day is the driving case:
a session ends, the driver needs telling, and a rest period follows before the next one.

Overrun

When the countdown reaches 00:00 the same field counts up in minutes and seconds, so the
driver sees how far past the end they are rather than a screen that simply stops.

• the numerals turn deep purple, unmistakably different from the green-through-red ramp
  that preceded them
• the estimated-laps line underneath is replaced by OVER RUN. A lap estimate is
  meaningless once the session is over, and the line is the natural place to say what state
  the timer is in
• the decay bar is empty, which is simply where the ramp ends

Rest

Double tap ends the session or the overrun and starts the rest period. Rest counts down
in the same way as the session: same fixed-cell numerals, same green-through-red ramp, same
decaying bar, with the line underneath reading REST.

Double tap again ends rest and returns to the start screen.

Double tap rather than a single press because this ends a session: a stray touch on a moving
car must not. It is also distinct from press-and-hold, which already opens the gated menu and
must keep working from a running session.

Colour

"Deep purple" and a driver-facing panel pull against each other, so the value is chosen on
measured contrast against the black background rather than by name:

Candidate	Contrast
#6A0DAD classic "deep purple"	2.27:1
#8A2BE2 blueviolet	3.52:1
#9A4DFF chosen	4.88:1
existing ramp red #FF3B30	5.92:1
existing ramp green #2FD16D	10.46:1

#6A0DAD is the literal answer and far too dim: at 2.27:1 a 10 mm numeral is hard work in
daylight, and every other state on this screen sits between 5.9 and 10.5. #9A4DFF reads as
a deep saturated purple while landing next to the ramp's red for legibility. Easy to darken
if it looks too bright on the panel.

What is already there

The state machine needs no changes. SessionController already models overtime,
session_overrun_ms, rest, rest_remaining_ms, and the transitions between them, all host
tested. This gap is entirely in the routing and the screen, which is what this issue said.

One consequence worth recording: confirm_stop moves running or overtime to review, and
complete_review moves review to rest. Double tap therefore passes through review
programmatically rather than jumping straight to rest, so the tested path is preserved and a
review screen can be inserted later without rearranging the state machine. If review later
becomes a screen the driver sees, this flow gains a stop on the way to rest - a deliberate
choice, noted here so it is not a surprise then.

Scope

• InputAction::double_tap, detected as two short clicks inside a window
• Overrun counting up in the countdown field, deep purple, OVER RUN beneath
• Rest counting down like the session, ramped, REST beneath
• Double tap: session or overrun to rest; rest to ready
• Route rest to the running screen, which today falls through to the dashboard
• Host tests for the phase selection, the counting-up format, the colour per phase, and
  that a single tap never ends a session

Still out of scope here

The review screen itself, and the deliberate-stop confirmation UI. Both remain on this issue.

[PurpleSentinel]

Overrun and rest are done, in #151

Three of the five scope items are complete, and the two that made the device misleading are
among them. The state machine needed no changes at all, as expected — this was entirely the
routing gap this issue described.

• InputAction::double_tap, two short clicks inside a 400 ms window
• Overrun counting up, #9A4DFF, OVER RUN beneath
• Rest counting down on the session's ramp, REST beneath
• Double tap: session or overrun to rest; rest to ready
• Route rest to the running screen
• Host tests for phase selection, the counting-up format, colour per phase, and the rest ramp

Verified end to end on the panel:

session start: 0 over 60 s
state=running   remaining=59935  overrun=0     rest=-1
state=overtime  remaining=0      overrun=67    rest=-1      <- by itself, at zero
session phase: overtime -> rest                             <- double tap
state=rest      remaining=0      overrun=6384  rest=1199999
session phase: rest -> ready                                <- double tap
state=ready

The 60 second session ran 60,010 ms, and no accidental transition occurred in the seconds
either side of either tap.

Left open here

• The review screen. Double tap currently passes through review programmatically on
  its way to rest, because confirm_stop lands there by design. That keeps the tested
  path intact and leaves a natural place to insert the screen — but when it becomes
  something the driver sees, this flow gains a stop before rest, which is a behaviour
  change to make deliberately rather than by accident.
• The deliberate-stop confirmation. request_stop / cancel_stop and
  stop_confirmation_pending are modelled and tested but unused on the device: the double
  tap calls request_stop and confirm_stop back to back. The double tap is itself the
  guard against a stray touch, so this is now about giving the driver a way to back out
  rather than about preventing an accident.

Review content stays thin until GNSS lands, but neither of these depends on it.