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(server): take the update lock in background syncs and never overwrite newer health rows (#4756)

Raghav Chamadiya796b892ae9ef
diff --git a/packages/server/src/repowise/server/job_executor.py b/packages/server/src/repowise/server/job_executor.py
index 43d19f4cf..b6570999a 100644
--- a/packages/server/src/repowise/server/job_executor.py
+++ b/packages/server/src/repowise/server/job_executor.py
@@ -32,6 +32,7 @@ from repowise.core.persistence.crud import (
from repowise.core.persistence.database import get_session, refresh_planner_stats
from repowise.core.pipeline import persist_pipeline_result, run_pipeline
from repowise.core.pipeline.modes import OrchestratorMode
+from repowise.core.update_lock import release_update_lock, try_acquire_update_lock
from repowise.server.job_events import JobEventBuffer, create_event_buffer
# The ``noqa: F401`` names live in the sibling job modules and are re-exported
@@ -57,7 +58,9 @@ from repowise.server.job_records import (
from repowise.server.job_state import (
_load_state, # noqa: F401
_persist_initial_index_state,
+ _read_head_sha,
_stamp_last_sync_commit,
+ newer_health_analyzer,
)
from repowise.server.services.areas import warm_area_model
from repowise.server.services.coupling import warm_coupling_model
@@ -527,12 +530,54 @@ async def _run_scoped_generation(run: _JobRun) -> None:
)
+def _refuse_older_analyzer(repo_path: Path) -> None:
+ """Fail the job before it writes health rows older than the stored ones."""
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+
+ stored = newer_health_analyzer(repo_path)
+ if stored is not None:
+ raise RuntimeError(
+ f"The index holds health scores from analyzer version {stored}, newer "
+ f"than this server's {HEALTH_ANALYZER_VERSION}. Restart `repowise serve` "
+ "to load the upgraded package."
+ )
+
+
async def _run_index_job(run: _JobRun, app_state: Any) -> None:
+ """Index under the CLI's update lock, so the two never write one index at once."""
+ repo_path = Path(run.spec.repo_path)
+ head = await asyncio.to_thread(_read_head_sha, repo_path)
+ # Acquired and released without an await, so a cancel cannot leak the lock.
+ owner = try_acquire_update_lock(repo_path, head)
+ if owner is not None:
+ # The holder's run advances the baseline; nothing failed here.
+ await _finalize_job_status(
+ app_state,
+ run.session_factory,
+ run.progress,
+ run.spec.job_id,
+ status="cancelled",
+ error_message=(
+ f"Another repowise update or sync (pid {owner.get('pid')}) is "
+ "running on this repository, so this job did not run."
+ ),
+ )
+ return
+ try:
+ await asyncio.to_thread(_refuse_older_analyzer, repo_path)
+ await _run_locked_index_job(run, app_state)
+ finally:
+ release_update_lock(repo_path)
+
+
+async def _run_locked_index_job(run: _JobRun, app_state: Any) -> None:
"""Index the repository, persist everything, and record the outcome."""
spec = run.spec
docs = _DocsPlan.for_job(spec, run.llm_client)
result = await _run_index_pipeline(run, docs)
incremental_pages = await _sync_incremental_pages(run, result)
+ # A CLI init does not take the update lock; check again right before writing.
+ await asyncio.to_thread(_refuse_older_analyzer, Path(spec.repo_path))
swept_page_ids = await _persist_index_result(run, result, incremental_pages)
all_pages = (result.generated_pages or []) + incremental_pages
@@ -544,7 +589,12 @@ async def _run_index_job(run: _JobRun, app_state: Any) -> None:
elapsed = time.monotonic() - run.start
pages_generated = await _record_index_completion(run, result, all_pages, elapsed)
- await _write_index_state(run, docs, total_pages=len(all_pages))
+ await _write_index_state(
+ run,
+ docs,
+ total_pages=len(all_pages),
+ health_rescored=getattr(result, "health_report", None) is not None,
+ )
await _reload_cross_repo_enricher(app_state, spec.job_id)
# The area rollup and the coupling fold are read on the first dashboard
# load after an index; fold them here, in the job's own task, instead.
@@ -711,11 +761,14 @@ async def _record_index_completion(
return pages_generated
-async def _write_index_state(run: _JobRun, docs: _DocsPlan, *, total_pages: int) -> None:
+async def _write_index_state(
+ run: _JobRun, docs: _DocsPlan, *, total_pages: int, health_rescored: bool = False
+) -> None:
"""Update state.json so CLI incremental updates know the new baseline.
An initial index also persists the full baseline (docs flags, run
- mode, config) that `repowise init` would have written.
+ mode, config) that `repowise init` would have written. A run that
+ rescored health stamps the analyzer version its rows came from.
"""
spec = run.spec
try:
@@ -729,9 +782,12 @@ async def _write_index_state(run: _JobRun, docs: _DocsPlan, *, total_pages: int)
total_pages=total_pages,
wiki_style=spec.wiki_style,
exclude_patterns=spec.exclude_patterns,
+ health_rescored=health_rescored,
)
else:
- await asyncio.to_thread(_stamp_last_sync_commit, Path(spec.repo_path))
+ await asyncio.to_thread(
+ _stamp_last_sync_commit, Path(spec.repo_path), health_rescored=health_rescored
+ )
except Exception:
logger.debug("state_json_update_failed", job_id=spec.job_id, exc_info=True)
diff --git a/packages/server/src/repowise/server/job_state.py b/packages/server/src/repowise/server/job_state.py
index a07616c21..9987829a8 100644
--- a/packages/server/src/repowise/server/job_state.py
+++ b/packages/server/src/repowise/server/job_state.py
@@ -52,16 +52,39 @@ def _save_state(repo_path: Path, state: dict) -> None:
restamp_changed_sync_commit(repo_path, previous, state.get("last_sync_commit"))
-def _stamp_last_sync_commit(repo_path: Path) -> None:
+def _stamp_last_sync_commit(repo_path: Path, *, health_rescored: bool = False) -> None:
"""Record the synced HEAD so CLI incremental updates know the baseline."""
head = _read_head_sha(repo_path)
if not head:
return
state = _load_state(repo_path)
state["last_sync_commit"] = head
+ if health_rescored:
+ _stamp_health_analyzer(state)
_save_state(repo_path, state)
+def _stamp_health_analyzer(state: dict) -> None:
+ """Label the health rows a full index just wrote with this process's analyzer."""
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+
+ state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
+
+
+def newer_health_analyzer(repo_path: Path) -> int | None:
+ """The stored ``health_analyzer_version`` when it is newer than this process's.
+
+ A server started before an upgrade still runs the old analyzer; its rows
+ must not replace the ones a newer CLI already wrote.
+ """
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+
+ stored = _load_state(repo_path).get("health_analyzer_version")
+ if isinstance(stored, int) and stored > HEALTH_ANALYZER_VERSION:
+ return stored
+ return None
+
+
def _persist_initial_index_state(
repo_path: Path,
*,
@@ -71,6 +94,7 @@ def _persist_initial_index_state(
total_pages: int,
wiki_style: str,
exclude_patterns: list[str],
+ health_rescored: bool = False,
) -> None:
"""Write the ``repowise init`` baseline after a first API-driven index.
@@ -109,6 +133,8 @@ def _persist_initial_index_state(
state["provider"] = getattr(llm_client, "provider_name", "")
state["model"] = getattr(llm_client, "model_name", "")
_stamp_store_format(state, repo_path)
+ if health_rescored:
+ _stamp_health_analyzer(state)
state["config_fingerprint"] = config_fingerprint(repo_path)
_save_state(repo_path, state)
diff --git a/packages/server/src/repowise/server/scheduler.py b/packages/server/src/repowise/server/scheduler.py
index 9afc829a7..64efe8c8e 100644
--- a/packages/server/src/repowise/server/scheduler.py
+++ b/packages/server/src/repowise/server/scheduler.py
@@ -9,11 +9,14 @@ from __future__ import annotations
import asyncio
import logging
+from pathlib import Path
from typing import TYPE_CHECKING, Any
from apscheduler.schedulers.asyncio import AsyncIOScheduler
from apscheduler.triggers.interval import IntervalTrigger
+from repowise.core.update_lock import read_update_lock
+
if TYPE_CHECKING:
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -28,7 +31,6 @@ def _inspect_repository(repo_path: str) -> tuple[str | None, str] | None:
"""
import json
import subprocess
- from pathlib import Path
state_path = Path(repo_path) / ".repowise" / "state.json"
stored_commit = None
@@ -138,6 +140,10 @@ def setup_scheduler(
if stored_commit and current_head == stored_commit:
continue
+ # A running `repowise update` will advance the baseline itself.
+ if await asyncio.to_thread(read_update_lock, Path(repo.local_path)):
+ continue
+
# Check no active job already
active = await session.execute(
select(GenerationJob.id)
diff --git a/tests/unit/server/test_job_executor.py b/tests/unit/server/test_job_executor.py
index 97c8f3a46..eaa356416 100644
--- a/tests/unit/server/test_job_executor.py
+++ b/tests/unit/server/test_job_executor.py
@@ -824,3 +824,179 @@ async def test_update_job_status_without_total_pages_preserves_existing_value(
job = await get_generation_job(session, job_id)
assert job.total_pages == 5
assert job.completed_pages == 250
+
+
+# ---------------------------------------------------------------------------
+# Update lock and analyzer stamp: a server job never overwrites newer health
+# ---------------------------------------------------------------------------
+
+
+def _write_state(repo_path: Path, state: dict) -> None:
+ import json
+
+ path = repo_path / ".repowise" / "state.json"
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps(state), encoding="utf-8")
+
+
+async def _job_row(session_factory, job_id: str):
+ async with session_factory() as session:
+ return await get_generation_job(session, job_id)
+
+
+async def test_sync_job_holds_the_update_lock_and_stamps_its_analyzer(session_factory, tmp_path):
+ import json
+
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+ from repowise.core.update_lock import read_update_lock
+
+ _write_state(tmp_path, {"last_sync_commit": "old", "health_analyzer_version": 1})
+ job_id = await _seed_job_with_config(session_factory, tmp_path, {"mode": "sync"})
+ app_state = SimpleNamespace(session_factory=session_factory, fts=None, vector_store=None)
+
+ held_during_run: list = []
+
+ async def pipeline(*_a, **_k):
+ held_during_run.append(read_update_lock(tmp_path))
+ return SimpleNamespace(**vars(_fake_result()), health_report=object())
+
+ with (
+ patch("repowise.server.job_executor.run_pipeline", side_effect=pipeline),
+ patch("repowise.server.job_executor.persist_pipeline_result", AsyncMock()),
+ patch("repowise.server.job_state._read_head_sha", return_value="new"),
+ _no_provider(),
+ ):
+ await execute_job(job_id, app_state)
+
+ assert (await _job_row(session_factory, job_id)).status == "completed"
+ assert held_during_run[0] is not None
+ assert read_update_lock(tmp_path) is None
+ state = json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert state["health_analyzer_version"] == HEALTH_ANALYZER_VERSION
+ assert state["last_sync_commit"] == "new"
+
+
+async def test_sync_job_does_not_run_while_a_cli_update_holds_the_lock(session_factory, tmp_path):
+ from repowise.core.update_lock import (
+ read_update_lock,
+ release_update_lock,
+ try_acquire_update_lock,
+ )
+
+ job_id = await _seed_job_with_config(session_factory, tmp_path, {"mode": "sync"})
+ app_state = SimpleNamespace(session_factory=session_factory, fts=None, vector_store=None)
+ assert try_acquire_update_lock(tmp_path, "cli-target") is None
+ run_pipeline_mock = AsyncMock(return_value=_fake_result())
+ try:
+ with (
+ patch("repowise.server.job_executor.run_pipeline", run_pipeline_mock),
+ patch("repowise.server.job_executor.persist_pipeline_result", AsyncMock()),
+ _no_provider(),
+ ):
+ await execute_job(job_id, app_state)
+ # The CLI's lock is left in place for its owner.
+ assert read_update_lock(tmp_path)["target_commit"] == "cli-target"
+ finally:
+ release_update_lock(tmp_path)
+
+ run_pipeline_mock.assert_not_called()
+ job = await _job_row(session_factory, job_id)
+ assert job.status == "cancelled"
+ assert "Another repowise update" in job.error_message
+
+
+async def test_older_server_never_overwrites_newer_health_rows(session_factory, tmp_path):
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+ from repowise.core.update_lock import read_update_lock
+
+ _write_state(tmp_path, {"health_analyzer_version": HEALTH_ANALYZER_VERSION + 1})
+ job_id = await _seed_job_with_config(session_factory, tmp_path, {"mode": "sync"})
+ app_state = SimpleNamespace(session_factory=session_factory, fts=None, vector_store=None)
+ run_pipeline_mock = AsyncMock(return_value=_fake_result())
+ persist = AsyncMock()
+ with (
+ patch("repowise.server.job_executor.run_pipeline", run_pipeline_mock),
+ patch("repowise.server.job_executor.persist_pipeline_result", persist),
+ _no_provider(),
+ ):
+ await execute_job(job_id, app_state)
+
+ run_pipeline_mock.assert_not_called()
+ persist.assert_not_called()
+ job = await _job_row(session_factory, job_id)
+ assert job.status == "failed"
+ assert f"analyzer version {HEALTH_ANALYZER_VERSION + 1}" in job.error_message
+ assert read_update_lock(tmp_path) is None
+
+
+async def test_newer_stamp_written_during_the_run_blocks_the_persist(session_factory, tmp_path):
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+
+ job_id = await _seed_job_with_config(session_factory, tmp_path, {"mode": "full_resync"})
+ app_state = SimpleNamespace(session_factory=session_factory, fts=None, vector_store=None)
+
+ async def pipeline(*_a, **_k):
+ _write_state(tmp_path, {"health_analyzer_version": HEALTH_ANALYZER_VERSION + 1})
+ return _fake_result()
+
+ persist = AsyncMock()
+ with (
+ patch("repowise.server.job_executor.run_pipeline", side_effect=pipeline),
+ patch("repowise.server.job_executor.persist_pipeline_result", persist),
+ _no_provider(),
+ ):
+ await execute_job(job_id, app_state)
+
+ persist.assert_not_called()
+ assert (await _job_row(session_factory, job_id)).status == "failed"
+
+
+async def test_cancelled_sync_job_releases_the_update_lock(session_factory, tmp_path):
+ import asyncio
+
+ from repowise.core.update_lock import read_update_lock
+
+ job_id = await _seed_job_with_config(session_factory, tmp_path, {"mode": "sync"})
+ app_state = SimpleNamespace(session_factory=session_factory, fts=None, vector_store=None)
+ started = asyncio.Event()
+
+ async def pipeline(*_a, **_k):
+ started.set()
+ await asyncio.sleep(60)
+
+ with (
+ patch("repowise.server.job_executor.run_pipeline", side_effect=pipeline),
+ _no_provider(),
+ ):
+ task = asyncio.create_task(execute_job(job_id, app_state))
+ await asyncio.wait_for(started.wait(), 30)
+ assert read_update_lock(tmp_path) is not None
+ task.cancel()
+ await task
+
+ assert read_update_lock(tmp_path) is None
+ assert (await _job_row(session_factory, job_id)).status == "cancelled"
+
+
+async def test_sync_job_without_a_health_report_keeps_the_stored_stamp(session_factory, tmp_path):
+ import json
+
+ _write_state(tmp_path, {"health_analyzer_version": 1})
+ job_id = await _seed_job_with_config(session_factory, tmp_path, {"mode": "sync"})
+ app_state = SimpleNamespace(session_factory=session_factory, fts=None, vector_store=None)
+ with (
+ patch("repowise.server.job_executor.run_pipeline", AsyncMock(return_value=_fake_result())),
+ patch("repowise.server.job_executor.persist_pipeline_result", AsyncMock()),
+ patch("repowise.server.job_state._read_head_sha", return_value="new"),
+ _no_provider(),
+ ):
+ await execute_job(job_id, app_state)
+
+ state = json.loads((tmp_path / ".repowise" / "state.json").read_text(encoding="utf-8"))
+ assert state["health_analyzer_version"] == 1
diff --git a/tests/unit/server/test_scheduler.py b/tests/unit/server/test_scheduler.py
index 676099e50..eff086fcd 100644
--- a/tests/unit/server/test_scheduler.py
+++ b/tests/unit/server/test_scheduler.py
@@ -138,3 +138,33 @@ async def test_polling_fallback_offloads_repository_inspection(session_factory,
await polling_job.func()
to_thread.assert_awaited_once_with(_inspect_repository, str(tmp_path))
+
+
+async def test_polling_fallback_skips_a_repo_while_an_update_holds_its_lock(
+ session_factory, tmp_path
+) -> None:
+ """A running `repowise update` advances the baseline; no sync job races it."""
+ from repowise.core.update_lock import release_update_lock, try_acquire_update_lock
+
+ state_path = tmp_path / ".repowise" / "state.json"
+ state_path.parent.mkdir(parents=True)
+ state_path.write_text(json.dumps({"last_sync_commit": "old-sha"}), encoding="utf-8")
+ async with get_session(session_factory) as session:
+ repo = await crud.upsert_repository(session, name="test-repo", local_path=str(tmp_path))
+ repo_id = repo.id
+
+ scheduler = setup_scheduler(session_factory, app_state=SimpleNamespace(background_tasks=set()))
+ polling_job = next(job for job in scheduler.get_jobs() if job.id == "polling_fallback")
+ head_result = SimpleNamespace(returncode=0, stdout="new-sha\n")
+ assert try_acquire_update_lock(tmp_path, "new-sha") is None
+ try:
+ with patch("subprocess.run", return_value=head_result):
+ await polling_job.func()
+ finally:
+ release_update_lock(tmp_path)
+
+ async with get_session(session_factory) as session:
+ result = await session.execute(
+ select(GenerationJob).where(GenerationJob.repository_id == repo_id)
+ )
+ assert result.scalars().all() == []