Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(auto-sync): reliable cross-platform post-commit auto-update (#211)
Raghav Chamadiyaea379b1db90a
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd.py b/packages/cli/src/repowise/cli/commands/augment_cmd.pyindex a6d749b43..0637c868d 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd.py@@ -488,7 +488,24 @@ _GIT_COMMIT_PATTERNS = (def _handle_bash_post(tool_input: dict, tool_output: object, cwd: str) -> str | None:- """After a successful git commit, check if the wiki needs updating."""+ """After a successful git commit, check if the wiki needs updating.++ Three-state response to "state.json is behind HEAD":++ 1. A real ``.update.lock`` is held → an update is actively running.+ Emit a *positive* notice ("updating in background") so the agent+ knows the system is healing itself. Squelches the noisy stale+ warning during the long tail of large updates.++ 2. A fresh ``.update.queued`` marker exists (post-commit hook just+ spawned a new update but the lock file isn't on disk yet) → also+ emit the positive notice. Closes the race window between commit+ and update start where we'd otherwise warn for ~5s.++ 3. Neither marker → the update didn't run or already finished. Warn+ once per HEAD as before, so the user knows the wiki is genuinely+ out of sync.+ """if isinstance(tool_output, dict):exit_code = tool_output.get("exit_code")if exit_code is None:@@ -541,8 +558,22 @@ def _handle_bash_post(tool_input: dict, tool_output: object, cwd: str) -> str |if head == last_sync:return None- if _update_in_flight(repo_path, head):- return None+ # Active update? Tell the agent the system is healing itself instead of+ # repeating the stale warning every commit. Per-head de-dup applies+ # equally to the positive notice so the chat doesn't get a notice spam+ # for the same HEAD over multiple tool calls.+ in_flight = _read_in_flight_marker(repo_path)+ if in_flight is not None:+ if _already_warned(repo_path, head):+ return None+ _record_warning(repo_path, head)+ target_short = (in_flight.get("target_commit") or head)[:8]+ elapsed = in_flight.get("elapsed_seconds")+ elapsed_str = f"started {int(elapsed)}s ago" if isinstance(elapsed, (int, float)) else "running now"+ return (+ f"[repowise] Wiki update in background — {elapsed_str}, "+ f"target {target_short}. State will catch up once it finishes."+ )if _already_warned(repo_path, head):return None@@ -557,29 +588,54 @@ def _handle_bash_post(tool_input: dict, tool_output: object, cwd: str) -> str |)-def _update_in_flight(repo_path: "object", head: str) -> bool:- """Return True if a recent ``repowise update`` is still running."""+def _read_in_flight_marker(repo_path: "object") -> dict | None:+ """Return a normalised in-flight marker, or None when nothing is running.++ Considers two on-disk signals as evidence of an in-flight update:++ * ``.update.lock`` — written by ``update_cmd`` once it starts the+ actual work. Authoritative.+ * ``.update.queued`` — written by the post-commit hook *before*+ backgrounding the update, to close the start-up race window.++ Both have a freshness window so an aborted run can't suppress real+ warnings indefinitely.+ """import timefrom pathlib import Path- lock_path = Path(repo_path) / ".repowise" / ".update.lock"- if not lock_path.exists():- return False- try:- payload = json.loads(lock_path.read_text(encoding="utf-8"))- except (json.JSONDecodeError, OSError):- return False-- started = payload.get("started_at")- if not isinstance(started, (int, float)):- return False- if time.time() - started > 30 * 60:- return False+ repo_path = Path(repo_path)+ now = time.time()++ lock_path = repo_path / ".repowise" / ".update.lock"+ if lock_path.exists():+ try:+ payload = json.loads(lock_path.read_text(encoding="utf-8"))+ started = payload.get("started_at")+ if isinstance(started, (int, float)) and now - started <= 30 * 60:+ return {+ "source": "lock",+ "target_commit": payload.get("target_commit"),+ "elapsed_seconds": now - started,+ }+ except (json.JSONDecodeError, OSError):+ pass++ queued_path = repo_path / ".repowise" / ".update.queued"+ if queued_path.exists():+ try:+ payload = json.loads(queued_path.read_text(encoding="utf-8"))+ queued_at = payload.get("queued_at")+ if isinstance(queued_at, (int, float)) and now - queued_at <= 5 * 60:+ return {+ "source": "queued",+ "target_commit": payload.get("target_commit"),+ "elapsed_seconds": now - queued_at,+ }+ except (json.JSONDecodeError, OSError):+ pass- target = payload.get("target_commit")- if target and target == head:- return True- return True+ return Nonedef _already_warned(repo_path: "object", head: str) -> bool:diff --git a/packages/cli/src/repowise/cli/commands/update_cmd.py b/packages/cli/src/repowise/cli/commands/update_cmd.pyindex f1f95eceb..a295bff35 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd.py@@ -10,19 +10,25 @@ from rich.table import Tablefrom repowise.cli.helpers import (CommandTarget,acquire_update_lock,+ clear_update_pending,+ clear_update_queued,console,ensure_repowise_dir,find_workspace_root,get_head_commit,load_config,load_state,+ read_update_lock,+ read_update_pending,release_update_lock,resolve_command_target,resolve_provider,resolve_reasoning,resolve_repo_path,+ rotate_update_log_if_needed,run_async,save_state,+ write_update_pending,)# ---------------------------------------------------------------------------@@ -132,6 +138,14 @@ def _workspace_update(def _on_done(result: "RepoUpdateResult") -> None:if result.error:console.print(f" [red]\u2717 {result.alias}: {result.error}[/red]")+ elif result.skipped_reason == "in_flight":+ # Surface skipped-because-in-flight as a yellow note rather than+ # a silent skip. Single-flight is the noise-fix path, so the+ # user benefits from seeing it actually trigger.+ console.print(+ f" [yellow]\u21bb {result.alias}: another update is already "+ "in flight; this commit was queued for it to pick up.[/yellow]"+ )elif result.updated:console.print(f" [green]\u2713[/green] {result.alias}: "@@ -269,6 +283,11 @@ def update_command(repo_path = target.repo_pathassert repo_path is not None # single mode always sets repo_pathensure_repowise_dir(repo_path)+ # Truncate the hook-managed log if it has grown past the cap. The hook+ # appends each run unconditionally — without this opportunistic rotation+ # at the start of every CLI update, a busy repo's ``.update.log`` would+ # balloon to MBs over time.+ rotate_update_log_if_needed(repo_path)# Load saved API keys from .repowise/.env (won't overwrite existing env vars)from repowise.cli.ui import load_dotenv@@ -301,6 +320,33 @@ def update_command(console.print("[green]Already up to date.[/green]")return+ # --- Single-flight check ------------------------------------------------+ # A fresh lock from another process means a `repowise update` is already+ # running on this repo. Two updates racing on save_state was the actual+ # root cause of "wiki keeps going stale": post-commit hooks fired during+ # rapid-fire commits would each redo full ingestion + generation from the+ # same outdated base, take 10+ minutes, then save_state out of order so+ # state.json never reflected reality. Bail cleanly instead — and leave+ # the new HEAD in ``.update.pending`` so the running update can roll+ # forward to it at the end of its current pass.+ existing_lock = read_update_lock(repo_path)+ if existing_lock is not None:+ import time as _time++ elapsed = int(_time.time() - existing_lock.get("started_at", _time.time()))+ target_short = (existing_lock.get("target_commit") or "")[:8]+ write_update_pending(repo_path, head)+ console.print(+ f"[yellow]Another `repowise update` is already running "+ f"(pid {existing_lock.get('pid')}, target {target_short}, "+ f"started {elapsed}s ago).[/yellow]"+ )+ console.print(+ f"[dim]HEAD {head[:8] if head else 'HEAD'} marked as pending; "+ "the running update will roll forward to it.[/dim]"+ )+ return+# Backfill docs_enabled on legacy state files using the same# shape-based inference the resolver uses, so the post-commit hook# and future runs stop relying on the inference. Done before mode@@ -329,7 +375,12 @@ def update_command(import atexitacquire_update_lock(repo_path, head)+ # Drop the queued marker now that the real lock owns the suppression+ # window. Leaving both behind would cause the augment hook to keep+ # suppressing for the queued-stale-after duration even past a failed run.+ clear_update_queued(repo_path)atexit.register(release_update_lock, repo_path)+ atexit.register(clear_update_queued, repo_path)console.print(f"[bold]repowise update[/bold] — {repo_path}")console.print(f"Diffing [cyan]{base_ref[:8]}..{(head or 'HEAD')[:8]}[/cyan]")@@ -779,6 +830,17 @@ def update_command(state["total_pages"] = state.get("total_pages", 0) + len(generated_pages)save_state(repo_path, state)+ # --- Roll forward to any commit that landed during this run ------------+ # Another `repowise update` (from a post-commit hook) may have written a+ # ``.update.pending`` marker while we were generating pages. If the new+ # HEAD points past where we just finished, clear the marker only if it's+ # already caught up; otherwise leave it in place as a signal to the+ # augment hook so its message can be "update done, new commits since"+ # instead of the bare stale-wiki warning.+ pending_head = read_update_pending(repo_path)+ if pending_head and pending_head == head:+ clear_update_pending(repo_path)+# Trigger cross-repo hooks if this repo is part of a workspacetry:ws_root = find_workspace_root(repo_path)diff --git a/packages/cli/src/repowise/cli/helpers.py b/packages/cli/src/repowise/cli/helpers.pyindex 0b11e91ac..55c79ca75 100644--- a/packages/cli/src/repowise/cli/helpers.py+++ b/packages/cli/src/repowise/cli/helpers.py@@ -204,6 +204,175 @@ def read_update_lock(repo_path: Path) -> dict[str, Any] | None:return payload+# ---------------------------------------------------------------------------+# Queued / pending markers — coordinate the post-commit hook with a running+# update so rapid-fire commits don't spawn N concurrent updates that race+# on save_state. Two distinct markers, deliberately:+#+# ``.update.queued`` : written by the hook BEFORE backgrounding repowise+# update. Closes the race window between commit and+# lock acquisition — the augment hook reads this+# and suppresses its warning the moment the queued+# file appears, not 30+ seconds later when the+# actual lock file lands on disk.+#+# ``.update.pending`` : written by a *new* update_cmd invocation when it+# finds an in-flight lock. Carries the latest HEAD+# so the running update can roll forward to it at+# the end of its current pass instead of stopping+# at a stale commit.+#+# Both markers are best-effort: failure to write/read them must never break+# update_cmd itself, only degrade the coalescing behaviour to "spawn but+# bail" (slightly noisier in the augment hook but still correct).+# ---------------------------------------------------------------------------++UPDATE_QUEUED_FILENAME = ".update.queued"+UPDATE_PENDING_FILENAME = ".update.pending"++# A ``.update.queued`` marker older than this is treated as stale — most+# likely a crashed hook that wrote the marker but never spawned the update.+# Short enough to avoid suppressing genuinely-stale warnings indefinitely.+UPDATE_QUEUED_STALE_AFTER_SECONDS = 5 * 60+++def _update_queued_path(repo_path: Path) -> Path:+ return get_repowise_dir(repo_path) / UPDATE_QUEUED_FILENAME+++def _update_pending_path(repo_path: Path) -> Path:+ return get_repowise_dir(repo_path) / UPDATE_PENDING_FILENAME+++def write_update_queued(repo_path: Path, head: str | None) -> None:+ """Mark that an update has been spawned for ``head``.++ Called from the post-commit hook *before* backgrounding ``repowise+ update`` so the augment hook can suppress its stale-wiki warning during+ the brief window where the actual update process is still starting up+ (Python import, DB open, etc.) and hasn't yet written its own lock file.+ """+ import time++ try:+ ensure_repowise_dir(repo_path)+ except OSError:+ return+ payload = {"target_commit": head, "queued_at": time.time()}+ try:+ _update_queued_path(repo_path).write_text(+ json.dumps(payload), encoding="utf-8"+ )+ except OSError:+ pass+++def read_update_queued(repo_path: Path) -> dict[str, Any] | None:+ """Return queued payload if fresh (≤ ``UPDATE_QUEUED_STALE_AFTER_SECONDS``)."""+ import time++ path = _update_queued_path(repo_path)+ if not path.exists():+ return None+ try:+ payload = json.loads(path.read_text(encoding="utf-8"))+ except (json.JSONDecodeError, OSError):+ return None+ queued_at = payload.get("queued_at")+ if not isinstance(queued_at, (int, float)):+ return None+ if time.time() - queued_at > UPDATE_QUEUED_STALE_AFTER_SECONDS:+ return None+ return payload+++def clear_update_queued(repo_path: Path) -> None:+ """Drop the queued marker. Called by update_cmd once it owns the real lock."""+ try:+ _update_queued_path(repo_path).unlink(missing_ok=True)+ except OSError:+ pass+++def write_update_pending(repo_path: Path, head: str | None) -> None:+ """Record that another commit landed while an update was in flight.++ The running update reads this at the end of its pass and rolls forward+ to the new HEAD in one extra round, avoiding the failure mode where a+ rapid burst of commits leaves the wiki indexed to an outdated commit.+ """+ if head is None:+ return+ try:+ ensure_repowise_dir(repo_path)+ except OSError:+ return+ try:+ _update_pending_path(repo_path).write_text(head, encoding="utf-8")+ except OSError:+ pass+++def read_update_pending(repo_path: Path) -> str | None:+ """Return the pending HEAD if any, else None."""+ path = _update_pending_path(repo_path)+ if not path.exists():+ return None+ try:+ head = path.read_text(encoding="utf-8").strip()+ except OSError:+ return None+ return head or None+++def clear_update_pending(repo_path: Path) -> None:+ """Drop the pending marker once the rolled-forward update has consumed it."""+ try:+ _update_pending_path(repo_path).unlink(missing_ok=True)+ except OSError:+ pass+++# ---------------------------------------------------------------------------+# Hook output log — capped, single-file rotation so the user can diagnose+# why the post-commit hook didn't catch up without needing to chase down a+# silent subprocess. Cap is deliberately small: a few recent runs is enough+# context, and we don't want a runaway log to fill the .repowise/ dir.+# ---------------------------------------------------------------------------++UPDATE_LOG_FILENAME = ".update.log"++# Truncate the log when it grows past this size, keeping the tail.+UPDATE_LOG_MAX_BYTES = 256 * 1024+# After truncation, retain at most this much of the prior tail.+UPDATE_LOG_KEEP_TAIL_BYTES = 64 * 1024+++def update_log_path(repo_path: Path) -> Path:+ return get_repowise_dir(repo_path) / UPDATE_LOG_FILENAME+++def rotate_update_log_if_needed(repo_path: Path) -> None:+ """Truncate ``.update.log`` if it has grown past the size cap.++ Called opportunistically from the hook before piping a new run's output+ in. We use simple in-place truncation (rewrite the tail) rather than+ renaming, because the post-commit hook can fire in parallel with a+ `repowise update` that may still be writing — a rename would orphan+ the writer's file descriptor on POSIX and outright fail on Windows.+ """+ path = update_log_path(repo_path)+ try:+ if not path.exists() or path.stat().st_size <= UPDATE_LOG_MAX_BYTES:+ return+ with path.open("rb") as f:+ f.seek(-UPDATE_LOG_KEEP_TAIL_BYTES, 2)+ tail = f.read()+ path.write_bytes(b"... (log truncated) ...\n" + tail)+ except OSError:+ pass++# ---------------------------------------------------------------------------# Git helpers# ---------------------------------------------------------------------------diff --git a/packages/cli/src/repowise/cli/hooks.py b/packages/cli/src/repowise/cli/hooks.pyindex 0c6001260..3703d3b78 100644--- a/packages/cli/src/repowise/cli/hooks.py+++ b/packages/cli/src/repowise/cli/hooks.py@@ -18,35 +18,72 @@ from pathlib import Path_HOOK_MARKER = "# repowise-hook-start"_HOOK_MARKER_END = "# repowise-hook-end"-# Fingerprints of legacy hook bodies (pre-marker era). When ``install`` is-# called over the top of a file containing these, we strip the legacy block-# rather than appending a second copy. The legacy block was unreachable due-# to a trailing ``exit 0`` and on Windows would fail every commit because+# Fingerprints of pre-marker legacy hook bodies. When ``install`` is called+# over the top of a file containing these, we strip the legacy block rather+# than appending a second copy. The legacy block was unreachable due to a+# trailing ``exit 0`` and on Windows would fail every commit because# ``uv run repowise update`` rebuilt the venv from a fresh resolve.+#+# DO NOT add fingerprints from *marker-bracketed* old hook bodies here —+# those are handled by ``_replace_marker_block`` instead. The strip path+# below walks until it finds ``exit 0``, which marker-bracketed bodies+# don't have, so a fingerprint match against them would over-delete and+# clobber unrelated hook content past the marker._LEGACY_HOOK_FINGERPRINTS = ("[repowise] Triggering incremental wiki update","/tmp/repowise-update.log",)-# The hook script detects the platform and runs repowise update in the-# background so the commit is never blocked.+# Post-commit hook contract. Works cross-platform because git always runs+# hooks under a POSIX shell (``/bin/sh`` on Linux/macOS, git-bash on+# Windows), so the same script body is correct everywhere — no platform+# detection needed.+#+# Two responsibilities:+#+# 1. Drop a ``.update.queued`` marker *before* backgrounding the update.+# Closes the race window where the agent-side augment hook would+# otherwise warn "wiki is stale" during the ~1–5 second start-up of+# ``repowise update`` (Python import, DB open) before the real lock+# file lands on disk. The marker is read by ``augment_cmd`` and+# treated identically to a held lock.+#+# 2. Capture the update's output to ``.repowise/.update.log``. Previously+# the hook piped to ``/dev/null``, which made silent failures+# impossible to diagnose — the symptom was just "state never moves".+# The log is appended; ``update_cmd`` truncates it on its next run+# via ``rotate_update_log_if_needed`` so it can't grow without bound.+#+# The outer ``{ ... } &`` brace group ensures the queued marker is written+# synchronously (so the augment hook sees it on the *next* tool call after+# the commit) before the heavy update spawns into the background._HOOK_SCRIPT = """\# repowise-hook-start# Auto-syncs repowise wiki after each commit (background, non-blocking).# Installed by: repowise hook install-(- cd "$(git rev-parse --show-toplevel)" || exit 1- if [ -d ".repowise" ]; then- # Detect the right way to invoke repowise+{+ ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0+ [ -d "$ROOT/.repowise" ] || exit 0+ HEAD=$(git rev-parse HEAD 2>/dev/null) || HEAD=""+ TS=$(date +%s 2>/dev/null) || TS=""+ if [ -n "$TS" ]; then+ printf '{"target_commit":"%s","queued_at":%s}\\n' "$HEAD" "$TS" \\+ > "$ROOT/.repowise/.update.queued" 2>/dev/null || true+ fi+ LOG="$ROOT/.repowise/.update.log"+ {+ printf '\\n--- post-commit hook fired at %s for HEAD %s ---\\n' \\+ "$(date 2>/dev/null)" "$HEAD"+ } >> "$LOG" 2>/dev/null || true+ (+ cd "$ROOT" || exit 1if command -v repowise >/dev/null 2>&1; then- repowise update > /dev/null 2>&1+ repowise update >> "$LOG" 2>&1elif command -v uv >/dev/null 2>&1; then- uv run repowise update > /dev/null 2>&1- elif command -v powershell.exe >/dev/null 2>&1; then- powershell.exe -Command "uv run repowise update" > /dev/null 2>&1+ uv run repowise update >> "$LOG" 2>&1fi- fi-) &+ ) &+} >/dev/null 2>&1# repowise-hook-end"""@@ -108,13 +145,43 @@ def _strip_legacy_block(content: str) -> tuple[str, bool]:return cleaned, True+def _replace_marker_block(content: str, new_block: str) -> tuple[str, bool]:+ """Replace an existing repowise marker block in place. Returns (content, replaced).++ Used when the hook is being upgraded: the marker is present but the+ body differs from the current ``_HOOK_SCRIPT``. We must not just bail+ with "already installed" — the user expects ``repowise hook install``+ to ship the latest hook script after a repowise upgrade.++ Only edits the marker-bracketed region; everything before ``_HOOK_MARKER``+ and after ``_HOOK_MARKER_END`` (other tools' hooks) is preserved.++ Implementation note: we use a *callable* repl with ``re.sub`` rather than+ passing the new block as a string. ``re.sub`` processes backslash+ escapes in string repls — so a literal ``\\n`` inside the hook script+ (e.g. a ``printf '%s\\n'`` format) would silently become a real newline,+ breaking the shell quoting of the printf format string. A callable+ bypasses escape processing entirely.+ """+ pattern = re.compile(+ rf"{re.escape(_HOOK_MARKER)}.*?{re.escape(_HOOK_MARKER_END)}\n?",+ flags=re.DOTALL,+ )+ if not pattern.search(content):+ return content, False+ replacement_text = new_block.rstrip() + "\n"+ new_content = pattern.sub(lambda _m: replacement_text, content, count=1)+ return new_content, new_content != content++def install(repo_path: Path) -> str:"""Install a repowise post-commit hook in the repo's .git/hooks/.- Appends to an existing post-commit hook if one exists (preserving- other tools' hooks). If a legacy (pre-marker) repowise body is found,- it is removed first to avoid an unreachable marker block. Returns a- human-readable status message.+ Behaves correctly under upgrades: when the marker block exists but its+ body is older than ``_HOOK_SCRIPT``, the block is replaced in place+ (preserving any unrelated hook content around it). Pre-marker legacy+ bodies are stripped before the new block is installed. Returns a+ human-readable status message describing what changed."""root = _git_root(repo_path)if root is None:@@ -132,7 +199,24 @@ def install(repo_path: Path) -> str:hook_path.write_text(content, encoding="utf-8")if _HOOK_MARKER in content:- return "migrated legacy hook" if migrated_legacy else "already installed"+ # Marker block present. Decide whether to leave alone or upgrade.+ current_block = _HOOK_SCRIPT.rstrip() + "\n"+ if current_block in content:+ return (+ "migrated legacy hook" if migrated_legacy else "already installed"+ )+ content, replaced = _replace_marker_block(content, _HOOK_SCRIPT)+ if replaced:+ hook_path.write_text(content, encoding="utf-8")+ try:+ hook_path.chmod(+ hook_path.stat().st_mode+ | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH+ )+ except OSError:+ pass+ return "upgraded"+ return "already installed"# Append to existing hookhook_path.write_text(content.rstrip() + "\n\n" + _HOOK_SCRIPT,diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.pyindex 294a227d0..ec1e968e4 100644--- a/packages/core/src/repowise/core/workspace/update.py+++ b/packages/core/src/repowise/core/workspace/update.py@@ -7,8 +7,11 @@ analysis hooks (Phase 3).from __future__ import annotationsimport asyncio+import json as _jsonimport logging+import osimport subprocess+import timefrom dataclasses import dataclass, fieldfrom datetime import datetime, timezonefrom pathlib import Path@@ -18,6 +21,63 @@ from .config import WorkspaceConfig_log = logging.getLogger("repowise.workspace.update")++# ---------------------------------------------------------------------------+# Per-repo update lock — duplicated from cli/helpers.py to avoid a core →+# cli import. The format and stale-after threshold MUST stay in sync with+# the canonical helpers; both versions are tiny and rarely change. This+# lives in core/ so ``update_single_repo_index`` (which workspace updates+# call directly, bypassing the CLI lock acquisition in update_cmd.py) is+# itself single-flight per repo.+# ---------------------------------------------------------------------------++_LOCK_FILENAME = ".update.lock"+_LOCK_STALE_AFTER_SECONDS = 30 * 60+++def _lock_path(repo_path: Path) -> Path:+ return repo_path / ".repowise" / _LOCK_FILENAME+++def _read_lock(repo_path: Path) -> dict[str, Any] | None:+ """Return a live lock payload, or None when absent / stale / unreadable."""+ path = _lock_path(repo_path)+ if not path.exists():+ return None+ try:+ payload = _json.loads(path.read_text(encoding="utf-8"))+ except (OSError, ValueError):+ return None+ started = payload.get("started_at")+ if not isinstance(started, (int, float)):+ return None+ if time.time() - started > _LOCK_STALE_AFTER_SECONDS:+ return None+ return payload+++def _acquire_lock(repo_path: Path, target_commit: str | None) -> None:+ """Best-effort write of the lock file. Caller still must release."""+ try:+ (repo_path / ".repowise").mkdir(parents=True, exist_ok=True)+ _lock_path(repo_path).write_text(+ _json.dumps({+ "pid": os.getpid(),+ "target_commit": target_commit,+ "started_at": time.time(),+ }),+ encoding="utf-8",+ )+ except OSError:+ pass+++def _release_lock(repo_path: Path) -> None:+ try:+ _lock_path(repo_path).unlink(missing_ok=True)+ except OSError:+ pass+# ---------------------------------------------------------------------------# Data models# ---------------------------------------------------------------------------@@ -323,11 +383,41 @@ async def update_workspace(# first-time indexing has a place to put wiki.db and state.json.(path / ".repowise").mkdir(parents=True, exist_ok=True)- result = await update_single_repo_index(- path,- commit_depth=commit_depth,- exclude_patterns=exclude_patterns,- )+ # Per-repo single-flight check. The post-commit hook fires a+ # new ``repowise update`` for every commit; without this guard,+ # rapid-fire commits race on save_state, each pass starts from+ # the same stale base, and the wiki never converges to HEAD.+ existing = _read_lock(path)+ if existing is not None:+ elapsed = int(time.time() - existing.get("started_at", time.time()))+ target_short = (existing.get("target_commit") or "")[:8]+ _log.info(+ "workspace_update: skipping %s — update already in flight "+ "(pid=%s target=%s elapsed=%ds)",+ alias, existing.get("pid"), target_short, elapsed,+ )+ # Record pending so the running update can roll forward.+ try:+ (path / ".repowise" / ".update.pending").write_text(+ new_head, encoding="utf-8"+ )+ except OSError:+ pass+ return RepoUpdateResult(+ alias=alias,+ updated=False,+ skipped_reason="in_flight",+ )++ _acquire_lock(path, new_head)+ try:+ result = await update_single_repo_index(+ path,+ commit_depth=commit_depth,+ exclude_patterns=exclude_patterns,+ )+ finally:+ _release_lock(path)result.alias = aliasresult.first_time_indexed = first_time and result.updateddiff --git a/tests/unit/cli/test_augment_staleness.py b/tests/unit/cli/test_augment_staleness.pyindex 64f034a32..3b4e76ae6 100644--- a/tests/unit/cli/test_augment_staleness.py+++ b/tests/unit/cli/test_augment_staleness.py@@ -93,12 +93,15 @@ class TestStaleWarning:class TestUpdateLockSuppression:- def test_lock_suppresses_warning(self, repo):+ def test_lock_emits_in_flight_notice_not_stale_warning(self, repo):+ # When an update is running, the agent should hear "updating in+ # background" instead of "wiki is stale". The original behavior was+ # to suppress entirely (return None); the explicit positive notice+ # is better UX because the agent can plan around it.repo_path, head = repo_state(repo_path, last_sync_commit=head, docs_enabled=True)new_head = _commit(repo_path)- # Simulate `repowise update` running with target_commit=new_headimport time(repo_path / ".repowise" / ".update.lock").write_text(@@ -110,7 +113,10 @@ class TestUpdateLockSuppression:encoding="utf-8",)- assert _post(repo_path) is None+ msg = _post(repo_path)+ assert msg is not None+ assert "update in background" in msg+ assert "stale" not in msg.lower()def test_stale_lock_does_not_suppress(self, repo):repo_path, head = repo@@ -123,12 +129,14 @@ class TestUpdateLockSuppression:encoding="utf-8",)- assert _post(repo_path) is not None+ msg = _post(repo_path)+ assert msg is not None+ assert "stale" in msg.lower() # Falls through to the real stale warning- def test_lock_for_different_commit_still_suppresses(self, repo):- # An update is running but its target predates HEAD. We still- # suppress: the in-flight run will at least narrow the gap, and- # the next tool call will re-evaluate.+ def test_lock_for_different_commit_still_signals_in_flight(self, repo):+ # An update is running but its target predates HEAD. We still emit+ # the in-flight notice (not the stale warning): the running update+ # will narrow the gap, and the next tool call will re-evaluate.repo_path, head = repo_state(repo_path, last_sync_commit=head, docs_enabled=True)_commit(repo_path)@@ -144,7 +152,49 @@ class TestUpdateLockSuppression:encoding="utf-8",)- assert _post(repo_path) is None+ msg = _post(repo_path)+ assert msg is not None+ assert "update in background" in msg+++class TestQueuedMarkerSuppression:+ """The post-commit hook drops ``.update.queued`` before backgrounding the+ update. The augment hook must treat that marker the same as a held lock,+ or every commit in a rapid burst will get a noisy stale warning during+ the start-up window before the real lock file lands on disk."""++ def test_queued_marker_emits_in_flight_notice(self, repo):+ repo_path, head = repo+ _state(repo_path, last_sync_commit=head, docs_enabled=True)+ new_head = _commit(repo_path)++ import time++ (repo_path / ".repowise" / ".update.queued").write_text(+ json.dumps({"target_commit": new_head, "queued_at": time.time()}),+ encoding="utf-8",+ )++ msg = _post(repo_path)+ assert msg is not None+ assert "update in background" in msg++ def test_stale_queued_marker_falls_through_to_stale_warning(self, repo):+ # The queued marker has a much shorter staleness window (5 min) than+ # the real lock (30 min) — a queued marker that age means the hook+ # spawned an update but it never reached the lock-acquire step.+ repo_path, head = repo+ _state(repo_path, last_sync_commit=head, docs_enabled=True)+ _commit(repo_path)++ (repo_path / ".repowise" / ".update.queued").write_text(+ json.dumps({"target_commit": "x", "queued_at": 0}),+ encoding="utf-8",+ )++ msg = _post(repo_path)+ assert msg is not None+ assert "stale" in msg.lower()class TestPerHeadDedupe:diff --git a/tests/unit/cli/test_helpers.py b/tests/unit/cli/test_helpers.pyindex 0383b5da9..f207d873c 100644--- a/tests/unit/cli/test_helpers.py+++ b/tests/unit/cli/test_helpers.py@@ -382,3 +382,119 @@ class TestResolveProviderBaseUrl:assert result == "provider"assert captured["name"] == "ollama"assert captured["kwargs"].get("base_url") == "http://ollama.local:11434"+++# ---------------------------------------------------------------------------+# Update queued / pending markers — coalescing primitives that prevent the+# post-commit hook from spawning N concurrent updates on rapid-fire commits.+# ---------------------------------------------------------------------------+++class TestUpdateQueuedMarker:+ """The hook drops .update.queued *before* backgrounding update_cmd so the+ augment hook can suppress its stale-wiki warning during the start-up+ window where the real lock hasn't been acquired yet."""++ def test_round_trip(self, tmp_path):+ from repowise.cli.helpers import (+ clear_update_queued,+ read_update_queued,+ write_update_queued,+ )++ write_update_queued(tmp_path, "abc123")+ payload = read_update_queued(tmp_path)+ assert payload is not None+ assert payload["target_commit"] == "abc123"+ assert isinstance(payload["queued_at"], float)++ clear_update_queued(tmp_path)+ assert read_update_queued(tmp_path) is None++ def test_stale_queued_returns_none(self, tmp_path):+ # A queued marker older than UPDATE_QUEUED_STALE_AFTER_SECONDS+ # (5 min) is treated as crashed-hook noise and ignored.+ import json++ from repowise.cli.helpers import ensure_repowise_dir, read_update_queued++ ensure_repowise_dir(tmp_path)+ (tmp_path / ".repowise" / ".update.queued").write_text(+ json.dumps({"target_commit": "abc", "queued_at": 0}),+ encoding="utf-8",+ )+ assert read_update_queued(tmp_path) is None++ def test_missing_marker_returns_none(self, tmp_path):+ from repowise.cli.helpers import read_update_queued++ assert read_update_queued(tmp_path) is None+++class TestUpdatePendingMarker:+ """A new update_cmd run that finds an existing lock writes the latest+ HEAD into .update.pending so the running update can roll forward to+ it instead of stopping at a stale commit."""++ def test_round_trip(self, tmp_path):+ from repowise.cli.helpers import (+ clear_update_pending,+ read_update_pending,+ write_update_pending,+ )++ write_update_pending(tmp_path, "deadbeef")+ assert read_update_pending(tmp_path) == "deadbeef"++ clear_update_pending(tmp_path)+ assert read_update_pending(tmp_path) is None++ def test_write_with_none_head_is_noop(self, tmp_path):+ from repowise.cli.helpers import read_update_pending, write_update_pending++ write_update_pending(tmp_path, None)+ assert read_update_pending(tmp_path) is None+++class TestRotateUpdateLog:+ """The post-commit hook appends every run's output to .update.log.+ Without rotation it would grow unboundedly on a busy repo."""++ def test_no_op_when_under_cap(self, tmp_path):+ from repowise.cli.helpers import (+ ensure_repowise_dir,+ rotate_update_log_if_needed,+ update_log_path,+ )++ ensure_repowise_dir(tmp_path)+ path = update_log_path(tmp_path)+ path.write_text("small log", encoding="utf-8")++ rotate_update_log_if_needed(tmp_path)+ assert path.read_text(encoding="utf-8") == "small log"++ def test_truncates_when_over_cap(self, tmp_path):+ from repowise.cli.helpers import (+ UPDATE_LOG_KEEP_TAIL_BYTES,+ UPDATE_LOG_MAX_BYTES,+ ensure_repowise_dir,+ rotate_update_log_if_needed,+ update_log_path,+ )++ ensure_repowise_dir(tmp_path)+ path = update_log_path(tmp_path)+ # Build a payload comfortably over the cap with a known tail so we+ # can assert what survives.+ body_size = UPDATE_LOG_MAX_BYTES * 2+ path.write_bytes(b"x" * (body_size - 20) + b"TAIL_MARKER_ZZZZ\n")++ rotate_update_log_if_needed(tmp_path)++ after = path.read_bytes()+ # Capped to roughly KEEP_TAIL_BYTES + the truncation banner; far+ # below the original size in any case.+ assert len(after) < UPDATE_LOG_MAX_BYTES+ assert b"TAIL_MARKER_ZZZZ" in after+ assert after.startswith(b"... (log truncated) ...")diff --git a/tests/unit/cli/test_hooks_legacy_migration.py b/tests/unit/cli/test_hooks_legacy_migration.pyindex 47daee188..c485c3733 100644--- a/tests/unit/cli/test_hooks_legacy_migration.py+++ b/tests/unit/cli/test_hooks_legacy_migration.py@@ -114,3 +114,96 @@ class TestInstallMigratesLegacyHook:content = hook.read_text(encoding="utf-8")assert "echo 'lint'" in contentassert "# repowise-hook-start" in content+++# Snapshot of the marker-bracketed hook body that shipped before the+# cross-platform / coalescing rewrite. Used to verify ``install`` upgrades+# the block in place (vs. bailing with "already installed", which was the+# behaviour that left users stuck on a buggy hook).+_PREVIOUS_MARKER_HOOK = """\+# repowise-hook-start+# Auto-syncs repowise wiki after each commit (background, non-blocking).+# Installed by: repowise hook install+(+ cd "$(git rev-parse --show-toplevel)" || exit 1+ if [ -d ".repowise" ]; then+ if command -v repowise >/dev/null 2>&1; then+ repowise update > /dev/null 2>&1+ elif command -v uv >/dev/null 2>&1; then+ uv run repowise update > /dev/null 2>&1+ elif command -v powershell.exe >/dev/null 2>&1; then+ powershell.exe -Command "uv run repowise update" > /dev/null 2>&1+ fi+ fi+) &+# repowise-hook-end+"""+++class TestInstallUpgradesMarkerBlock:+ """``install`` over an existing marker block whose body differs from the+ current ``_HOOK_SCRIPT`` should replace the block in place, preserving+ any other content around the markers."""++ def test_install_upgrades_in_place_when_body_differs(self, git_repo):+ hook = git_repo / ".git" / "hooks" / "post-commit"+ hook.parent.mkdir(parents=True, exist_ok=True)+ hook.write_text("#!/bin/sh\n" + _PREVIOUS_MARKER_HOOK, encoding="utf-8")++ result = install(git_repo)+ assert result == "upgraded"++ content = hook.read_text(encoding="utf-8")+ # The new hook writes the queued marker before backgrounding; the+ # old hook didn't. Use that signal as the upgrade fingerprint.+ assert ".update.queued" in content+ # And the silent /dev/null sink from the old hook must be gone.+ assert "repowise update > /dev/null 2>&1" not in content++ def test_install_upgrades_preserves_surrounding_hooks(self, git_repo):+ hook = git_repo / ".git" / "hooks" / "post-commit"+ hook.parent.mkdir(parents=True, exist_ok=True)+ hook.write_text(+ "#!/bin/sh\n"+ "# my lint hook\n"+ "echo 'pre-existing lint'\n\n"+ + _PREVIOUS_MARKER_HOOK+ + "\n# trailing hook\necho 'trailing'\n",+ encoding="utf-8",+ )++ install(git_repo)++ content = hook.read_text(encoding="utf-8")+ assert "pre-existing lint" in content+ assert "trailing" in content+ assert ".update.queued" in content++ def test_install_idempotent_when_body_already_current(self, git_repo):+ install(git_repo) # Fresh install of the current body.+ result = install(git_repo)+ assert result == "already installed"+++class TestInstalledHookScript:+ """Sanity checks on the shipped hook script so platform-specific+ regressions (e.g. accidentally introducing bash-only syntax) get caught+ by unit tests rather than by a user's git commit."""++ def test_hook_does_not_use_bash_only_features(self):+ from repowise.cli.hooks import _HOOK_SCRIPT++ # ``[[ ]]``, ``$( <(...) )``, named arrays — all bashisms that fail+ # under plain ``/bin/sh`` on Alpine and minimal Mac installs. The+ # hook must stay POSIX-clean.+ assert "[[" not in _HOOK_SCRIPT+ assert "<(" not in _HOOK_SCRIPT++ def test_hook_writes_queued_marker_and_log(self):+ from repowise.cli.hooks import _HOOK_SCRIPT++ # Two invariants the augment-hook tests rely on.+ assert ".update.queued" in _HOOK_SCRIPT+ assert ".update.log" in _HOOK_SCRIPT+ # And no silent /dev/null sink — that was the original bug.+ assert "> /dev/null 2>&1" not in _HOOK_SCRIPT or ">> \"$LOG\"" in _HOOK_SCRIPT