diff --git a/api/search.py b/api/search.py
index f6e1442..05b6e1d 100644
--- a/api/search.py
+++ b/api/search.py
@@ -1,9 +1,14 @@
 """
 API route for search — mirrors src/app/api/search/route.ts
-GET /api/search?q=...&type=all|chat|composer&all_history=1
+GET /api/search?q=...&type=all|chat|composer&all_history=1&workspace=<id>
 """
 
+from __future__ import annotations
+
 import logging
+import os
+import re
+import sqlite3
 from typing import Any
 
 from flask import Blueprint, Response, current_app, request
@@ -19,12 +24,16 @@
     search_global_storage,
     search_legacy_workspaces,
 )
+from utils.cli_chat_reader import list_cli_projects
 from utils.workspace_path import get_cli_chats_path, resolve_workspace_path
 
 bp = Blueprint("search", __name__)
 _logger = logging.getLogger(__name__)
 
 _MAX_SEARCH_SINCE_DAYS = 36_500  # ~100 years; avoids timedelta overflow on bad input
+_MAX_SEARCH_QUERY_LEN = 500
+_VALID_SEARCH_TYPES = frozenset({"all", "chat", "composer"})
+_SAFE_WORKSPACE_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
 
 
 def _parse_since_days_param(raw: str | None) -> int | None:
@@ -39,6 +48,56 @@ def _parse_since_days_param(raw: str | None) -> int | None:
     return days
 
 
+def _search_error(
+    message: str,
+    code: str,
+    status: int,
+) -> tuple[Response, int]:
+    return json_response({"error": message, "code": code}, status)
+
+
+def _is_safe_workspace_folder_id(workspace_id: str) -> bool:
+    """Return whether *workspace_id* is a safe Cursor workspace folder name."""
+    if not workspace_id or workspace_id in {".", ".."}:
+        return False
+    if (
+        os.path.isabs(workspace_id)
+        or ".." in workspace_id
+        or "/" in workspace_id
+        or "\\" in workspace_id
+    ):
+        return False
+    return _SAFE_WORKSPACE_ID_RE.fullmatch(workspace_id) is not None
+
+
+def _workspace_exists(workspace_id: str, workspace_path: str) -> bool:
+    if workspace_id == "global":
+        return True
+    if workspace_id.startswith("cli:"):
+        project_id = workspace_id[4:]
+        if not _is_safe_workspace_folder_id(project_id):
+            return False
+        return any(
+            cp.get("project_id") == project_id
+            for cp in list_cli_projects(get_cli_chats_path())
+        )
+    if not _is_safe_workspace_folder_id(workspace_id):
+        return False
+    candidate = os.path.join(workspace_path, workspace_id)
+    root = os.path.normpath(workspace_path)
+    joined = os.path.normpath(candidate)
+    if os.path.commonpath([root, joined]) != root:
+        return False
+    return os.path.isdir(joined)
+
+
+def _filter_results_by_workspace(
+    results: list[SearchResult],
+    workspace_id: str,
+) -> list[SearchResult]:
+    return [r for r in results if r.get("workspaceId") == workspace_id]
+
+
 @bp.route("/api/search")
 def search() -> tuple[Response, int] | Response:
     """Search chats, composers, and CLI sessions across Cursor storage.
@@ -46,24 +105,44 @@ def search() -> tuple[Response, int] | Response:
     Args:
         q: Search query string (required; 400 when empty).
         type: Filter scope — ``all`` (default), ``chat``, or ``composer``.
+        workspace: Optional workspace folder hash; 404 when unknown.
 
     Returns:
-        JSON ``{"results": [...]}`` with optional ``warnings``. 400 when ``q`` is
-        empty; 500 with ``{"error": ..., "results": []}`` on unexpected failure.
+        JSON ``{"results": [...]}`` with optional ``warnings``. Structured
+        ``{"error", "code"}`` bodies for 400/404/503/500 failures.
     """
+    query = request.args.get("q", "").strip()
+    if not query:
+        return _search_error("No search query provided", "empty_query", 400)
+    if len(query) > _MAX_SEARCH_QUERY_LEN:
+        return _search_error("Search query is too long", "query_too_long", 400)
+
+    search_type = request.args.get("type", "all")
+    if search_type not in _VALID_SEARCH_TYPES:
+        return _search_error("Invalid search type", "invalid_type", 400)
+
+    since_days_raw = request.args.get("since_days")
+    if (
+        since_days_raw is not None
+        and str(since_days_raw).strip()
+        and _parse_since_days_param(since_days_raw) is None
+    ):
+        return _search_error("Invalid since_days parameter", "invalid_since_days", 400)
+
+    workspace_filter = request.args.get("workspace", "").strip() or None
+
     try:
-        query = request.args.get("q", "").strip()
-        search_type = request.args.get("type", "all")
+        workspace_path = resolve_workspace_path()
+        if workspace_filter and not _workspace_exists(workspace_filter, workspace_path):
+            return _search_error("Workspace not found", "workspace_not_found", 404)
+
         rules = current_app.config.get("EXCLUSION_RULES") or []
         all_history = request.args.get("all_history") in ("1", "true")
         since_ms = resolve_search_since_ms(
             all_history=all_history,
-            since_days=_parse_since_days_param(request.args.get("since_days")),
+            since_days=_parse_since_days_param(since_days_raw),
         )
 
-        if not query:
-            return json_response({"error": "No search query provided"}, 400)
-        workspace_path = resolve_workspace_path()
         parse_warnings = ParseWarningCollector()
         query_lower = query.lower()
 
@@ -101,18 +180,30 @@ def search() -> tuple[Response, int] | Response:
                 )
             )
 
+        ranked = rank_results(results)
+        if workspace_filter:
+            ranked = _filter_results_by_workspace(ranked, workspace_filter)
+
         payload: dict[str, Any] = {
-            "results": rank_results(results),
+            "results": ranked,
             "allHistory": since_ms is None,
             "searchWindowDays": (
                 None if since_ms is None else (
-                    _parse_since_days_param(request.args.get("since_days"))
+                    _parse_since_days_param(since_days_raw)
                     or DEFAULT_SEARCH_WINDOW_DAYS
                 )
             ),
         }
         return json_response(parse_warnings.attach_to(payload))
 
+    except sqlite3.OperationalError:
+        _logger.exception("Search index unavailable")
+        return _search_error(
+            "Search index is temporarily unavailable",
+            "search_index_unavailable",
+            503,
+        )
     except Exception:
         _logger.exception("Search failed")
-        return json_response({"error": "Search failed", "results": []}, 500)
\ No newline at end of file
+        return _search_error("Search failed", "internal_error", 500)
+
diff --git a/static/css/style.css b/static/css/style.css
index d6387f0..01e4535 100644
--- a/static/css/style.css
+++ b/static/css/style.css
@@ -245,9 +245,58 @@ h3 { font-size: 1.15rem; font-weight: 600; }
 }
 .input:focus { border-color: var(--blue); box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.2); }
 
-.search-bar { display: flex; gap: 0.5rem; }
+.search-bar { display: flex; gap: 0.5rem; align-items: center; }
 .search-bar .input { flex: 1; }
 
+.search-info-tooltip {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border: none;
+  background: none;
+  padding: 0;
+  font: inherit;
+  cursor: help;
+}
+.search-info-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+  font-size: 0.75rem;
+  font-weight: 700;
+  font-style: italic;
+  cursor: help;
+  user-select: none;
+}
+.search-info-tooltip-text {
+  display: none;
+  position: absolute;
+  top: calc(100% + 0.5rem);
+  right: 0;
+  z-index: 60;
+  width: min(20rem, 70vw);
+  padding: 0.75rem 0.875rem;
+  border: 1px solid var(--info-border);
+  border-radius: 0.5rem;
+  background: var(--info-bg);
+  color: var(--info-text);
+  font-size: 0.8125rem;
+  line-height: 1.45;
+  box-shadow: 0 4px 12px var(--shadow);
+}
+.search-info-tooltip:hover .search-info-tooltip-text,
+.search-info-tooltip:focus .search-info-tooltip-text,
+.search-info-tooltip:focus-within .search-info-tooltip-text {
+  display: block;
+}
+
 /* ---------- Alerts ---------- */
 .alert {
   padding: 0.75rem 1rem;
diff --git a/templates/search.html b/templates/search.html
index 50ebce0..b2408ac 100644
--- a/templates/search.html
+++ b/templates/search.html
@@ -14,6 +14,19 @@ <h1>Search</h1>
   <div class="form-group" style="margin-bottom:1.5rem">
     <div class="search-bar">
       <input type="text" id="search-input" class="input" placeholder="Search across all logs..." autofocus>
+      <button
+        type="button"
+        class="search-info-tooltip"
+        id="search-window-help"
+        aria-describedby="search-window-help-text"
+      >
+        <span class="search-info-icon" aria-hidden="true">i</span>
+        <span class="search-info-tooltip-text" id="search-window-help-text" role="tooltip">
+          By default, search covers the most recent 30-day indexed window.
+          Chats without a parseable date are always included.
+          Check &ldquo;Include chats older than 30 days&rdquo; to search full history.
+        </span>
+      </button>
       <button class="btn btn-primary" onclick="doSearch()">Search</button>
     </div>
     <label class="text-sm" style="display:flex;align-items:center;gap:0.5rem;margin-top:0.75rem;cursor:pointer">
@@ -94,13 +107,14 @@ <h1>Search</h1>
     const params = new URLSearchParams({ q: query, type: type });
     if (allHistory) params.set('all_history', '1');
     const res = await fetch(`/api/search?${params.toString()}`);
+    const data = await res.json().catch(() => ({}));
     if (!res.ok) {
       showIncompleteResultsBanner('parse-warnings-host', []);
       loading.style.display = 'none';
-      container.innerHTML = '<p class="text-danger">Search failed.</p>';
+      const message = typeof data.error === 'string' ? data.error : 'Search failed.';
+      container.innerHTML = `<p class="text-danger">${escapeHtml(message)}</p>`;
       return;
     }
-    const data = await res.json();
     const results = data.results || [];
     showIncompleteResultsBanner('parse-warnings-host', data.warnings);
 
diff --git a/tests/test_api_search.py b/tests/test_api_search.py
index 21fb27a..46ccc1a 100644
--- a/tests/test_api_search.py
+++ b/tests/test_api_search.py
@@ -1,9 +1,12 @@
-"""Flask test-client coverage for GET /api/search (issue #101)."""
+"""Flask test-client coverage for GET /api/search (issue #101, #117)."""
 
 from __future__ import annotations
 
+import sqlite3
 from unittest.mock import patch
 
+import pytest
+
 from tests._fixture_ids import HAPPY_COMPOSER_ID, HAPPY_WORKSPACE_ID
 from tests._helpers import client_with_rules
 
@@ -21,6 +24,11 @@ def _assert_search_result_shape(hit: dict) -> None:
         assert hit["source"] == "cli"
 
 
+def _assert_error_body(body: dict, *, code: str) -> None:
+    assert body.get("code") == code
+    assert isinstance(body.get("error"), str) and body["error"]
+
+
 class TestSearchHappyPath:
     def test_finds_seeded_term_and_result_shape(self, client):
         response = client.get("/api/search?q=sentinel-grep&all_history=1")
@@ -44,25 +52,43 @@ def test_type_composer_still_finds_global_match(self, client):
         assert all(r["type"] == "composer" for r in body["results"])
 
 
-class TestSearchErrorResponses:
-    def test_missing_q_returns_400(self, client):
-        response = client.get("/api/search")
-        assert response.status_code == 400
-        body = response.get_json()
-        assert body.get("error") == "No search query provided"
-        assert "results" not in body
+@pytest.mark.parametrize(
+    ("path", "expected_status", "expected_code"),
+    [
+        ("/api/search", 400, "empty_query"),
+        ("/api/search?q=", 400, "empty_query"),
+        ("/api/search?q=%20%20%20", 400, "empty_query"),
+        ("/api/search?q=x&type=invalid", 400, "invalid_type"),
+        ("/api/search?q=x&since_days=0", 400, "invalid_since_days"),
+        ("/api/search?q=x&since_days=not-a-number", 400, "invalid_since_days"),
+        (
+            "/api/search?q=no-such-workspace-scope&workspace=does-not-exist-xyzzy",
+            404,
+            "workspace_not_found",
+        ),
+        (
+            "/api/search?q=x&workspace=..%2F..%2Fetc",
+            404,
+            "workspace_not_found",
+        ),
+    ],
+)
+def test_search_error_status_codes(client, path, expected_status, expected_code):
+    response = client.get(path)
+    assert response.status_code == expected_status
+    body = response.get_json()
+    assert isinstance(body, dict)
+    _assert_error_body(body, code=expected_code)
+    assert "results" not in body
 
-    def test_empty_q_returns_400(self, client):
-        response = client.get("/api/search?q=")
-        assert response.status_code == 400
-        assert response.get_json().get("error") == "No search query provided"
 
-    def test_whitespace_only_q_returns_400(self, client):
-        response = client.get("/api/search?q=%20%20%20")
+class TestSearchErrorResponses:
+    def test_query_too_long_returns_400(self, client):
+        response = client.get("/api/search?q=" + ("x" * 501))
         assert response.status_code == 400
-        assert response.get_json().get("error") == "No search query provided"
+        _assert_error_body(response.get_json(), code="query_too_long")
 
-    def test_internal_failure_returns_500_with_empty_results(self, client):
+    def test_internal_failure_returns_500(self, client):
         with patch(
             "api.search.search_global_storage",
             side_effect=RuntimeError("simulated DB failure"),
@@ -70,8 +96,28 @@ def test_internal_failure_returns_500_with_empty_results(self, client):
             response = client.get("/api/search?q=sentinel-grep&all_history=1")
         assert response.status_code == 500
         body = response.get_json()
-        assert body.get("error") == "Search failed"
-        assert body.get("results") == []
+        _assert_error_body(body, code="internal_error")
+        assert "results" not in body
+
+    def test_index_lock_returns_503(self, client):
+        with patch(
+            "api.search.search_global_storage",
+            side_effect=sqlite3.OperationalError("database is locked"),
+        ):
+            response = client.get("/api/search?q=sentinel-grep&all_history=1")
+        assert response.status_code == 503
+        body = response.get_json()
+        _assert_error_body(body, code="search_index_unavailable")
+        assert "results" not in body
+
+    def test_workspace_path_resolution_failure_returns_structured_500(self, client):
+        with patch(
+            "api.search.resolve_workspace_path",
+            side_effect=OSError("simulated storage discovery failure"),
+        ):
+            response = client.get("/api/search?q=sentinel-grep&all_history=1")
+        assert response.status_code == 500
+        _assert_error_body(response.get_json(), code="internal_error")
 
 
 class TestSearchEdgeCases:
@@ -94,6 +140,15 @@ def test_workspace_scoped_hit_has_workspace_id(self, client):
         workspace_ids = {r["workspaceId"] for r in results}
         assert HAPPY_WORKSPACE_ID in workspace_ids or "global" in workspace_ids
 
+    def test_workspace_filter_limits_results(self, client):
+        response = client.get(
+            f"/api/search?q=sentinel-grep&all_history=1&workspace={HAPPY_WORKSPACE_ID}",
+        )
+        assert response.status_code == 200
+        results = response.get_json()["results"]
+        assert results
+        assert all(r["workspaceId"] == HAPPY_WORKSPACE_ID for r in results)
+
 
 class TestSearchWindow:
     def test_default_window_excludes_old_seeded_composer(self, client):