Skip to content

Stop the lock screen overheating the fingerprint reader - #7179

Draft
AdamWorley wants to merge 6 commits into
omacom:quattrofrom
AdamWorley:fingerprint-retry-backoff
Draft

AdamWorley wants to merge 6 commits into
omacom:quattrofrom
AdamWorley:fingerprint-retry-backoff

Conversation

@AdamWorley

@AdamWorley AdamWorley commented Aug 16, 2026 •

Copy link
Copy Markdown

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:

if (priv->temp_last_active) {
    alpha = exp (-passed_seconds / priv->temp_hot_seconds);
    priv->temp_current_ratio = alpha * priv->temp_current_ratio + 1 - alpha;
} else {
    alpha = exp (-passed_seconds / priv->temp_cold_seconds);
    priv->temp_current_ratio = alpha * priv->temp_current_ratio;
}
DEFAULT_TEMP_HOT_SECONDS 180s — time constant while a verify is open
DEFAULT_TEMP_COLD_SECONDS 540s — time constant while idle
TEMP_WARM_HOT_THRESH 0.731 — device starts refusing here
TEMP_HOT_WARM_THRESH 0.5 — the refusal latches until the ratio falls back under this

A 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:

-180 * ln((0.731 - 1) / (0.269 - 1)) = 180 seconds

Measured here: first arm 18:17:19, first Device disabled to prevent overheating at 18:20:21 — 182 seconds. Upek Touchstrip (147e:2016), which takes libfprint's defaults, as does every driver that doesn't set temp_hot_seconds itself. 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:

  • Back off on device errors. A failing verify returned instantly and retried at a flat 250ms, spinning PAM sessions as fast as they could be created — ~2.6 sessions/second for six minutes here. The lock screen was busy enough that a typed password never got checked, so it appeared to reject a correct password. Now exponential, 250ms to a 30s ceiling.
  • Only back off on fast errors. A swipe timeout returns the same PAM code as a broken reader; only elapsed time separates them (~0ms vs ~31s). Backing off on timeouts would leave a healthy reader unarmed. A failed attempt also raises both onError and onCompleted, 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.
  • Re-arm on user presence. LockView already emits wakeRequested() 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 from Service.qml and 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:

ok - re-arming on completion overheats the reader, so the guard has something to prevent
ok - the arming ceiling keeps libfprint below its cutoff, peaked at 0.577
ok - the duty cycle stays under what libfprint tolerates, got 30.0%
ok - quick attempts leave the reader responsive, waited 5.9s
ok - a full timeout still re-arms within two minutes, waited 77.1s
ok - blanking releases the reader so it can cool
ok - waking re-arms the reader after a blank rather than bailing on a stale attempt

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:

before after
reader arms 767 1
Device disabled to prevent overheating 760 0

Then 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 three omarchy-pkgs failures are pre-existing on quattro and unrelated.

Related: #7176.

Fixes #9913

AdamWorley and others added 2 commits August 16, 2026 21:11
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
Copilot AI balanced review requested due to automatic review settings August 17, 2026 07:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

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
Copilot AI review requested due to automatic review settings August 17, 2026 07:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 invokes scheduleFingerprintRetry(false) before scheduleFingerprintRetry(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 in Service.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 {
@jcperdomoybarra

Copy link
Copy Markdown

Can confirm this reproduces on different hardware too — ELAN 04f3:0c4b, via the libfprint-tod proprietary driver path (not the Upek TouchChip in the PR description; see #7483 for that setup).

Hit it after a heavy testing session: libfprint's overheating protection kicked in (Device reported an error during verify: Device disabled to prevent overheating.), and the lock screen's fixed 250ms retry hammered it — 74 fingerprint PAM sessions in ~7 seconds, all erroring immediately, before I gave up and typed my password. Matches the mechanism described here exactly: a fast device-level error, no backoff, no idle window for the reader to cool down.

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.
@AdamWorley AdamWorley changed the title Back off lock screen fingerprint retries on device errors Stop the lock screen overheating the fingerprint reader Aug 19, 2026
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.
@jcperdomoybarra

Copy link
Copy Markdown

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: runBlank()'s fingerprintPam.abort() on screen-blank left fprintd's device claim stuck permanently on my hardware once — every subsequent unlock attempt failed instantly with Device was already claimed, for well over an hour, and it didn't self-clear. Even systemctl restart/kill fprintd as a non-interactive call hung (waiting on an unanswered polkit prompt in my case, so that part's environment-specific), but the underlying claim itself needed a full fprintd restart to release — no in-flight libusb transfer ever seemed to finish its cancel.

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 startFingerprint() already guards on displayBlanked, I ended up just not calling abort() in runBlank() — letting any in-flight verify finish on its own instead of cancelling it — which keeps "don't arm while blanked" for future attempts and avoided the wedge for me. Happy to share the exact diff if it's useful, or this may just be a quirk of my driver stack specifically.

@AdamWorley

Copy link
Copy Markdown
Author

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

@omarchybot

Copy link
Copy Markdown
Collaborator

Re-reviewed at 6aec521. Ran test/shell.d/lock-fingerprint-backoff-test.sh on a disposable VM with the shell actually loaded from this branch: 54 assertions, all pass. Everything below comes from reading the source and from a probe driving your real updateThermalRatio() / thermalCooldownMs() bodies, not from the suite.

@jcperdomoybarra's stuck claim has a mechanism, and the workaround you landed on is the right one. Quickshell cannot cancel a PAM conversation gracefully. PamContext::abort() goes setActive(false) → abortConversation() → deleteLater(), and ~PamConversation() calls PamConversation::abort(), which is kill(childPid, SIGKILL); waitpid(...) (src/services/pam/conversation.cpp:54-61). The child dies inside pam_authenticate() and never reaches pam_end() (subprocess.cpp:125) — which is the call that makes pam_fprintd release its fprintd claim. So Device was already claimed after a blank is the expected result of runBlank()'s abort() rather than a TOD quirk; TOD just makes it stick, because a cancelled bulk transfer never completes. Dropping the abort() and letting the verify run out under the displayBlanked guard removes the SIGKILL entirely.

Worth knowing how often that fires: idleBlankTimer.interval is 5000 and every wake re-arms it, so a user who wakes the screen and hesitates five seconds has their live 30s verify SIGKILLed. That is most wake cycles, not an edge case.

If the abort() goes, runBlank()'s updateThermalRatio(false) has to go with it, or the estimate books the reader as cool while a verify is still armed. handleFingerprintFinished() already disarms it on the real completion.

A suspend while a verify is armed costs about six minutes of fingerprint on resume. updateThermalRatio() integrates raw Date.now() deltas with no clamp, so any wall-clock gap while thermalArmed is true is charged as heating at the full 180s constant. Driving your own function bodies:

suspend   300s armed -> ratio 0.861921  cooldown 294.1s (4.90 min)
suspend   600s armed -> ratio 0.973920  cooldown 360.0s (6.00 min)
suspend  3600s armed -> ratio 1.000000  cooldown 374.3s (6.24 min)

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 Math.max(250, thermalCooldownMs()) parks the retry 374s out. nudgeFingerprint() cannot rescue it, because startFingerprint() recomputes the same cooldown; and the UI still shows the fingerprint glyph throughout, so it reads as the reader being dead. Clamping passed on the armed branch to the longest a single verify can last would cover it, since no legitimate armed interval exceeds one verify timeout.

Copilot's comment on line 334 does not hold, worth saying before you spend time on it. Quickshell's PamContext emits in a fixed order: onError() does emit error(...) then emit completed(PamResult::Error) (src/services/pam/qml.cpp:203-207), and the header documents it — "A completed(PamResult.Error) will be emitted after this event." So scheduleFingerprintRetry(true) always runs first, fingerprintAttemptErrored is set, and the false call returns at your line 332. The ordering it describes cannot occur. The one thing I would change is the comment at line 322: it claims order-independence the code does not actually have, and the code is only fine because quickshell's order is documented.

The nudge still undercuts the ceiling. Every keystroke raises wakeRequested() (LockView.qml:166,178), so during input the real floor is nudgeFingerprint()'s 2000ms cooldown, not the 30s backoff ceiling. Against a wedged reader that errors instantly — which consumes no thermal budget, so the ceiling does not engage either — someone typing a password sustains roughly one fingerprint PAM session every two seconds, concurrent with the password conversation. Guarding the nudge on authenticatingPassword, or flooring it at the current backoff, closes it.

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 startFingerprint() returning early on displayBlanked the sensor is unclaimed, the touch raises no wakeRequested, and the user has to hit a key first. Worth naming in the PR body — it is a real behaviour change and not obvious from "waking arms it immediately".

Smaller: if (!fingerprintPam.start()) at line 305 schedules no retry, and nudgeFingerprint() needs a running timer, so a synchronous start failure leaves the reader disarmed for the rest of the lock. Quickshell returns false without emitting anything on config-directory, config-file and getpwuid_r failures (qml.cpp:31-85). Near-unreachable, since fingerprintConfigured already checks the pam file, but it is a dead end. Same shape at line 512, where fingerprintPam.abort() leaves fingerprintAuthenticating set — the exact wedge 34ad8b2 fixed in runBlank().

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: PamSubprocess::conversation() allocates responses at subprocess.cpp:161 and hands it over at :200, but the fail: label frees responseArray at :204, which is the pam_response** out-parameter and not the block. Frame #4 of that report being libjemalloc is what an invalid free looks like. The issue's own journal shows a single arm and a single 30s timeout rather than a retry storm, so the 250ms loop is not the cause either. What this PR does is cut the number of PAM conversations by orders of magnitude, which makes the crash much rarer without removing it. The overlapping-subprocess mechanism in #7645 and #7172 also survives, because abortConversation() uses deleteLater(), so the old child is still alive at the moment QML sees active === false and starts a new one.

Password fallback was the other thing checked: it stays live throughout. passwordPam is a separate context, inputEnabled is bound to lockRequested alone, and nothing added here gates submitPassword() on fingerprint state, thermal cooldown, backoff or blanking.

Nothing pushed — it is a draft and you say more is coming. Waiting on you.

@bmcswee

bmcswee commented Aug 27, 2026

Copy link
Copy Markdown

Independent confirmation of the duty-cycle claim, from a different measurement
path and on a sensor class that never trips the thermal latch — so this lands
as a standalone power argument for "don't arm the reader while the display is
blanked," separate from the overheating one.

Setup: ThinkPad T14 Gen 1, Omarchy 4.0.1-1, Hyprland 0.56.2, quickshell
0.3.1-1, kernel 7.1.9-arch1-2, fprintd 1.94.5-2, libfprint 1.94.100-1.
Synaptics Prometheus MIS Touch (06cb:00bd) — a press sensor, not a swipe
sensor. It never overheats and fingerprint unlock works on first touch.

Rather than counting journal lines, I read the kernel's USB runtime-PM counters
for the reader, which measure armed time directly:

$ cat /sys/bus/usb/devices/4-3/power/runtime_active_time      # 101681594 ms
$ cat /sys/bus/usb/devices/4-3/power/runtime_suspended_time   #  54514683 ms
Uptime 47.6 h
Reader active 28.24 h
Reader suspended 15.14 h
Duty cycle 65% active
omarchy-lock-fingerprint PAM sessions since boot 3,363

The two independent sources agree almost exactly:

3363 spawns x 30.05s = 28.07 h armed   (journal)
runtime_active_time  = 28.24 h         (kernel)   -> 99.4% agreement

So "a locked screen holds the reader open essentially 100% of the time" is
measurably correct: every hour spent locked is an hour the sensor is armed. On
this machine that was 28 of 47 hours of uptime.

The cadence here is the slow variant AdamWorley flagged above — each verify runs
its full ~30s timeout and returns PAM_AUTHINFO_UNAVAIL (9), then
fingerprintRetryTimer re-arms 250 ms later, forever:

09:16:13  Starting pam session (pid 2288310)
09:16:43  Verification timed out
09:16:44  Starting pam session (pid 2289704)
09:17:14  Verification timed out
          ... until unlock

Two things this adds to the case for the blanking guard specifically:

  1. Failure-keyed backoff would not help here. Nothing is failing. Every
    cycle is a legitimate "nobody touched the sensor" timeout on healthy
    hardware, already naturally spaced at 30s. Only a rule that stops arming —
    the blanked-display guard, or a duty-cycle cap — changes this machine's
    behavior.

  2. There is a cost on readers that never latch. The device never
    autosuspends for the entire lock, so beyond the sensor's own draw it holds a
    USB device active on a laptop that is otherwise idle overnight. The thermal
    argument doesn't apply to this reader at all, and the guard is still clearly
    worth it.

I have not measured wattage (this machine is on AC), so I'm claiming duty cycle
only, not a power figure.

assada added a commit to assada/omarchy-t480-fingerprint that referenced this pull request Sep 5, 2026
## 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.
@4A616D6573

Copy link
Copy Markdown

Adding a fourth vendor and the longest non-recovery window in the thread.

Setup: Goodix 27c6:533c (Shenzhen Goodix) on the proprietary TOD path — libfprint-tod 1.95.2+tod1-1 + libfprint-goodix-53xc 0.0.6-2, fprintd 1.94.5-2, Omarchy 4.0.4-1.

Measured over one boot:

Device disabled to prevent overheating 4,398
first → last 09:05:30 → 13:23:48 (~4h18m)
active minutes 134 (median 42/min, max 43, mean 32.8)
fprintd cost 5m 725ms CPU over 2h28m wall, 37.9M peak

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. idleBlankTimer gates only on authenticatingPassword, not the combined authenticating state, and runBlank() just calls omarchy-brightness-* off — it never releases the fingerprint PAM. So the entire 4h18m storm ran with nothing stopping the reader from being re-armed. That isolates exactly the gap your "don't arm while blanked" change closes: on this hardware, leaving the arming unstopped is terminal inside ~3 minutes, and nothing on the current lock path ever stops it.

Vendor coverage: fourth, after Upek 147e:2016, ELAN 04f3:0c4b, and Synaptics 06cb:00bd — and the second independent confirmation on the libfprint-tod path alongside @jcperdomoybarra's ELAN.

@pelifix

pelifix commented Sep 17, 2026

Copy link
Copy Markdown

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 (0a5c:5843, libfprint-2-tod1-broadcom 5.15.021.0, libfprint-tod 1.95.2, fprintd 1.94.5), quattro r2153:

  • Locked 12:21:37, first Device disabled to prevent overheating at 12:24:40 — 183 s, against your predicted 180 s.
  • Then a flat cycle: 205 s refusing, 122 s available, repeating unchanged for the next four hours.
  • 31,534 refusals in 3 h 50 min, ~4/s, each one a forked PAM subprocess returning code 9 (PAM_AUTHINFO_UNAVAIL).

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.

@omarchybot

Copy link
Copy Markdown
Collaborator

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.

@prabhatCH

Copy link
Copy Markdown

Hardware report: Dell XPS 15 9500, Goodix 27c6:533c, Omarchy 4.0.6-1, fprintd 1.94.5-2, libfprint-tod 1.95.2+tod1-1, and libfprint-goodix-53xc 0.0.6-2.

We previously observed repeated Device disabled to prevent overheating failures on this reader while locked. Releasing fingerprint PAM when the display blanks and pacing retries helped restore usable lock-screen fingerprint authentication in a local plugin.

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 wakeRequested() from a click/key/pointer event. Otherwise the owner had to click the password field before a finger touch would work.

Our combined local workaround now follows PrepareForSleep, waits 1.5 seconds after resume, retains known enrollment rather than immediately probing it (the journal showed transient ListEnrolledFingers authorization denials), clears the blanked flag, and rearms scanning. With a 30-second blank timeout and a resident fprintd service, the owner confirmed lid-open followed directly by a finger touch now unlocks successfully.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Lock screen keeps fingerprint PAM armed for the whole lock, wedging USB imaging readers

8 participants