Repository navigation
Stop the lock screen overheating the fingerprint reader - #7179
AdamWorley wants to merge 6 commits into
Conversation
The lock screen retried fingerprint auth on a flat 250ms timer whenever the PAM context errored. A device-level error returns instantly and keeps returning instantly, so the retry ran as fast as PAM sessions could be created — roughly 4 a second for as long as the screen stayed locked. On readers libfprint thermally throttles this is self-sustaining: the retries never leave the device idle long enough to cool out of its lockout, so fingerprint unlock cannot succeed for the whole lock and the journal fills with tens of thousands of errors. Separate the two failure modes. A swipe that did not match is a real attempt and keeps the responsive 250ms delay; a device error now backs off exponentially to a 30s ceiling, which drops a stuck reader from ~240 retries a minute to 8 and leaves it idle long enough to recover.
The first pass counted every failed attempt the same way, which two field traces showed was wrong. PamContext raises onError and onCompleted for a single failed attempt. The onCompleted handler classified the device error as an ordinary failed swipe and zeroed the streak in the same millisecond onError had incremented it, so the backoff never advanced past its first step and the retry loop still ran at roughly 2.6 PAM sessions a second. Track whether the current attempt already errored so the device error wins it regardless of signal order. A swipe that times out reports the same PAM_AUTHINFO_UNAVAIL as a wedged reader, so counting both would grow the delay toward the 30s ceiling on a perfectly healthy device and leave the reader unarmed when the user finally swipes. Only errors that come back faster than the swipe wait indicate the hot loop, so gate the streak on elapsed time. The test now replays both PAM signals against the real function bodies rather than checking the delay curve in isolation, which is why it passed against the broken version. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DPU8cKnu5DchNMJqE89odF
Backing off keeps a wedged reader from being hammered, but it also leaves the reader unarmed for up to 30s at the ceiling. Someone who walks up and swipes during that gap gets nothing, which reads as the reader being broken even after it has recovered. The lock screen already raises wakeRequested() on key presses, typing, clicks and cursor movement, so it knows when someone is there. Use it: cut the remaining wait short and try immediately. The streak is deliberately kept, so a reader that is still wedged goes back to its long gaps rather than restarting the fast ramp, and a cooldown keeps a moving cursor from spinning the loop back up. A reader that has recovered clears the streak the usual way, by succeeding. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DPU8cKnu5DchNMJqE89odF
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (2)
test/shell.d/lock-fingerprint-backoff-test.sh:69
- The fixture always replays signals in the order
onError(device error) then completion, but the QML comments/assertions imply correctness regardless of which arrives first. Add a test case (and/or a fixture mode) that invokesscheduleFingerprintRetry(false)beforescheduleFingerprintRetry(true)for the same attempt and asserts the streak/backoff still increases across consecutive device errors.
// One authentication attempt: the reader is armed, time passes, then PAM
// reports back. A failure raises both onError and onCompleted, so replay both.
state.attempt = ({ elapsedMs, deviceError }) => {
state.fingerprintAttemptErrored = false
state.fingerprintAttemptStartedAt = state.clock
state.clock += elapsedMs
if (deviceError) state.scheduleFingerprintRetry(true)
state.scheduleFingerprintRetry(false)
return state.fingerprintRetryTimer.interval
}
test/shell.d/lock-fingerprint-backoff-test.sh:26
- These regexes hardcode a specific newline + two-space indentation pattern for the closing brace (
\\n \\}), making the test fail on formatting-only changes inService.qml. To reduce brittleness, make the closing brace match whitespace more flexibly (e.g.,\\n\\s*\\}) while still anchoring enough context to avoid accidental over-capture.
const delayBody = capture(
/function fingerprintRetryDelay\(streak\) \{([\s\S]*?)\n \}/,
'the retry delay is computed by fingerprintRetryDelay()'
)
const scheduleBody = capture(
/function scheduleFingerprintRetry\(isDeviceError\) \{([\s\S]*?)\n \}/,
'the retry is scheduled by scheduleFingerprintRetry()'
)
| fingerprintErrorStreak += 1 | ||
| } else if (fingerprintAttemptErrored) { | ||
| return | ||
| } else { |
|
Can confirm this reproduces on different hardware too — ELAN Hit it after a heavy testing session: libfprint's overheating protection kicked in ( The device did recover on its own a few minutes later once nothing was hammering it, so the backoff approach here (rather than a hard disable) looks like the right fix — an exponential backoff would have let it recover mid-lock instead of me having to fall back to password. Happy to test this PR if useful. |
libfprint charges a device for the whole time it is armed, not for the time a finger is on it. fpi-device.c models heat as an exponential ratio that rises toward 1 with a 180s constant while a verify is open and decays with a 540s one while idle, refuses the device above 0.731, and holds that refusal until the ratio falls back under 0.5. An unswiped verify stays armed for its full timeout, and the lock screen re-arms as soon as it returns, so a locked screen keeps the reader open essentially all the time. From a cold start that reaches the cutoff in -180*ln((0.731-1)/(0.269-1)) = 180 seconds. Locally the first arm was at 18:17:19 and the first "Device disabled to prevent overheating" at 18:20:21 -- 182 seconds, on an Upek Touchstrip, which takes libfprint's defaults. It does not recover on its own either. The retry backoff added earlier keeps poking a refused device every 30s; those pokes are rejected too cheaply to matter and the ratio drifts down to 0.5, at which point the next poke arms for real, heats it back over the line, and the cycle repeats. The reader here sat refused for two hours and twenty minutes and only came back on a fprintd restart. Two changes, in order of how much they matter: Do not arm the reader while the display is blanked. Nobody is there to swipe it, so the whole cost is heat. Waking arms it immediately, which also means the reader is cold and ready exactly when someone walks up instead of part-way through a backoff. Mirror libfprint's ratio and refuse to arm above 0.5 -- its own clear-threshold, so the lock screen stops a full band short of the cutoff and never contends with a latched refusal. This bounds the awake-but-not-swiping case, which blanking does not cover. A retry now waits for whichever is longer, its backoff or the sensor. The test drives the real policy against an independent implementation of libfprint's model: unguarded arming overheats, the guard holds the duty cycle at 30% against a tolerance of 47%, and libfprint's ratio peaks at 0.577 over a simulated hour of a user who never swipes.
Blanking releases the reader so it can cool, but PAM's abort() does not raise completed, so fingerprintAuthenticating stayed set against an attempt that was already gone. Every later startFingerprint() returned early on that flag, leaving the reader disarmed for the rest of the lock: the screen came back and the sensor was dead. Clear the flag where the attempt is cancelled. Measured over a five minute lock, before and after the gate: 767 arms and 760 "Device disabled to prevent overheating" become 1 arm and none.
handleFingerprintFinished() returned on !lockRequested before recording that the attempt had ended, so an attempt completing after unlock left the estimate integrating as though the reader were still armed.
|
Following up on my earlier comment — I applied this patch locally on 04f3:0c4b/libfprint-tod (ThinkPad E15 Gen3 AMD) and the backoff itself works well, thanks. One related thing worth flagging, found after a couple of days of real use: I don't have visibility into whether this is a general fprintd/libfprint-tod interaction or specific to the ELAN TOD driver's handling of a cancelled bulk transfer. Since |
|
Hi @jcperdomoybarra, Thanks for checking this and sorry for the delay in responding, I found that my initial changes helped a little but still had issues if left long enough and so I have been working on this a little more and should have some more changes to push up once I'm happy with it on my machine |
|
Re-reviewed at 6aec521. Ran @jcperdomoybarra's stuck claim has a mechanism, and the workaround you landed on is the right one. Quickshell cannot cancel a PAM conversation gracefully. Worth knowing how often that fires: If the A suspend while a verify is armed costs about six minutes of fingerprint on resume. The precondition is a verify armed at suspend, which is the ordinary lid-close path — the lock arms the reader and the lid suspends the machine well inside the 5s blank window. On resume the stale conversation errors, elapsed is the whole suspend so it does not count as fast, the streak correctly resets to 0, and then Copilot's comment on line 334 does not hold, worth saying before you spend time on it. Quickshell's The nudge still undercuts the ceiling. Every keystroke raises Touch-to-unlock from a dark screen goes away, which is a maintainer call rather than a defect. Today the reader is armed continuously, so on a machine where the sensor is not the power button you can walk up to a dark screen and just touch it. With Smaller: On #7645 — it is not this PR's to fix, and I would not let it be closed by this. That crash is an invalid free inside quickshell: Password fallback was the other thing checked: it stays live throughout. Nothing pushed — it is a draft and you say more is coming. Waiting on you. |
|
Independent confirmation of the duty-cycle claim, from a different measurement Setup: ThinkPad T14 Gen 1, Omarchy 4.0.1-1, Hyprland 0.56.2, quickshell Rather than counting journal lines, I read the kernel's USB runtime-PM counters
The two independent sources agree almost exactly: So "a locked screen holds the reader open essentially 100% of the time" is The cadence here is the slow variant AdamWorley flagged above — each verify runs Two things this adds to the case for the blanking guard specifically:
I have not measured wattage (this machine is on AC), so I'm claiming duty cycle |
## What happens today
After a resume the reader lights up but reports every finger as
unrecognized. Sometimes. Other resume cycles are fine, which is what
made this hard to pin down.
## Root cause
Omarchy Quattro locks the screen *before* the machine sleeps:
`omarchy-sleep-lock.service` holds a `delay` sleep inhibitor and runs
`omarchy-system-sleep-lock`, which waits for the lock to report
`secure`. The lock screen arms fingerprint auth the moment the session
becomes secure (`shell/plugins/lock/Service.qml`, `onSecureStateChanged`
→ `startFingerprint()`), so a `pam_fprintd` verify is almost always in
flight when the machine actually suspends.
`python-validity` runs that verify on a thread and holds a TLS session
with the sensor. The suspend resets the USB device under that session,
so the call fails inside libusb — and its error path (python-validity
0.15, `dbus_service/dbus-service:129-131`) does two damaging things:
```python
except usb_core.USBError as e:
logging.exception(e)
self.VerifyStatus('verify-no-match', True) # not a device error
loop.quit() # the driver exits
```
* `verify-no-match` is why the lock screen says the finger was not
recognized instead of showing a device problem.
* `loop.quit()` ends the daemon with status **0**, so the packaged
`Restart=on-failure` never brings it back. The packaged udev rule only
starts the driver on a USB `add`/`change` event, and a resume that
merely resets the device emits neither.
Whether that verify was in flight at the moment of the suspend is
exactly what made the failure intermittent.
The hook this PR removes treated the symptom instead: it stopped both
services before sleep, restarted them afterwards, and `SIGKILL`ed the
lock screen's PAM subprocesses (matched as "a `quickshell` process whose
parent is also `quickshell`"). Three problems with that:
1. It ran in `post`, after the driver had already died.
2. It depended on an undocumented Quickshell implementation detail, and
could not tell a fingerprint PAM subprocess from a password one.
3. Its two 10-second polls lived in a `/usr/lib/systemd/system-sleep`
script, and `systemd-sleep` waits for every hook before it finishes the
resume — so every wake paid for them, and the kill landed on processes
that were still frozen.
## The fix
`open-fprintd` already publishes the repair call for this case, and both
packages ship it (open-fprintd 0.7 `openfprintd/manager.py:64-85`,
python-validity 0.15 `dbus_service/dbus-service:72-77`):
`Manager.Resume()` makes the driver run `tls.reset()` +
`init.open_common()`, which re-opens the sensor in place. Nothing
restarts, so a live PAM claim keeps working.
* **New `omarchy-t480-fingerprint-resume.service`**, ordered `After=`
the four sleep targets. It waits for `06cb:009a` to return to the bus,
calls `Manager.Resume()`, and restarts `open-fprintd` +
`python3-validity` **only** when the driver is gone or the re-open
failed. Because it is a unit and not a sleep hook, its waits happen
after the resume is complete and no longer delay the wake.
* **New drop-in for `python3-validity.service`** with `Restart=always` /
`RestartSec=10`, so an exit on a libusb error is systemd's problem.
`RestartSec` deliberately stays under the driver's own "no more than ten
starts per minute" backoff.
* **The `system-sleep` hook is gone.** No service stop/start around
sleep, and nothing kills Quickshell processes any more.
* **Exactly one recovery path.** The setup removes the legacy hook and
disables `python3-validity-suspend-hotfix.service` (restarts both
services after every resume, dropping live claims),
`open-fprintd-suspend.service` (no ordering against the suspend itself,
so its `Suspend()` can land after the resume and park the backend), and
`open-fprintd-resume.service` (no ordering against the new unit, and two
concurrent re-opens race on the same sensor).
* `--check` keeps `Resume recovery` and gains a `Driver restart` line.
## Validation
* `.github/test-resume.sh` replaces `test-sleep-hook.sh`: five scenarios
against fake `systemctl`/`gdbus`/`logger` — healthy resume (asserts
**no** restart happens), dead driver, failed re-open, unrecoverable
backend (exit 1), and a reader that never comes back. Plus a consistency
check that the unit, the setup script and the remove script agree on the
path of the resume script.
* Mutation-checked: making the script always restart fails the healthy
scenario; skipping the driver liveness check fails the dead-driver
scenario.
* `shellcheck` and `bash -n` clean on the new file list.
* `systemd-analyze verify` on the unit (added as a CI step; it caught an
invalid `Condition…` key while writing this), and `systemd-analyze
cat-config` confirms the drop-in turns `Restart=no` into
`Restart=always` + `RestartSec=10`.
## Upgrading
Re-running `install.sh`, or `Setup > Security > Fingerprint`, migrates
an existing install: the old hook is deleted from
`/usr/lib/systemd/system-sleep` and from `~/.local/lib`, the unit is
enabled, and the drop-in is installed. `Remove > Security > Fingerprint`
and `uninstall.sh` clean up both the new files and the legacy hook.
## Known limit
The verify that is in flight when the machine suspends still fails once,
so the first touch after a resume can report a mismatch; Omarchy arms a
new scan by itself, so the next touch works. Releasing the claim
*before* the suspend belongs in the lock screen, and it is not specific
to this reader — that half is proposed upstream in
[omacom/omarchy#7158](omacom/omarchy#7158)
(park fingerprint auth across the suspend window) and
[omacom/omarchy#7179](omacom/omarchy#7179)
(back off the 250 ms retry on device errors). The
`verify-no-match`-plus-exit behaviour is worth reporting to
[uunicorn/python-validity](https://github.com/uunicorn/python-validity)
as well.
|
Adding a fourth vendor and the longest non-recovery window in the thread. Setup: Goodix Measured over one boot:
Sustained ~43/min is roughly one PAM session every 1.4s — the fixed 250ms re-arm plus ~1.1s of per-session overhead through PAM/fprintd (the refusal itself returns instantly). It never recovered. The ratio never fell back under the latch across the whole 4h18m; the reader only worked again after I replaced the driver outright. Consistent with your 2h20m. What I think is most useful for this PR: the blanking path already exists in 4.0.4, but it does not stop the arming. Vendor coverage: fourth, after Upek |
|
Independent confirmation on a second sensor, since "this isn't specific to one sensor" is doing a lot of work in your write-up. Broadcom CV3 Citadel (
Two different TOD drivers landing within 3 s of your prediction is about as good as that model gets. The latch is what a user actually feels: come back inside three minutes and the finger works, come back after fifteen and it's a coin toss. That's the bug report we started from. Your oscillation argument holds up here too. Gating the arm on display state instead — armed only while a display is awake, live for 45 s after it blanks, re-armed on wake — gives 0 refusals across a 15-minute lock and a first-touch read on return. The reader is rested because nothing touched it while nobody was there. Same shape as #12201. |
|
The fast-error backoff is superseded by merged #7158. The thermal duty-cycle model and stopping scans while the display is blank remain unmerged; healthy 30-second timeouts still re-arm. Keeping this open for that remaining prevention policy, with the retry path needing a rebase. GPT-6 in Codex and Claude Opus 5.5 Medium checked the coverage against the landed source; Claude's agreement does not guarantee independence. This closure review was read-only and did not rerun runtime tests. |
|
Hardware report: Dell XPS 15 9500, Goodix We previously observed repeated One integration detail surfaced during subsequent lid-close tests: after pausing scanning on display blank, resume must also clear the blanked state and rearm scanning without relying on Our combined local workaround now follows We have not tested this PR's thermal model independently, nor completed overnight-sleep or cold-boot validation. Sharing the blank/resume interaction as an integration case to cover alongside the overheating fix. Related: #9919 and #8561. |
The lock screen overheats the fingerprint reader about three minutes after the screen locks, and then never lets it recover.
What happens
libfprint charges a device for the time it is armed, not for the time a finger is on it. From
fpi-device.c:DEFAULT_TEMP_HOT_SECONDSDEFAULT_TEMP_COLD_SECONDSTEMP_WARM_HOT_THRESHTEMP_HOT_WARM_THRESHA verify nobody swipes stays armed for its full ~30s timeout, and
handleFingerprintFinished()re-arms the moment it returns. So a locked screen holds the reader open essentially 100% of the time. From libfprint's cold start of 0.269 that reaches 0.731 in:Measured here: first arm
18:17:19, firstDevice disabled to prevent overheatingat18:20:21— 182 seconds. Upek Touchstrip (147e:2016), which takes libfprint's defaults, as does every driver that doesn't settemp_hot_secondsitself. This isn't specific to one sensor.Why it doesn't recover
Backing off on errors isn't enough on its own. A refused device returns instantly, so those retries are too cheap to heat it and the ratio drifts down toward 0.5 — at which point the next retry arms for real, holds 30s, and pushes it straight back over. It oscillates around the latch threshold indefinitely. The reader here sat refused for 2h20m and only came back on a
systemctl restart fprintd.The fix
Don't arm the reader while the display is blanked. Nobody is there to swipe it, so the entire cost is heat. Waking arms it immediately — which also means the reader is cold and ready when someone walks up, rather than part-way through a backoff.
Mirror libfprint's ratio and refuse to arm above 0.5. That's libfprint's own clear-threshold, so the lock screen stops a full band short of the cut-off and never contends with a latched refusal. This bounds the awake-but-not-swiping case that blanking doesn't cover. A scheduled retry waits for whichever is longer, its backoff or the sensor.
The sustainable duty cycle is
3d/(1+2d) < 0.731, i.e. d < 47%. The guard settles at 30%.Also here
Three smaller fixes to the same path, each of which stands on its own:
onErrorandonCompleted, so the device error has to win the attempt whichever signal lands first — otherwise the completion resets the streak and the backoff never advances past one step.LockViewalready emitswakeRequested()on key press, typing, click and cursor movement.Testing
test/shell.d/lock-fingerprint-backoff-test.sh, 54 assertions. It extracts the real function bodies fromService.qmland runs them against a stand-in for the QML root, so it exercises the state machine rather than a paraphrase of it.The thermal cases drive the real arming policy against an independent implementation of libfprint's model:
Mutation-tested: raising the ceiling, dropping the cooldown, removing the blanking gate, letting a retry ignore the cooldown, and leaving the in-flight flag set on blank each fail the suite.
Measured on hardware over a five minute lock, before and after:
Device disabled to prevent overheatingThen confirmed end to end across three locks, including one of 3m38s that spans the old 180-second failure point: all three unlocked by fingerprint on first touch, 5 arms total, no overheat events, and the error streak never left 0.
./test/all: 2365 assertions pass. The threeomarchy-pkgsfailures are pre-existing onquattroand unrelated.Related: #7176.
Fixes #9913