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(cli): resolve the persisted embedder key, and make degraded runs visible (#1599)

Raghav Chamadiyacd2c9b4607d9
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 b4991517f..3c07a4a8c 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
@@ -616,7 +616,7 @@ def _run_repo_checks(
# combination and returns None, so a repo whose embedder is
# unavailable is left alone instead of wrecked.
embedder_name = resolve_embedder_for_repo(repo_path)
- embedder = build_embedder(embedder_name)
+ embedder = build_embedder(embedder_name, repo_path)
vs = build_vector_store(_DoctorPath(repo_path), embedder)
if vs is None:
raise RuntimeError(
diff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/engine.py b/packages/cli/src/repowise/cli/commands/generate_cmd/engine.py
index bb4894ad4..6433e808b 100644
--- a/packages/cli/src/repowise/cli/commands/generate_cmd/engine.py
+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/engine.py
@@ -183,7 +183,7 @@ async def run_scoped_generation(
embedder = None
vector_store = None
try:
- embedder = build_embedder(resolve_embedder(embedder_name))
+ embedder = build_embedder(resolve_embedder(embedder_name), repo_path)
vector_store = build_vector_store(repo_path, embedder)
except Exception as exc:
# Null BOTH on any failure. If the embedder built but the store did
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 ddbf55831..78095573c 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -1356,6 +1356,9 @@ def init_command(
# state.json persistence below and for any future "profile" tooling
# that wants to introspect a run.
phase_timings: dict[str, float] = callback.timings
+ # Same idea, for the failures rather than the durations: what the run
+ # degraded on, in a place an agent can read after the terminal is gone.
+ run_warnings: list[str] = list(rich_callback.warnings)
# ---- Analysis summary (shown between analysis and generation) ----
show_analysis_summary(result)
@@ -1469,8 +1472,28 @@ def init_command(
"Saving to database and building search index",
)
- with console.status(" Persisting to database…", spinner=OWL_SPINNER):
- run_async(persist_result(result, repo_path))
+ # A bar rather than the old indeterminate spinner: full-text indexing walks
+ # every generated page one await at a time, so on a few thousand pages this
+ # stage ran for minutes with nothing on screen but a spinner, immediately
+ # after a generation bar that had just claimed to be finished. The columns
+ # are the index run's, minus the cost one — nothing here spends tokens.
+ with Progress(
+ SpinnerColumn(spinner_name=OWL_SPINNER, style=BRAND_STYLE),
+ TextColumn("[progress.description]{task.description}"),
+ BarColumn(),
+ MaybeCountColumn(),
+ TimeElapsedColumn(),
+ console=console,
+ ) as persist_bar:
+ persist_callback = RichProgressCallback(persist_bar, console)
+ # Announced before the work starts and re-announced with a real total
+ # once the page loop knows one, so the stage is never silent.
+ persist_callback.on_phase_start("persist", None)
+ run_async(persist_result(result, repo_path, persist_callback))
+ persist_callback.on_phase_done("persist")
+ # Persistence has its own callback, so its warnings need folding into the
+ # run record explicitly — the state write below is the last chance.
+ run_warnings.extend(persist_callback.warnings)
console.print(f" [{OK}]✓[/] Database updated")
# Persist the onboarding choice so subsequent `repowise update` runs
@@ -1564,6 +1587,12 @@ def init_command(
base_state["include_submodules"] = include_submodules
if phase_timings:
base_state["phase_timings"] = phase_timings
+ # Cleared before it is set: ``base_state`` came from the previous run's
+ # state.json, and a fixed re-run must not inherit its predecessor's
+ # degradation report (see save_full_state_and_config for the same rule).
+ base_state.pop("degraded", None)
+ if run_warnings:
+ base_state["degraded"] = run_warnings
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
base_state["knowledge_graph"] = build_kg_state(kg)
@@ -1622,6 +1651,7 @@ def init_command(
result=result,
provider=provider,
phase_timings=phase_timings,
+ degraded=run_warnings,
embedder_name_resolved=embedder_name_resolved,
exclude_patterns=exclude_patterns,
commit_limit=commit_limit,
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 78333f068..d0bae6092 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
@@ -280,7 +280,7 @@ def run_repo_generation(
if verbose:
announce_file_page_cap(result.parsed_files, gen_config)
- embedder_impl: Any = build_embedder(embedder_name_resolved)
+ embedder_impl: Any = build_embedder(embedder_name_resolved, repo_path)
vector_store: Any = build_vector_store(repo_path, embedder_impl)
result.vector_store = vector_store
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 d966761d1..58436e4e0 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -106,10 +106,16 @@ async def _index_preserved_pages(sf: Any, fts: Any, preserved_page_ids: set[str]
logger.debug("persist.preserved_fts_backfill_failed", error=str(exc))
-async def persist_result(result: Any, repo_path: Path) -> None:
+async def persist_result(result: Any, repo_path: Path, progress: Any | None = None) -> None:
"""Persist a PipelineResult to the local SQLite database.
Handles both index-only (no pages) and full (with pages + FTS) modes.
+
+ *progress* is optional and reports the full-text indexing loop below, the
+ one part of persistence whose length is known in advance and proportional
+ to the wiki. Everything after "Generated N pages" used to happen under a
+ single indeterminate spinner, so on a repo of a few thousand pages the run
+ sat silent for minutes with no way to tell work from a hang.
"""
from datetime import UTC, datetime
@@ -237,6 +243,8 @@ async def persist_result(result: Any, repo_path: Path) -> None:
if fts is not None and swept_page_ids:
await fts.delete_many(swept_page_ids)
if fts is not None and result.generated_pages:
+ if progress is not None:
+ progress.on_phase_start("persist", len(result.generated_pages))
for page in result.generated_pages:
await fts.index(
page.page_id,
@@ -245,6 +253,10 @@ async def persist_result(result: Any, repo_path: Path) -> None:
summary=page.summary,
target_path=page.target_path,
)
+ if progress is not None:
+ progress.on_item_done("persist")
+ if progress is not None:
+ progress.on_phase_done("persist")
await _index_preserved_pages(sf, fts, getattr(result, "preserved_page_ids", None))
# Stamp the analysis (+ generation) phases in the resume ledger now that
@@ -305,6 +317,7 @@ def save_full_state_and_config(
result: Any,
provider: Any,
phase_timings: dict[str, float],
+ degraded: list[str] | None = None,
embedder_name_resolved: str,
exclude_patterns: list[str],
commit_limit: int | None,
@@ -358,6 +371,18 @@ def save_full_state_and_config(
state["total_tokens"] = total_tokens
if phase_timings:
state["phase_timings"] = phase_timings
+ # What this run degraded on. A scripted run exits 0 either way, so without
+ # this an agent records a clean index for a run that skipped, say, execution
+ # flow tracing entirely.
+ #
+ # Cleared first, because ``state`` is the *previous* run's dict read back
+ # from disk. Only setting it would let one bad run mark a repo degraded
+ # forever: the re-run that fixed the problem writes no key, the stale list
+ # is re-serialised verbatim, and every later ``update`` carries it on. The
+ # key describes this run or it is absent.
+ state.pop("degraded", None)
+ if degraded:
+ state["degraded"] = list(degraded)
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
state["knowledge_graph"] = build_kg_state(kg)
diff --git a/packages/cli/src/repowise/cli/commands/reindex_cmd.py b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
index 2b6cb23b0..1b9906cf9 100644
--- a/packages/cli/src/repowise/cli/commands/reindex_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
@@ -60,7 +60,7 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
embedder_name = _resolve_embedder(None)
- embedder_impl = build_embedder(embedder_name)
+ embedder_impl = build_embedder(embedder_name, repo_path)
if isinstance(embedder_impl, MockEmbedder) and requested_embedder != "mock":
console.print(
"[red]No real embedder available. Set a real embedder key, configure Ollama, or pass --embedder mock for test vectors.[/red]"
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 800e082fb..3c2d26dfb 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -171,7 +171,9 @@ def _render_pages(
from repowise.cli.providers import build_embedder, build_vector_store
try:
- vector_store = build_vector_store(repo_path, build_embedder(embedder_name))
+ vector_store = build_vector_store(
+ repo_path, build_embedder(embedder_name, repo_path)
+ )
except Exception as exc: # embedding is optional; FTS still indexes
degraded.append(f"Page embedding: {exc}")
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 dfceb0886..081f548a2 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/incremental.py
@@ -26,7 +26,7 @@ def _build_update_vector_store(repo_path: Any, cfg: dict) -> Any | None:
try:
from repowise.cli.providers import build_embedder, build_vector_store, resolve_embedder
- embedder = build_embedder(resolve_embedder(cfg.get("embedder")))
+ embedder = build_embedder(resolve_embedder(cfg.get("embedder")), repo_path)
return build_vector_store(repo_path, embedder)
except Exception:
return None
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index 32b734d84..ea2c33b85 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -260,7 +260,7 @@ async def _run_upgrade(
embedder = None
vector_store = None
try:
- embedder = build_embedder(resolve_embedder(embedder_name))
+ embedder = build_embedder(resolve_embedder(embedder_name), repo_path)
vector_store = build_vector_store(repo_path, embedder)
except Exception as exc:
console.print(f"[yellow]Embedding skipped: {exc}[/yellow]")
diff --git a/packages/cli/src/repowise/cli/commands/workspace_cmd.py b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
index 8c151ef2a..5b40b20a9 100644
--- a/packages/cli/src/repowise/cli/commands/workspace_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
@@ -569,8 +569,14 @@ def _run_index_for_repo(
primary_cfg: dict = {}
if primary is not None:
from repowise.cli.helpers import load_config as _load_cfg
+ from repowise.cli.ui import load_dotenv
- primary_cfg = _load_cfg((ws_root / primary.path).resolve())
+ primary_path = (ws_root / primary.path).resolve()
+ primary_cfg = _load_cfg(primary_path)
+ # The provider settings are inherited from the primary repo, so the
+ # credential that goes with them lives in the primary's ``.env`` —
+ # the new repo has none yet. Same call `init`'s workspace flow makes.
+ load_dotenv(primary_path)
effective_provider = provider_name or primary_cfg.get("provider")
effective_model = model or primary_cfg.get("model")
diff --git a/packages/cli/src/repowise/cli/providers/embedders.py b/packages/cli/src/repowise/cli/providers/embedders.py
index eff34357c..231540af2 100644
--- a/packages/cli/src/repowise/cli/providers/embedders.py
+++ b/packages/cli/src/repowise/cli/providers/embedders.py
@@ -3,10 +3,13 @@
from __future__ import annotations
import os
+from collections.abc import Mapping
from typing import Any
+from repowise.cli.providers.keys import embedder_key_env_vars, resolve_embedder_api_key
-def _embedder_kwargs(embedder_name: str) -> dict[str, Any]:
+
+def _embedder_kwargs(embedder_name: str, repo_path: Any = None) -> dict[str, Any]:
kwargs: dict[str, Any] = {}
model = os.environ.get("REPOWISE_EMBEDDING_MODEL")
if embedder_name == "ollama":
@@ -25,6 +28,14 @@ def _embedder_kwargs(embedder_name: str) -> dict[str, Any]:
kwargs["output_dimensionality"] = int(dimensions)
if model:
kwargs["model"] = model
+ # Passed explicitly rather than left to the adapter's own ``os.environ``
+ # read, which is the only route this had and the reason a key persisted to
+ # ``.repowise/.env`` never reached the embedder from a command that had not
+ # called ``load_dotenv``. Absent keys stay absent: the adapter still raises
+ # its own "API key required", which is the message worth showing.
+ lookup = resolve_embedder_api_key(embedder_name, repo_path)
+ if lookup.key:
+ kwargs["api_key"] = lookup.key
return kwargs
@@ -43,20 +54,30 @@ def resolve_embedding_model(embedder_name: str) -> str | None:
return os.environ.get("REPOWISE_EMBEDDING_MODEL")
-def resolve_embedder(embedder_flag: str | None) -> str:
- """Auto-detect embedder from env vars, or use the flag value."""
+def resolve_embedder(embedder_flag: str | None, env: Mapping[str, str] | None = None) -> str:
+ """Auto-detect embedder from env vars, or use the flag value.
+
+ *env* layers a repo's persisted ``.repowise/.env`` under the process
+ environment for callers that must not merge it into ``os.environ``. The
+ process still wins on every key, so an exported variable keeps overriding
+ the file, exactly as ``load_dotenv``'s non-overwriting merge did.
+ """
if embedder_flag:
return embedder_flag
- configured = os.environ.get("REPOWISE_EMBEDDER", "").strip().lower()
+
+ def _get(name: str) -> str:
+ return os.environ.get(name) or (env or {}).get(name) or ""
+
+ configured = _get("REPOWISE_EMBEDDER").strip().lower()
if configured:
return configured
- if os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):
+ if _get("GEMINI_API_KEY") or _get("GOOGLE_API_KEY"):
return "gemini"
- if os.environ.get("OPENAI_API_KEY"):
+ if _get("OPENAI_API_KEY"):
return "openai"
- if os.environ.get("OPENROUTER_API_KEY"):
+ if _get("OPENROUTER_API_KEY"):
return "openrouter"
- if os.environ.get("OLLAMA_EMBEDDING_MODEL"):
+ if _get("OLLAMA_EMBEDDING_MODEL"):
return "ollama"
return "mock"
@@ -118,12 +139,31 @@ def resolve_embedder_for_repo(repo_path: Any) -> str:
pinned = load_config(Path(repo_path)).get("embedder")
except Exception:
pinned = None
- return str(pinned) if pinned else resolve_embedder(None)
+ if pinned:
+ return str(pinned)
+ # No pin, so fall back to detection — and let this repo's own persisted
+ # ``.env`` count as evidence. Read purely rather than merged into
+ # ``os.environ``: a workspace resolves several repos in one process, and a
+ # merge is first-writer-wins, so the first repo's key would silently answer
+ # for every sibling afterwards.
+ try:
+ from repowise.core.repo_config import load_repo_env
+
+ overlay = load_repo_env(repo_path)
+ except Exception:
+ overlay = {}
+ return resolve_embedder(None, overlay)
-def build_embedder(embedder_name_resolved: str) -> Any:
+def build_embedder(embedder_name_resolved: str, repo_path: Any = None) -> Any:
"""Construct the configured embedder, falling back to KeylessEmbedder.
+ *repo_path* lets the credential come from that repo's ``.repowise/.env``
+ or the global config, not only from an exported variable. Callers that have
+ a repo in hand should pass it: without it this resolves exactly as far as
+ ``os.environ`` reaches, which is how ``search`` and ``ask`` fell back to
+ keyless against an index full of real vectors.
+
Shared by the generation flows and the decision semantic-dedup wiring so
the same backend selection logic isn't duplicated. Real providers fall
back to the keyless embedder when their SDK/credentials are unavailable.
@@ -145,7 +185,9 @@ def build_embedder(embedder_name_resolved: str) -> Any:
if embedder_name_resolved == "mock":
return KeylessEmbedder()
try:
- return get_embedder(embedder_name_resolved, **_embedder_kwargs(embedder_name_resolved))
+ return get_embedder(
+ embedder_name_resolved, **_embedder_kwargs(embedder_name_resolved, repo_path)
+ )
except Exception as exc:
# Said here, once, rather than in each of the thirteen call sites, for
# the same reason build_vector_store says its own refusal here: a
@@ -158,9 +200,19 @@ def build_embedder(embedder_name_resolved: str) -> Any:
# keyless repo, not an exotic one.
from repowise.cli.helpers import err_console
+ # Name the places that were actually consulted. "Set OPENAI_API_KEY" is
+ # advice that does not apply to a user whose key is sitting in
+ # ``.repowise/.env``, and sends them to fix something already correct.
+ searched = ""
+ if embedder_key_env_vars(embedder_name_resolved):
+ lookup = resolve_embedder_api_key(embedder_name_resolved, repo_path)
+ if lookup.key is None and lookup.searched:
+ places = "\n".join(f" · {place}" for place in lookup.searched)
+ searched = f"\nNo API key was found in any of:\n{places}"
+
err_console.print(
f"[yellow]Embedder '{embedder_name_resolved}' could not be built:[/yellow] "
- f"{type(exc).__name__}: {exc}\n"
+ f"{type(exc).__name__}: {exc}{searched}\n"
"Falling back to keyless embeddings, which means [bold]no semantic search[/bold] "
"for this run.\nFull-text and symbol search are unaffected. Fix the key or "
"endpoint and run [cyan]repowise reindex[/cyan]\nto restore semantic search."
diff --git a/packages/cli/src/repowise/cli/providers/keys.py b/packages/cli/src/repowise/cli/providers/keys.py
new file mode 100644
index 000000000..e6ae55678
--- /dev/null
+++ b/packages/cli/src/repowise/cli/providers/keys.py
@@ -0,0 +1,115 @@
+"""One resolver for the embedder credential every CLI command needs.
+
+The CLI used to have no resolver at all: :func:`_embedder_kwargs` never set
+``api_key``, so the only route was ``OpenAIEmbedder.__init__`` reading
+``os.environ`` directly. A command that forgot ``load_dotenv`` therefore built a
+``KeylessEmbedder`` against an index written with real 1536-wide vectors, and
+said so in a warning that named the one place the key was *not*
+(``OPENAI_API_KEY``) rather than the two places it was.
+
+The MCP server already resolved this correctly
+(``mcp_server/_server.py::_persisted_embedder_key``). Centralising *persistence*
+without centralising *consumption* is what let the two halves drift: the same
+repo, in the same shell, answers semantically through MCP and lexically through
+``repowise search``. This module is the consumption half, and it deliberately
+mirrors the server's precedence rather than inventing a new one.
+
+Pure by construction: nothing here mutates ``os.environ``. ``load_dotenv``'s
+merge-into-the-process semantics are first-writer-wins, so in a workspace one
+repo's key would answer for every sibling. Resolving per call with an explicit
+``repo_path`` cannot do that.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, NamedTuple
+
+# Mirrors ``mcp_server/_server.py::_EMBEDDER_KEY_ENV``. The two copies are the
+# shape this module exists to stop spreading, but the server cannot import the
+# CLI and neither can reach a shared home without moving the map into
+# ``core.providers.embedding`` — a wider change than the defect needs. Ceiling
+# noted deliberately: fold both into core when a third consumer appears.
+_EMBEDDER_KEY_ENV: dict[str, tuple[str, ...]] = {
+ "openai": ("OPENAI_API_KEY",),
+ "gemini": ("GEMINI_API_KEY", "GOOGLE_API_KEY"),
+ "openrouter": ("OPENROUTER_API_KEY",),
+}
+
+
+class KeyLookup(NamedTuple):
+ """The resolved key, and the places that were consulted to find it.
+
+ ``searched`` exists so the degraded-run message can name what it looked at.
+ A user whose key sits in ``.repowise/.env`` was previously told to "set
+ OPENAI_API_KEY", advice that does not apply to them and sends them to fix
+ something that is not broken.
+ """
+
+ key: str | None
+ searched: tuple[str, ...]
+
+
+def embedder_key_env_vars(embedder_name: str) -> tuple[str, ...]:
+ """Environment variables that carry *embedder_name*'s credential.
+
+ Empty when the embedder needs no key (``ollama``, ``mock``), which callers
+ use to skip the whole resolution rather than report a missing key for a
+ backend that never wanted one.
+ """
+ return _EMBEDDER_KEY_ENV.get(embedder_name, ())
+
+
+def resolve_embedder_api_key(embedder_name: str, repo_path: Any = None) -> KeyLookup:
+ """Find *embedder_name*'s API key, in the order the MCP server uses.
+
+ 1. the process environment — an exported key is an explicit override and
+ nothing may outrank it;
+ 2. ``<repo>/.repowise/.env`` — where ``save_config`` persists the key at
+ init time, read without merging it into ``os.environ``;
+ 3. ``~/.repowise/config.yaml``'s ``embedder_api_key``, and only when its
+ ``embedder`` names this same backend. Handing an OpenAI key to Gemini
+ fails in a way that reads as a bad key rather than a mismatched one.
+ """
+ env_vars = embedder_key_env_vars(embedder_name)
+ if not env_vars:
+ return KeyLookup(None, ())
+
+ searched: list[str] = [" or ".join(env_vars) + " in the environment"]
+ for var in env_vars:
+ value = os.environ.get(var)
+ if value:
+ return KeyLookup(value, tuple(searched))
+
+ if repo_path is not None:
+ searched.append(f"{Path(repo_path) / '.repowise' / '.env'}")
+ try:
+ from repowise.core.repo_config import load_repo_env
+
+ overlay = load_repo_env(repo_path)
+ except Exception:
+ overlay = {}
+ for var in env_vars:
+ value = overlay.get(var)
+ if value:
+ return KeyLookup(value, tuple(searched))
+
+ global_config = Path.home() / ".repowise" / "config.yaml"
+ searched.append(f"embedder_api_key in {global_config}")
+ try:
+ if global_config.is_file():
+ import yaml # type: ignore[import-untyped]
+
+ cfg = yaml.safe_load(global_config.read_text(encoding="utf-8")) or {}
+ if str(cfg.get("embedder") or "").strip().lower() == embedder_name:
+ key = str(cfg.get("embedder_api_key") or "").strip()
+ if key:
+ return KeyLookup(key, tuple(searched))
+ except Exception:
+ pass
+
+ return KeyLookup(None, tuple(searched))
+
+
+__all__ = ["KeyLookup", "embedder_key_env_vars", "resolve_embedder_api_key"]
diff --git a/packages/cli/src/repowise/cli/tool_bridge.py b/packages/cli/src/repowise/cli/tool_bridge.py
index 86e48390f..d06ed4831 100644
--- a/packages/cli/src/repowise/cli/tool_bridge.py
+++ b/packages/cli/src/repowise/cli/tool_bridge.py
@@ -110,8 +110,12 @@ async def _open_vector_store(repo_path: Path) -> Any:
from repowise.cli.providers.embedders import build_embedder, resolve_embedder_for_repo
from repowise.core.persistence.vector_store import InMemoryVectorStore
+ # Both halves read ``<repo>/.repowise/.env`` themselves rather than the
+ # process environment, which is why this path needs no ``load_dotenv``:
+ # the tools serve one repo per call, and merging a repo's keys into
+ # ``os.environ`` is first-writer-wins for the life of the process.
requested = resolve_embedder_for_repo(repo_path)
- embedder = build_embedder(requested)
+ embedder = build_embedder(requested, repo_path)
_publish_embedder_status(requested, embedder)
lance_dir = repo_path / REPOWISE_DIR / "lancedb"
if lance_dir.is_dir():
diff --git a/packages/cli/src/repowise/cli/ui/progress.py b/packages/cli/src/repowise/cli/ui/progress.py
index 8d3ef374e..6474eeb6f 100644
--- a/packages/cli/src/repowise/cli/ui/progress.py
+++ b/packages/cli/src/repowise/cli/ui/progress.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import contextlib
+import re
from collections.abc import Callable
from typing import Any
@@ -32,6 +33,32 @@ _STAGE_HEADERS: dict[str, tuple[int, str, str]] = {
}
+# Credential shapes that turn up inside provider exception text. OpenAI and
+# Anthropic auth errors quote the offending key back ("Incorrect API key
+# provided: sk-abc…"), and several pipeline warnings interpolate ``str(exc)``
+# verbatim. That was transient terminal output; once the warnings are also
+# written to ``.repowise/state.json`` it becomes a secret at rest, in the one
+# file agents and MCP tools read back.
+_SECRET_PATTERNS = (
+ re.compile(r"\bsk-[A-Za-z0-9_-]{8,}"), # OpenAI / Anthropic
+ re.compile(r"\bAIza[A-Za-z0-9_-]{10,}"), # Google
+ re.compile(r"\bgh[pousr]_[A-Za-z0-9]{10,}"), # GitHub
+)
+
+
+def redact_secrets(text: str) -> str:
+ """Blank anything key-shaped in *text*.
+
+ Deliberately conservative: it matches issuer-prefixed shapes rather than
+ "any long token", because over-matching would eat the file paths and hashes
+ that make these messages useful. A key in an unrecognised format still gets
+ through, so this reduces exposure rather than guaranteeing its absence.
+ """
+ for pattern in _SECRET_PATTERNS:
+ text = pattern.sub("[redacted]", text)
+ return text
+
+
class MaybeCountColumn(ProgressColumn):
"""Progress column that shows ``completed/total`` when total is known,
or just ``completed`` when total is ``None`` (indeterminate phase).
@@ -79,7 +106,9 @@ _PHASE_LABELS: dict[str, str] = {
"knowledge_graph.skeleton": "Building the knowledge graph…",
"knowledge_graph.enrich": " ↳ Naming layers and building the tour",
"generation": "Generating pages…",
+ "generation.llm": " ↳ Writing pages that need the model",
"onboarding": "Curating onboarding docs…",
+ "persist": "Saving to the database…",
}
@@ -99,6 +128,17 @@ class RichProgressCallback:
self._progress = progress
self._console = console
self._tasks: dict[str, Any] = {}
+ # Every warning this callback rendered, in order. Printing is enough
+ # for a human watching, but agent-driven mode is the primary path and
+ # nobody is watching there: a run that degraded and a run that did not
+ # both exit 0 and both write a state.json that looks identical.
+ # ``init`` persists this list so the degradation is recoverable after
+ # the terminal output is gone. ``update`` already reports a ``degraded``
+ # list for the same reason; this is the missing half on the init side.
+ #
+ # Ceiling: this instance covers the index+analysis run. The generation
+ # phase builds its own callback, so its warnings are not collected here.
+ self.warnings: list[str] = []
# Set only by the single-repo init flow, which is the one screen that
# numbers its phases. The workspace flow prints its own per-repo header
# and would otherwise draw a "Phase 1 of 4" rule for every repo.
@@ -172,6 +212,8 @@ class RichProgressCallback:
# rather than "this succeeded".
style_map = {"warning": WARN, "error": ERR}
style = style_map.get(level, "")
+ if level in style_map:
+ self.warnings.append(redact_secrets(text))
# Insight lines (indented with →) get special formatting
if text.lstrip().startswith("→"):
line = f" [dim]{text}[/dim]"
diff --git a/packages/cli/src/repowise/cli/upgrade.py b/packages/cli/src/repowise/cli/upgrade.py
index b52cde5d1..50f61995e 100644
--- a/packages/cli/src/repowise/cli/upgrade.py
+++ b/packages/cli/src/repowise/cli/upgrade.py
@@ -143,7 +143,7 @@ def _vector_dims(repo_path: Path) -> tuple[int | None, int | None]:
from .providers.vector_store import existing_vector_dim
try:
- embedder = build_embedder(resolve_embedder_for_repo(repo_path))
+ embedder = build_embedder(resolve_embedder_for_repo(repo_path), repo_path)
except Exception:
return None, None
if isinstance(embedder, MockEmbedder):
diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.py
index 00708cb35..3fbb175a4 100644
--- a/packages/core/src/repowise/core/ingestion/parser.py
+++ b/packages/core/src/repowise/core/ingestion/parser.py
@@ -25,6 +25,7 @@ Capture-name conventions (shared across ALL .scm files):
from __future__ import annotations
import re
+from collections.abc import Iterable
from functools import cache
from pathlib import Path
@@ -206,6 +207,57 @@ def _build_language_registry() -> dict[str, Language]:
_LANGUAGE_REGISTRY: dict[str, Language] = {}
+# Languages already reported as having a config but no installed grammar, so
+# the report is one line per language per process instead of one per file. A
+# repo with a few thousand shell scripts otherwise emitted a few thousand
+# identical lines, all saying the same three facts.
+_MISSING_GRAMMAR_REPORTED: set[str] = set()
+
+
+def missing_grammar_languages(language_tags: Iterable[str]) -> list[str]:
+ """Of *language_tags*, those that parse via tree-sitter but have no grammar.
+
+ Answers the question once, in the parent, before up to eight spawned
+ workers each rediscover it and log their own copy of the answer at a level
+ the CLI discards anyway.
+
+ Deliberately uses ``find_spec`` rather than importing: the whole point is
+ to stay cheap enough to run on every index. Building the real registry here
+ would import every tree-sitter package into the parent process, which is
+ memory the parse pool is about to need for something else.
+
+ A tag with no :data:`LANGUAGE_CONFIGS` entry is not a gap — nothing claims
+ to parse it — so it is skipped rather than reported.
+
+ Ceiling: "importable" is not "loadable". A grammar whose compiled ABI does
+ not match the installed ``tree_sitter`` imports fine and then raises inside
+ ``Language()``, which this cannot see, so that case reports nothing here
+ and stays a per-worker debug line. Reporting it properly means loading the
+ grammars, which is the cost this function exists to avoid.
+ """
+ import importlib.util
+
+ specs = {spec.tag: spec for spec in _LANG_REGISTRY.all_specs()}
+ missing: list[str] = []
+ for tag in language_tags:
+ if tag not in LANGUAGE_CONFIGS:
+ continue
+ spec = specs.get(tag)
+ if spec is None:
+ continue
+ package = spec.grammar_package
+ if not package and spec.shares_grammar_with:
+ shared = specs.get(spec.shares_grammar_with)
+ package = shared.grammar_package if shared else None
+ if not package:
+ continue
+ try:
+ if importlib.util.find_spec(package) is None:
+ missing.append(tag)
+ except (ImportError, ValueError):
+ missing.append(tag)
+ return sorted(missing)
+
def _get_language(tag: str) -> Language | None:
global _LANGUAGE_REGISTRY
@@ -263,12 +315,12 @@ class ASTParser:
language = _get_language(grammar_tag)
if config is None or language is None:
- if config is not None and language is None:
- log.debug(
- "tree-sitter grammar unavailable",
- language=lang,
- path=file_info.path,
- )
+ if config is not None and language is None and lang not in _MISSING_GRAMMAR_REPORTED:
+ # Once per language, not once per file: the fact is about the
+ # environment, and it does not become truer on the four
+ # thousandth shell script.
+ _MISSING_GRAMMAR_REPORTED.add(lang)
+ log.debug("tree-sitter grammar unavailable", language=lang)
# Languages without a grammar may still carry regex-tier import
# extraction (their specs declare import_support="partial");
# symbols stay empty — the regex tier claims no symbol knowledge.
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 2057c0610..a76d6a806 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -29,6 +29,7 @@ from repowise.core.pipeline.progress import (
STAGE_INGESTION,
ProgressCallback,
emit_stage,
+ emit_warning,
)
from repowise.core.registry import HookProgressCallback
@@ -401,6 +402,11 @@ async def run_pipeline(
)
except Exception as _ext_err:
logger.warning("external_systems_extraction_failed", error=str(_ext_err))
+ emit_warning(
+ progress,
+ f"External dependency manifests not parsed ({_ext_err}); "
+ "pages will not name this repo's third-party systems.",
+ )
_phase_done(progress, "external_systems")
# ---- Checkpoint: INDEX -------------------------------------------------
@@ -415,6 +421,7 @@ async def run_pipeline(
git_summary=git_summary,
external_systems=external_systems,
source_map=source_map,
+ progress=progress,
)
# Emit rich insight summary for the ingestion phase
@@ -645,6 +652,7 @@ async def run_pipeline(
health_report=health_report,
decision_report=decision_report,
git_metadata_list=git_metadata_list,
+ progress=progress,
)
# ---- Phase 3: Generation (optional) ------------------------------------
@@ -709,6 +717,10 @@ async def run_pipeline(
progress.on_message("info", f"→ Detected {flipped} additional API contract file(s)")
except Exception as _api_err:
logger.warning("api_contract_detection_failed", error=str(_api_err))
+ emit_warning(
+ progress,
+ f"API contract detection skipped ({_api_err}); endpoint pages may be missing.",
+ )
# Launch the page-independent half of KG enrichment (LLM layer naming +
# tour) so it overlaps page generation instead of running strictly
@@ -873,6 +885,11 @@ async def run_pipeline(
execution_flow_report = await asyncio.to_thread(graph_builder.execution_flows)
except Exception as _flow_err:
logger.warning("execution_flow_tracing_skipped", error=str(_flow_err))
+ emit_warning(
+ progress,
+ f"Execution flow tracing skipped ({_flow_err}); "
+ "entry-point scores and flow-based pages will be absent.",
+ )
_phase_done(progress, "graph.flows")
# ---- Build result -------------------------------------------------------
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index 3736b67e7..00d1dd518 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -360,6 +360,29 @@ async def _run_decision_extraction(
f"→ {report.total_found} architectural decisions found"
+ (f": {summary}" if summary else ""),
)
+ # And the sources that produced nothing. Hiding these was what made
+ # a source failing outright indistinguishable from a source with
+ # honestly nothing to find: every failure inside the extractor is
+ # swallowed and reported only through ``logger.warning``, which no
+ # default CLI run renders. A repo with no ADR files legitimately
+ # scores zero there, so this is not itself a failure report — it is
+ # the list you need to have before you can tell the two apart.
+ # The labels read "from git history" because they are normally
+ # rendered as "5 from git history"; strung together after one
+ # "No decisions" they would read "No decisions from inline
+ # markers, from ADR files". Drop the preposition and name the
+ # sources plainly.
+ #
+ # ``session`` is in the label table but is not one of the
+ # extractor's own sources, so ``source in enabled`` leaves it out
+ # of this list — correct, since it is mined separately below.
+ empty = [
+ label.removeprefix("from ")
+ for source, label in _DECISION_SOURCE_LABELS
+ if source in enabled and not bs.get(source)
+ ]
+ if empty:
+ progress.on_message("info", f"→ Nothing found in: {', '.join(empty)}")
_phase_done(progress, "decisions")
return report
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index 0d6cc9e5e..8ec070920 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -12,6 +12,7 @@ from typing import Any
import structlog
+from repowise.core.cost_estimator.estimator import STRUCTURAL_PAGE_TYPES
from repowise.core.generation.models import count_stub_fallbacks
from repowise.core.pipeline.progress import ProgressCallback
@@ -19,6 +20,12 @@ from ._common import _phase_done
logger = structlog.get_logger(__name__)
+# Page types rendered from a Jinja template with no provider call. Reused from
+# the cost estimator rather than restated: that set is already the answer to
+# "does this page cost tokens", and a second copy here would be the thing that
+# drifts the first time a page type changes tier.
+_FREE_PAGE_TYPES = STRUCTURAL_PAGE_TYPES
+
async def run_generation(
*,
@@ -100,16 +107,46 @@ async def run_generation(
# phase so the terminal UI shows them as a distinct, named step rather
# than blending into the long file_page run.
_pages_done = 0
+ _llm_pages_done = 0
def on_page_done(page_type: str) -> None:
- nonlocal _pages_done
+ nonlocal _pages_done, _llm_pages_done
_pages_done += 1
- if progress:
- phase = "onboarding" if page_type == "onboarding" else "generation"
- progress.on_item_done(phase)
- # Push live cost update if the callback supports it
- if cost_tracker is not None and hasattr(progress, "set_cost"):
- progress.set_cost(cost_tracker.session_cost)
+ if not progress:
+ return
+ # Onboarding keeps its own named step, and also advances the overall
+ # bar. It used to do only the former while ``_announce_total`` counted
+ # onboarding slots into the overall total, so that bar's denominator
+ # included pages that could never tick it and it never reached 100%
+ # on its own — ``on_phase_done`` forcing it there at the end is what
+ # hid the arithmetic.
+ if page_type == "onboarding":
+ progress.on_item_done("onboarding")
+ progress.on_item_done("generation")
+
+ # One bar counting 4,229 items where ~4,134 are free template renders
+ # and ~95 are paid model calls reads as frozen: the cheap levels run
+ # first, so it sprints to 97% and then crawls for another quarter of an
+ # hour with the cost figure sitting still. The paid work gets its own
+ # counter so that stretch has something visibly moving in it.
+ #
+ # Counted rather than announced up front: the per-tier totals are known
+ # only inside the level builders, which this phase does not own. An
+ # indeterminate counter states what is true without inventing a
+ # denominator.
+ #
+ # Counts by page *type*, not by whether a call was made, so a resume or
+ # update run that reuses a cached page still counts it here. The tier
+ # is right; on a heavily-reused run the count overstates the calls.
+ if page_type not in _FREE_PAGE_TYPES:
+ _llm_pages_done += 1
+ if _llm_pages_done == 1:
+ progress.on_phase_start("generation.llm", None)
+ progress.on_item_done("generation.llm")
+
+ # Push live cost update if the callback supports it
+ if cost_tracker is not None and hasattr(progress, "set_cost"):
+ progress.set_cost(cost_tracker.session_cost)
if progress:
progress.on_phase_start("generation", None)
@@ -192,6 +229,7 @@ async def run_generation(
# Surface the FAQ-weighted budget tilt when session demand shaped it
# (silent on fresh repos with no history — nothing to weight yet).
_phase_done(progress, "onboarding")
+ _phase_done(progress, "generation.llm")
_phase_done(progress, "generation")
return generated_pages
diff --git a/packages/core/src/repowise/core/pipeline/phases/ingestion.py b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
index 6ff8d0834..7617e27b6 100644
--- a/packages/core/src/repowise/core/pipeline/phases/ingestion.py
+++ b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
@@ -17,13 +17,43 @@ from typing import Any
import structlog
-from repowise.core.pipeline.progress import ProgressCallback
+from repowise.core.pipeline.progress import ProgressCallback, emit_warning
from ._common import _phase_done
logger = structlog.get_logger(__name__)
+def _report_missing_grammars(stats: Any, progress: ProgressCallback | None) -> None:
+ """Name the languages present in this repo that have no installed grammar.
+
+ Scoped to what the traversal actually found, so a machine missing a grammar
+ for a language the repo does not contain says nothing. Best-effort: a
+ reporting failure must not stop an index.
+ """
+ if progress is None or stats is None:
+ return
+ lang_counts = getattr(stats, "lang_counts", None)
+ if not lang_counts:
+ return
+ try:
+ from repowise.core.ingestion.parser import missing_grammar_languages
+
+ missing = missing_grammar_languages(lang_counts)
+ except Exception:
+ logger.debug("grammar_preflight_failed", exc_info=True)
+ return
+ if not missing:
+ return
+ detail = ", ".join(f"{lang} ({lang_counts[lang]:,} files)" for lang in missing)
+ emit_warning(
+ progress,
+ f"No parser installed for: {detail}. "
+ "These files are indexed but contribute no symbols; "
+ "reinstall repowise to pick up the missing grammars.",
+ )
+
+
async def _timed_step(
label: str,
fn: Any,
@@ -431,6 +461,14 @@ async def _run_ingestion(
_emit_traversal_summary(progress, traverser.stats, len(file_infos))
# ---- Parse phase: CPU-bound, run in ProcessPoolExecutor ----------------
+ # Say once, here, what each spawned worker would otherwise discover
+ # independently and log at a level no default run renders: this
+ # environment cannot parse some of the languages this repo contains.
+ # Those files still index (paths, git history, regex-tier imports) but
+ # carry no symbols, which is not something to find out from an empty
+ # symbol list weeks later.
+ _report_missing_grammars(getattr(traverser, "stats", None), progress)
+
if progress:
progress.on_phase_start("parse", len(file_infos))
@@ -481,6 +519,15 @@ async def _run_ingestion(
"process_pool_parse_failed_falling_back",
error=str(pool_exc),
)
+ # Worth saying out loud rather than only logging: the run still
+ # produces a correct index, but every file is now parsed in one
+ # process instead of up to eight, so a large repo takes several
+ # times longer for a reason nothing on screen explained.
+ emit_warning(
+ progress,
+ f"Parallel parsing unavailable ({pool_exc}); "
+ "falling back to a single process, which is much slower.",
+ )
# Fallback: in-process sequential parse
parse_results = []
_fallback_parser = ASTParser()
@@ -593,6 +640,11 @@ async def _run_ingestion(
logger.info("dynamic_hints_added", count=len(dynamic_edges))
except Exception as hints_exc:
logger.warning("dynamic_hints_failed", error=str(hints_exc))
+ emit_warning(
+ progress,
+ f"Dynamic edge hints skipped ({hints_exc}); "
+ "framework-wired call edges will be missing from the graph.",
+ )
_phase_done(progress, "dynamic_hints")
# ---- Graph metrics: prime caches with live progress ---------------------
diff --git a/packages/core/src/repowise/core/pipeline/progress.py b/packages/core/src/repowise/core/pipeline/progress.py
index ca70af783..794c78912 100644
--- a/packages/core/src/repowise/core/pipeline/progress.py
+++ b/packages/core/src/repowise/core/pipeline/progress.py
@@ -35,6 +35,40 @@ def emit_stage(progress: Any, stage: str) -> None:
fn(stage)
+def emit_warning(progress: Any, text: str) -> None:
+ """Report a degradation on the one channel a default run actually shows.
+
+ ``logger.warning`` is invisible in every CLI run: ``configure_cli_logging``
+ pins ``repowise.core`` to ERROR unless ``--verbose``, and the structlog
+ filtering bound logger drops the record before it is formatted. So a phase
+ could fail completely — three decision sources returning nothing, the parse
+ pool dying and falling back to sequential — and the run printed nothing at
+ all. ``vector_store/_base.py`` already reached this conclusion and logs its
+ truncation report at ``error`` to get around it; that works, but it makes
+ the level describe the plumbing rather than the severity.
+
+ ``on_message`` is the channel the CLI renders, and it survives a non-TTY:
+ Rich's ``Live`` passes renderables straight through when the console is not
+ interactive, so a piped or CI run still gets the line (asserted in
+ ``tests/unit/cli/test_progress_non_tty.py`` — that is the load-bearing
+ assumption here, not an incidental detail).
+
+ Call this *in addition to* the structured ``logger.warning``, not instead
+ of it: the log keeps the machine-readable key and fields, this carries the
+ sentence a human or an agent reads. Never raises — a reporting failure must
+ not abort a run that was otherwise fine.
+ """
+ if progress is None:
+ return
+ fn = getattr(progress, "on_message", None)
+ if fn is None:
+ return
+ try:
+ fn("warning", text)
+ except Exception:
+ logger.debug("progress_warning_emit_failed", text=text, exc_info=True)
+
+
@runtime_checkable
class ProgressCallback(Protocol):
"""Protocol for pipeline progress reporting."""
diff --git a/packages/core/src/repowise/core/pipeline/resume/controller.py b/packages/core/src/repowise/core/pipeline/resume/controller.py
index 71cdbc067..e83498449 100644
--- a/packages/core/src/repowise/core/pipeline/resume/controller.py
+++ b/packages/core/src/repowise/core/pipeline/resume/controller.py
@@ -26,6 +26,7 @@ from typing import Any
import structlog
from ..persist import persist_analysis, persist_git, persist_ingestion
+from ..progress import emit_warning
from .ledger import ResumeLedger
from .phases import RESUME_PHASE_ORDER, ResumePhase
from .rehydrate import (
@@ -136,9 +137,13 @@ class ResumeController:
external_systems: list[dict] | None = None,
execution_flow_report: Any | None = None,
source_map: dict[str, bytes] | None = None,
+ progress: Any | None = None,
) -> None:
"""Persist the INDEX phase (graph + symbols + git) and record it.
+ *progress* is taken per call rather than at construction because the
+ controller is built before the CLI opens its progress display.
+
Idempotent UPSERTs throughout, so a later full persist that re-writes
the same rows (e.g. graph nodes with entry-point scores once execution
flow is known) is harmless. Best-effort: a persistence hiccup is logged
@@ -166,6 +171,15 @@ class ResumeController:
await persist_git(view, session, self._repo_id)
except Exception as exc:
logger.warning("resume_checkpoint_index_failed", error=str(exc))
+ # The CLI tells the user their index was saved and that
+ # ``--resume`` will pick it up. When this write fails that promise
+ # is false, and silence is the one outcome that lets them find out
+ # only by paying for the whole index a second time.
+ emit_warning(
+ progress,
+ f"Index checkpoint not saved ({exc}); "
+ "a resumed run will have to recompute it.",
+ )
return
self._index_persisted = True
await self._ledger.mark_completed(ResumePhase.INDEX)
@@ -179,6 +193,7 @@ class ResumeController:
decision_report: Any | None,
git_metadata_list: list[dict],
vector_store: Any | None = None,
+ progress: Any | None = None,
) -> None:
"""Persist the ANALYSIS phase (dead code + health + decisions) and record it.
@@ -207,6 +222,11 @@ class ResumeController:
await persist_analysis(view, session, self._repo_id)
except Exception as exc:
logger.warning("resume_checkpoint_analysis_failed", error=str(exc))
+ emit_warning(
+ progress,
+ f"Analysis checkpoint not saved ({exc}); "
+ "a resumed run will have to recompute dead code, health and decisions.",
+ )
return
await self._ledger.mark_completed(ResumePhase.ANALYSIS)
logger.info("resume_checkpoint_analysis", repo_id=self._repo_id)
diff --git a/tests/unit/cli/test_doctor_embed_recipe.py b/tests/unit/cli/test_doctor_embed_recipe.py
index e623b5670..bfbde5c71 100644
--- a/tests/unit/cli/test_doctor_embed_recipe.py
+++ b/tests/unit/cli/test_doctor_embed_recipe.py
@@ -118,7 +118,7 @@ def repair(monkeypatch):
def _run(repo_path: Path) -> _RecordingStore:
recorder = _RecordingStore()
monkeypatch.setattr("repowise.cli.providers.resolve_embedder_for_repo", lambda _p: "mock")
- monkeypatch.setattr("repowise.cli.providers.build_embedder", lambda _n: object())
+ monkeypatch.setattr("repowise.cli.providers.build_embedder", lambda _n, _p=None: object())
monkeypatch.setattr("repowise.cli.providers.build_vector_store", lambda _p, _e: recorder)
repo_checks._run_repo_checks(Path(repo_path), repair=True)
return recorder
diff --git a/tests/unit/cli/test_embedder_key_resolution.py b/tests/unit/cli/test_embedder_key_resolution.py
new file mode 100644
index 000000000..497b42859
--- /dev/null
+++ b/tests/unit/cli/test_embedder_key_resolution.py
@@ -0,0 +1,339 @@
+"""The CLI must find the key ``init`` persisted.
+
+Immediately after an init that generated and embedded 6,072 pages with a real
+key, in the same shell, ``repowise search`` printed:
+
+ Embedder 'openai' could not be built: ValueError: OpenAI API key required.
+ Falling back to keyless embeddings, which means no semantic search.
+
+The index was fine — 1536-wide vectors, all of them. What was missing was a key
+*resolver*: the CLI's ``_embedder_kwargs`` never set ``api_key``, so the only
+route was the adapter reading ``os.environ`` directly, and the tool surface
+never merged ``.repowise/.env`` into it. The MCP server resolved the same repo
+correctly, so the two disagreed about the same directory in the same shell.
+
+These cover the resolver's precedence and, separately, the call site — a helper
+test alone would keep passing if the threading were reverted.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+import yaml
+
+from repowise.cli.providers.keys import resolve_embedder_api_key
+
+KEY_ENV_VARS = ("OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "OPENROUTER_API_KEY")
+
+
[email protected](autouse=True)
+def _no_ambient_keys(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ """A developer's exported key must not decide these assertions.
+
+ Precedence tests are meaningless if the highest-precedence source is
+ populated by the machine running them. ``HOME`` is redirected too, so the
+ global-config tier reads a directory this test owns rather than the
+ author's real ``~/.repowise/config.yaml``.
+ """
+ for var in (*KEY_ENV_VARS, "REPOWISE_EMBEDDER", "REPOWISE_EMBEDDING_MODEL"):
+ monkeypatch.delenv(var, raising=False)
+ home = tmp_path / "home"
+ home.mkdir()
+ monkeypatch.setattr(Path, "home", classmethod(lambda _cls: home))
+
+
+def _write_env(repo_path: Path, **keys: str) -> None:
+ repowise_dir = repo_path / ".repowise"
+ repowise_dir.mkdir(parents=True, exist_ok=True)
+ body = "".join(f"{k}={v}\n" for k, v in keys.items())
+ (repowise_dir / ".env").write_text(body, encoding="utf-8")
+
+
+def _write_config(repo_path: Path, **keys: object) -> None:
+ repowise_dir = repo_path / ".repowise"
+ repowise_dir.mkdir(parents=True, exist_ok=True)
+ (repowise_dir / "config.yaml").write_text(yaml.safe_dump(keys), encoding="utf-8")
+
+
+def _write_global_config(**keys: object) -> None:
+ global_dir = Path.home() / ".repowise"
+ global_dir.mkdir(parents=True, exist_ok=True)
+ (global_dir / "config.yaml").write_text(yaml.safe_dump(keys), encoding="utf-8")
+
+
+# --- precedence -------------------------------------------------------------
+
+
+def test_env_wins_over_everything(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """An exported key is an explicit override and nothing may outrank it."""
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+ _write_global_config(embedder="openai", embedder_api_key="sk-from-global")
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-from-env")
+
+ assert resolve_embedder_api_key("openai", tmp_path).key == "sk-from-env"
+
+
+def test_dotenv_is_read_without_an_exported_key(tmp_path: Path) -> None:
+ """The defect, at its narrowest: this is where ``init`` puts the key."""
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+
+ assert resolve_embedder_api_key("openai", tmp_path).key == "sk-from-dotenv"
+
+
+def test_dotenv_outranks_the_global_config(tmp_path: Path) -> None:
+ """Repo-local beats machine-global — the repo's own key describes it."""
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+ _write_global_config(embedder="openai", embedder_api_key="sk-from-global")
+
+ assert resolve_embedder_api_key("openai", tmp_path).key == "sk-from-dotenv"
+
+
+def test_global_config_is_the_last_resort(tmp_path: Path) -> None:
+ _write_global_config(embedder="openai", embedder_api_key="sk-from-global")
+
+ assert resolve_embedder_api_key("openai", tmp_path).key == "sk-from-global"
+
+
+def test_global_key_is_ignored_for_a_different_embedder(tmp_path: Path) -> None:
+ """Handing an OpenAI key to Gemini fails as "bad key", not "wrong key".
+
+ The gate is the server's, mirrored: the saved credential belongs to the
+ saved embedder, and only to it.
+ """
+ _write_global_config(embedder="openai", embedder_api_key="sk-from-global")
+
+ assert resolve_embedder_api_key("gemini", tmp_path).key is None
+
+
+def test_gemini_accepts_either_of_its_two_variables(tmp_path: Path) -> None:
+ _write_env(tmp_path, GOOGLE_API_KEY="goog-key")
+
+ assert resolve_embedder_api_key("gemini", tmp_path).key == "goog-key"
+
+
+def test_keyless_backends_resolve_to_nothing(tmp_path: Path) -> None:
+ """``ollama`` and ``mock`` want no credential, so none is "missing"."""
+ for name in ("ollama", "mock", "unknown-backend"):
+ lookup = resolve_embedder_api_key(name, tmp_path)
+ assert lookup.key is None
+ assert lookup.searched == ()
+
+
+def test_resolution_does_not_mutate_the_environment(tmp_path: Path) -> None:
+ """``load_dotenv``'s merge is first-writer-wins across the whole process.
+
+ In a workspace that leaks repo A's key into every sibling's resolution.
+ This resolver takes an explicit ``repo_path`` precisely so it cannot.
+ """
+ import os
+
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+
+ assert resolve_embedder_api_key("openai", tmp_path).key == "sk-from-dotenv"
+ assert "OPENAI_API_KEY" not in os.environ
+
+
+def test_a_repoless_lookup_still_reads_env_and_global(tmp_path: Path) -> None:
+ """Callers without a repo in hand must not crash, only resolve less far."""
+ _write_global_config(embedder="openai", embedder_api_key="sk-from-global")
+
+ assert resolve_embedder_api_key("openai", None).key == "sk-from-global"
+
+
+# --- the key reaches the constructor ---------------------------------------
+
+
+def test_embedder_kwargs_passes_the_dotenv_key_through(tmp_path: Path) -> None:
+ """The adapter reads ``os.environ`` itself, so an unset var raises there.
+
+ Passing ``api_key`` explicitly is the only way a key that lives on disk
+ reaches it.
+ """
+ from repowise.cli.providers.embedders import _embedder_kwargs
+
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+
+ assert _embedder_kwargs("openai", tmp_path).get("api_key") == "sk-from-dotenv"
+
+
+def test_embedder_kwargs_omits_api_key_when_there_is_none(tmp_path: Path) -> None:
+ """An empty ``api_key=`` would mask the adapter's own clearer refusal."""
+ from repowise.cli.providers.embedders import _embedder_kwargs
+
+ assert "api_key" not in _embedder_kwargs("openai", tmp_path)
+
+
+def test_build_embedder_hands_the_key_to_the_registry(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from repowise.cli import providers
+
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+ seen: dict = {}
+
+ def _spy(name: str, **kwargs: object):
+ seen.update(kwargs)
+ return object()
+
+ monkeypatch.setattr("repowise.core.providers.embedding.registry.get_embedder", _spy)
+ providers.build_embedder("openai", tmp_path)
+
+ assert seen.get("api_key") == "sk-from-dotenv"
+
+
+# --- the call site that actually broke --------------------------------------
+
+
+def test_the_tool_bridge_resolves_the_persisted_key(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """``search`` and ``ask`` both build their store here.
+
+ This is the reproducer for the reported symptom: an init-shaped repo, a
+ real key on disk, nothing exported, and the store must come up with the
+ configured embedder rather than the keyless fallback.
+ """
+ from repowise.cli import tool_bridge
+
+ _write_config(tmp_path, embedder="openai")
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+ (tmp_path / ".repowise" / "lancedb").mkdir(parents=True, exist_ok=True)
+
+ seen: dict = {}
+
+ def _spy(name: str, **kwargs: object):
+ seen["name"] = name
+ seen.update(kwargs)
+ return object()
+
+ monkeypatch.setattr("repowise.core.providers.embedding.registry.get_embedder", _spy)
+ asyncio.run(tool_bridge._open_vector_store(tmp_path))
+
+ assert seen.get("name") == "openai"
+ assert seen.get("api_key") == "sk-from-dotenv"
+
+
+def test_the_tool_bridge_does_not_report_a_degraded_embedder(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The user-visible half: ``_meta.embedder_degraded`` must come back false.
+
+ A degraded status is what tells an agent the answer skipped semantic
+ retrieval, and it was true for every ``search`` on a correctly indexed repo.
+ """
+ from repowise.cli import tool_bridge
+ from repowise.server.mcp_server import _state
+
+ _write_config(tmp_path, embedder="openai")
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+
+ def _needs_a_key(name: str, **kwargs: object):
+ # What ``OpenAIEmbedder.__init__`` does: no key, no embedder. A stub
+ # that succeeds unconditionally would pass with the fix reverted.
+ if not kwargs.get("api_key"):
+ raise ValueError("OpenAI API key required")
+ return object()
+
+ monkeypatch.setattr("repowise.core.providers.embedding.registry.get_embedder", _needs_a_key)
+ monkeypatch.setattr(_state, "_embedder_status", None, raising=False)
+ asyncio.run(tool_bridge._open_vector_store(tmp_path))
+
+ assert _state._embedder_status["degraded"] is False
+ assert _state._embedder_status["active"] == "openai"
+
+
+# --- the degraded message must name what it looked at -----------------------
+
+
+def test_the_degraded_message_names_the_places_it_searched(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """"Set OPENAI_API_KEY" is wrong advice for a user whose key is on disk.
+
+ It sends them to fix something that is already correct, which is how this
+ defect survived a user looking straight at it.
+ """
+ from repowise.cli import helpers, providers
+
+ def _boom(name: str, **kwargs: object):
+ raise ValueError("OpenAI API key required")
+
+ monkeypatch.setattr("repowise.core.providers.embedding.registry.get_embedder", _boom)
+ printed: list[str] = []
+ monkeypatch.setattr(
+ helpers.err_console, "print", lambda *a, **k: printed.append(" ".join(str(x) for x in a))
+ )
+
+ providers.build_embedder("openai", tmp_path)
+
+ said = " ".join(printed)
+ assert "OPENAI_API_KEY" in said
+ assert str(tmp_path / ".repowise" / ".env") in said
+ assert "config.yaml" in said
+
+
+# --- the CLI and the MCP server must not disagree ---------------------------
+
+
+ "seed",
+ [
+ pytest.param("dotenv", id="key-in-dotenv"),
+ pytest.param("global", id="key-in-global-config"),
+ pytest.param("nowhere", id="no-key-anywhere"),
+ ],
+)
+def test_cli_and_mcp_resolve_the_same_key_for_the_same_repo(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, seed: str
+) -> None:
+ """The disagreement is itself the bug, not just the CLI's half of it.
+
+ An agent that reaches this repo over MCP got semantic search while the same
+ agent shelling out to ``repowise search`` got full-text only, from the same
+ directory in the same shell. The two resolvers are separate code (the
+ server cannot import the CLI), so only a test holds them together.
+ """
+ from repowise.server.mcp_server import _server, _state
+
+ if seed == "dotenv":
+ _write_env(tmp_path, OPENAI_API_KEY="sk-from-dotenv")
+ expected = "sk-from-dotenv"
+ elif seed == "global":
+ _write_global_config(embedder="openai", embedder_api_key="sk-from-global")
+ expected = "sk-from-global"
+ else:
+ expected = None
+
+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path), raising=False)
+
+ assert resolve_embedder_api_key("openai", tmp_path).key == expected
+ assert _server._persisted_embedder_key("openai") == expected
+
+
+def test_no_key_search_is_reported_for_a_keyless_backend(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Ollama refusing a connection is not a missing-credential problem.
+
+ Listing key locations there would send the user hunting for a key that
+ backend never wanted.
+ """
+ from repowise.cli import helpers, providers
+
+ def _boom(name: str, **kwargs: object):
+ raise RuntimeError("connection refused")
+
+ monkeypatch.setattr("repowise.core.providers.embedding.registry.get_embedder", _boom)
+ printed: list[str] = []
+ monkeypatch.setattr(
+ helpers.err_console, "print", lambda *a, **k: printed.append(" ".join(str(x) for x in a))
+ )
+
+ providers.build_embedder("ollama", tmp_path)
+
+ said = " ".join(printed)
+ assert "connection refused" in said
+ assert "No API key was found" not in said
diff --git a/tests/unit/cli/test_embedder_resolution.py b/tests/unit/cli/test_embedder_resolution.py
index 2936b5815..b3e7a0329 100644
--- a/tests/unit/cli/test_embedder_resolution.py
+++ b/tests/unit/cli/test_embedder_resolution.py
@@ -149,7 +149,7 @@ def test_semantic_search_reads_through_the_repo_resolver(
seen: list[str] = []
- def _record(name: str):
+ def _record(name: str, _repo_path=None):
seen.append(name)
return MockEmbedder()
@@ -254,7 +254,7 @@ async def test_reindex_persists_its_resolved_embedder(
# _reindex imports build_embedder from this module inside the function, so
# the module attribute is the one that takes effect.
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda _n: _WideEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda _n, _p=None: _WideEmbedder()
)
await reindex_cmd._reindex(tmp_path, "openai", batch_size=8)
@@ -303,7 +303,7 @@ async def test_reindex_does_not_pin_an_embedder_that_wrote_nothing(
"sqlalchemy.ext.asyncio.async_sessionmaker", lambda *a, **k: lambda: _Session()
)
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda _n: _WideEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda _n, _p=None: _WideEmbedder()
)
await reindex_cmd._reindex(tmp_path, "openai", batch_size=8)
@@ -421,7 +421,7 @@ def test_mock_width_with_a_real_pin_proposes_a_re_embed(
monkeypatch.delenv("REPOWISE_EMBEDDER", raising=False)
_patch_stored_dim(monkeypatch, 8)
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda _n: _WideEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda _n, _p=None: _WideEmbedder()
)
assert _vector_dims(tmp_path) == (8, 1536)
@@ -451,7 +451,7 @@ def test_two_real_widths_are_never_compared(
return [[0.0] * 1024 for _ in texts]
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda _n: _MisreportingEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda _n, _p=None: _MisreportingEmbedder()
)
assert _vector_dims(tmp_path) == (None, None)
@@ -516,7 +516,7 @@ def test_a_real_pin_still_reads_the_stored_table(
monkeypatch.setattr("repowise.cli.providers.vector_store.existing_vector_dim", _spy)
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda _n: _WideEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda _n, _p=None: _WideEmbedder()
)
assert _vector_dims(tmp_path) == (8, 1536)
diff --git a/tests/unit/cli/test_persist_result_progress.py b/tests/unit/cli/test_persist_result_progress.py
new file mode 100644
index 000000000..38751b85a
--- /dev/null
+++ b/tests/unit/cli/test_persist_result_progress.py
@@ -0,0 +1,105 @@
+"""Persistence must not be a silent stretch at the end of a run.
+
+Everything after "Generated N pages" ran under one indeterminate spinner:
+SQL upserts, the stale-page sweep, and a full-text index loop that awaits once
+per generated page. On a few thousand pages that is minutes of a screen that
+looks identical whether the run is working or wedged — directly after a
+generation bar that had just announced it was finished.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+from repowise.cli.commands.init_cmd.persistence import persist_result
+from repowise.core.generation.models import GeneratedPage
+
+
+class _RecordingProgress:
+ def __init__(self) -> None:
+ self.started: list[tuple[str, int | None]] = []
+ self.items: list[str] = []
+ self.done: list[str] = []
+
+ def on_phase_start(self, phase: str, total: int | None) -> None:
+ self.started.append((phase, total))
+
+ def on_item_done(self, phase: str) -> None:
+ self.items.append(phase)
+
+ def on_phase_done(self, phase: str) -> None:
+ self.done.append(phase)
+
+ def on_message(self, level: str, text: str) -> None:
+ pass
+
+
+def _page(target: str) -> GeneratedPage:
+ now = datetime.now(UTC).isoformat()
+ return GeneratedPage(
+ page_id=f"module_page:{target}",
+ page_type="module_page",
+ title=target,
+ content=f"content for {target}",
+ source_hash="x" * 64,
+ model_name="mock",
+ provider_name="mock",
+ input_tokens=1,
+ output_tokens=1,
+ cached_tokens=0,
+ generation_level=4,
+ target_path=target,
+ created_at=now,
+ updated_at=now,
+ )
+
+
+def _result(pages: list[GeneratedPage]) -> SimpleNamespace:
+ return SimpleNamespace(
+ repo_name="r",
+ index_persisted_incrementally=True,
+ generated_pages=pages,
+ tech_stack=None,
+ vector_store=None,
+ dead_code_report=None,
+ health_report=None,
+ decision_report=None,
+ git_metadata_list=[],
+ knowledge_graph_result=None,
+ authoritative_page_types=set(),
+ preserved_page_ids=set(),
+ )
+
+
+async def test_full_text_indexing_reports_a_page_at_a_time(tmp_path):
+ repo_path = tmp_path / "repo"
+ repo_path.mkdir()
+ progress = _RecordingProgress()
+
+ pages = [_page("a"), _page("b"), _page("c")]
+ await persist_result(_result(pages), repo_path, progress)
+
+ # A real denominator, not a spinner: the loop length is known up front.
+ assert ("persist", len(pages)) in progress.started
+ assert progress.items.count("persist") == len(pages)
+ assert "persist" in progress.done
+
+
+async def test_persistence_still_works_without_a_progress_callback(tmp_path):
+ """The parameter is optional — the workspace flow and the tests pass none."""
+ repo_path = tmp_path / "repo"
+ repo_path.mkdir()
+
+ await persist_result(_result([_page("a")]), repo_path)
+
+
+async def test_an_index_only_run_announces_no_page_loop(tmp_path):
+ """With no pages there is no per-page work, so there is no total to show."""
+ repo_path = tmp_path / "repo"
+ repo_path.mkdir()
+ progress = _RecordingProgress()
+
+ await persist_result(_result([]), repo_path, progress)
+
+ assert [phase for phase, _ in progress.started if phase == "persist"] == []
diff --git a/tests/unit/cli/test_pricing_table_agreement.py b/tests/unit/cli/test_pricing_table_agreement.py
new file mode 100644
index 000000000..d621516f2
--- /dev/null
+++ b/tests/unit/cli/test_pricing_table_agreement.py
@@ -0,0 +1,92 @@
+"""The quoted estimate and the live counter must price a model the same way.
+
+The pre-run estimate ("$1.19 - $1.98, median $1.59") comes from
+``cost_estimator/pricing.py``, in USD per **1K** tokens. The live counter that
+ticks up during the run comes from ``generation/cost_tracker.py``, in USD per
+**1M** tokens. Two hand-maintained tables in different units, feeding two
+numbers a user compares directly, is a 1000x error waiting for someone to add a
+row to one of them.
+
+The tables agree today. This is the guard that says so, because the failure
+mode is silent: an estimate that is wrong by three orders of magnitude still
+renders as a plausible dollar figure, and it is shown *before* the user commits
+to spending.
+
+Only models present in both tables are compared. Each deliberately carries rows
+the other does not — the estimator prices what an index plan can select, the
+tracker prices what a session transcript can report — and requiring identical
+membership would be a different, unwanted constraint.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.cost_estimator.pricing import _COST_TABLE_EXACT, _lookup_cost
+from repowise.core.generation.cost_tracker import _PRICING, get_model_pricing
+
+_SHARED_MODELS = sorted(set(_COST_TABLE_EXACT) & set(_PRICING))
+
+# Models where the two tables already disagree, found by this test on the run
+# that introduced it. Both are Gemini "preview" rows that ``cost_tracker``
+# still prices at the gemini-1.5-flash rate ($0.075/$0.30 per MTok) it sits
+# directly beneath in that file, while the estimator carries per-row rates with
+# explicit per-MTok comments. ``gemini-3.5-flash-lite`` agrees in both tables,
+# which is what makes these two look like copied placeholders rather than a
+# deliberate split.
+#
+# Not fixed here: the wrong half is ``core/generation/cost_tracker.py``, and
+# this branch does not own that file. ``strict=True`` on purpose — whoever
+# corrects the rate gets a failing test telling them to delete this entry,
+# rather than a silently-passing xfail that outlives the bug.
+_KNOWN_DRIFT = {
+ "gemini-3-flash-preview": "cost_tracker prices it at the 1.5-flash rate",
+ "gemini-3.1-flash-lite-preview": "cost_tracker prices it at the 1.5-flash rate",
+}
+
+
+def _param(model: str):
+ if model in _KNOWN_DRIFT:
+ return pytest.param(model, marks=pytest.mark.xfail(strict=True, reason=_KNOWN_DRIFT[model]))
+ return pytest.param(model)
+
+
+def test_the_two_tables_actually_overlap() -> None:
+ """Otherwise the parametrised test below would vacuously pass on zero cases."""
+ assert len(_SHARED_MODELS) >= 5, _SHARED_MODELS
+
+
[email protected]("model", [_param(m) for m in _SHARED_MODELS])
+def test_estimate_and_live_counter_price_a_model_identically(model: str) -> None:
+ """Per-1K x 1000 must equal per-MTok, for both directions of the bill."""
+ est_input, est_output = _lookup_cost(model)
+ live = get_model_pricing(model)
+
+ assert est_input * 1000 == pytest.approx(live["input"]), (
+ f"{model}: estimate says ${est_input * 1000:.4f}/MTok input, "
+ f"live counter says ${live['input']:.4f}/MTok"
+ )
+ assert est_output * 1000 == pytest.approx(live["output"]), (
+ f"{model}: estimate says ${est_output * 1000:.4f}/MTok output, "
+ f"live counter says ${live['output']:.4f}/MTok"
+ )
+
+
+def test_the_default_model_is_priced_by_both() -> None:
+ """The one model almost every run actually uses.
+
+ A default that only one table knows is the case where the mismatch reaches
+ the most users, so it is asserted by name rather than left to the overlap.
+ """
+ import inspect
+
+ from repowise.core.providers.llm.openai import OpenAIProvider
+
+ # Read from the constructor signature rather than repeating the name, so
+ # bumping the default (as #1594 did) fails here instead of silently
+ # pricing the new default off the fallback tier.
+ default = inspect.signature(OpenAIProvider.__init__).parameters["model"].default
+ assert isinstance(default, str) and default
+
+ assert default in _COST_TABLE_EXACT, f"{default} missing from the estimator table"
+ assert default in _PRICING, f"{default} missing from the live cost table"
diff --git a/tests/unit/cli/test_progress_non_tty.py b/tests/unit/cli/test_progress_non_tty.py
new file mode 100644
index 000000000..94b6f9c4d
--- /dev/null
+++ b/tests/unit/cli/test_progress_non_tty.py
@@ -0,0 +1,265 @@
+"""``on_message`` must reach an agent, not just a terminal.
+
+Routing pipeline failures through ``progress.on_message`` is only an
+improvement over ``logger.warning`` if that channel survives the absence of a
+TTY. Agent-driven mode — scripted ``repowise init --yes``, CI, a subprocess
+call — is the primary path and has no terminal at all, so if Rich suppressed
+these lines when stdout is a pipe the fix would be worth nothing precisely
+where it is needed most.
+
+It does survive: Rich's ``Live`` only splices its own render into the output
+when the console is interactive, and otherwise lets the caller's renderables
+through untouched. That is a property of a third-party library, which is
+exactly the kind of assumption that should be pinned by a test rather than
+believed.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+from pathlib import Path
+from typing import ClassVar
+
+import pytest
+from rich.console import Console
+from rich.progress import Progress, TextColumn
+
+from repowise.cli.ui.progress import RichProgressCallback
+from repowise.core.pipeline.progress import emit_warning
+
+
+def _non_tty_console() -> tuple[Console, io.StringIO]:
+ """A console whose file is a pipe, the way a piped CLI run gets one."""
+ buf = io.StringIO()
+ console = Console(file=buf, width=200)
+ assert console.is_terminal is False, "fixture must model a non-TTY"
+ return console, buf
+
+
+def test_a_warning_reaches_a_piped_stdout() -> None:
+ """The load-bearing assumption, stated as an assertion."""
+ console, buf = _non_tty_console()
+ with Progress(TextColumn("{task.description}"), console=console) as bar:
+ callback = RichProgressCallback(bar, console)
+ callback.on_phase_start("parse", 10)
+ callback.on_message("warning", "Parallel parsing unavailable (boom)")
+
+ assert "Parallel parsing unavailable (boom)" in buf.getvalue()
+
+
+def test_emit_warning_reaches_a_piped_stdout() -> None:
+ """Through the helper the pipeline actually calls, not just the method."""
+ console, buf = _non_tty_console()
+ with Progress(TextColumn("{task.description}"), console=console) as bar:
+ emit_warning(RichProgressCallback(bar, console), "Index checkpoint not saved (disk full)")
+
+ assert "Index checkpoint not saved (disk full)" in buf.getvalue()
+
+
+def test_emit_warning_tolerates_a_missing_channel() -> None:
+ """A reporting failure must never abort a run that was otherwise fine."""
+
+ class _NoMessages:
+ pass
+
+ class _Raises:
+ def on_message(self, level: str, text: str) -> None:
+ raise RuntimeError("console is gone")
+
+ emit_warning(None, "nobody listening")
+ emit_warning(_NoMessages(), "no such method")
+ emit_warning(_Raises(), "raises")
+
+
+def test_warnings_are_collected_for_the_run_record() -> None:
+ """Printing is for humans; an agent needs it after the output is gone."""
+ console, _ = _non_tty_console()
+ with Progress(TextColumn("{task.description}"), console=console) as bar:
+ callback = RichProgressCallback(bar, console)
+ callback.on_message("info", "Scanned 12,431 files")
+ callback.on_message("warning", "Execution flow tracing skipped (boom)")
+ callback.on_message("error", "Analysis checkpoint not saved (disk full)")
+
+ # ``info`` carries neutral facts and is not a degradation.
+ assert callback.warnings == [
+ "Execution flow tracing skipped (boom)",
+ "Analysis checkpoint not saved (disk full)",
+ ]
+
+
+def test_degraded_run_is_recorded_in_state_json(tmp_path: Path, monkeypatch) -> None:
+ """The machine-readable half.
+
+ Exit code and completion panel look identical whether or not a phase
+ silently degraded, so ``state.json`` is where a scripted run finds out.
+ """
+ from repowise.cli.commands.init_cmd import persistence
+
+ (tmp_path / ".repowise").mkdir(parents=True)
+ monkeypatch.setattr(persistence, "get_head_commit", lambda _p: "abc123")
+ monkeypatch.setattr(persistence, "run_async", lambda _c: 7)
+ monkeypatch.setattr(persistence, "stamp_offered_slots", lambda *a, **k: None)
+ monkeypatch.setattr(persistence, "config_fingerprint", lambda _p: "fp")
+ monkeypatch.setattr(persistence, "head_commit_ts", lambda _p: None)
+ monkeypatch.setattr(persistence, "save_config", lambda *a, **k: None)
+
+ class _Provider:
+ provider_name = "openai"
+ model_name = "gpt-5.6-luna"
+
+ class _Result:
+ generated_pages: ClassVar[list] = []
+ knowledge_graph_result = None
+ health_report = None
+
+ persistence.save_full_state_and_config(
+ repo_path=tmp_path,
+ result=_Result(),
+ provider=_Provider(),
+ phase_timings={},
+ degraded=["Execution flow tracing skipped (boom)"],
+ embedder_name_resolved="openai",
+ exclude_patterns=[],
+ commit_limit=None,
+ resolved_commit_limit=500,
+ resolved_reasoning="medium",
+ )
+
+ state = json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert state["degraded"] == ["Execution flow tracing skipped (boom)"]
+
+
+def test_a_clean_run_records_no_degraded_key(tmp_path: Path, monkeypatch) -> None:
+ """An empty list is a third state nothing should have to interpret."""
+ from repowise.cli.commands.init_cmd import persistence
+
+ (tmp_path / ".repowise").mkdir(parents=True)
+ monkeypatch.setattr(persistence, "get_head_commit", lambda _p: "abc123")
+ monkeypatch.setattr(persistence, "run_async", lambda _c: 7)
+ monkeypatch.setattr(persistence, "stamp_offered_slots", lambda *a, **k: None)
+ monkeypatch.setattr(persistence, "config_fingerprint", lambda _p: "fp")
+ monkeypatch.setattr(persistence, "head_commit_ts", lambda _p: None)
+ monkeypatch.setattr(persistence, "save_config", lambda *a, **k: None)
+
+ class _Provider:
+ provider_name = "openai"
+ model_name = "gpt-5.6-luna"
+
+ class _Result:
+ generated_pages: ClassVar[list] = []
+ knowledge_graph_result = None
+ health_report = None
+
+ persistence.save_full_state_and_config(
+ repo_path=tmp_path,
+ result=_Result(),
+ provider=_Provider(),
+ phase_timings={},
+ degraded=[],
+ embedder_name_resolved="openai",
+ exclude_patterns=[],
+ commit_limit=None,
+ resolved_commit_limit=500,
+ resolved_reasoning="medium",
+ )
+
+ state = json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert "degraded" not in state
+
+
+def test_a_clean_rerun_clears_a_previous_runs_degradation(tmp_path: Path, monkeypatch) -> None:
+ """The key describes *this* run, or it is absent.
+
+ Both writers read the previous state.json back and mutate it, so only ever
+ setting the key would mark a repo degraded permanently: the re-run that
+ fixed the problem writes nothing, the stale list is re-serialised, and
+ every later ``update`` carries it forward.
+ """
+ from repowise.cli.commands.init_cmd import persistence
+
+ (tmp_path / ".repowise").mkdir(parents=True)
+ monkeypatch.setattr(persistence, "get_head_commit", lambda _p: "abc123")
+ monkeypatch.setattr(persistence, "run_async", lambda _c: 7)
+ monkeypatch.setattr(persistence, "stamp_offered_slots", lambda *a, **k: None)
+ monkeypatch.setattr(persistence, "config_fingerprint", lambda _p: "fp")
+ monkeypatch.setattr(persistence, "head_commit_ts", lambda _p: None)
+ monkeypatch.setattr(persistence, "save_config", lambda *a, **k: None)
+
+ class _Provider:
+ provider_name = "openai"
+ model_name = "gpt-5.6-luna"
+
+ class _Result:
+ generated_pages: ClassVar[list] = []
+ knowledge_graph_result = None
+ health_report = None
+
+ def _save(degraded: list[str]) -> dict:
+ persistence.save_full_state_and_config(
+ repo_path=tmp_path,
+ result=_Result(),
+ provider=_Provider(),
+ phase_timings={},
+ degraded=degraded,
+ embedder_name_resolved="openai",
+ exclude_patterns=[],
+ commit_limit=None,
+ resolved_commit_limit=500,
+ resolved_reasoning="medium",
+ )
+ return json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+
+ assert _save(["Execution flow tracing skipped (boom)"])["degraded"]
+ # The fix lands and the next run is clean.
+ assert "degraded" not in _save([])
+
+
+def test_a_key_quoted_back_by_a_provider_is_not_written_to_disk() -> None:
+ """Auth errors echo the offending key, and these messages interpolate them.
+
+ That was transient terminal output. Once the same text is persisted to
+ ``.repowise/state.json`` it is a secret at rest in the file agents read.
+ """
+ from repowise.cli.ui.progress import redact_secrets
+
+ console, _ = _non_tty_console()
+ with Progress(TextColumn("{task.description}"), console=console) as bar:
+ callback = RichProgressCallback(bar, console)
+ callback.on_message(
+ "warning",
+ "Decision extraction skipped: Incorrect API key provided: sk-abcd1234efgh5678",
+ )
+
+ assert callback.warnings == [
+ "Decision extraction skipped: Incorrect API key provided: [redacted]"
+ ]
+ # The paths and counts that make these messages useful must survive.
+ kept = redact_secrets("No parser installed for: bash (1,204 files) at /repo/.repowise/.env")
+ assert kept == "No parser installed for: bash (1,204 files) at /repo/.repowise/.env"
+
+
+ "phase_fn",
+ [
+ pytest.param("flows", id="execution-flow-tracing"),
+ pytest.param("hints", id="dynamic-edge-hints"),
+ ],
+)
+def test_a_swallowed_pipeline_failure_is_now_reported(phase_fn: str) -> None:
+ """The shape of the defect, at the two sites that most often hide it.
+
+ Both of these catch, log at ``warning``, and continue. The CLI pins
+ ``repowise.core`` to ERROR, so before this the run printed nothing and the
+ resulting wiki was quietly missing a whole class of content.
+ """
+ console, buf = _non_tty_console()
+ with Progress(TextColumn("{task.description}"), console=console) as bar:
+ callback = RichProgressCallback(bar, console)
+ if phase_fn == "flows":
+ emit_warning(callback, "Execution flow tracing skipped (boom); entry-point scores")
+ else:
+ emit_warning(callback, "Dynamic edge hints skipped (boom); framework-wired call edges")
+
+ assert "skipped (boom)" in buf.getvalue()
+ assert callback.warnings and "skipped (boom)" in callback.warnings[0]
diff --git a/tests/unit/cli/test_tool_bridge.py b/tests/unit/cli/test_tool_bridge.py
index d296000ac..1ae945fb5 100644
--- a/tests/unit/cli/test_tool_bridge.py
+++ b/tests/unit/cli/test_tool_bridge.py
@@ -189,7 +189,7 @@ def test_it_falls_back_to_an_in_memory_store_when_the_repo_has_no_lancedb(
monkeypatch.setattr(
"repowise.cli.providers.embedders.resolve_embedder_for_repo", lambda p: "mock"
)
- monkeypatch.setattr("repowise.cli.providers.embedders.build_embedder", lambda name: object())
+ monkeypatch.setattr("repowise.cli.providers.embedders.build_embedder", lambda name, _p=None: object())
import asyncio
@@ -214,7 +214,7 @@ def test_a_repo_whose_embedder_key_went_away_is_recorded_as_degraded(
"repowise.cli.providers.embedders.resolve_embedder_for_repo", lambda p: "openai"
)
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda name: KeylessEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda name, _p=None: KeylessEmbedder()
)
asyncio.run(tool_bridge._open_vector_store(tmp_path))
@@ -380,7 +380,7 @@ def test_a_repo_that_asked_for_keyless_is_not_reported_as_degraded(
"repowise.cli.providers.embedders.resolve_embedder_for_repo", lambda p: "mock"
)
monkeypatch.setattr(
- "repowise.cli.providers.embedders.build_embedder", lambda name: KeylessEmbedder()
+ "repowise.cli.providers.embedders.build_embedder", lambda name, _p=None: KeylessEmbedder()
)
asyncio.run(tool_bridge._open_vector_store(tmp_path))
diff --git a/tests/unit/ingestion/test_grammar_preflight.py b/tests/unit/ingestion/test_grammar_preflight.py
new file mode 100644
index 000000000..b680a98d4
--- /dev/null
+++ b/tests/unit/ingestion/test_grammar_preflight.py
@@ -0,0 +1,146 @@
+"""Missing grammars should be said once, in the parent, not per file per worker.
+
+Two shapes of noise sat behind the same fact. ``_build_language_registry``
+logs one line per missing language *per worker process*, and the parse pool
+spawns up to eight, so three missing grammars produced ~24 identical lines.
+``parse_file`` logged one line *per file* for a language with a config but no
+grammar, which is unbounded on a repo full of shell scripts.
+
+Both are ``log.debug``, so a default run shows neither — which is the worse
+half of the problem: an environment that cannot parse a language the repo is
+written in indexes those files with no symbols at all, and nothing says so.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+import pytest
+
+from repowise.core.ingestion.parser import missing_grammar_languages
+
+
+def test_a_language_with_an_installed_grammar_is_not_reported() -> None:
+ """Python's grammar is a hard dependency; reporting it would be crying wolf."""
+ assert missing_grammar_languages(["python"]) == []
+
+
+def test_a_language_with_no_ast_config_is_not_a_gap() -> None:
+ """Nothing claims to parse these, so there is no missing parser to report.
+
+ Reporting them would tell the user to fix an install that is already
+ correct — the same failure mode as the old "set OPENAI_API_KEY" advice.
+ """
+ assert missing_grammar_languages(["markdown", "json", "unknown", "text"]) == []
+
+
+def test_an_uninstalled_grammar_is_reported(monkeypatch: pytest.MonkeyPatch) -> None:
+ import importlib.util
+
+ real_find_spec = importlib.util.find_spec
+
+ def _pretend_python_is_missing(name: str, package: str | None = None):
+ if name == "tree_sitter_python":
+ return None
+ return real_find_spec(name, package)
+
+ monkeypatch.setattr(importlib.util, "find_spec", _pretend_python_is_missing)
+
+ assert missing_grammar_languages(["python"]) == ["python"]
+
+
+def test_the_check_does_not_import_the_grammar(monkeypatch: pytest.MonkeyPatch) -> None:
+ """The preflight runs on every index, in the parent, right before the parse
+ pool forks. Importing every tree-sitter package to answer it would spend
+ exactly the memory the pool is about to need."""
+ import builtins
+
+ imported: list[str] = []
+ real_import = builtins.__import__
+
+ def _spy(name: str, *args: object, **kwargs: object):
+ if name.startswith("tree_sitter_"):
+ imported.append(name)
+ return real_import(name, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "__import__", _spy)
+ missing_grammar_languages(["python", "go", "rust", "bash"])
+
+ assert imported == []
+
+
+def test_results_are_sorted_and_deduplicated() -> None:
+ """It renders into one sentence, so order must not depend on set iteration."""
+ result = missing_grammar_languages(["python", "python", "go"])
+ assert result == sorted(result)
+
+
+def test_a_missing_language_is_reported_through_the_progress_channel() -> None:
+ """The point of the preflight: one visible line, not 24 suppressed ones."""
+ from repowise.core.pipeline.phases.ingestion import _report_missing_grammars
+
+ class _Stats:
+ lang_counts: ClassVar[dict] = {"python": 10}
+
+ class _Progress:
+ def __init__(self) -> None:
+ self.messages: list[tuple[str, str]] = []
+
+ def on_message(self, level: str, text: str) -> None:
+ self.messages.append((level, text))
+
+ import importlib.util
+
+ real_find_spec = importlib.util.find_spec
+ progress = _Progress()
+
+ try:
+ importlib.util.find_spec = lambda name, package=None: ( # type: ignore[assignment]
+ None if name == "tree_sitter_python" else real_find_spec(name, package)
+ )
+ _report_missing_grammars(_Stats(), progress)
+ finally:
+ importlib.util.find_spec = real_find_spec # type: ignore[assignment]
+
+ assert len(progress.messages) == 1
+ level, text = progress.messages[0]
+ assert level == "warning"
+ assert "python" in text
+ # The file count is what makes it actionable rather than trivia.
+ assert "10" in text
+
+
+def test_nothing_is_said_when_every_grammar_is_present() -> None:
+ from repowise.core.pipeline.phases.ingestion import _report_missing_grammars
+
+ class _Stats:
+ lang_counts: ClassVar[dict] = {"python": 10}
+
+ class _Progress:
+ def __init__(self) -> None:
+ self.messages: list[tuple[str, str]] = []
+
+ def on_message(self, level: str, text: str) -> None:
+ self.messages.append((level, text))
+
+ progress = _Progress()
+ _report_missing_grammars(_Stats(), progress)
+
+ assert progress.messages == []
+
+
+def test_the_preflight_never_breaks_an_index() -> None:
+ """Best-effort: a reporting failure must not stop a run that was fine."""
+ from repowise.core.pipeline.phases.ingestion import _report_missing_grammars
+
+ class _Exploding:
+ @property
+ def lang_counts(self):
+ raise RuntimeError("boom")
+
+ class _Progress:
+ def on_message(self, level: str, text: str) -> None:
+ pass
+
+ _report_missing_grammars(None, _Progress())
+ _report_missing_grammars(_Exploding(), None)
diff --git a/tests/unit/pipeline/test_generation_progress_split.py b/tests/unit/pipeline/test_generation_progress_split.py
new file mode 100644
index 000000000..b7a766a68
--- /dev/null
+++ b/tests/unit/pipeline/test_generation_progress_split.py
@@ -0,0 +1,141 @@
+"""Free and paid page generation must not share one progress bar.
+
+A single bar counting 4,229 items where ~4,134 are template renders and ~95 are
+model calls reads as frozen. The cheap levels run first, so it reaches 97% in
+minutes and then crawls for another quarter of an hour with the cost figure
+sitting still at $0.009 — measured live at 4107/4229, then 4125 three minutes
+later. Nothing on screen distinguished that from a hang.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from repowise.core.pipeline.phases.generation import _FREE_PAGE_TYPES, run_generation
+
+
+class _RecordingProgress:
+ def __init__(self) -> None:
+ self.started: list[tuple[str, int | None]] = []
+ self.items: list[str] = []
+ self.done: list[str] = []
+ self.costs: list[float] = []
+
+ def on_phase_start(self, phase: str, total: int | None) -> None:
+ self.started.append((phase, total))
+
+ def on_item_done(self, phase: str) -> None:
+ self.items.append(phase)
+
+ def on_phase_done(self, phase: str) -> None:
+ self.done.append(phase)
+
+ def on_message(self, level: str, text: str) -> None:
+ pass
+
+ def set_cost(self, total_cost: float) -> None:
+ self.costs.append(total_cost)
+
+
+class _CostTracker:
+ session_cost = 0.25
+
+
+def _run(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, page_types: list[str]) -> _RecordingProgress:
+ """Drive ``run_generation``'s callbacks with a fixed sequence of page types."""
+ import asyncio
+
+ import repowise.core.generation as gen_pkg
+
+ class _FakeGenerator:
+ def __init__(self, *a: Any, **k: Any) -> None:
+ pass
+
+ async def generate_all(self, *a: Any, **kwargs: Any) -> list[Any]:
+ on_total_known = kwargs["on_total_known"]
+ on_page_done = kwargs["on_page_done"]
+ on_total_known(len(page_types))
+ for page_type in page_types:
+ on_page_done(page_type)
+ return []
+
+ monkeypatch.setattr(gen_pkg, "PageGenerator", _FakeGenerator)
+
+ progress = _RecordingProgress()
+ asyncio.run(
+ run_generation(
+ repo_path=tmp_path,
+ parsed_files=[],
+ source_map={},
+ graph_builder=None,
+ repo_structure=None,
+ git_meta_map={},
+ llm_client=None,
+ embedder=None,
+ vector_store=None,
+ concurrency=4,
+ progress=progress,
+ cost_tracker=_CostTracker(),
+ )
+ )
+ return progress
+
+
+def test_free_page_types_are_the_ones_that_cost_nothing() -> None:
+ """The predicate the split turns on, stated explicitly.
+
+ These render from a Jinja template with no provider call. If a type ever
+ moves tier, this is the assertion that should fail first.
+ """
+ assert {"file_page", "symbol_spotlight", "api_contract", "scc_page"} <= _FREE_PAGE_TYPES
+ assert "module_page" not in _FREE_PAGE_TYPES
+ assert "repo_overview" not in _FREE_PAGE_TYPES
+ assert "onboarding" not in _FREE_PAGE_TYPES
+
+
+def test_paid_pages_get_their_own_counter(monkeypatch, tmp_path: Path) -> None:
+ progress = _run(monkeypatch, tmp_path, ["file_page"] * 5 + ["module_page"] * 3)
+
+ # The free pages must not appear on the paid counter...
+ assert progress.items.count("generation.llm") == 3
+ # ...and the paid counter must not be announced before the first paid page,
+ # or it sits at 0 on screen through the entire free stretch.
+ assert ("generation.llm", None) in progress.started
+ assert progress.started.index(("generation.llm", None)) > 0
+
+
+def test_a_run_with_no_paid_pages_shows_no_paid_counter(monkeypatch, tmp_path: Path) -> None:
+ """``--no-prose`` renders everything from templates. A paid bar stuck at 0
+ would be an unanswered question, not an answer."""
+ progress = _run(monkeypatch, tmp_path, ["file_page"] * 4)
+
+ assert "generation.llm" not in [phase for phase, _ in progress.started]
+ assert "generation.llm" not in progress.items
+
+
+def test_every_page_still_advances_the_overall_bar(monkeypatch, tmp_path: Path) -> None:
+ """The overall total counts onboarding, so the overall bar must too.
+
+ It previously routed onboarding pages *only* to the onboarding task while
+ ``_announce_total`` counted them into the overall total, so that bar could
+ never reach its own denominator — ``on_phase_done`` forcing it to 100% at
+ the end is what hid the arithmetic.
+ """
+ page_types = ["file_page", "module_page", "onboarding", "onboarding"]
+ progress = _run(monkeypatch, tmp_path, page_types)
+
+ announced = dict(progress.started)["generation"]
+ assert announced == len(page_types)
+ assert progress.items.count("generation") == len(page_types)
+ # Onboarding keeps its own named step as well.
+ assert progress.items.count("onboarding") == 2
+
+
+def test_cost_is_pushed_on_every_page(monkeypatch, tmp_path: Path) -> None:
+ """The figure freezing between completions is half of why it looked hung."""
+ progress = _run(monkeypatch, tmp_path, ["file_page", "module_page"])
+
+ assert progress.costs == [0.25, 0.25]
diff --git a/tests/unit/pipeline/test_resume.py b/tests/unit/pipeline/test_resume.py
index e9e5e6afa..20c7d1439 100644
--- a/tests/unit/pipeline/test_resume.py
+++ b/tests/unit/pipeline/test_resume.py
@@ -223,3 +223,77 @@ async def test_rehydrate_analysis_returns_empty_views_when_none_persisted(sf):
dead_code_report, decision_report = await ctrl.rehydrate_analysis()
assert dead_code_report.findings == []
assert decision_report.decisions == []
+
+
+# ---------------------------------------------------------------------------
+# A failed checkpoint must be audible
+# ---------------------------------------------------------------------------
+
+
+class _RecordingProgress:
+ def __init__(self) -> None:
+ self.messages: list[tuple[str, str]] = []
+
+ def on_message(self, level: str, text: str) -> None:
+ self.messages.append((level, text))
+
+
+async def test_a_failed_index_checkpoint_is_reported(sf, monkeypatch):
+ """The CLI promises "indexed work so far has been saved — run --resume".
+
+ When this write fails that promise is false. It was reported only through
+ ``logger.warning``, which the CLI pins to ERROR, so the user found out by
+ paying for the whole index a second time.
+ """
+ repo_id = await _make_repo(sf)
+
+ def _boom(*_a: object, **_k: object):
+ raise RuntimeError("database is locked")
+
+ monkeypatch.setattr(
+ "repowise.core.pipeline.resume.controller.persist_ingestion", _boom
+ )
+
+ progress = _RecordingProgress()
+ ctrl = ResumeController(sf, repo_id, resume=False)
+ await ctrl.checkpoint_index(
+ parsed_files=[],
+ graph_builder=None,
+ git_metadata_list=[],
+ progress=progress,
+ )
+
+ assert progress.messages, "a failed checkpoint said nothing"
+ level, text = progress.messages[0]
+ assert level == "warning"
+ assert "database is locked" in text
+ # And it must not claim the index is on disk when it is not.
+ assert await ctrl.can_skip(ResumePhase.INDEX) is False
+
+
+async def test_a_successful_checkpoint_says_nothing(sf, monkeypatch):
+ """Only failures are worth a line; a clean run must stay quiet.
+
+ The persisters are stubbed to succeed rather than fed a real graph: what
+ is under test is that the reporting sits on the failure path only, not
+ what ``persist_ingestion`` writes.
+ """
+ repo_id = await _make_repo(sf)
+
+ async def _ok(*_a: object, **_k: object) -> None:
+ return None
+
+ monkeypatch.setattr("repowise.core.pipeline.resume.controller.persist_ingestion", _ok)
+ monkeypatch.setattr("repowise.core.pipeline.resume.controller.persist_git", _ok)
+
+ progress = _RecordingProgress()
+
+ ctrl = ResumeController(sf, repo_id, resume=False)
+ await ctrl.checkpoint_index(
+ parsed_files=[],
+ graph_builder=None,
+ git_metadata_list=[],
+ progress=progress,
+ )
+
+ assert progress.messages == []