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(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.py
index 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 time
from 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 None
def _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.py
index 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 Table
from 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_path
assert repo_path is not None # single mode always sets repo_path
ensure_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 atexit
acquire_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 workspace
try:
ws_root = find_workspace_root(repo_path)
diff --git a/packages/cli/src/repowise/cli/helpers.py b/packages/cli/src/repowise/cli/helpers.py
index 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.py
index 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 1
if command -v repowise >/dev/null 2>&1; then
- repowise update > /dev/null 2>&1
+ repowise update >> "$LOG" 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
+ uv run repowise update >> "$LOG" 2>&1
fi
- 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 hook
hook_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.py
index 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 annotations
import asyncio
+import json as _json
import logging
+import os
import subprocess
+import time
from dataclasses import dataclass, field
from datetime import datetime, timezone
from 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 = alias
result.first_time_indexed = first_time and result.updated
diff --git a/tests/unit/cli/test_augment_staleness.py b/tests/unit/cli/test_augment_staleness.py
index 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_head
import 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.py
index 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.py
index 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 content
assert "# 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