Skip to content

Stop the lock fingerprint retry loop instead of slowing it - #12461

Open
alanwcurry-dev wants to merge 1 commit into
omacom:quattrofrom
alanwcurry-dev:lock-fingerprint-attempt-budget
Open

alanwcurry-dev wants to merge 1 commit into
omacom:quattrofrom
alanwcurry-dev:lock-fingerprint-attempt-budget

Conversation

@alanwcurry-dev

@alanwcurry-dev alanwcurry-dev commented Sep 18, 2026 •

Copy link
Copy Markdown

The problem

shell/plugins/lock/Service.qml at the current quattro tip still arms omarchy-lock-fingerprint every scan window for as long as the machine is locked, whatever #7158 did in between: an attempt that reaches the reader and finds no finger is the healthy case there, so it keeps MATCH_RETRY_MS (250 ms) and the loop never ends. On a press-type reader each arm waits ~30 s for a finger, so an unattended lock is never idle.

Measured on the reference machine (ASUS ExpertBook, FocalTech FT9365 2808:a57a, press sensor, one enrolled finger), from journalctl:

night lock-PAM sessions
Sep 11 70
Sep 12 1348
Sep 13 3680

The last night contains a single hour with 2972 sessions; 71% of consecutive sessions are under 0.5 s apart, the rest ~30 s apart — burst plus idle wait, the same shape @CoreyH reported in #11918 and the same loop @kirkules1000010 traced into a battery that flattened overnight. @makoni reports the same endless re-arm wedging a T1Bridge reader's Secure Enclave until the machine is power cycled (standardagents/t1bridge#14).

The change

Bound the loop at the reader instead of slowing it. An attempt that never reaches the reader already has its own pacing, so this only ends the scanning loop:

  • A budget on attempts that reached the reader (FingerprintModel.UNATTENDED_BUDGET, 6). Spent, the sensor pauses and is no longer armed.
  • Deliberate input hands it a fresh budget — a click on the lock, a tap or click in the password field, a keystroke, typing — rate-limited to one decision per cooldown (INTERACTION_COOLDOWN_MS) so a typing run is one decision rather than one per keystroke, and clearing the count even when the sensor is not paused, so a budget spent while the user was away cannot pause in front of them the moment they come back.
  • A resume clears a pause: the machine comes back under someone who is about to touch the reader, and one budget per wake keeps the bound across a night of suspends.
  • The user is told, below the field rather than inside it: the field's single line elides the sentence, and its error styling would read as a failed login on a lock that is only waiting.
  • status() gains fingerprintPaused and fingerprintUnattended.

Unchanged on purpose: an attempt that never reached the reader keeps its backoff, its unavailable notice and its retries, because that is how a reader that comes back is found again, and #12420's blank gate is the right fix for a display that is blanked regardless. This PR no longer makes promptless failures terminal — that is the one part of the original proposal that #7158's settled model covers differently.

Cases

case result
unattended press reader 6 sessions, one scan window apart, then fingerprint-paused: budget exhausted after 6 attempts (unit-tested)
pointer motion while paused no re-arm (static check; 0 events over 29 s in the original build)
deliberate input while paused one fingerprint-rearmed: interaction, fresh budget
deliberate input while not paused count cleared, no extra session
reader that never answers keeps backing off, keeps retrying, still reports unavailable
suspend/resume while paused pause cleared once per resume, one fresh budget
password path untouched

What was verified

  • The policy is unit-tested in test/shell.d/lock-fingerprint-retry-test.sh (extended, not a new file): an unattended reader must stop after exactly the budget and an unreached one must not, deliberate input refreshes once per cooldown, and a static check holds pointer motion off the re-arm path.
  • The lock service's own Quickshell harness (test/shell.d/fixtures/lock-fingerprint-service/shell.qml) was updated for the pause and passes its 41 checks: a run of attempts that reached the reader must spend the budget and leave the sensor unarmed, an attempt that never reached the reader must spend nothing of it, and a settle while paused must not arm a retry.
  • Both QML files lint with the same warning categories as the base (comm on the category lists is empty; LockView's six warnings are its unresolved project types under a bare qmllint).
  • The pause notice was rendered in a running lock preview on the reference machine: full sentence, outside the field, no elision, no collision with the existing unavailable notice.
  • The field's tap path uses the default TapHandler policy, which takes only a passive grab on press (qquicktaphandler.cpp calls setPassiveGrab for DragThreshold, and setExclusiveGrab only for the other policies), so the input keeps the press for its own cursor placement.

Not verified: a full locked cycle on hardware after this rewrite. The session counts above are from the original build of this change, measured while it lived in a plugin clone; the accounting and pause logic are the same, but the running trace has not been re-taken, and I would rather say so than imply otherwise.

@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.

Verified: in source review, the change bounds the fingerprint retry loop as described. Remaining points are the pause notice presentation, a narrower re-arm than the code comment states, and one suspend/resume path worth testing on hardware.

Details, from head f5124c9 read against Quickshell 0.3.1, fprintd 1.94.5 and libfprint 1.94.100 source:

  • At most 6 fingerprint sessions run per budget, with retries at 250, 500, 1000, 2000 and 4000 ms. pauseFingerprint stops the timer, and startFingerprint refuses while paused, which covers every start path.
  • Quickshell's PamContext::onError aborts the conversation, then emits error(...) followed by completed(PamResult.Error). The fingerprintOutcomeHandled flag makes that pair cost one slot.
  • pam_fprintd sends a PAM info message after every successful VerifyStart and on its 30 s timeout, so prompted failures and idle timeouts spend the budget. Claim refusals (including the AlreadyInUse case from Lock screen retries fingerprint PAM every 250ms with no backoff, preventing fprintd recovery #9905) return without any message and now pause at once instead of looping.
  • Pointer motion only emits wakeRequested. State resets on every lock and unlock, and the password path is unchanged.
  • The fingerprint code at the current quattro tip is unchanged from this PR's base. The tip's lock changes (video poster) do not touch these paths.

Pause notice is cut off in the password field

pauseFingerprint sets failureMessage to "Fingerprint paused \u2014 press a key or type your password" in source (54 characters). LockView.qml draws it in the single-line placeholder Text (elide: Text.ElideRight, no wrapping) inside the fixed 381 px field. The field font is 18 px (base-size 12, heading 16), and the margins plus fingerprint icon reserve leave roughly 267 to 291 px for text:

needed:    ~583 px   all 54 characters
available: ~291 px   "Fingerprint paused \u2014 pres…"  (rest elided)

The estimate uses JetBrains Mono's 0.6 em advance. The exact cut point depends on installed font metrics and was not checked in a running lock; at default sizing the notice fits only if glyphs average about 0.30 em or less. The notice also drives errorState, so an idle, unattended lock shows the red error border and italic error text, and the notice replaces any "Authentication failed (N)" text.

Impact: the user sees that fingerprint paused but not how to resume it, and an unattended lock looks like a failed login.

Suggested change: shorten the in-field text to about 24 characters (for example "Fingerprint paused"), or show the notice as a separate line outside the field with neutral styling.

Deliberate input refreshes the budget only after it is exhausted

The comment on rearmFingerprintFromInteraction says deliberate interaction should "hand the sensor a fresh budget", but the function returns early unless fingerprintPaused is already true. On a press reader:

t≈0      lock, session 1 (30 s timeout)
t≈2.5m   5 sessions spent; user returns, presses a key  -> ignored (not paused)
t≈3m     session 6 times out                            -> paused in front of the user

Impact: a user who returns during the last session can see the pause notice appear shortly after interacting.

Suggested change: reset fingerprintAttempts on deliberate input (still rate-limited) and restart only when paused, or reword the comment if pause-only re-arming is intended.

Worth testing: suspend and resume can end in the paused state

Traced in source; how often it happens depends on timing and was not observed:

  • Omarchy locks on lid close and on logind PrepareForSleep(true). On the same signal, fprintd suspends readers, and libfprint rejects open for a suspended device with FP_DEVICE_ERROR_BUSY.
  • focaltech_moc (the reader named in the PR) registers no suspend hook, so a running verify can be cancelled rather than suspended.
  • If a retry or the first session reaches Claim (or fails in VerifyStart) in that window, pam_fprintd returns without any PAM message. fingerprintFailureIsTerminal then treats that as terminal, even at zero attempts, and nothing re-arms on resume.

Impact if it occurs: after closing and reopening the lid, touching the reader does nothing until a key press or click.

Suggested change: check the journal for fingerprint-paused: terminal result 2 after a lock, suspend, resume cycle on a reader without a suspend hook. If it appears, a single re-arm on resume or lid open, or one or two backed-off retries for promptless failures, would keep the unattended bound.

Documentation note: the comment on fingerprintOutcomeHandled says a failed session emits both completed(Failed) and error(...). In Quickshell 0.3.1, PAM_AUTH_ERR emits only completed(Failed); the double emission is error(...) then completed(PamResult.Error), which includes the routine 30 s timeout. Since completed always follows error, scheduling retries only from onCompleted would also remove the need for the flag.

Click re-arm note: a left click on the password input itself is accepted by the TextInput and does not reach the background MouseArea, so it does not emit rearmRequested. Clicks elsewhere on the lock surface, key presses and typing do re-arm, which matches the notice text.

Design note: the lock blanks displays 5 s after locking. After about 3 minutes on a press reader, touching the reader on a dark screen does nothing until a key press, click or typing. This follows from the stop-instead-of-slow design; stating it in the description would help maintainers weigh it against a capped slow re-arm.


Review information

Test scope: source review of head f5124c9d89001bde8309e8797f446c850837a424, including Quickshell 0.3.1 PAM, fprintd 1.94.5, libfprint 1.94.100 driver and suspend code, and Qt 6 input delivery. No code was executed; no fingerprint hardware, live lock screen or suspend cycle was tested. The notice width is an estimate from source geometry and font metrics, not a screenshot. The PR's measured traces come from the author's earlier copy and were not reproduced.

AI process: Opus 5.5 Medium coordination and synthesis; independent Opus 5.5 Xhigh and GPT 6 Sol Xhigh technical assessments, with targeted follow-ups to cross-check single-reviewer points; 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

Merged #7158 resolves repeated immediate-error storms with capped backoff and unavailable feedback. It preserves healthy scan-timeout retries, so the proposed six-attempt terminal state and deliberate-input re-arm policy remain distinct. Keeping this open for the unattended scanning policy; please rebase the shared retry path.

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.

@makoni

makoni commented Oct 9, 2026

Copy link
Copy Markdown

A data point for the unattended-scanning policy, from a 2017 Touch Bar MacBook Pro (MacBookPro14,3) where Touch ID goes through T1Bridge. There, the healthy scan-timeout retries that #7158 deliberately keeps are exactly what breaks the reader.

Each lock-fingerprint session makes T1Bridge stop and restore its keybag relay, which reloads the keybag into the T1's Secure Enclave. With the lock left alone, it starts a new session every ~31 s. Twice on Oct 9, with nobody touching the machine and no suspend, the Secure Enclave started rejecting the keybag after 23 and 34 minutes of lock (43 and 65 clean rounds). After that every fingerprint request fails instantly (the Touch Bar prompt either flashes and disappears or doesn't show at all), and it took a full power-off to bring the Secure Enclave back both times. Details are in standardagents/t1bridge#14 (comment). That's a T1Bridge bug, but the trigger is the endless re-arm.

Tuning PAM didn't help: setting timeout=-1 on pam_fprintd didn't change the ~31 s cadence, because T1Bridge appears to cap each match at 30 s itself (MAX_MATCH_TIMEOUT). For now I've removed omarchy-lock-fingerprint on that machine, which is also what another T1Bridge user in that issue ended up doing.

A budget like this PR's would cap an unattended lock at six sessions, well short of where the wedge shows up. I haven't run this branch myself.

@makoni

makoni commented Oct 9, 2026

Copy link
Copy Markdown

Following up on my earlier comment: I tested this on that MacBookPro14,3 (T1Bridge Touch ID), and it kept the wedge away.

I applied this PR's diff at f5124c9 to the lock plugin of the Omarchy 4.0.4 I'm running (not quattro). All hunks applied, one with fuzz 2. I put the stock omarchy-lock-fingerprint back and restarted the shell. A quick check first: unlock by fingerprint and by password both work.

Then I locked it and left it alone for just over an hour, no suspend, no lid events:

  • Six fingerprint sessions, starting 31-35 s apart: each one ran the full scan window, plus the retry delays of 250 ms to 4 s.
  • About three minutes after locking, the log shows fingerprint-paused: budget exhausted after 6 attempts, and nothing touched the reader for the rest of the hour.
  • Over the whole lock T1Bridge's keybag relay was stopped and restored 7 times, with zero Secure Enclave rejections. On the same machine without this PR it went through 43 and 65 of those cycles and then wedged, after 23 and 34 minutes.
  • A key press gave fingerprint-rearmed: interaction, the next session matched, and the lock opened five seconds later.

So on T1 hardware the budget is the difference between Touch ID working in the morning and needing a full power-off. I haven't tested the suspend/resume path the community review flagged.

@jandrusk

Copy link
Copy Markdown

Distinct from #7158 (merged capped backoff): this is the unattended six-attempt terminal + deliberate-input re-arm policy. Still wanted for press-type / T1Bridge readers (#9905 cluster). Merge dirty — please rebase the shared retry path on current quattro.

@alanwcurry-dev

alanwcurry-dev commented Oct 12, 2026 •

Copy link
Copy Markdown
Author

Rebased onto the current quattro tip (4c1b4cb3): f5124c9 → e84c778a, one commit, MERGEABLE, +251/−3 over four files.

This is a rework rather than a literal conflict resolution. The shared retry path is now FingerprintModel.js, so the budget hooks into settleFingerprintAttempt() — and the accounting question the review raised is already answered there: that function is guarded per attempt by fingerprintAuthenticating, so one failed session spends one slot without a flag of its own, and the retry is scheduled from the settle path that both onCompleted and onError reach.

The review items, in order:

  • Pause notice elided in the field, and an idle lock painted as a failure. Fixed by moving it out of the field. It is now its own line below the field (fingerprintPausedNotice, the same pattern as the existing Fingerprint reader unavailable notice), so nothing elides and failureMessage is left alone — the field no longer draws the error border for a lock that is merely waiting. Rendered in a lock preview on the reference machine to check placement and wording.
  • Deliberate input refreshed the budget only after it was exhausted. Deliberate input now clears the count whether or not the sensor has paused, rate-limited by INTERACTION_COOLDOWN_MS, so a user who comes back during the last session keeps the budget instead of watching the pause appear right after they touched the machine. Restarting still happens only while paused.
  • Suspend and resume could end in the paused state. A resume clears a pause (fingerprint-rearmed: resume) and arms once, so the bound still holds across a night of suspends. Separately, the promptless case that could feed it is no longer terminal: a failure that never reached the reader keeps upstream's streak/backoff/unavailable path, and can still recover. That is also why the "promptless failure is terminal" part of the original is gone — it is the one part Fix fingerprint enrollment and lock-screen recovery #7158's model already covers, differently.
  • Which PAM signals pair — right, and the comment is corrected; nothing depends on the flag any more.
  • A click on the password input did not re-arm. Now covered: the input carries a TapHandler, and the default policy takes only a passive grab on press — qquicktaphandler.cpp calls setPassiveGrab() for DragThreshold and setExclusiveGrab() only for the other policies — so the tap is observed without the input losing the press for its own cursor placement.
  • Touching a dark screen does nothing while paused — stated in the description, as suggested.

One thing the seeded tests caught and this commit carries: the lock service's Quickshell harness asserted that a long run of reached attempts keeps retrying, which is exactly what the budget ends. It now asserts the pause instead (spends the budget, leaves the sensor unarmed, spends nothing on an attempt that never reached the reader, and does not arm a retry from a settle while paused).

Also: status() now exposes fingerprintPaused and fingerprintUnattended (renamed from fingerprintAttempts, since only attempts that reached the reader are counted).

@makoni — thank you for the T1Bridge measurement; it is the strongest evidence in the thread and it is why the budget stays this narrow: reached-device attempts only, so a reader that is genuinely unavailable is still found again.

What this does not have: a re-taken runtime trace on hardware after the rewrite. The unit tests, the lint comparison and the preview render are what I have; the measured session counts are from the original build.

@greptile-apps

greptile-apps Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[Medium impact] Changes fingerprint sensor retry logic to pause instead of backoff.

The PR still needs a fix before merging: ordinary timer stalls can restart a paused reader and grant another six attempts.

Findings

  1. P1 Stalls restart paused scans ▶
  2. P2 Resume stops the final scan ▶
  3. P2 Restart instructions disappear ▶

Summary

The PR adds a six-attempt limit for fingerprint scans that reach the reader.

  • Unattended fingerprint scans pause after six reader attempts.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Fingerprint attempt ends] --> B{Reached reader?}
  B -->|No| C[Keep existing backoff]
  B -->|Yes| D[Spend one attempt]
  D --> E{Six attempts spent?}
  E -->|No| F[Schedule next attempt]
  E -->|Yes| G[Pause reader]
  G --> H[Deliberate input or sleep restart]
  H --> I[Clear pause and refresh budget]
  I --> F
Loading

Reviews (2) · Last reviewed commit: "Bound unattended fingerprint scans on a ..." · Reviewed by Greptile

Comment on lines +310 to +314
if (fingerprintPaused) {
fingerprintPaused = false
fingerprintUnattended = 0
logEvent("fingerprint-rearmed: resume")
}

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.

P1 Stalls restart paused scans

restartFingerprintAfterSleep() clears the pause after any timer gap over three seconds, not just suspend. If waking a blanked display stalls the compositor past that threshold, the paused reader gets another six attempts without deliberate input. Repeated stalls can keep granting fresh attempts.

Keep timer gaps from clearing the unattended budget; use a confirmed resume event for that exception.

Comment on lines +310 to +312
if (fingerprintPaused) {
fingerprintPaused = false
fingerprintUnattended = 0

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.

P2 Resume stops the final scan

The resume path resets fingerprintUnattended only when the reader was already paused. If five attempts have finished and the sixth has prompted when the machine suspends, resume aborts that session and calls settleFingerprintAttempt(). That spends the sixth slot and immediately pauses the reader instead of restarting it. The user must press a key or click before trying their finger.

Reset the count before settling a session interrupted by suspend.

anchors.top: inputField.bottom
anchors.topMargin: 18
anchors.horizontalCenter: inputField.horizontalCenter
visible: root.fingerprintPaused && !root.fingerprintUnavailable

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.

P2 Restart instructions disappear

fingerprintPausedNotice is hidden when fingerprintUnavailable is true, but those states can occur together. Six attempts that prompt and then fail quickly spend the budget while also marking the reader unavailable. Retries stop, and the visible message does not tell the user how to restart them—even after the reader recovers.

Show the restart instruction whenever fingerprintPaused is true.

omacom#7158 paced the failures that never reach the reader, but an attempt that *does*
reach it and finds no finger is the healthy case there, so it keeps the fast
retry and the loop never ends: a press-type reader is re-armed every scan window
for as long as the machine stays locked. On the reference machine (FocalTech
FT9365, press sensor) three unattended nights produced 70, 1348 and 3680 lock-PAM
sessions, 2972 of them inside a single hour (omacom#9905), and the same endless re-arm
wedges T1Bridge readers until the machine is power cycled
(standardagents/t1bridge#14).

Bound the loop at the reader instead of slowing it:

- attempts that reached the reader are counted (UNATTENDED_BUDGET, 6), and the
  budget is terminal: the sensor pauses and stops being armed;
- deliberate input - a click, a tap or click in the password field, a keystroke,
  typing - hands it a fresh budget, rate-limited to one decision per cooldown so a
  typing run does not count as a new decision per keystroke, and it clears the
  count whether or not the sensor had paused, so a budget spent before the user
  came back cannot pause in front of them;
- a resume clears a pause: the machine comes back under someone who is about to
  touch the reader, and one budget per wake keeps the bound across a night of
  suspends;
- while paused the lock says so, below the field rather than inside it, because
  the field's single line elides the sentence and its error styling would read as
  a failed login on a lock that is only waiting.

An attempt that never reached the reader is unchanged: it keeps its backoff and
its unavailable notice, and keeps retrying, because that is how a reader that
comes back is found again.

The policy is unit-tested in test/shell.d/lock-fingerprint-retry-test.sh,
including an unattended reader that must stop after exactly the budget and an
unreached reader that must not, and the lock service's own quickshell harness
(spends the budget and pauses) carries the same two cases.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants