Skip to content

Back off fingerprint lock retries on hard device errors - #12544

Closed
thabopal wants to merge 1 commit into
omacom:quattrofrom
thabopal:fix-fingerprint-lock-retry-backoff
Closed

thabopal wants to merge 1 commit into
omacom:quattrofrom
thabopal:fix-fingerprint-lock-retry-backoff

Conversation

@thabopal

@thabopal thabopal commented Sep 19, 2026 •

Copy link
Copy Markdown

Summary

  • The lock screen's fingerprint retry timer (shell/plugins/lock/Service.qml) retried at a flat 250ms on any fingerprintPam.onError, the same interval used for a genuine completed-no-match.
  • On the Goodix GXFP5130 (and reportedly other readers), a run of consecutive hard device errors polled that fast trips the sensor's thermal cutoff (Device disabled to prevent overheating, logged by fprintd), which then locks out fingerprint auth entirely — lock screen and PAM (sudo, polkit) alike — until the device is manually reset (gxfp_recovery --reset-mcu --reset-sensor).
  • This adds exponential backoff (2s, doubling, capped at 30s) specifically on the onError path, while a genuine no-match completion still retries at the fast 250ms base and resets the backoff.

Test plan

  • test/shell.d/lock-fingerprint-indicator-test.sh — passes
  • test/shell.d/lock-blank-fingerprint-test.sh — passes
  • Full test/all suite not run (scoped change, targeted tests above cover the touched behavior)

Disclosure

This fix was diagnosed and written by Claude (Sonnet 5, via Claude Code) working on the reporter's machine, from a live reproduction: journalctl -u fprintd.service showed a continuous ~1-2s stream of Device disabled to prevent overheating correlating with a lock-screen retry storm, and Service.qml's mtime matched the omarchy 4.0.4-1 package (installed 2026-09-16), which had silently reverted an earlier local patch doing the same thing.

🤖 Generated with Claude Code

A hard device error (as opposed to a completed no-match) retried at
the same flat 250ms interval as a genuine no-match. Some readers,
including the Goodix GXFP5130, trip their thermal cutoff when polled
this fast through a run of consecutive errors rather than an actual
touch, which then locks fingerprint auth out entirely (lock screen
and PAM alike) until the sensor is manually reset. Hard errors now
back off exponentially (2s, capped at 30s); a genuine no-match still
retries at the fast base interval and resets the backoff.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LonAaqr1pXKCGe9zmfXFB1
@llstrk

llstrk commented Sep 25, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

The backoff in this PR does not take effect with any released Quickshell version. After a hard fingerprint error the lock screen still retries after 250 ms, the same as the base branch. No regression was found: runtime behavior matches the base branch.

The completion handler overwrites the error backoff

Quickshell's PamContext always emits completed(PamResult.Error) right after error (Quickshell v0.3.1 src/services/pam/qml.cpp:203-207, documented in qml.hpp:102-105; unchanged since the PAM service was added). The PR's handleFingerprintFinished treats every non-success result as a genuine no-match, so it runs after onError and undoes it:

Hard error, e.g. "Device disabled to prevent overheating"

Quickshell signal        Service.qml at PR head
error(...)          -->  onError: interval = 2000, restart(), backoff -> 4000
completed(Error)    -->  handleFingerprintFinished: backoff = 2000, interval = 250, restart()

Result: retry after 250 ms, backoff back at 2000 (same as base)

Impact: The 2 s doubling to 30 s never happens, so the retry storm described in the PR is not reduced.

Suggested change: Make the split inside handleFingerprintFinished based on the result, and stop restarting the timer in onError. With pam_fprintd as the only module in Omarchy's lock PAM file, a finger mismatch always ends as PamResult.MaxTries (three no-match attempts end in PAM_MAXTRIES). PamResult.Failed on this context comes from D-Bus or VerifyStart failures, not from a mismatch. MaxTries is the reliable "genuine no-match" signal, and both Failed and Error are device or daemon faults.

A working backoff would also delay fingerprint unlock on an idle lock screen

Omarchy writes the lock PAM file as a bare auth required pam_fprintd.so (bin/omarchy-apply-lock), so pam_fprintd's 30 s default timeout applies. Ordinary outcomes reach the same Error path as the overheating fault:

pam_fprintd 1.94.5 outcome PAM code Service.qml sees
Three finger mismatches PAM_MAXTRIES completed(MaxTries)
30 s timeout, nobody touched the reader PAM_AUTHINFO_UNAVAIL error, then completed(Error)
Reader already claimed by another client (e.g. a sudo prompt) PAM_AUTHINFO_UNAVAIL error, then completed(Error)
Device too hot or disconnected PAM_AUTHINFO_UNAVAIL error, then completed(Error)
VerifyStart D-Bus error PAM_AUTH_ERR completed(Failed)

Impact: If the first finding is fixed by backing off on every Error, an idle lock backs off after each 30 s timeout. After about 2.5 minutes the reader alternates between roughly 30 s listening and 30 s not listening. A touch during a gap gets no response for up to 30 s, compared with about 250 ms on the base branch. The fingerprint indicator stays visible throughout, because it follows fingerprintConfigured.

Suggested change: Back off only on fast failures. For example, record the start time in startFingerprint() and grow the backoff only when a fault result arrives within a few seconds. Treat an Error after a long attempt (the 30 s timeout) as healthy: retry at the base interval and reset the backoff. Also reset fingerprintErrorBackoffMs in resetAuthenticationState() and on success. Today it is only reset on the no-match branch, so once the backoff works, a large value would carry into the next lock.

Optional test improvement: Neither test in the PR's test plan reaches the changed code. lock-blank-fingerprint-test.sh checks blank-timer source lines, and lock-fingerprint-indicator-test.sh loads only LockView.qml, so both give the same result with or without the first finding. A check that sends error and then completed(PamResult.Error) and asserts the resulting timer interval and backoff value would catch it.

Verified: The PR leaves password authentication, fingerprint success and unlock, and timer stop and PAM abort on reset unchanged. The fingerprint indicator is unaffected. The PR also applies to the current quattro tip, where the fingerprint section of Service.qml is identical to the PR's merge-base.


Review information

Test scope: Source review of the PR head, its merge-base and the current quattro tip, plus Quickshell v0.3.1 PAM code (also checked at Omarchy's quickshell-git pin), fprintd/pam_fprintd 1.94.5, libfprint 1.94.100 and Linux-PAM 1.7.2. Nothing was executed. No fingerprint hardware, PAM stack or GXFP5130 driver was tested, so the reader's thermal and recovery behavior under any retry schedule is untested.

AI process: Opus 5.5 Medium coordination and synthesis, independent Opus 5.5 Xhigh and GPT 6 Sol Xhigh technical assessments with targeted follow-up questions, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed by Claude Opus 5.5 and run on an Omarchy ISO worker, with a second opinion from Codex at medium effort. The retry storm you describe is real, but this change doesn't slow it down: after a hard error the lock screen still retries 250 ms later, the same as quattro.

Why. Quickshell's PamContext follows every error with completed(PamResult.Error) (src/services/pam/qml.cpp, PamContext::onError, unchanged in 0.3.1). Here onError sets the timer to the backoff and doubles it, and then handleFingerprintFinished (shell/plugins/lock/Service.qml:263) treats that Error completion as a no-match. It resets the backoff to 2000 and the interval to 250 ms, and restarts the timer. @llstrk's review above found the same thing from the source.

Reproduced on the worker. I spliced the handleFingerprintFinished and onError handlers out of quattro and out of this head, verbatim, into a harness. It drives a real Quickshell 0.3.1 PamContext into a hard PAM error. Both fired error, then completed(Error), and retried after 250 ms with the backoff left at 2000. As a control, this head with completed(Error) ignored retried after 2000 ms, so the harness does tell the difference. On the same worker, lock-fingerprint-indicator-test.sh and lock-password-overflow-test.sh pass. lock-blank-fingerprint-test.sh and lock-stranded-recovery-test.sh did not run, because the worker has no node. Neither test reaches the changed handlers.

Fixing the order alone would not be enough. pam_fprintd returns PAM_AUTHINFO_UNAVAIL for its 30-second timeout and for a reader claimed by a sudo prompt, just as it does for a hot sensor. All of them arrive as error then completed(Error). Backing off on every error would leave an idle lock screen not listening for up to 30 s at a time. What sets a dead reader apart is how fast the attempt fails, not which signal reports it.

A competing fix already covers this. #11918 schedules the retry only from the completion, and it backs off only on attempts that fail within a second. A wrong finger or a timeout still retries at 250 ms. It has been verified on a worker and is labelled ready. #7179, #10393, #10653, #12461 and #13819 also target this loop. Codex, asked which of the seven fixes is best without being told my view, also preferred #11918. Its comparison is provisional: it couldn't read the other diffs from its sandbox, and it can read my session, so its agreement isn't independent. I've pushed nothing here, so that there's one fix in front of the maintainer rather than two.

Neither review could test a real GXFP5130. Whether the sensor recovers sooner under a backoff depends on hardware a worker doesn't have.

This now waits on the maintainer, who chooses between the competing fixes.

@omarchybot

Copy link
Copy Markdown
Collaborator

Thank you for this, @thabopal. #11918 fixes the same problem in a way the review judged better, so this is closed in favour of it. If it does not cover your case, please say so there.

Closed at the maintainer's request. The review comment above has the details; it was done by Claude Opus 5.5 with Codex Medium as a second opinion, whose agreement is not independent.

@omarchybot omarchybot closed this Oct 1, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

The replacement error-backoff fix is now shipped in merged #7158, including fast errors after the finger prompt. #11918 is being closed as superseded; this alternative remains closed.

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.

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

Labels

bug Something isn't working compatibility Make Omarchy work better on everything!

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants