Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(index): report a failed embed instead of a healthy semantic index (#3015)

Raghav Chamadiya2dc57adaf944
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 7b7d96dc4..64442edcb 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -210,6 +210,14 @@ repowise init . --no-prose -x "node_modules/" # workspace, no LLM
repowise init . --no-workspace # force single-repo, even in a workspace root
```
+**Exit status when embedding fails.** With a real embedder (anything but
+`mock`), a run whose page vectors fail to write, for example because the
+LanceDB install is broken, still saves its pages and full-text index but
+exits `1`, records `search.semantic: unavailable` in the index scope, and names
+the fix: reinstall the dependency, then `repowise reindex`. `update` follows the
+same rule, and a workspace `init` exits `1` after saving every repo, naming the
+repos whose embed failed. The keyless `mock` embedder never fails a run this way.
+
**Documentation output limit.** Set `max_tokens` in
`.repowise/config.yaml` to bound each model-written page. It is persistent, not
a per-run flag, and is honored by `init`, `update`, `generate`, `restyle`,
@@ -2073,6 +2081,10 @@ Rebuild the vector search index by re-embedding all wiki pages. No LLM calls, on
| `--embedder` | `gemini`, `openai`, `openrouter`, `ollama`, `edenai`, `mock`, or `auto` (default: auto) |
| `--batch-size` | Embedding batch size (default: 32) |
+A reindex that writes every item with a real embedder marks semantic search
+available again in the index scope, clearing what a failed `init` or `update`
+recorded.
+
```bash
repowise reindex
repowise reindex --embedder gemini --batch-size 50
@@ -2091,6 +2103,12 @@ Run health checks on the wiki setup. Auto-detects workspace mode; in workspace m
| `--no-workspace` | Force single-repo mode |
| `--format` | Output: `table` (default) or `json` |
+A `Vector store` row fails when `.repowise/lancedb` exists but cannot be
+opened, and names the error. A store that opens but holds none of the indexable
+pages reports them all missing rather than in sync. `--repair` does not re-embed
+such a store with a paid embedder: it prints the page count and points to
+`repowise reindex`.
+
```bash
repowise doctor # auto-detects
repowise doctor --repair # fix detected store mismatches
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 959af6b91..18c7f3a69 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -29,7 +29,7 @@ Every response carries `_meta`. Fields are present only when they carry a signal
| `stale_warning` | Only on a real signal | HEAD moved and the move changed files this response serves, or the index is very old and git is unreachable. Two commits with identical trees set `index_behind` with no warning |
| `index_scope` | When the index records it | Compact description of how the index was built: run mode, provenance, git tier, whether it is whole |
| `embedder_degraded` | When an embedder is resolved | `true` or `false` |
-| `embedder`, `embedder_warning` | Only when the embedder fell back to a mock or degraded mode | Which embedder, and why |
+| `embedder`, `embedder_warning` | Only when the embedder fell back to a mock or degraded mode, or the semantic index on disk could not be opened | Which embedder, and why |
| `newer_release` | Once per server process | A newer repowise is published; restart the MCP server after upgrading |
| `response_budget` | Always | `limit_chars` (the ceiling), `tier` (`default` or `expanded`), `serialized_chars` (size delivered) |
| `omitted` | When content was cut | `refs`, `tokens`, `restore`. See [Truncation and recovery](#truncation-and-recovery) |
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
index 173558d6a..a8e795d62 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
@@ -420,6 +420,9 @@ def _run_repo_checks(
orphaned_vector: set[str] = set()
missing_from_fts: set[str] = set()
orphaned_fts: set[str] = set()
+ # An index on disk holding no vectors at all. Repairing that is a whole
+ # reindex, which doctor does not start on a hosted embedder unasked.
+ vector_store_empty = False
if db_ok and page_count > 0:
try:
@@ -450,7 +453,7 @@ def _run_repo_checks(
repo = await get_repository_by_path(session, str(repo_path))
if not repo:
await engine.dispose()
- return set(), set(), set(), set()
+ return set(), set(), set(), set(), 0, None, False
pages = await _all_pages_for_reconciliation(session, repo.id)
sql_ids = {p.id for p in pages}
# ``Page``'s primary key is the column ``id``; there is no
@@ -524,6 +527,7 @@ def _run_repo_checks(
# Check vector store
vs_ids: set[str] = set()
+ vs_error: str | None = None
lance_dir = repowise_dir / "lancedb"
if lance_dir.exists():
try:
@@ -531,11 +535,20 @@ def _run_repo_checks(
vs = LanceDBVectorStore(str(lance_dir), embedder=embedder)
vs_ids = await vs.list_page_ids()
await vs.close()
- except Exception:
- pass # LanceDB not available
+ except Exception as exc:
+ # Named, not passed: a store that cannot be opened
+ # used to read as an empty one, and so as "in sync".
+ from repowise.core.persistence.vector_store.lancedb_store import (
+ store_open_fix_hint,
+ )
+
+ vs_error = f"{type(exc).__name__}: {exc}; to fix: {store_open_fix_hint(exc)}"
- m_vec = vector_indexable_ids - vs_ids if vs_ids else set()
- o_vec = vs_ids - vector_sql_ids if vs_ids else set()
+ # An index on disk that holds none of the indexable pages is
+ # every one of them missing. Only no index at all (fast mode,
+ # nothing embedded yet) has nothing to compare.
+ m_vec = vector_indexable_ids - vs_ids if lance_dir.exists() else set()
+ o_vec = vs_ids - vector_sql_ids
# Check FTS
fts = FullTextSearch(engine)
@@ -547,7 +560,8 @@ def _run_repo_checks(
o_fts = fts_ids - sql_ids if fts_ids else set()
await engine.dispose()
- return m_vec, o_vec, m_fts, o_fts, len(stub_ids)
+ empty = lance_dir.exists() and vs_error is None and not vs_ids
+ return m_vec, o_vec, m_fts, o_fts, len(stub_ids), vs_error, empty
(
missing_from_vector,
@@ -555,7 +569,18 @@ def _run_repo_checks(
missing_from_fts,
orphaned_fts,
stub_count,
+ vector_store_error,
+ vector_store_empty,
) = run_async(_check_stores())
+ if vector_store_error is not None:
+ checks.append(
+ _check(
+ "Vector store",
+ False,
+ f"cannot open .repowise/lancedb ({vector_store_error}); semantic "
+ "search is off until it opens, then run `repowise reindex`",
+ )
+ )
vec_ok = not missing_from_vector and not orphaned_vector
vec_detail = (
@@ -843,13 +868,23 @@ def _run_repo_checks(
# that does not exist), so a hosted embedder here is a new
# charge on a command people run to diagnose, not to spend.
# Say so. It is bounded by the missing pages, not the wiki.
- if missing_from_vector and embedder_name != "mock":
+ reindex_instead = (
+ bool(missing_from_vector) and embedder_name != "mock" and vector_store_empty
+ )
+ if reindex_instead:
+ console.print(
+ f" [yellow]The vector store is empty: {len(missing_from_vector)} "
+ f"page(s) need embedding with {embedder_name}. Not starting a "
+ "paid re-embed of the whole wiki from doctor; run "
+ "`repowise reindex` to do it.[/yellow]"
+ )
+ elif missing_from_vector and embedder_name != "mock":
console.print(
f" [dim]Embedding {len(missing_from_vector)} missing "
f"page(s) with {embedder_name}.[/dim]"
)
- if missing_from_vector:
+ if missing_from_vector and not reindex_instead:
async with get_session(sf) as session:
from sqlalchemy import select
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index 70a062166..8ea0f6820 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -252,6 +252,7 @@ def _run_deterministic_generation_phase(
embedder_was_requested: bool,
resume: bool,
timings: Any | None = None,
+ warnings: list[str] | None = None,
) -> str:
"""Render the whole wiki from templates, for ``init --index-only``.
@@ -319,6 +320,7 @@ def _run_deterministic_generation_phase(
resume=resume,
verbose=True,
timings=timings,
+ warnings=warnings,
)
return embedder
@@ -1629,6 +1631,7 @@ def init_command(
embedder_was_requested=embedder_was_requested,
resume=resume,
timings=callback.table,
+ warnings=run_warnings,
)
else:
gen_stop, cost_declined = _run_generation_phase(
@@ -1691,6 +1694,7 @@ def init_command(
embedder_name_resolved=embedder_name_resolved,
resume=resume,
timings=callback.table,
+ warnings=run_warnings,
)
# ---- Persistence ----
@@ -1819,6 +1823,7 @@ def init_command(
base_state["run_mode"] = run_mode
base_state["git_tier"] = git_tier_for_run_mode(run_mode)
apply_git_history_coverage_state(base_state, result)
+ from repowise.cli.providers import semantic_search_status
from repowise.core.generation.selection import count_documentable_files
from repowise.core.index_scope import dropped_files_scope, file_page_scope, stamp_index_scope
@@ -1860,8 +1865,10 @@ def init_command(
search={
"full_text": "available" if result.generated_pages else "unavailable",
"semantic": (
- "available"
- if result.generated_pages and _scope_embedder and _scope_embedder != "mock"
+ semantic_search_status(
+ _scope_embedder, getattr(result, "embed_failed_pages", 0)
+ )
+ if result.generated_pages
else "unavailable"
),
"next_command": "repowise reindex" if result.generated_pages else None,
@@ -2017,3 +2024,13 @@ def init_command(
setup=_setup_outcome,
files_written=files_written,
)
+ # Raised last, so everything above is kept: pages, state and full-text
+ # search are fine. Exiting 0 here is what let a scripted run record a
+ # healthy semantic index that held no vectors.
+ from repowise.cli.providers import embed_failure_message
+
+ _embed_error = embed_failure_message(
+ _scope_embedder, getattr(result, "embed_failed_pages", 0)
+ )
+ if _embed_error:
+ raise click.ClickException(_embed_error)
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
index d06e4b96c..93a1a0e50 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
@@ -272,7 +272,9 @@ def run_repo_generation(
(the pages a resumed run skipped, which persistence must not sweep) and
``vector_store``
(the latter is shared so the Phase-2C decision dedup matches + embeds
- decisions into the same store the pages land in). Returns the pages.
+ decisions into the same store the pages land in), plus
+ ``embed_failed_pages`` (pages whose vectors failed to land). Returns the
+ pages.
``verbose`` controls only console output: the single-repo flow prints the
page count + KG status; the workspace flow stays quiet and prints its own
@@ -337,6 +339,7 @@ def run_repo_generation(
result.preserved_page_ids = preserved_page_ids
generation_scope: dict[str, int | None] = {}
result.generation_scope = generation_scope
+ generation_stats: dict[str, int] = {}
with Progress(*columns, console=console) as gen_progress:
gen_callback: Any = RichProgressCallback(gen_progress, console)
@@ -376,6 +379,7 @@ def run_repo_generation(
),
test_run=test_run,
selection_out=generation_scope,
+ stats_out=generation_stats,
)
)
if warnings is not None:
@@ -398,6 +402,7 @@ def run_repo_generation(
result.generated_pages = generated_pages
result.failed_page_ids = failed_page_ids
+ result.embed_failed_pages = generation_stats.get("embed_failed_pages", 0)
# A page whose provider call failed is still handed back, as a stub rendered
# from structure alone, so that the row exists and a later run can find it
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
index b9f2b517b..fbb36a81f 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -364,6 +364,11 @@ def _stamp_full_init_scope(
)
else:
pages = {"effective_cap": None, "eligible": None, "generated": None, "omitted": None}
+ from repowise.cli.providers import semantic_search_status
+
+ semantic = semantic_search_status(
+ embedder_name_resolved, getattr(result, "embed_failed_pages", 0)
+ )
stamp_index_scope(
state,
{"commit_limit": resolved_commit_limit, "max_file_pages": max_file_pages},
@@ -383,8 +388,8 @@ def _stamp_full_init_scope(
},
search={
"full_text": "available",
- "semantic": "unavailable" if embedder_name_resolved == "mock" else "available",
- "next_command": "repowise reindex" if embedder_name_resolved == "mock" else None,
+ "semantic": semantic,
+ "next_command": "repowise reindex" if semantic == "unavailable" else None,
},
upgrade={"status": "not_applicable", "retryable": False, "completed_stages": []},
)
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
index 732649dc0..fd0fbb693 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
@@ -144,6 +144,10 @@ def show_completion(
_scope = resolve_index_scope(load_state(Path(repo_path)), load_config(Path(repo_path)))
+ # Unavailable also describes a keyless run; only a failed write earns
+ # the failure line.
+ _embed_failed = getattr(result, "embed_failed_pages", 0)
+
_graph_final = result.graph_builder.graph()
_dc_unreachable = sum(
1
@@ -251,11 +255,22 @@ def show_completion(
# Fast mode reaches this branch too, and it generates nothing, so the
# note has to check rather than assume.
if result.generated_pages:
+ # Read from the stamped scope, so the note cannot contradict what
+ # status and MCP report for the same run.
+ if _embed_failed:
+ _search_note = "Full-text\n search works now."
+ elif _scope["search"]["semantic"] == "available":
+ _search_note = "Full-text\n and semantic search work now."
+ else:
+ _search_note = (
+ "Full-text\n search works now; semantic search needs an embedder "
+ "(Ollama is the keyless one)."
+ )
console.print(
" [dim]Every page is derived from structure and says so in its footer. "
- "Full-text\n search works now; semantic search needs an embedder "
- "(Ollama is the keyless one).[/dim]"
+ f"{_search_note}[/dim]"
)
+ _print_embed_failure(_embed_failed)
else:
console.print(
" [dim]No wiki pages: fast mode indexes the graph and git history only.\n"
@@ -320,6 +335,7 @@ def show_completion(
build_completion_panel("repowise init complete", metrics, next_steps=next_steps)
)
console.print()
+ _print_embed_failure(_embed_failed)
_render_defect_accuracy(result)
# A concise, dynamic MCP note (who is connected, how others connect)
# replaces the old wall of manual per-client config: init already wrote
@@ -333,6 +349,15 @@ def show_completion(
_show_generation_checks(result)
+def _print_embed_failure(failed: int) -> None:
+ if failed:
+ console.print(
+ f" [{WARN}]Semantic search is unavailable:[/] embedding failed for "
+ f"{failed} page(s). See the warning above, then run "
+ "[bold]repowise reindex[/bold]."
+ )
+
+
def _show_generation_checks(result: Any) -> None:
"""Report the generation quality checks on the pages this run wrote.
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
index 98f8d5883..2116eecca 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
@@ -45,7 +45,7 @@ from repowise.cli.helpers import (
save_config_partial,
save_state,
)
-from repowise.cli.providers import resolve_embedder
+from repowise.cli.providers import resolve_embedder, semantic_search_status
from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_json
from repowise.cli.ui import (
BRAND,
@@ -296,6 +296,8 @@ class _RepoOutcome:
symbol_count: int = 0
pages_generated: int = 0
docs_outcome: tuple[int, str | None] = (0, None)
+ #: Pages a real embedder failed to write; the repo is still persisted.
+ embed_failed_pages: int = 0
def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCtx) -> _RepoOutcome:
@@ -561,8 +563,8 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
search={
"full_text": "available" if result.generated_pages else "unavailable",
"semantic": (
- "available"
- if result.generated_pages and scope_embedder not in {None, "mock"}
+ semantic_search_status(scope_embedder, getattr(result, "embed_failed_pages", 0))
+ if result.generated_pages
else "unavailable"
),
"next_command": "repowise reindex" if result.generated_pages else None,
@@ -636,11 +638,15 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
embedding_model=(resolve_embedding_model(det_embedder) if det_embedder else None),
)
+ from repowise.cli.providers import embed_failure_message
+
+ failed = getattr(result, "embed_failed_pages", 0)
return _RepoOutcome(
file_count=result.file_count,
symbol_count=result.symbol_count,
pages_generated=pages_generated,
docs_outcome=docs_outcome,
+ embed_failed_pages=failed if embed_failure_message(scope_embedder, failed) else 0,
)
@@ -917,6 +923,7 @@ def _workspace_init(
run_mode=run_mode,
)
+ embed_failures: dict[str, int] = {}
for i, repo in enumerate(selected, 1):
outcome = _ingest_and_generate_repo(repo, i, len(selected), ctx)
if outcome.error:
@@ -926,6 +933,8 @@ def _workspace_init(
total_symbols += outcome.symbol_count
total_pages += outcome.pages_generated
docs_outcomes[repo.alias] = outcome.docs_outcome
+ if outcome.embed_failed_pages:
+ embed_failures[repo.alias] = outcome.embed_failed_pages
# Save workspace config with updated timestamps. On a dry run nothing is
# written for any repo (see _ingest_and_generate_repo), so nothing is
@@ -984,3 +993,15 @@ def _workspace_init(
no_editor_setup=not editor_setup,
)
console.print()
+ # Raised after every repo is persisted, as single-repo init does: the
+ # other repos and full-text search are fine, but a scripted run must see
+ # that these semantic indexes were not built.
+ if embed_failures:
+ import click
+
+ listed = ", ".join(f"{alias} ({n} page(s))" for alias, n in embed_failures.items())
+ raise click.ClickException(
+ f"Embedding failed for {listed}, so semantic search is unavailable there "
+ "(full-text search still works). Fix the cause in the warnings above, "
+ "then run: repowise reindex in each."
+ )
diff --git a/packages/cli/src/repowise/cli/commands/reindex_cmd.py b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
index 70b77e8db..e1dda66d7 100644
--- a/packages/cli/src/repowise/cli/commands/reindex_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
@@ -293,6 +293,21 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
save_config_partial(Path(repo_path), embedder=embedder_name)
+ # The run that clears a failed embed must say so: init and update mark the
+ # semantic leg unavailable and point here, and nothing else flips it back.
+ if indexed and not failed and embedder_name != "mock":
+ from repowise.cli.helpers import load_config, load_state, save_state
+ from repowise.core.index_scope import stamp_index_scope
+
+ state = load_state(Path(repo_path))
+ if "index_scope" in state:
+ stamp_index_scope(
+ state,
+ load_config(Path(repo_path)),
+ search={"semantic": "available", "next_command": None},
+ )
+ save_state(Path(repo_path), state)
+
console.print(
f"\n[bold green]Done![/bold green] Indexed {indexed} items"
+ (f" ({failed} failed)" if failed else "")
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 3cb54dff2..22d1b380c 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -98,6 +98,34 @@ def _generation_warning_handler(
return _handle
+def _fail_on_embed_failure(
+ repo_path: Path, embedder: str | None, embed_failed_pages: int, emitter: Any
+) -> None:
+ """Exit non-zero, and say semantic search is unavailable, after a failed embed.
+
+ Called once the run's pages and state are saved: full-text search is
+ fine, so only the search leg and the exit status change. A zero exit here
+ let a scripted run, or the post-commit log, read a failed write as a
+ healthy index.
+ """
+ from repowise.cli.providers import embed_failure_message
+ from repowise.core.index_scope import stamp_index_scope
+
+ message = embed_failure_message(embedder, embed_failed_pages)
+ if message is None:
+ return
+ state = load_state(repo_path)
+ stamp_index_scope(
+ state,
+ load_config(repo_path),
+ search={"semantic": "unavailable", "next_command": "repowise reindex"},
+ )
+ save_state(repo_path, state)
+ if emitter is not None:
+ emitter.error(message)
+ raise click.ClickException(message)
+
+
def _docs_provider_prompt_allowed(emitter: Any) -> bool:
"""Whether a docs run may block on an interactive provider prompt.
@@ -1549,6 +1577,7 @@ def run_update(
# with no pages (fast mode, or an index from before templates existed)
# skip this and stay a pure index.
det_pages: list = []
+ render_stats: dict[str, int] = {}
index_only_cost = 0.0
docs_mode = resolve_docs_mode(state)
if docs_mode == "deterministic":
@@ -1584,6 +1613,7 @@ def run_update(
dead_code_report=dead_code_report,
prior_page_ids=prior_ids,
full_scope=generation_config_changed,
+ stats_out=render_stats,
)
if stale_deterministic_ids and not generation_config_changed:
det_pages.extend(
@@ -1600,6 +1630,7 @@ def run_update(
degraded=degraded,
dead_code_report=dead_code_report,
prior_page_ids=prior_ids,
+ stats_out=render_stats,
)
)
if generation_config_changed and len(degraded) > degraded_before_render:
@@ -1721,6 +1752,15 @@ def run_update(
generated_pages=det_pages,
docs_mode=docs_mode,
)
+ if render_stats.get("embed_failed_pages"):
+ from .deterministic import deterministic_embedder_name
+
+ _fail_on_embed_failure(
+ repo_path,
+ deterministic_embedder_name(cfg),
+ render_stats["embed_failed_pages"],
+ emitter,
+ )
if emitter is not None:
emitter.done(
ok=True,
@@ -2244,6 +2284,7 @@ def run_update(
# Surface the FAQ-weighted budget tilt when session demand shaped this run
# (silent when there is no history to weight; human console mode only).
+ full_stats = {"embed_failed_pages": generator.embed_failed_pages}
if checkpointer.failure:
degraded.append(f"Per-page crash checkpointing: {checkpointer.failure}")
@@ -2271,6 +2312,7 @@ def run_update(
dead_code_report=dead_code_report,
prior_page_ids=prior_pages,
vector_store=decision_vector_store,
+ stats_out=full_stats,
)
)
@@ -2463,7 +2505,20 @@ def run_update(
provider=provider,
generated_pages=generated_pages,
)
+
+ def _fail_if_embed_failed() -> None:
+ if full_stats["embed_failed_pages"]:
+ from repowise.cli.providers import resolve_embedder
+
+ _fail_on_embed_failure(
+ repo_path,
+ resolve_embedder(cfg.get("embedder")),
+ full_stats["embed_failed_pages"],
+ emitter,
+ )
+
if emitter is not None:
+ _fail_if_embed_failed()
emitter.done(
ok=True,
pages_generated=len(generated_pages),
@@ -2484,4 +2539,5 @@ def run_update(
degraded=degraded,
)
_render_update_report(generated_pages, affected, new_decision_markers, elapsed, detail=verbose)
+ _fail_if_embed_failed()
return UpdateOutcome.REGENERATED
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
index 00f506f58..00af8a2e2 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -92,6 +92,7 @@ def regenerate_deterministic_pages(
dead_code_report: Any = None,
prior_page_ids: dict | None = None,
full_scope: bool = False,
+ stats_out: dict[str, int] | None = None,
) -> list:
"""Re-render the template pages for *regenerate_paths*. Never raises.
@@ -119,6 +120,7 @@ def regenerate_deterministic_pages(
prior_page_ids=prior_page_ids,
degrade_label="Template page refresh",
full_scope=full_scope,
+ stats_out=stats_out,
)
@@ -137,6 +139,7 @@ def regenerate_deterministic_page_ids(
dead_code_report: Any = None,
prior_page_ids: dict | None = None,
vector_store: Any = None,
+ stats_out: dict[str, int] | None = None,
) -> list:
"""Render exact deterministic page ids from the complete repository view.
@@ -164,6 +167,7 @@ def regenerate_deterministic_page_ids(
degrade_label="Structural page refresh",
only_page_ids=page_ids,
vector_store=vector_store,
+ stats_out=stats_out,
)
@@ -185,11 +189,16 @@ def _render_pages(
full_scope: bool = False,
only_page_ids: set[str] | None = None,
vector_store: Any = None,
+ stats_out: dict[str, int] | None = None,
) -> list:
"""Render the changed files' pages from structure (free, no LLM).
Every file page is structural now, so there is one render mode: the template
renderer, driven by ``deterministic=True``. There is no model path to choose.
+
+ ``stats_out["embed_failed_pages"]`` accumulates the pages whose vectors
+ failed to land, so the caller can fail the run instead of reporting a
+ healthy semantic index.
"""
from repowise.core.generation import ContextAssembler, GenerationConfig, PageGenerator
from repowise.core.providers.llm.template import TemplateProvider
@@ -255,7 +264,7 @@ def _render_pages(
# A template render takes every page it is fed; deterministic mode
# bypasses the budget already, so no page-id scoping is needed.
with console.status(" Re-rendering wiki pages from structure…"):
- return run_async(
+ pages = run_async(
generator.generate_all(
affected_parsed,
affected_source,
@@ -266,8 +275,15 @@ def _render_pages(
repo_path=repo_path,
dead_code_report=dead_code_report,
only_page_ids=only_page_ids,
+ # Without it a failed embed was logged and nothing else.
+ on_warning=degraded.append,
)
)
+ if stats_out is not None:
+ stats_out["embed_failed_pages"] = (
+ stats_out.get("embed_failed_pages", 0) + generator.embed_failed_pages
+ )
+ return pages
except Exception as exc:
degraded.append(f"{degrade_label}: {exc}")
return []
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py b/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
index f41a912ec..765bb28a2 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
@@ -27,8 +27,8 @@ def _build_update_vector_store(
upserted decisions *without* a vector store, so semantic dedup, decision
search visibility, and supersession detection were all off on incremental
runs. We mirror ``init``'s store construction (LanceDB at
- ``.repowise/lancedb`` so previously-embedded decisions are matchable; the
- in-memory store is a degraded fallback that only sees this run's vectors).
+ ``.repowise/lancedb`` so previously-embedded decisions are matchable; a
+ missing or broken lancedb fails on first use, not here).
Returns ``None`` on any failure — the decision upsert still works without
it. A failure is recorded in *degraded* (when given) so the run's degraded
panel says why semantic dedup is off instead of silently skipping it
diff --git a/packages/cli/src/repowise/cli/providers/__init__.py b/packages/cli/src/repowise/cli/providers/__init__.py
index 483014802..d375c7b4a 100644
--- a/packages/cli/src/repowise/cli/providers/__init__.py
+++ b/packages/cli/src/repowise/cli/providers/__init__.py
@@ -21,13 +21,19 @@ from repowise.cli.providers.embedders import (
resolve_embedder_for_repo,
template_run_embedder,
)
-from repowise.cli.providers.vector_store import build_vector_store, existing_vector_dim
+from repowise.cli.providers.vector_store import (
+ build_vector_store,
+ embed_failure_message,
+ existing_vector_dim,
+ semantic_search_status,
+)
__all__ = [
"build_cost_tracker",
"build_embedder",
"build_vector_store",
"cost_tracking_disabled",
+ "embed_failure_message",
"embedder_was_requested",
"existing_vector_dim",
"flush_cost_tracker",
@@ -35,5 +41,6 @@ __all__ = [
"pin_names_an_embedder",
"resolve_embedder",
"resolve_embedder_for_repo",
+ "semantic_search_status",
"template_run_embedder",
]
diff --git a/packages/cli/src/repowise/cli/providers/vector_store.py b/packages/cli/src/repowise/cli/providers/vector_store.py
index bda147b1a..ac92903bd 100644
--- a/packages/cli/src/repowise/cli/providers/vector_store.py
+++ b/packages/cli/src/repowise/cli/providers/vector_store.py
@@ -49,6 +49,34 @@ def existing_vector_dim(lance_dir: Path) -> int | None:
return dim
+def semantic_search_status(embedder: str | None, embed_failed_pages: int) -> str:
+ """Whether a run left semantic search usable: ``available`` or not.
+
+ Read from what the run did, not only from the embedder's name: a real
+ embedder whose vector writes failed leaves the same empty index the mock
+ does, and calling it available hid exactly that.
+ """
+ if not embedder or embedder == "mock" or embed_failed_pages:
+ return "unavailable"
+ return "available"
+
+
+def embed_failure_message(embedder: str | None, embed_failed_pages: int) -> str | None:
+ """The error a run exits with when a real embedder failed to write.
+
+ ``None`` for the mock: its vectors were never semantic, so losing them
+ changes nothing a reader relies on.
+ """
+ if not embed_failed_pages or not embedder or embedder == "mock":
+ return None
+ return (
+ f"Embedding failed for {embed_failed_pages} page(s), so semantic search is "
+ "unavailable (full-text search still works). Fix the cause in the warning "
+ "above (for a broken LanceDB install: pip install --force-reinstall lancedb), "
+ "then run: repowise reindex"
+ )
+
+
def _mock_would_clobber(lance_dir: Path, embedder: Any) -> bool:
"""True when writing *embedder* into the store at *lance_dir* would drop it.
@@ -72,14 +100,16 @@ def build_vector_store(repo_path: Path, embedder: Any) -> Any | None:
"""Build the repo-local vector store, preferring LanceDB.
Uses LanceDB at ``.repowise/lancedb`` so previously-embedded pages and
- decisions stay matchable across runs; falls back to an in-memory store
- (which only sees this run's vectors) when LanceDB isn't installed.
+ decisions stay matchable across runs. There is no in-memory fallback:
+ the store imports lancedb on first use, so a missing or broken install
+ fails there with a named error, which the embed step reports as a failed
+ embed rather than a run that only looked healthy.
Returns ``None`` when handing back a store would destroy the existing one
(see :func:`_mock_would_clobber`). Every caller already treats ``None`` as
"embedding is off for this run"; full-text search is unaffected either way.
"""
- from repowise.core.persistence.vector_store import InMemoryVectorStore
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
lance_dir = repo_path / ".repowise" / "lancedb"
if _mock_would_clobber(lance_dir, embedder):
@@ -102,10 +132,5 @@ def build_vector_store(repo_path: Path, embedder: Any) -> Any | None:
"Set an\nembedder key and run [cyan]repowise reindex[/cyan] to refresh it."
)
return None
- try:
- from repowise.core.persistence.vector_store import LanceDBVectorStore
-
- lance_dir.mkdir(parents=True, exist_ok=True)
- return LanceDBVectorStore(str(lance_dir), embedder=embedder)
- except ImportError:
- return InMemoryVectorStore(embedder)
+ lance_dir.mkdir(parents=True, exist_ok=True)
+ return LanceDBVectorStore(str(lance_dir), embedder=embedder)
diff --git a/packages/cli/src/repowise/cli/tool_bridge.py b/packages/cli/src/repowise/cli/tool_bridge.py
index f7f7c2e8e..66233eea1 100644
--- a/packages/cli/src/repowise/cli/tool_bridge.py
+++ b/packages/cli/src/repowise/cli/tool_bridge.py
@@ -74,6 +74,8 @@ async def _acall_tool(
engine = create_engine(db_url)
session_factory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
store = await _open_vector_store(repo_path)
+ if tool_name in _VECTOR_TOOLS:
+ store = await _connect_or_degrade(store)
init_tool_state(
session_factory,
FullTextSearch(engine),
@@ -122,6 +124,33 @@ def _budgeted(tool_name: str, result: dict) -> dict:
)
+#: Tools whose answer reads the vector store. Only these open it up front:
+#: importing lancedb costs about a second, which every other tool skips.
+_VECTOR_TOOLS = frozenset({"search_codebase", "get_answer"})
+
+
+async def _connect_or_degrade(store: Any) -> Any:
+ """Open a LanceDB store now, or fall back and say so in ``_meta``.
+
+ The store imports lancedb lazily, so a missing or broken install only
+ fails on first use. A vector tool makes that use, so it is made here,
+ where a failure can still be reported instead of passing for healthy.
+ """
+ from repowise.core.persistence.vector_store import InMemoryVectorStore, LanceDBVectorStore
+
+ if not isinstance(store, LanceDBVectorStore):
+ return store
+ try:
+ await store._ensure_connected()
+ return store
+ except Exception as exc:
+ # The tool still answers from full-text search.
+ from repowise.server.mcp_server._server import _mark_vector_store_unreadable
+
+ _mark_vector_store_unreadable(exc)
+ return InMemoryVectorStore(embedder=store._embedder)
+
+
async def _open_vector_store(repo_path: Path) -> Any:
"""The repo's LanceDB store, or an in-memory one when there is none.
@@ -142,17 +171,15 @@ async def _open_vector_store(repo_path: Path) -> Any:
requested = resolve_embedder_for_repo(repo_path)
embedder = build_embedder(requested, repo_path)
_publish_embedder_status(requested, embedder)
+ from repowise.server.mcp_server import _state
+
+ _state._vector_store_errors.pop("", None)
lance_dir = repo_path / REPOWISE_DIR / "lancedb"
if lance_dir.is_dir():
- try:
- from repowise.core.persistence.vector_store import LanceDBVectorStore
-
- return LanceDBVectorStore(str(lance_dir), embedder=embedder)
- except Exception:
- # No lancedb wheel, or an unreadable table. The tools that do not
- # need vector search still work off the session factory and FTS,
- # so degrade rather than refuse to run.
- pass
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+
+ # Not opened here: see ``_connect_or_degrade``.
+ return LanceDBVectorStore(str(lance_dir), embedder=embedder)
return InMemoryVectorStore(embedder=embedder)
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index e87893285..ee1bf59f1 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -176,6 +176,10 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
# table.
self._prior_pages: dict[str, PriorPage] = prior_pages or {}
self._reuse_count: int = 0
+ # Pages whose vectors failed to land this run. Read by callers after
+ # ``generate_all``: a failed embed leaves semantic search without
+ # them, which a run must not report as healthy.
+ self.embed_failed_pages: int = 0
# Per-template structural fingerprints, lazily computed; every input
# they fold is fixed for the generator's lifetime. Keyed by template
# name because each structural page type folds its own template source.
@@ -286,6 +290,7 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
# onboarding level would otherwise report the previous run's
# vocabulary as its own.
reset_house_terms()
+ self.embed_failed_pages = 0
return await run_generate_all(
self,
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index 1c971253c..c1c6cc896 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -754,6 +754,7 @@ class _GenerationRun:
try:
await self.vector_store.embed_batch(embed_items)
except Exception as e:
+ self.gen.embed_failed_pages += len(embed_items)
log.warning(
"rag.embed_batch_failed",
level=level,
diff --git a/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py b/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py
index ac1db0412..734ccd68d 100644
--- a/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py
+++ b/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py
@@ -134,6 +134,21 @@ def _last_row_per_page(batches: list[Any]) -> Any:
return table
+class LanceDBUnavailableError(RuntimeError):
+ """lancedb is missing or broken: an install problem, not a store one."""
+
+
+def store_open_fix_hint(exc: BaseException) -> str:
+ """What to do about a store that would not open, by what actually failed.
+
+ Only an install problem earns "reinstall"; a locked or unreadable table
+ does not, and telling someone to reinstall for it sends them the wrong way.
+ """
+ if isinstance(exc, (LanceDBUnavailableError, ImportError, AttributeError)):
+ return "pip install --force-reinstall lancedb"
+ return "retry; if it persists, run repowise doctor"
+
+
class LanceDBVectorStore(VectorStore):
"""Vector store backed by LanceDB (embedded, local file storage).
@@ -162,9 +177,14 @@ class LanceDBVectorStore(VectorStore):
return
try:
import lancedb # type: ignore[import]
- except ImportError as exc:
- raise RuntimeError(
- "LanceDB is not installed. Install it with: pip install repowise-core[search]"
+
+ connect_async = lancedb.connect_async
+ except (ImportError, AttributeError) as exc:
+ # A partial install imports fine and lacks the async API, which
+ # used to surface as a bare AttributeError far from its cause.
+ raise LanceDBUnavailableError(
+ f"LanceDB is missing or broken ({type(exc).__name__}: {exc}). "
+ "Reinstall it with: pip install --force-reinstall lancedb"
) from exc
# ``Session`` arrived after the oldest supported LanceDB; without it
@@ -175,7 +195,7 @@ class LanceDBVectorStore(VectorStore):
if session_cls is not None
else {}
)
- self._db = await lancedb.connect_async(self._db_path, **kwargs)
+ self._db = await connect_async(self._db_path, **kwargs)
table_names = await self._db.table_names()
if self._table_name in table_names:
self._table = await self._db.open_table(self._table_name)
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index cbc3e594d..eaa7c1426 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -55,6 +55,7 @@ async def run_generation(
test_run: bool = False,
selection_out: dict[str, Any] | None = None,
persisted_page_ids: set[str] | None = None,
+ stats_out: dict[str, int] | None = None,
) -> list[Any]:
"""Run LLM-powered page generation.
@@ -75,6 +76,10 @@ async def run_generation(
``persisted_page_ids`` (ids with a stored page row) narrows what a
``resume`` run treats as already done; see ``PageGenerator.generate_all``.
+ ``stats_out`` is filled with ``embed_failed_pages``: how many pages this
+ run failed to embed, so a caller can refuse to call semantic search
+ healthy after a failed write.
+
``test_run`` limits generation to the top 10 files by PageRank, so a quick
validation run can exercise the whole generation path without paying for a
full index's worth of pages.
@@ -218,6 +223,8 @@ async def run_generation(
on_warning=on_warning,
persisted_page_ids=persisted_page_ids,
)
+ if stats_out is not None:
+ stats_out["embed_failed_pages"] = generator.embed_failed_pages
selection = getattr(generator, "selection", None)
if selection_out is not None and selection is not None:
selection_out.update(
diff --git a/packages/core/src/repowise/core/workspace/registry.py b/packages/core/src/repowise/core/workspace/registry.py
index 6034d7b71..8a9639793 100644
--- a/packages/core/src/repowise/core/workspace/registry.py
+++ b/packages/core/src/repowise/core/workspace/registry.py
@@ -80,10 +80,14 @@ class RepoRegistry:
workspace_root: Path,
ws_config: Any, # WorkspaceConfig
embedder_factory: Callable[[], Any] | None = None,
+ on_vector_store_error: Callable[[str, BaseException], None] | None = None,
) -> None:
self._workspace_root = workspace_root
self._ws_config = ws_config
self._embedder_factory = embedder_factory
+ # Told when a repo's semantic index exists but cannot be opened, so
+ # the server can stop calling semantic search healthy.
+ self._on_vector_store_error = on_vector_store_error
self._contexts: dict[str, RepoContext] = {}
self._access_order: dict[str, float] = {}
self._vs_tasks: dict[str, asyncio.Task[None]] = {}
@@ -271,12 +275,18 @@ class RepoRegistry:
embedder: Any,
) -> None:
"""Background task: load LanceDB vector stores for a repo."""
+ lance_dir = repo_path / ".repowise" / "lancedb"
+
+ def _report(exc: BaseException) -> None:
+ # No index on disk is a keyless repo, not a failure.
+ if lance_dir.exists() and self._on_vector_store_error is not None:
+ self._on_vector_store_error(ctx.alias, exc)
+
try:
try:
await asyncio.to_thread(__import__, "lancedb")
from repowise.core.persistence.vector_store import LanceDBVectorStore
- lance_dir = repo_path / ".repowise" / "lancedb"
if lance_dir.exists():
vs = LanceDBVectorStore(str(lance_dir), embedder=embedder)
await vs._ensure_connected()
@@ -284,13 +294,14 @@ class RepoRegistry:
# Decisions live under the "decision:" page-id namespace.
ctx.vector_store = vs
ctx.decision_store = vs
- except ImportError:
- pass
- except Exception:
+ except ImportError as exc:
+ _report(exc)
+ except Exception as exc:
_log.warning(
"LanceDB load failed for '%s' — using InMemory fallback",
ctx.alias,
)
+ _report(exc)
finally:
# Only signal ready if this context is still the active one.
# If it was evicted before we finished loading, a fresh context
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index 7edef142a..79abe8ff3 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -530,7 +530,7 @@ def semantic_search_state() -> bool | None:
status = getattr(_state, "_embedder_status", None)
if not status:
return None
- if status.get("degraded"):
+ if status.get("degraded") or getattr(_state, "_vector_store_errors", None):
return False
return status.get("active") != "mock"
@@ -569,7 +569,8 @@ def _embedder_meta() -> dict[str, Any]:
# Embedder never initialised, so there is nothing to report either way.
# Absence means "not evaluated", distinct from an explicit ``false``.
return {}
- if not status.get("degraded"):
+ store_errors = getattr(_state, "_vector_store_errors", None) or {}
+ if not status.get("degraded") and not store_errors:
if status.get("active") == "mock":
return {"embedder": "mock", "embedder_degraded": False, "semantic_search": False}
return {"embedder_degraded": False}
@@ -578,7 +579,7 @@ def _embedder_meta() -> dict[str, Any]:
"embedder_degraded": True,
"semantic_search": False,
}
- reason = status.get("reason")
+ reason = status.get("reason") or " ".join(store_errors.values())
if reason:
out["embedder_warning"] = reason
return out
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index 26a64b22f..2fd692736 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -388,6 +388,28 @@ async def _warm_lancedb() -> None:
_state._lancedb_ready.set()
+def _mark_vector_store_unreadable(exc: BaseException, alias: str | None = None) -> None:
+ """Flag semantic search degraded: the index exists but cannot be opened.
+
+ Recorded in ``_state._vector_store_errors``, which ``build_meta`` reads
+ beside the embedder status, so ``embedder_degraded`` and
+ ``embedder_warning`` carry it and a later embedder resolve cannot erase it.
+ Without this a broken LanceDB install served an empty in-memory store with
+ ``embedder_degraded: false``.
+ """
+ from repowise.core.persistence.vector_store.lancedb_store import store_open_fix_hint
+
+ where = f" for '{alias}'" if alias else ""
+ reason = (
+ f"The semantic index{where} exists but could not be opened "
+ f"({type(exc).__name__}: {exc}). Semantic search (search_codebase, "
+ "get_answer) is off; full-text search still works. To fix: "
+ f"{store_open_fix_hint(exc)}, then restart the MCP server."
+ )
+ _log.error(reason)
+ _state._vector_store_errors[alias or ""] = reason
+
+
async def _load_vector_stores(repo_path: str | None) -> None:
"""Load embedder + vector stores in the background.
@@ -412,25 +434,26 @@ async def _load_vector_stores(repo_path: str | None) -> None:
embedder = _query_embedder()
vector_store: Any = InMemoryVectorStore(embedder=embedder)
+ from pathlib import Path
+
+ lance_dir = Path(repo_path) / ".repowise" / "lancedb" if repo_path else None
try:
# Step 1 — import lancedb in a thread to keep event loop free.
await _asyncio.to_thread(__import__, "lancedb")
from repowise.core.persistence.vector_store import LanceDBVectorStore
- if repo_path:
- from pathlib import Path
-
- lance_dir = Path(repo_path) / ".repowise" / "lancedb"
- if lance_dir.exists():
- vs = LanceDBVectorStore(str(lance_dir), embedder=embedder)
- # Step 2 — pre-connect so first search() is instant.
- await vs._ensure_connected()
- vector_store = vs
- except ImportError:
- pass
- except Exception:
- _log.warning("LanceDB pre-connect failed — using InMemory fallback")
+ if lance_dir is not None and lance_dir.exists():
+ vs = LanceDBVectorStore(str(lance_dir), embedder=embedder)
+ # Step 2: pre-connect so first search() is instant.
+ await vs._ensure_connected()
+ vector_store = vs
+ _state._vector_store_errors.pop("", None)
+ except Exception as exc:
+ # ImportError included: with an index on disk, a missing lancedb
+ # is as broken as an unreadable one. No index is a keyless repo.
+ if lance_dir is not None and lance_dir.exists():
+ _mark_vector_store_unreadable(exc)
# decision_store is repointed to the shared page store — decisions are
# now embedded under the "decision:" namespace within the same table.
@@ -537,6 +560,7 @@ async def _lifespan(server: FastMCP):
workspace_root=ws_root,
ws_config=ws_config,
embedder_factory=_query_embedder,
+ on_vector_store_error=lambda alias, exc: _mark_vector_store_unreadable(exc, alias),
)
# Eagerly load the default repo so tools work immediately. A failure
diff --git a/packages/server/src/repowise/server/mcp_server/_state.py b/packages/server/src/repowise/server/mcp_server/_state.py
index be60de3b7..2d3493171 100644
--- a/packages/server/src/repowise/server/mcp_server/_state.py
+++ b/packages/server/src/repowise/server/mcp_server/_state.py
@@ -58,6 +58,12 @@ _test_impact_lock: tuple[Any, asyncio.Lock] | None = None
# "degraded": bool, "reason": str (only when degraded)}.
_embedder_status: dict[str, Any] | None = None
+# Semantic indexes that exist on disk but would not open, keyed by repo alias
+# ("" for the single-repo server), valued with the reason. Kept apart from
+# ``_embedder_status`` because resolving the embedder again (every workspace
+# repo load) rewrites that, and must not clear a store failure.
+_vector_store_errors: dict[str, str] = {}
+
# Release currency. The stdio server is the longest-lived process the product
# runs and was the one path that never checked PyPI, so a client could sit on
# an old release for weeks with no signal. ``_release_check`` is the latest
diff --git a/tests/unit/cli/test_doctor_store_reconciliation.py b/tests/unit/cli/test_doctor_store_reconciliation.py
index eddb35909..8606bf49b 100644
--- a/tests/unit/cli/test_doctor_store_reconciliation.py
+++ b/tests/unit/cli/test_doctor_store_reconciliation.py
@@ -24,12 +24,7 @@ PAGE_MISSING = "file_page:dropped.py"
async def _build_repo(tmp_path: Path) -> Path:
- """A repo whose database holds two pages and whose store holds one.
-
- The reconciliation only reports a missing page when the store is
- non-empty — an empty store reads as "not indexed yet", not as drift — so
- the kept page is what makes the missing one visible.
- """
+ """A repo whose database holds two pages and whose store holds one."""
import git as gitpython
from repowise.core.persistence import (
@@ -140,3 +135,89 @@ def test_a_failed_reconciliation_no_longer_passes_as_a_bare_note(tmp_path: Path)
_ok, detail = broken["Store consistency"]
assert "RuntimeError" in detail
assert "store unreadable" in detail
+
+
+def test_an_unopenable_vector_store_is_a_failing_row(tmp_path: Path, monkeypatch) -> None:
+ """It used to read as an empty store, and so as "in sync"."""
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+
+ repo_path = asyncio.run(_build_repo(tmp_path))
+
+ async def _boom(self):
+ raise RuntimeError("LanceDB is missing or broken (AttributeError: connect_async)")
+
+ monkeypatch.setattr(LanceDBVectorStore, "_ensure_connected", _boom)
+ rows = _rows(repo_path)
+
+ assert "Vector store" in rows
+ ok, detail = rows["Vector store"]
+ assert ok is False
+ assert "connect_async" in detail
+ assert "repowise reindex" in detail
+ assert rows["SQL ↔ Vector Store"] != (True, "in sync")
+
+
+def test_an_empty_vector_store_is_not_in_sync(tmp_path: Path) -> None:
+ import shutil
+
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ repo_path = asyncio.run(_build_repo(tmp_path))
+ lance_dir = repo_path / ".repowise" / "lancedb"
+ shutil.rmtree(lance_dir)
+
+ async def _empty_table():
+ store = LanceDBVectorStore(str(lance_dir), embedder=MockEmbedder())
+ await store._ensure_connected()
+ await store.close()
+
+ lance_dir.mkdir()
+ asyncio.run(_empty_table())
+ ok, detail = _rows(repo_path)["SQL ↔ Vector Store"]
+
+ assert ok is False
+ assert detail == "2 missing, 0 orphaned"
+
+
+def test_repair_does_not_reembed_a_whole_wiki_on_a_paid_embedder(tmp_path: Path, monkeypatch) -> None:
+ """An empty store is a whole reindex; doctor points there instead of spending."""
+ import shutil
+
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ repo_path = asyncio.run(_build_repo(tmp_path))
+ lance_dir = repo_path / ".repowise" / "lancedb"
+ shutil.rmtree(lance_dir)
+ lance_dir.mkdir()
+
+ async def _empty_table():
+ store = LanceDBVectorStore(str(lance_dir), embedder=MockEmbedder())
+ await store._ensure_connected()
+ await store.close()
+
+ asyncio.run(_empty_table())
+ embedded: list[str] = []
+
+ async def _record(self, page_id, *_a, **_k):
+ embedded.append(page_id)
+
+ monkeypatch.setattr(LanceDBVectorStore, "embed_and_upsert", _record)
+ monkeypatch.setattr(
+ "repowise.cli.providers.resolve_embedder_for_repo", lambda _p: "openai"
+ )
+ monkeypatch.setattr(
+ "repowise.cli.providers.build_embedder", lambda _n, _p=None: MockEmbedder()
+ )
+ printed: list[str] = []
+ monkeypatch.setattr(
+ repo_checks.console, "print", lambda *a, **k: printed.append(" ".join(map(str, a)))
+ )
+
+ repo_checks._run_repo_checks(repo_path, repair=True)
+
+ assert embedded == []
+ out = " ".join(" ".join(printed).split())
+ assert "2 page(s) need embedding with openai" in out
+ assert "repowise reindex" in out
diff --git a/tests/unit/cli/test_embed_failure_reporting.py b/tests/unit/cli/test_embed_failure_reporting.py
new file mode 100644
index 000000000..39942468a
--- /dev/null
+++ b/tests/unit/cli/test_embed_failure_reporting.py
@@ -0,0 +1,473 @@
+"""A failed embed must not be reported as a healthy semantic index.
+
+With a broken LanceDB install, ``init`` printed "Embedding failed", exited 0,
+stamped ``search.semantic = available`` from the embedder's name alone, and
+closed with a note that had nothing to do with what happened. These tests pin
+the count that replaced the guess, the exit status, the stamped scope, the
+closing card, and the ``reindex`` that clears it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import click
+import pytest
+from click.testing import CliRunner
+from rich.console import Console
+
+from repowise.cli.providers import embed_failure_message, semantic_search_status
+from repowise.core.generation.models import GeneratedPage
+
+
+ ("embedder", "failed", "expected"),
+ [
+ ("openai", 0, "available"),
+ ("openai", 2, "unavailable"),
+ ("mock", 0, "unavailable"),
+ (None, 0, "unavailable"),
+ ],
+)
+def test_semantic_status_reads_what_the_run_did(embedder, failed, expected):
+ assert semantic_search_status(embedder, failed) == expected
+
+
+def test_only_a_real_embedder_that_failed_is_an_error():
+ assert embed_failure_message("openai", 0) is None
+ # The mock's vectors were never semantic; losing them changes nothing.
+ assert embed_failure_message("mock", 5) is None
+ message = embed_failure_message("ollama", 5)
+ assert message is not None
+ assert "5 page(s)" in message
+ assert "repowise reindex" in message
+ assert "pip install --force-reinstall lancedb" in message
+
+
+def test_the_full_init_scope_marks_a_failed_embed_unavailable():
+ from repowise.cli.commands.init_cmd.persistence import _stamp_full_init_scope
+
+ def _stamp(failed: int) -> dict:
+ state: dict = {}
+ result = SimpleNamespace(
+ health_report=object(),
+ generation_scope={"effective_cap": 1, "eligible": 1, "generated": 1, "omitted": 0},
+ traversal_stats=None,
+ embed_failed_pages=failed,
+ )
+ _stamp_full_init_scope(
+ state,
+ result,
+ SimpleNamespace(provider_name="openai", model_name="m"),
+ resolved_commit_limit=10,
+ max_file_pages=None,
+ embedder_name_resolved="openai",
+ )
+ return state["index_scope"]["search"]
+
+ assert _stamp(0) == {
+ "full_text": "available",
+ "semantic": "available",
+ "next_command": None,
+ }
+ assert _stamp(3)["semantic"] == "unavailable"
+ assert _stamp(3)["next_command"] == "repowise reindex"
+
+
+def test_run_repo_generation_records_the_failed_count(tmp_path, monkeypatch):
+ async def _fake_generation(**kwargs):
+ kwargs["stats_out"]["embed_failed_pages"] = 4
+ return []
+
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd._generation_persist.run_generation_with_persistence",
+ _fake_generation,
+ )
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.generation._enrich_knowledge_graph", lambda **kw: None
+ )
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.generation.console.print", lambda *a, **k: None
+ )
+ from repowise.cli.commands.init_cmd.generation import run_repo_generation
+
+ result = SimpleNamespace(
+ repo_name="r",
+ parsed_files=[],
+ source_map={},
+ graph_builder=MagicMock(),
+ repo_structure=MagicMock(),
+ git_meta_map={},
+ vector_store=object(),
+ )
+ run_repo_generation(
+ repo_path=tmp_path,
+ result=result,
+ provider=SimpleNamespace(provider_name="template", model_name="template"),
+ gen_config=SimpleNamespace(max_concurrency=1, deterministic=True),
+ concurrency=1,
+ embedder_name_resolved="mock",
+ resume=False,
+ verbose=False,
+ )
+ assert result.embed_failed_pages == 4
+
+
+# ---------------------------------------------------------------------------
+# Closing card
+# ---------------------------------------------------------------------------
+
+
+def _page() -> GeneratedPage:
+ return GeneratedPage(
+ page_id="file_page:a.py",
+ page_type="file_page",
+ title="a.py",
+ content="content",
+ source_hash="h",
+ model_name="template",
+ provider_name="template",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=2,
+ target_path="a.py",
+ created_at="2026-10-03T00:00:00Z",
+ updated_at="2026-10-03T00:00:00Z",
+ )
+
+
+def _closing_card(tmp_path: Path, monkeypatch, *, semantic: str, failed: int) -> str:
+ from repowise.cli.commands.init_cmd.reporting import show_completion
+
+ (tmp_path / ".repowise").mkdir(exist_ok=True)
+ (tmp_path / ".repowise" / "state.json").write_text(
+ json.dumps({"index_scope": {"search": {"full_text": "available", "semantic": semantic}}}),
+ encoding="utf-8",
+ )
+ buf = io.StringIO()
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.reporting.console",
+ Console(file=buf, width=200, force_terminal=False),
+ )
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.reporting.build_completion_panel",
+ lambda title, metrics, next_steps=None: "PANEL",
+ )
+ graph = MagicMock()
+ graph.number_of_nodes.return_value = 1
+ graph.number_of_edges.return_value = 0
+ show_completion(
+ repo_path=tmp_path,
+ result=SimpleNamespace(
+ graph_builder=MagicMock(graph=lambda: graph),
+ dead_code_report=None,
+ decision_report=None,
+ git_summary=None,
+ git_meta_map={},
+ repo_structure=SimpleNamespace(root_language_distribution={"Python": 1.0}),
+ generated_pages=[_page()],
+ failed_page_ids=[],
+ file_count=1,
+ symbol_count=1,
+ embed_failed_pages=failed,
+ ),
+ start=0.0,
+ effective_index_only=True,
+ run_mode="standard",
+ provider=None,
+ )
+ return " ".join(buf.getvalue().split())
+
+
+def test_card_names_a_failed_embed(tmp_path, monkeypatch):
+ out = _closing_card(tmp_path, monkeypatch, semantic="unavailable", failed=3)
+ assert "Semantic search is unavailable: embedding failed for 3 page(s)" in out
+ assert "needs an embedder" not in out
+
+
+def test_card_does_not_ask_for_an_embedder_the_run_used(tmp_path, monkeypatch):
+ out = _closing_card(tmp_path, monkeypatch, semantic="available", failed=0)
+ assert "and semantic search work now" in out
+ assert "needs an embedder" not in out
+
+
+def test_card_keeps_the_keyless_note(tmp_path, monkeypatch):
+ out = _closing_card(tmp_path, monkeypatch, semantic="unavailable", failed=0)
+ assert "semantic search needs an embedder" in out
+ assert "Semantic search is unavailable" not in out
+
+
+# ---------------------------------------------------------------------------
+# Exit status
+# ---------------------------------------------------------------------------
+
+
+def _broken_store(monkeypatch):
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+
+ async def _boom(self, items):
+ raise RuntimeError("LanceDB is missing or broken (AttributeError: connect_async)")
+
+ monkeypatch.setattr(LanceDBVectorStore, "embed_batch", _boom)
+
+
+def test_init_with_a_real_embedder_exits_nonzero_when_embedding_fails(tmp_path, monkeypatch):
+ from repowise.cli.main import cli
+
+ monkeypatch.setenv("OLLAMA_BASE_URL", "http://127.0.0.1:9")
+ for var in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"):
+ monkeypatch.delenv(var, raising=False)
+ _broken_store(monkeypatch)
+ (tmp_path / "app.py").write_text("def main():\n return 1\n", encoding="utf-8")
+
+ result = CliRunner().invoke(
+ cli, ["init", str(tmp_path), "--index-only", "--embedder", "ollama", "--yes"]
+ )
+
+ assert result.exit_code == 1, result.output
+ assert "Embedding failed for" in result.output
+ assert "repowise reindex" in result.output
+ state = json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert state["index_scope"]["search"]["semantic"] == "unavailable"
+ assert state["index_scope"]["search"]["full_text"] == "available"
+
+
+def test_keyless_init_still_exits_zero_when_the_store_fails(tmp_path, monkeypatch):
+ from repowise.cli.main import cli
+
+ for var in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"):
+ monkeypatch.delenv(var, raising=False)
+ monkeypatch.delenv("REPOWISE_EMBEDDER", raising=False)
+ _broken_store(monkeypatch)
+ (tmp_path / "app.py").write_text("def main():\n return 1\n", encoding="utf-8")
+
+ result = CliRunner().invoke(cli, ["init", str(tmp_path), "--index-only", "--yes"])
+
+ assert result.exit_code == 0, result.output
+
+
+def test_update_marks_semantic_unavailable_and_fails(tmp_path):
+ from repowise.cli.commands.update_cmd.command import _fail_on_embed_failure
+ from repowise.cli.helpers import save_state
+
+ (tmp_path / ".repowise").mkdir()
+ save_state(tmp_path, {"index_scope": {"search": {"semantic": "available"}}})
+ emitter = MagicMock()
+
+ with pytest.raises(click.ClickException, match="Embedding failed for 2 page"):
+ _fail_on_embed_failure(tmp_path, "openai", 2, emitter)
+
+ state = json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert state["index_scope"]["search"]["semantic"] == "unavailable"
+ assert state["index_scope"]["search"]["next_command"] == "repowise reindex"
+ emitter.error.assert_called_once()
+
+
+def test_update_with_the_mock_embedder_is_not_failed(tmp_path):
+ from repowise.cli.commands.update_cmd.command import _fail_on_embed_failure
+
+ _fail_on_embed_failure(tmp_path, "mock", 2, None)
+ assert not (tmp_path / ".repowise" / "state.json").exists()
+
+
+def test_the_deterministic_update_render_records_a_failed_embed(tmp_path, monkeypatch):
+ """The index-only update passed no ``on_warning``, so nothing was recorded."""
+ from repowise.cli.commands.update_cmd import deterministic
+
+ class _Generator:
+ embed_failed_pages = 0
+
+ def __init__(self, *a, **k):
+ pass
+
+ async def generate_all(self, *a, **kwargs):
+ kwargs["on_warning"]("Embedding failed for 2 page(s)")
+ self.embed_failed_pages = 2
+ return ["page"]
+
+ monkeypatch.setattr("repowise.core.generation.PageGenerator", _Generator)
+ monkeypatch.setattr(
+ "repowise.core.generation.GenerationConfig.from_repo_config",
+ lambda *a, **k: SimpleNamespace(language="en"),
+ )
+ monkeypatch.setattr("repowise.core.generation.ContextAssembler", lambda *a, **k: None)
+ degraded: list[str] = []
+ stats: dict[str, int] = {}
+
+ pages = deterministic.regenerate_deterministic_page_ids(
+ repo_path=tmp_path,
+ parsed_files=[SimpleNamespace(file_info=SimpleNamespace(path="a.py"))],
+ source_map={},
+ graph_builder=None,
+ repo_structure=None,
+ git_meta_map={},
+ page_ids={"file_page:a.py"},
+ cfg={},
+ concurrency=1,
+ degraded=degraded,
+ vector_store=object(),
+ stats_out=stats,
+ )
+
+ assert pages == ["page"]
+ assert degraded == ["Embedding failed for 2 page(s)"]
+ assert stats == {"embed_failed_pages": 2}
+
+
+def test_reindex_clears_the_unavailable_stamp(tmp_path, monkeypatch):
+ """``init`` and ``update`` point at reindex; nothing else flipped it back."""
+ from repowise.cli.commands import reindex_cmd
+ from repowise.cli.helpers import save_state
+ from repowise.core.persistence import create_engine, create_session_factory, get_session
+ from repowise.core.persistence.crud import upsert_page, upsert_repository
+ from repowise.core.persistence.database import init_db
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ class _RealEmbedder:
+ """Not the mock by type, so the reindex guard lets it through."""
+
+ dimensions = 8
+
+ async def embed(self, texts):
+ return await MockEmbedder().embed(texts)
+
+ monkeypatch.setattr(
+ "repowise.cli.providers.embedders.build_embedder",
+ lambda name, _p=None: _RealEmbedder(),
+ )
+ repowise_dir = tmp_path / ".repowise"
+ repowise_dir.mkdir()
+ save_state(
+ tmp_path,
+ {"index_scope": {"search": {"semantic": "unavailable", "next_command": "repowise reindex"}}},
+ )
+
+ async def _seed():
+ engine = create_engine(f"sqlite+aiosqlite:///{repowise_dir / 'wiki.db'}")
+ await init_db(engine)
+ async with get_session(create_session_factory(engine)) as session:
+ repo = await upsert_repository(session, name="r", local_path=str(tmp_path))
+ await upsert_page(
+ session,
+ page_id="file_page:a.py",
+ repository_id=repo.id,
+ page_type="file_page",
+ title="File: a.py",
+ content="A module that parses configuration files and validates them. " * 5,
+ summary="",
+ target_path="a.py",
+ source_hash="",
+ model_name="m",
+ provider_name="p",
+ )
+ await session.commit()
+ await engine.dispose()
+
+ asyncio.run(_seed())
+ monkeypatch.setattr(
+ reindex_cmd, "get_db_url_for_repo", lambda p: f"sqlite+aiosqlite:///{repowise_dir / 'wiki.db'}"
+ )
+
+ asyncio.run(reindex_cmd._reindex(tmp_path, "openai", 8))
+
+ state = json.loads((repowise_dir / "state.json").read_text(encoding="utf-8"))
+ assert state["index_scope"]["search"]["semantic"] == "available"
+ assert state["index_scope"]["search"]["next_command"] is None
+
+
+def test_workspace_init_persists_every_repo_then_exits_nonzero(tmp_path, monkeypatch):
+ import git as gitpython
+
+ from repowise.cli.main import cli
+
+ monkeypatch.setenv("OLLAMA_BASE_URL", "http://127.0.0.1:9")
+ for var in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"):
+ monkeypatch.delenv(var, raising=False)
+ _broken_store(monkeypatch)
+ for name in ("api", "web"):
+ repo = tmp_path / name
+ repo.mkdir()
+ (repo / "app.py").write_text("def main():\n return 1\n", encoding="utf-8")
+ g = gitpython.Repo.init(repo)
+ g.index.add(["app.py"])
+ g.index.commit("init")
+
+ result = CliRunner().invoke(
+ cli,
+ ["init", str(tmp_path), "--index-only", "--embedder", "ollama", "--yes", "--all"],
+ )
+
+ assert result.exit_code == 1, result.output
+ assert "Embedding failed for" in " ".join(result.output.split())
+ for name in ("api", "web"):
+ state = json.loads((tmp_path / name / ".repowise" / "state.json").read_text("utf-8"))
+ assert state["index_scope"]["search"]["semantic"] == "unavailable"
+ assert state["index_scope"]["search"]["full_text"] == "available"
+
+
+def _indexed_repo_with_broken_store(tmp_path, monkeypatch) -> Path:
+ """An index-only repo pinned to a real embedder, with a store that fails.
+
+ Init itself exits 1 here (its embed fails too); the stamp is reset to
+ available so the update test proves the update is what marks it.
+ """
+ import subprocess
+
+ from repowise.cli.helpers import load_state, save_state
+ from repowise.cli.main import cli
+
+ monkeypatch.setenv("OLLAMA_BASE_URL", "http://127.0.0.1:9")
+ for var in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"):
+ monkeypatch.delenv(var, raising=False)
+ _broken_store(monkeypatch)
+ repo = tmp_path / "repo"
+ repo.mkdir()
+
+ def git(*args):
+ subprocess.run(["git", *args], cwd=repo, capture_output=True, check=True)
+
+ git("init")
+ git("config", "user.email", "[email protected]")
+ git("config", "user.name", "T")
+ (repo / "a.py").write_text("def alpha():\n return 1\n", encoding="utf-8")
+ git("add", ".")
+ git("commit", "-m", "initial")
+ init = CliRunner().invoke(
+ cli, ["init", str(repo), "--index-only", "--embedder", "ollama", "--yes", "--no-workspace"]
+ )
+ assert init.exit_code == 1, init.output
+ state = load_state(repo)
+ state["index_scope"]["search"]["semantic"] = "available"
+ save_state(repo, state)
+
+ (repo / "a.py").write_text("def alpha():\n return 2\n", encoding="utf-8")
+ git("add", ".")
+ git("commit", "-m", "change")
+ return repo
+
+
+ "extra_args",
+ [
+ pytest.param([], id="index-only render"),
+ pytest.param(["--docs", "--provider", "mock"], id="model generation"),
+ ],
+)
+def test_update_with_a_failing_store_exits_nonzero(tmp_path, monkeypatch, extra_args):
+ from repowise.cli.main import cli
+
+ repo = _indexed_repo_with_broken_store(tmp_path, monkeypatch)
+
+ result = CliRunner().invoke(cli, ["update", str(repo), "--no-workspace", *extra_args])
+
+ assert result.exit_code == 1, result.output
+ assert "Embedding failed for" in " ".join(result.output.split())
+ state = json.loads((repo / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert state["index_scope"]["search"]["semantic"] == "unavailable"
+ assert state["index_scope"]["search"]["next_command"] == "repowise reindex"
diff --git a/tests/unit/generation/test_run_level_embed_gating.py b/tests/unit/generation/test_run_level_embed_gating.py
index 6fc1a0180..982db25e1 100644
--- a/tests/unit/generation/test_run_level_embed_gating.py
+++ b/tests/unit/generation/test_run_level_embed_gating.py
@@ -93,3 +93,34 @@ def test_ephemeral_store_still_embeds_reused_pages() -> None:
embedded = _run_level(store)
assert "fresh.py" in embedded
assert "reused.py" in embedded
+
+
+class _FailingStore:
+ persists_across_runs = True
+
+ async def embed_batch(self, items):
+ raise AttributeError("module 'lancedb' has no attribute 'connect_async'")
+
+
+def test_a_failed_embed_is_counted_on_the_generator() -> None:
+ """Callers read the count to refuse calling semantic search healthy.
+
+ A warning string alone left init and update exiting 0 with a semantic
+ index that held none of the pages.
+ """
+ warnings: list[str] = []
+ gen = SimpleNamespace(embed_failed_pages=0)
+
+ async def _go():
+ async def fresh():
+ return _page("fresh.py")
+
+ run = _fake_run(_FailingStore())
+ run.gen = gen
+ run.on_warning = warnings.append
+ await _GenerationRun.run_level(run, [("p1", fresh())], level=2)
+
+ asyncio.run(_go())
+
+ assert gen.embed_failed_pages == 1
+ assert warnings and "Embedding failed for 1 page(s)" in warnings[0]
diff --git a/tests/unit/persistence/test_vector_store.py b/tests/unit/persistence/test_vector_store.py
index fd6c2ce42..9dc324c8c 100644
--- a/tests/unit/persistence/test_vector_store.py
+++ b/tests/unit/persistence/test_vector_store.py
@@ -587,3 +587,24 @@ async def test_lancedb_embed_batch_failed_write_reports_every_chunk(tmp_path, mo
assert caught.value.successful_count == 0
finally:
await store.close()
+
+
+async def test_lancedb_partial_install_fails_with_a_named_cause(tmp_path, monkeypatch, mock_embedder):
+ """A partial install imports fine and lacks the async API.
+
+ That used to raise a bare ``AttributeError`` from deep inside the first
+ write, which the embed step reported with no hint that the install was
+ the problem.
+ """
+ import sys
+ import types
+
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+
+ monkeypatch.setitem(sys.modules, "lancedb", types.ModuleType("lancedb"))
+ store = LanceDBVectorStore(str(tmp_path / "lance"), mock_embedder)
+
+ with pytest.raises(RuntimeError, match="connect_async") as excinfo:
+ await store._ensure_connected()
+ assert "pip install --force-reinstall lancedb" in str(excinfo.value)
diff --git a/tests/unit/pipeline/test_generation_warning_wiring.py b/tests/unit/pipeline/test_generation_warning_wiring.py
index 0ac76e833..c697f5d16 100644
--- a/tests/unit/pipeline/test_generation_warning_wiring.py
+++ b/tests/unit/pipeline/test_generation_warning_wiring.py
@@ -105,3 +105,26 @@ async def test_embed_failure_handled_through_progress_warnings(
)
assert len(progress.warnings) == 1
assert "Embedding failed for 3 page(s)" in progress.warnings[0]
+
+
+async def test_failed_embed_count_reaches_the_caller(
+ _stub_generator: _StubGenerator, tmp_path: pytest.TempPathFactory
+) -> None:
+ """The count, not the warning text, is what callers decide on."""
+ _stub_generator.embed_failed_pages = 3 # type: ignore[attr-defined]
+ stats: dict[str, int] = {}
+ await run_generation(
+ repo_path=tmp_path,
+ parsed_files=_parsed_files(1),
+ source_map={},
+ graph_builder=SimpleNamespace(),
+ repo_structure=SimpleNamespace(),
+ git_meta_map={},
+ llm_client=SimpleNamespace(),
+ embedder=None,
+ vector_store=None,
+ concurrency=1,
+ progress=_WarningRecorder(),
+ stats_out=stats,
+ )
+ assert stats == {"embed_failed_pages": 3}
diff --git a/tests/unit/server/mcp/test_vector_store_open_failure.py b/tests/unit/server/mcp/test_vector_store_open_failure.py
new file mode 100644
index 000000000..cb142cd69
--- /dev/null
+++ b/tests/unit/server/mcp/test_vector_store_open_failure.py
@@ -0,0 +1,170 @@
+"""A semantic index on disk that cannot be opened must not pass for healthy.
+
+A partial LanceDB install imports fine and lacks ``connect_async``. The server
+caught that, served an empty in-memory store, and every response still said
+``embedder_degraded: false``. Only an index that exists and fails counts: no
+index at all is a keyless repo, not a failure.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.persistence.vector_store import InMemoryVectorStore, LanceDBVectorStore
+from repowise.core.persistence.vector_store.lancedb_store import LanceDBUnavailableError
+from repowise.core.providers.embedding.base import MockEmbedder
+from repowise.server.mcp_server import _server, _state
+from repowise.server.mcp_server._meta import build_meta
+
+
[email protected](autouse=True)
+def fresh_store_errors(monkeypatch):
+ monkeypatch.setattr(_state, "_vector_store_errors", {}, raising=False)
+
+
+def healthy_openai(monkeypatch):
+ monkeypatch.setattr(
+ _state,
+ "_embedder_status",
+ {"active": "openai", "requested": "openai", "degraded": False},
+ raising=False,
+ )
+ monkeypatch.setattr(_state, "_vector_store", None, raising=False)
+ monkeypatch.setattr(_state, "_decision_store", None, raising=False)
+ monkeypatch.setattr(_state, "_vector_store_ready", None, raising=False)
+ monkeypatch.setattr(_server, "_query_embedder", MockEmbedder)
+
+
+def broken_lancedb(monkeypatch):
+ async def _boom(self):
+ raise LanceDBUnavailableError("LanceDB is missing or broken (AttributeError: connect_async)")
+
+ monkeypatch.setattr(LanceDBVectorStore, "_ensure_connected", _boom)
+
+
+def test_an_unopenable_index_marks_the_embedder_degraded(
+ tmp_path, healthy_openai, broken_lancedb
+):
+ (tmp_path / ".repowise" / "lancedb").mkdir(parents=True)
+
+ asyncio.run(_server._load_vector_stores(str(tmp_path)))
+
+ assert isinstance(_state._vector_store, InMemoryVectorStore)
+ meta = build_meta(timing_ms=1.0)
+ assert meta["embedder_degraded"] is True
+ assert meta["semantic_search"] is False
+ assert "connect_async" in meta["embedder_warning"]
+ assert "reinstall" in meta["embedder_warning"]
+
+
+def test_the_mark_survives_resolving_the_embedder_again(
+ tmp_path, healthy_openai, broken_lancedb, monkeypatch
+):
+ """The workspace registry resolves the embedder on every repo (re)load,
+ which rewrites ``_embedder_status``. The store failure must outlive that."""
+ (tmp_path / ".repowise" / "lancedb").mkdir(parents=True)
+ asyncio.run(_server._load_vector_stores(str(tmp_path)))
+
+ monkeypatch.setattr(_server, "_configured_embedder_name", lambda: "mock")
+ _server._resolve_embedder()
+
+ meta = build_meta(timing_ms=1.0)
+ assert meta["embedder_degraded"] is True
+ assert "connect_async" in meta["embedder_warning"]
+
+
+def test_a_locked_table_is_not_blamed_on_the_install(tmp_path, healthy_openai, monkeypatch):
+ async def _locked(self):
+ raise OSError("database is locked")
+
+ monkeypatch.setattr(LanceDBVectorStore, "_ensure_connected", _locked)
+ (tmp_path / ".repowise" / "lancedb").mkdir(parents=True)
+
+ asyncio.run(_server._load_vector_stores(str(tmp_path)))
+
+ warning = build_meta(timing_ms=1.0)["embedder_warning"]
+ assert "database is locked" in warning
+ assert "reinstall" not in warning
+ assert "retry" in warning
+
+
+def test_no_index_on_disk_is_not_a_failure(tmp_path, healthy_openai, broken_lancedb):
+ asyncio.run(_server._load_vector_stores(str(tmp_path)))
+
+ assert build_meta(timing_ms=1.0)["embedder_degraded"] is False
+
+
+def test_the_workspace_registry_reports_an_unopenable_index(tmp_path, broken_lancedb):
+ from repowise.core.workspace.registry import RepoRegistry
+
+ (tmp_path / ".repowise" / "lancedb").mkdir(parents=True)
+ reported: list[tuple[str, BaseException]] = []
+
+ async def _go():
+ ctx = SimpleNamespace(alias="api", vector_store_ready=asyncio.Event())
+ registry = SimpleNamespace(
+ _on_vector_store_error=lambda alias, exc: reported.append((alias, exc)),
+ _contexts={"api": ctx},
+ _vs_tasks={},
+ )
+ await RepoRegistry._load_vector_stores(registry, ctx, tmp_path, MockEmbedder())
+ return ctx
+
+ ctx = asyncio.run(_go())
+
+ assert [alias for alias, _ in reported] == ["api"]
+ assert "connect_async" in str(reported[0][1])
+ assert ctx.vector_store_ready.is_set()
+
+
+def bridge_repo(tmp_path, monkeypatch):
+ monkeypatch.setattr(_state, "_embedder_status", None, raising=False)
+ monkeypatch.setattr(
+ "repowise.cli.providers.embedders.resolve_embedder_for_repo", lambda p: "openai"
+ )
+ monkeypatch.setattr(
+ "repowise.cli.providers.embedders.build_embedder", lambda name, _p=None: MockEmbedder()
+ )
+ (tmp_path / ".repowise" / "lancedb").mkdir(parents=True)
+ return tmp_path
+
+
+def test_the_cli_bridge_reports_an_unopenable_index(bridge_repo, broken_lancedb):
+ from repowise.cli import tool_bridge
+
+ async def _go():
+ return await tool_bridge._connect_or_degrade(
+ await tool_bridge._open_vector_store(bridge_repo)
+ )
+
+ store = asyncio.run(_go())
+
+ assert isinstance(store, InMemoryVectorStore)
+ assert build_meta(timing_ms=1.0)["embedder_degraded"] is True
+ assert "connect_async" in build_meta(timing_ms=1.0)["embedder_warning"]
+
+
+def test_the_cli_bridge_does_not_open_the_store_for_other_tools(bridge_repo, monkeypatch):
+ """Importing lancedb costs about a second; tools that never read vectors
+ must not pay it."""
+ from repowise.cli import tool_bridge
+
+ connected: list[bool] = []
+
+ async def _spy(self):
+ connected.append(True)
+
+ monkeypatch.setattr(LanceDBVectorStore, "_ensure_connected", _spy)
+
+ assert "get_context" not in tool_bridge._VECTOR_TOOLS
+ store = asyncio.run(tool_bridge._open_vector_store(bridge_repo))
+
+ assert isinstance(store, LanceDBVectorStore)
+ assert connected == []
+ assert {"search_codebase", "get_answer"} <= tool_bridge._VECTOR_TOOLS