fix: search review follow-ups (index lock fallback, error body parse)

Author: clean6378-max-it

api/search.py

@@ -37,10 +37,6 @@
 _MAX_SEARCH_SINCE_DAYS = 36_500
 
 
-class _SearchIndexUnavailable(Exception):
-    """Raised when the FTS index exists but is locked during rebuild."""
-
-
 def _parse_limit(raw: str | None, default: int = _DEFAULT_LIMIT) -> int:
     """Parse a positive integer limit from a query string value."""
     if raw is None or raw.strip() == "":
@@ -149,7 +145,13 @@ def _search_via_index(
             sql_offset=sql_offset,
         )
         if indexed["index_locked"]:
-            raise _SearchIndexUnavailable()
+            _logger.warning(
+                "Search index locked during query; %d hit(s) collected so far",
+                len(results),
+            )
+            if results:
+                return _rank_search_hits(results)[:max_results]
+            return None
         if not indexed["query_ok"]:
             return None
         if indexed["sql_rows_fetched"] == 0:
@@ -308,12 +310,6 @@ def search() -> FlaskReturn:
                 max_results=max_results,
             )
         )
-    except _SearchIndexUnavailable:
-        return error_response(
-            ErrorCode.SEARCH_INDEX_UNAVAILABLE,
-            "Search index is temporarily unavailable",
-            503,
-        )
     except Exception:
         _logger.exception("Unexpected error during search")
         return error_response(

docs/api-reference.md

@@ -60,7 +60,6 @@ Extra fields may appear for specific codes (for example `since` on invalid bulk-
 | `SEARCH_QUERY_TOO_LONG` | 400 | `GET /api/search` | Query param `q` exceeds 500 characters |
 | `SEARCH_INVALID_SINCE_DAYS` | 400 | `GET /api/search` | Query param `since_days` is not a positive integer |
 | `SEARCH_PROJECTS_UNAVAILABLE` | 503 | `GET /api/search` | Claude projects directory exists but is not readable |
-| `SEARCH_INDEX_UNAVAILABLE` | 503 | `GET /api/search` | FTS index is locked during rebuild |
 | `INVALID_PATH` | 400 | Session, stats, export session | Path traversal or rejected URL segment |
 | `SESSION_NOT_FOUND` | 404 | Session, stats, export session | File missing on disk or session excluded by rules |
 | `INVALID_REQUEST_BODY` | 400 | `POST /api/export` | Body is not a JSON object |
@@ -320,7 +319,6 @@ By default, messages older than 30 days are excluded. Sessions without a parseab
 | 400 | `SEARCH_INVALID_LIMIT` | `limit` not a positive integer (e.g. `abc`, `0`, `1.5`) |
 | 400 | `SEARCH_INVALID_SINCE_DAYS` | `since_days` not a positive integer |
 | 503 | `SEARCH_PROJECTS_UNAVAILABLE` | Projects directory exists but is not readable |
-| 503 | `SEARCH_INDEX_UNAVAILABLE` | FTS index locked during rebuild |
 | 500 | `INTERNAL_ERROR` | Unexpected server failure |
 
 ```bash

models/error_codes.py

@@ -11,7 +11,6 @@ class ErrorCode(StrEnum):
     SEARCH_QUERY_TOO_LONG = "SEARCH_QUERY_TOO_LONG"
     SEARCH_INVALID_SINCE_DAYS = "SEARCH_INVALID_SINCE_DAYS"
     SEARCH_PROJECTS_UNAVAILABLE = "SEARCH_PROJECTS_UNAVAILABLE"
-    SEARCH_INDEX_UNAVAILABLE = "SEARCH_INDEX_UNAVAILABLE"
     INVALID_PATH = "INVALID_PATH"
     SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
     INVALID_REQUEST_BODY = "INVALID_REQUEST_BODY"

static/js/search.js

@@ -106,12 +106,14 @@ export async function doSearch() {
         if (!res.ok) {
             let message = `Search failed (${res.status})`;
             let code = '';
+            const raw = await res.text();
             try {
-                const body = await res.json();
+                const body = JSON.parse(raw);
                 if (body && typeof body.error === 'string') message = body.error;
                 if (body && typeof body.code === 'string') code = body.code;
             } catch {
-                try { message = await res.text() || message; } catch { /* ignore */ }
+                const trimmed = raw.trim();
+                if (trimmed) message = trimmed;
             }
             if (localRequestId !== lastSearchRequestId) return;
             const codeAttr = code ? ` data-error-code="${esc(code)}"` : '';

static/js/search.test.js

@@ -126,19 +126,36 @@ describe('search page', () => {
         fetch.mockResolvedValue({
             ok: false,
             status: 503,
-            json: () => Promise.resolve({
-                error: 'Search index is temporarily unavailable',
-                code: 'SEARCH_INDEX_UNAVAILABLE',
-            }),
+            text: () => Promise.resolve(JSON.stringify({
+                error: 'Claude projects directory is not accessible',
+                code: 'SEARCH_PROJECTS_UNAVAILABLE',
+            })),
         });
         document.getElementById('search-input').value = 'fail';
 
         await doSearch();
 
         const err = document.querySelector('.search-error');
         expect(err).not.toBeNull();
-        expect(err.getAttribute('data-error-code')).toBe('SEARCH_INDEX_UNAVAILABLE');
-        expect(err.textContent).toContain('temporarily unavailable');
+        expect(err.getAttribute('data-error-code')).toBe('SEARCH_PROJECTS_UNAVAILABLE');
+        expect(err.textContent).toContain('not accessible');
+    });
+
+    it('doSearch shows plain-text error body when response is not JSON', async () => {
+        showSearchPage();
+        fetch.mockResolvedValue({
+            ok: false,
+            status: 502,
+            text: () => Promise.resolve('Bad Gateway from proxy'),
+        });
+        document.getElementById('search-input').value = 'fail';
+
+        await doSearch();
+
+        const err = document.querySelector('.search-error');
+        expect(err).not.toBeNull();
+        expect(err.textContent).toBe('Bad Gateway from proxy');
+        expect(err.getAttribute('data-error-code')).toBeNull();
     });
 
     it('doSearch ignores stale responses when a newer request was started', async () => {

tests/test_search.py

@@ -118,22 +118,22 @@ def test_missing_projects_dir_is_not_unavailable(client_single, monkeypatch):
     assert resp.status_code == 200
 
 
-def test_index_unavailable_when_locked(tmp_path, monkeypatch):
+def test_index_lock_falls_back_to_live_scan(tmp_path, monkeypatch):
     recent_ts = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
     client = _seed_indexed_client(tmp_path, monkeypatch, timestamp=recent_ts)
     with patch(
         "api.search.query_index_hits",
         return_value={
             "hits": [],
-            "query_ok": False,
+            "query_ok": True,
             "sql_rows_fetched": 0,
             "sql_exhausted": True,
             "index_locked": True,
         },
     ):
         resp = client.get("/api/search?q=Hello")
-    assert resp.status_code == 503
-    assert_error_response(resp, expected_code="SEARCH_INDEX_UNAVAILABLE")
+    assert resp.status_code == 200
+    assert len(resp.get_json()) >= 1
 
 
 def _index_patches(cache_root: Path):