fix: prevent futile retries after empty or deferred results

docs/implementation/cli-commands.md

@@ -13,7 +13,7 @@ The CLI exposes setup/auth commands, `doctor`, `example`, `languages`, `feedback
 | `login` | — | `--no-browser`, `--port <port>`, `--force` | Authenticate with browser OAuth using a loopback callback on the machine running GitHits |
 | `example <query>` | `<query>` | `-l, --lang <language>`, `--license <mode>`, `--explain`, `--json` | Search for code examples |
 | `search <query>` | `--in <target>` | `--source <source>`, `--kind <kind>`, `--category <category>`, `--path-prefix <prefix>`, `--intent <intent>`, `--public`, `--name <name>`, `--lang <language>`, `--allow-partial`, `--limit <n>`, `--offset <n>`, `--wait <seconds>`, `--json` | Unified indexed search across dependency/repository code, docs, and symbols. Defaults to 10 results. |
-| `search-status <search-ref>` | `<search-ref>` | `--json` | Check progress, fetch partial hits, or fetch final results for a prior unified search |
+| `search-status <search-ref>` | `<search-ref>` | `--wait <seconds>`, `--json` | Check progress, fetch partial hits, or fetch final results for a prior unified search; waits up to 20 seconds by default |
 | `languages [query]` | — | `--json` | List or filter supported languages |
 | `feedback [solution_id]` | `--accept` or `--reject` | `-m, --message <text>`, `--tool <name>`, `--json` | Submit solution-tied or generic session feedback |
 | `doctor` | — | `--json` | Print redacted diagnostics for GitHits runtime, environment, service URLs, config, and auth storage |
@@ -413,7 +413,7 @@ Deterministic text grep over indexed dependency or repository source. Defaults t
 
 **`--verbose`.** Adds a summary header and grouped file sections with a `>` marker on match lines.
 
-**`stdout` vs `stderr` routing (plain mode).** The pagination hint for `nextCursor` goes to **stderr** so stdout stays machine-friendly.
+**`stdout` vs `stderr` routing (plain mode).** Pagination and zero-match decision guidance go to **stderr** so stdout stays machine-friendly. Empty guidance reports scanned/in-scope counts and the served ref/version when known. A completed scan with zero files in scope recommends loosening selectors; otherwise it recommends changing the pattern or using conceptual `search`, and explicitly rejects an unchanged repeat. When the failed call enabled `--case-sensitive`, it also recommends dropping that flag. An incomplete empty page instead preserves truncation or `--cursor` continuation guidance.
 
 **Exit codes (grep-compatible).**
 

docs/implementation/mcp-cli-parity.md

@@ -73,6 +73,8 @@ test suite anchors the doc.
 - **CLI flags** use `--kebab-case`. They are the user-facing surface.
   `allow_partial_results` maps to CLI `--allow-partial` because the CLI
   name reads better as a command flag while preserving the same behaviour.
+  `search_status.wait_timeout_ms` maps to `search-status --wait <seconds>`;
+  both default to the shared 20-second bounded wait.
 - **Public enum values** are lowercase strings on both surfaces
   (`production`, `test`, `summary`, `all`).
 - **Service coercion** from lowercase enum values to the internal
@@ -119,6 +121,9 @@ test suite anchors the doc.
   `allow_partial_results` / `--allow-partial` opt into backend partial
   payloads while indexing continues; incomplete JSON envelopes may then
   carry non-empty `results` plus the `searchRef`.
+- Completed empty search JSON retains zero-result source/target context;
+  healthy source status remains suppressed for non-empty success. Text advice
+  is renderer-only and never replaces structured JSON.
 
 ### `PARITY-ERROR-ENVELOPE`
 
@@ -132,6 +137,9 @@ test suite anchors the doc.
   mechanism, not a convention.
 - MCP error text is always valid JSON. A client that parses
   `content[0].text` on error gets the same envelope as CLI `--json`.
+- Backend error messages, hints, indexing estimates, available versions/refs,
+  and suggested refs are preserved when supplied. Clients do not replace
+  specific backend guidance or synthesize target candidates.
 - The REST-backed `example`, `languages`, and `feedback` CLI commands preserve
   this envelope for generic transport/backend failures as well as typed auth
   failures. Human mode renders the same message as terminal text.
@@ -144,6 +152,11 @@ test suite anchors the doc.
   CLI-only instructions like `--verbose` or `--lifecycle all`.
 - Default MCP success output should be compact `text-v1`; programmatic
   parity tests must pass `format: "json"` explicitly.
+- Empty `code_grep` decision guidance is shared between MCP text and CLI
+  terminal stderr, with surface-native cursor syntax. Incomplete empty pages
+  render truncation/pagination guidance instead of completed-result pivots.
+  CLI stdout remains empty for grep-compatible zero-match behavior; JSON
+  remains the shared structured envelope.
 
 ## Checklist for adding a new dual-surface tool
 
@@ -347,4 +360,7 @@ envelope shape.
   whole-target regexes must include at least one literal substring.
   `symbol_fields` / `--symbol-field` passes backend symbol
   hydration through to `symbolFields`; the response envelope
-  carries `matches[].symbol` when the backend hydrates it.
+  carries `matches[].symbol` when the backend hydrates it. Empty text uses
+  shared scan/scope/served-target context and branches recovery on whether
+  `filesInScope` is zero. Completed scans reject an unchanged repeat;
+  incomplete empty pages preserve truncation/pagination continuation instead.