~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
docs(rekey): clarify transient contention during pending recovery (#7692)
Chanhyo Jung15df3e0ef8d4
diff --git a/changelog.d/7691.misc.md b/changelog.d/7691.misc.mdnew file mode 100644index 0000000000..ad48ab13c3--- /dev/null+++ b/changelog.d/7691.misc.md@@ -0,0 +1 @@+Clarify when pending-rekey recovery errors call for retrying transient contention rather than manual recovery.diff --git a/docs/security/rekey-recovery.md b/docs/security/rekey-recovery.mdindex 948340630f..9a1e36bace 100644--- a/docs/security/rekey-recovery.md+++ b/docs/security/rekey-recovery.md@@ -127,8 +127,21 @@ Login refused for <user>: rekey state requires operator attention (RekeySidecarI| `RekeyLockContentionError` | Another holder kept the user's `.rekey.lock` for more than 5 seconds: a password change of a large database, another worker's cold open, a stopped process or a hung mount | Yes, when the holder finishes || `RekeySidecarIOError` | `.rekey.lock` could not be opened or locked, or an epoch file could not be written (`operation` is `open`, `acquire`, `unlock`, `close` or `publish`; check the errno: `ENOSPC`, `EROFS`, `EACCES`, `EMFILE`, `ELOOP` for a symlink, `EINVAL` for a non-regular file, `EMLINK` for an already-unlinked lock file or one hard-linked to another file in the same directory) | Once the cause is fixed || `RekeyEpochUnreadableError` | An epoch file exists but cannot be read (I/O error, permissions, a symlink or non-regular file planted at its name) | Once the cause is fixed |-| `DatabaseKeyCheckUnavailableError` | The database could not be opened to check the password: SQLite reported it locked or busy past the busy timeout (`db_config.busy_timeout_ms`), an I/O error, or a file it cannot open. The password was not checked, so no lockout strike is counted | Yes, once the lock holder finishes or the I/O problem is fixed |-| `RekeyRecoveryRequiredError` | The epoch files do not vouch for a stable state: a malformed token, `.rekey.pending` without `.rekey.epoch`, or the password opened the database but committing the pending epoch failed (often disk full) | No, if the files are malformed: see below |+| `DatabaseKeyCheckUnavailableError` | Outside pending-rekey recovery, the database could not be opened to check the password: SQLite reported it locked or busy past the busy timeout (`db_config.busy_timeout_ms`), an I/O error, or a file it cannot open. The password was not checked, so no lockout strike is counted | Yes, once the lock holder finishes or the I/O problem is fixed |+| `RekeyRecoveryRequiredError` | The epoch files do not vouch for a stable state (a malformed token or `.rekey.pending` without `.rekey.epoch`), or pending-rekey recovery failed while opening/verifying the surviving key or publishing the pending epoch. Recovery also wraps SQLite busy/locked errors during key proof in this type | Yes for transient contention once the lock holder finishes; persistent failures or malformed metadata need attention (see below) |++`RekeyRecoveryRequiredError` alone does not establish that the password was+verified or that the epoch files are malformed. During pending-rekey+recovery, a key-proof failure can be wrapped in this type before a password+verdict is available. It still produces the login 503 above, without a+lockout strike; this is not an invalid-password response.++For transient contention, let the lock holder finish and retry the login+before attempting manual recovery. Use [manual recovery](#manual-recovery)+only if the 503 persists after the underlying cause is fixed, or if the+epoch files are malformed. Do not delete the rekey files to bypass a+transient lock; the server-stop, backup and file-protection requirements+below still apply.## Related log linesdiff --git a/src/local_deep_research/database/encrypted_db.py b/src/local_deep_research/database/encrypted_db.pyindex 63cae4cc0c..7916fc0dfa 100644--- a/src/local_deep_research/database/encrypted_db.py+++ b/src/local_deep_research/database/encrypted_db.py@@ -2859,9 +2859,12 @@ class DatabaseManager:Returns False when ``password`` does not open the surviving key: anordinary wrong password, which callers must treat exactly like anyother failed credential (the login route counts it toward the- lockout). Only a password that opens the database but whose- verification or epoch publication fails raises- ``RekeyRecoveryRequiredError``.+ lockout). Other failures while opening or verifying the surviving key+ or publishing the pending epoch raise ``RekeyRecoveryRequiredError``.+ This includes transient SQLite busy/locked errors during key proof,+ before a password verdict is available. The error type alone proves+ neither successful password verification nor malformed epoch metadata;+ the login route answers it with 503 and no lockout strike."""pending_epoch = state.pending_epochif pending_epoch is None:@@ -2879,6 +2882,8 @@ class DatabaseManager:commit_rekey_epoch(db_path, pending_epoch)clear_pending_rekey_epoch(db_path, pending_epoch)except Exception:+ # This also wraps key-proof contention before a password verdict;+ # the type alone does not establish malformed epoch metadata.raise RekeyRecoveryRequiredError(db_path) from Nonefinally:if connection is not None: