phase: 81_login_rate_limit

All gates verified. The phase is complete — everything was already implemented by prior task runs; this pass verified each completion criterion end-to-end and found no defects.

**Phase 81 final verification report** (tasks 01–03 all present in `complete/`; no code changes needed this pass)

- Verified: `app/core/rate_limit.py` (stdlib sliding window, fail-open) + both login routes' 429 pre-check/record/reset wiring + all unit/integration pins present (11th-429, blocked-success-still-429, clean-counter reset, shared counter, autouse `clean_rate_limit` fixture documented).
- Live check (task 03): dev server + 11 rapid wrong logins → `401 ×10, 429`; 429 body carries `retry-after: 900` + generic detail; server restarted (per-process counter cleared by design).
- `uv run pytest tests/unit/test_rate_limit.py -v --no-cov` → 10 passed
- `uv run pytest --cov=app --cov-report=term-missing` → 1652 passed, **TOTAL 99%** (>90%; rate_limit.py 100%, auth.py 100%)
- `uv run pytest tests/e2e/test_smoke.py -v --no-cov` (isolation) → 3 passed
- `uv run ruff check . && uv run pyright` → All checks passed / 0 errors, 0 warnings
- Completion criteria: all met, except commit + phase-dir move — per harness rules I left all changes uncommitted in the working tree (harness commits atomically and moves the phase).
- Diff scope: exactly `app/core/rate_limit.py`, `app/api/auth.py`, `tests/unit/test_rate_limit.py`, `tests/integration/test_auth_api.py` + phase files; `pyproject.toml` / `uv.lock` / `frontend/` untouched.
- Deviations: none in code; commit/move deferred to harness as instructed.
- Next pending phase: `82_security_headers`.

.agents/reports/81_login_rate_limit/81_login_rate_limit__00_phase.a1.md

@@ -0,0 +1,14 @@
+All gates verified. The phase is complete — everything was already implemented by prior task runs; this pass verified each completion criterion end-to-end and found no defects.
+
+**Phase 81 final verification report** (tasks 01–03 all present in `complete/`; no code changes needed this pass)
+
+- Verified: `app/core/rate_limit.py` (stdlib sliding window, fail-open) + both login routes' 429 pre-check/record/reset wiring + all unit/integration pins present (11th-429, blocked-success-still-429, clean-counter reset, shared counter, autouse `clean_rate_limit` fixture documented).
+- Live check (task 03): dev server + 11 rapid wrong logins → `401 ×10, 429`; 429 body carries `retry-after: 900` + generic detail; server restarted (per-process counter cleared by design).
+- `uv run pytest tests/unit/test_rate_limit.py -v --no-cov` → 10 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 1652 passed, **TOTAL 99%** (>90%; rate_limit.py 100%, auth.py 100%)
+- `uv run pytest tests/e2e/test_smoke.py -v --no-cov` (isolation) → 3 passed
+- `uv run ruff check . && uv run pyright` → All checks passed / 0 errors, 0 warnings
+- Completion criteria: all met, except commit + phase-dir move — per harness rules I left all changes uncommitted in the working tree (harness commits atomically and moves the phase).
+- Diff scope: exactly `app/core/rate_limit.py`, `app/api/auth.py`, `tests/unit/test_rate_limit.py`, `tests/integration/test_auth_api.py` + phase files; `pyproject.toml` / `uv.lock` / `frontend/` untouched.
+- Deviations: none in code; commit/move deferred to harness as instructed.
+- Next pending phase: `82_security_headers`.

.agents/reports/81_login_rate_limit/81_login_rate_limit__00_phase.a1.validate

@@ -0,0 +1,82 @@
+........................................................................ [  4%]
+........................................................................ [  8%]
+........................................................................ [ 13%]
+........................................................................ [ 17%]
+........................................................................ [ 21%]
+........................................................................ [ 26%]
+........................................................................ [ 30%]
+........................................................................ [ 34%]
+........................................................................ [ 39%]
+........................................................................ [ 43%]
+........................................................................ [ 47%]
+........................................................................ [ 52%]
+........................................................................ [ 56%]
+........................................................................ [ 61%]
+........................................................................ [ 65%]
+........................................................................ [ 69%]
+........................................................................ [ 74%]
+........................................................................ [ 78%]
+........................................................................ [ 82%]
+........................................................................ [ 87%]
+........................................................................ [ 91%]
+........................................................................ [ 95%]
+....................................................................     [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                52      0   100%
+app/api/chat.py               178      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        212      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py         29      0   100%
+app/api/sync.py               101      0   100%
+app/api/tokens.py              28      0   100%
+app/config.py                 141      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               45      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/core/rate_limit.py         44      0   100%
+app/core/tokens.py             33      0   100%
+app/db.py                      21      0   100%
+app/main.py                    62      0   100%
+app/models.py                  94      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py              222      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                216      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             88      0   100%
+app/rag/retriever.py          150      3    98%
+app/rag/scaffolding.py         55      0   100%
+app/rag/source_removal.py      41      0   100%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                231      0   100%
+-----------------------------------------------
+TOTAL                        3211     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agents/reports/81_login_rate_limit/81_login_rate_limit__01_rate_limiter_core.a1.md

@@ -0,0 +1,18 @@
+Task 01 complete — all gates green.
+
+**Implemented**
+- `app/core/rate_limit.py` (new): stdlib-only sliding-window limiter — `MAX_FAILURES = 10` / `WINDOW_SECONDS = 900` module constants, per-IP `deque[float]` of `time.monotonic()` timestamps under a `threading.Lock`; `record_failure` (append + prune, never raises, drops the count silently on corrupt state), `remaining_wait` (0 when < 10 in-window; else `max(1, ceil(900 − (now − oldest)))`, never raises), `reset` (pop, no-op on unknown). Docstring carries the SEC-03 audit basis, shared-counter intent, fail-open rationale, and the `request.client.host` / no-proxy assumption.
+- `tests/unit/test_rate_limit.py` (new): 10 tests pinning, in task order — 9 failures allowed → 10th blocks (`0 < wait ≤ 900`, int) → second IP independent → expiry via pre-seeded `WINDOW_SECONDS + 1` state AND a fake monotonic clock (whole-window wait from the oldest: 891 → 300 → clamped 1 → 0 the moment the oldest slides out) → `reset` unblocks → unknown IP 0 → fail-open on non-deque state and on a raising clock → `reset` no-op on unknown IP.
+
+**Results**
+- `uv run pytest tests/unit/test_rate_limit.py -v` → 10 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 1648 passed; `app/core/rate_limit.py` **100%**, TOTAL **99%** (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `git status`: only the two new files are code changes (pre-existing untracked phase/report files untouched); no tracked file modified
+
+**Notable decisions**
+- Corrupt state entry → `record_failure` is a literal no-op (entry left in place, treated as not-blocked) per the phase's "record_failure no-ops" wording; over-denial is the only forbidden outcome.
+- Removed one unreachable defensive branch after the first coverage run to reach 100% on the module.
+- `.agents/PLAN.md` is absent from the repo (AGENTS.md references it); the phase overview's design block was followed as the binding spec — no deviation.
+
+**Next pending task:** `02_auth_routes_wiring.md` (429 pre-check + bookkeeping on both login routes + integration tests).

.agents/reports/81_login_rate_limit/81_login_rate_limit__01_rate_limiter_core.a1.validate

@@ -0,0 +1,82 @@
+........................................................................ [  4%]
+........................................................................ [  8%]
+........................................................................ [ 13%]
+........................................................................ [ 17%]
+........................................................................ [ 21%]
+........................................................................ [ 26%]
+........................................................................ [ 30%]
+........................................................................ [ 34%]
+........................................................................ [ 39%]
+........................................................................ [ 43%]
+........................................................................ [ 48%]
+........................................................................ [ 52%]
+........................................................................ [ 56%]
+........................................................................ [ 61%]
+........................................................................ [ 65%]
+........................................................................ [ 69%]
+........................................................................ [ 74%]
+........................................................................ [ 78%]
+........................................................................ [ 83%]
+........................................................................ [ 87%]
+........................................................................ [ 91%]
+........................................................................ [ 96%]
+................................................................         [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                40      0   100%
+app/api/chat.py               178      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        212      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py         29      0   100%
+app/api/sync.py               101      0   100%
+app/api/tokens.py              28      0   100%
+app/config.py                 141      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               45      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/core/rate_limit.py         44      0   100%
+app/core/tokens.py             33      0   100%
+app/db.py                      21      0   100%
+app/main.py                    62      0   100%
+app/models.py                  94      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py              222      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                216      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             88      0   100%
+app/rag/retriever.py          150      3    98%
+app/rag/scaffolding.py         55      0   100%
+app/rag/source_removal.py      41      0   100%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                231      0   100%
+-----------------------------------------------
+TOTAL                        3199     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agents/reports/81_login_rate_limit/81_login_rate_limit__02_auth_routes_wiring.a1.md

@@ -0,0 +1,16 @@
+**Task 02 complete — report**
+
+**Implemented**
+- `app/api/auth.py`: `TOO_MANY_DETAIL` constant + `rate_limit` import; on both `login` and `token_auth` — 429 pre-check (`Retry-After`, generic detail) at handler top, `record_failure` before the 401, `reset` before the 204 (shared per-IP counter); module + handler docstrings extended with the 429 case.
+- `tests/integration/test_auth_api.py`: autouse `clean_rate_limit` fixture (`rate_limit.reset("testclient")` around every test — documented: TestClient's host is a fixed shared IP, counter is process state) + 4 new pins: 11th failed login → 429 + detail + `Retry-After` (≤ window); correct password while blocked → still 429; 9 failures + success → counter reset (next 9 all 401); 5 login + 5 token failures → 11th (valid token) → 429.
+
+**Results**
+- `uv run pytest tests/integration/test_auth_api.py tests/unit/test_rate_limit.py` → 27 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 1652 passed; **99%** total (`app/api/auth.py` 100%, `app/core/rate_limit.py` 100%)
+- `uv run pytest tests/e2e/test_smoke.py -v --no-cov` → 3 passed (isolation)
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+- `pyproject.toml`/`uv.lock` untouched; diff limited to `app/api/auth.py` + the two test files (plus task-01's two new files, untracked for the harness commit)
+
+**Deviation**: used `request.client.host if request.client is not None else "unknown"` instead of the task's literal `or "unknown"` — starlette types `client` as optional; pyright (non-negotiable gate) requires the explicit check. Same fail-open semantics.
+
+**Next pending task**: `.agents/phases/todo/81_login_rate_limit/03_verify_and_commit.md`

.agents/reports/81_login_rate_limit/81_login_rate_limit__02_auth_routes_wiring.a1.validate

@@ -0,0 +1,82 @@
+........................................................................ [  4%]
+........................................................................ [  8%]
+........................................................................ [ 13%]
+........................................................................ [ 17%]
+........................................................................ [ 21%]
+........................................................................ [ 26%]
+........................................................................ [ 30%]
+........................................................................ [ 34%]
+........................................................................ [ 39%]
+........................................................................ [ 43%]
+........................................................................ [ 47%]
+........................................................................ [ 52%]
+........................................................................ [ 56%]
+........................................................................ [ 61%]
+........................................................................ [ 65%]
+........................................................................ [ 69%]
+........................................................................ [ 74%]
+........................................................................ [ 78%]
+........................................................................ [ 82%]
+........................................................................ [ 87%]
+........................................................................ [ 91%]
+........................................................................ [ 95%]
+....................................................................     [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                52      0   100%
+app/api/chat.py               178      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        212      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py         29      0   100%
+app/api/sync.py               101      0   100%
+app/api/tokens.py              28      0   100%
+app/config.py                 141      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               45      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/core/rate_limit.py         44      0   100%
+app/core/tokens.py             33      0   100%
+app/db.py                      21      0   100%
+app/main.py                    62      0   100%
+app/models.py                  94      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py              222      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                216      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             88      0   100%
+app/rag/retriever.py          150      3    98%
+app/rag/scaffolding.py         55      0   100%
+app/rag/source_removal.py      41      0   100%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                231      0   100%
+-----------------------------------------------
+TOTAL                        3211     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK

.agents/reports/81_login_rate_limit/81_login_rate_limit__03_verify_and_commit.a1.md

@@ -0,0 +1,15 @@
+**Task 03 (phase-level gate) complete — report**
+
+**Gate results (all run in this session):**
+- `uv run pytest` → 1652 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 99% total; `app/api/auth.py` 100%, `app/core/rate_limit.py` 100%
+- `uv run pytest tests/e2e/test_smoke.py -v --no-cov` → 3 passed (in isolation, server on :8123)
+- `uv run ruff check . && uv run pyright` → all checks passed; 0 errors
+- Live check (fresh `uv run uvicorn app.main:app` on :8000): 11 rapid wrong logins → `401 ×10, 429`; the 429 carries `retry-after: 900` + generic detail; correct password while blocked → 429; kill + restart → counter cleared (wrong login → 401). Server stopped, port free.
+- `git diff` scope: only `app/api/auth.py`, `tests/integration/test_auth_api.py` (modified) + `app/core/rate_limit.py`, `tests/unit/test_rate_limit.py` (new); `pyproject.toml`/`uv.lock`/`frontend/` untouched (0 diff lines).
+
+**Notable decisions:**
+- Per harness rules (which override the task file), I did **not** run `git add`/`git commit` nor move the phase dir to `complete/` — the harness makes the atomic commit and the move. All changes left in the working tree.
+- No defects found in tasks 01/02; one operational slip of my own (first restart check killed the wrong pid, so a stale blocked server answered) — redone cleanly with a full process kill; final results above are from a verified-fresh server.
+
+**Next pending task:** `.agents/phases/todo/82_security_headers/01_headers_middleware.md` (phase 81 is fully gated — harness commit + move remains).

.agents/reports/81_login_rate_limit/81_login_rate_limit__03_verify_and_commit.a1.validate

@@ -0,0 +1,82 @@
+........................................................................ [  4%]
+........................................................................ [  8%]
+........................................................................ [ 13%]
+........................................................................ [ 17%]
+........................................................................ [ 21%]
+........................................................................ [ 26%]
+........................................................................ [ 30%]
+........................................................................ [ 34%]
+........................................................................ [ 39%]
+........................................................................ [ 43%]
+........................................................................ [ 47%]
+........................................................................ [ 52%]
+........................................................................ [ 56%]
+........................................................................ [ 61%]
+........................................................................ [ 65%]
+........................................................................ [ 69%]
+........................................................................ [ 74%]
+........................................................................ [ 78%]
+........................................................................ [ 82%]
+........................................................................ [ 87%]
+........................................................................ [ 91%]
+........................................................................ [ 95%]
+....................................................................     [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                52      0   100%
+app/api/chat.py               178      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        212      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py         29      0   100%
+app/api/sync.py               101      0   100%
+app/api/tokens.py              28      0   100%
+app/config.py                 141      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               45      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/core/rate_limit.py         44      0   100%
+app/core/tokens.py             33      0   100%
+app/db.py                      21      0   100%
+app/main.py                    62      0   100%
+app/models.py                  94      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py              222      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                216      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             88      0   100%
+app/rag/retriever.py          150      3    98%
+app/rag/scaffolding.py         55      0   100%
+app/rag/source_removal.py      41      0   100%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                231      0   100%
+-----------------------------------------------
+TOTAL                        3211     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK