witan-core 0.2.0__py3-none-any.whl

witan_core/__init__.py

@@ -0,0 +1,29 @@
+"""witan-core — shared core for the witan MCP servers.
+
+A leaf package that ``witan`` (witan-council) and ``witan_code`` both depend on,
+extracted from the surface they were previously carrying as copy-paste-and-diverge
+duplicates. See ``docs/design/witan-core-extraction-spec.md``.
+
+``witan_core`` imports neither ``witan`` nor ``witan_code``: it sits below both,
+preserving the one-directional ``witan`` → ``witan_code`` optional-mount DAG.
+
+The root package is dependency-free (stdlib only). Heavier concerns live in
+submodules gated behind extras and are NOT re-exported here: ``witan_core.elicit``
+needs ``fastmcp`` (the ``mcp`` extra); the omnigraph installer imports ``rich``
+lazily.
+"""
+
+from __future__ import annotations
+
+from ._detach import popen_detached
+from .omnigraph_install import install_omnigraph
+from .repo_key import find_git_config, normalise
+from .timeutil import now_iso
+
+__all__ = [
+    "find_git_config",
+    "install_omnigraph",
+    "normalise",
+    "now_iso",
+    "popen_detached",
+]

witan_core/_detach.py

@@ -0,0 +1,25 @@
+"""Cross-platform detached-subprocess spawning.
+
+``subprocess.Popen``'s ``start_new_session=True`` (setsid) is POSIX-only — a
+no-op on Windows, where a background hook child can otherwise get torn down
+with its parent's process group/console. Used by every hook that must spawn
+work and return immediately: the witan-code SessionStart indexer and both
+servers' throttled optimize checkpoint (``maintenance.py``), spawned from the
+``Stop`` hook.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def popen_detached(args: list[str], **kwargs: object) -> subprocess.Popen:
+    """Spawn ``args`` fully detached from the current process, cross-platform."""
+    if sys.platform == "win32":
+        kwargs["creationflags"] = (
+            subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS
+        )
+    else:
+        kwargs["start_new_session"] = True
+    return subprocess.Popen(args, **kwargs)  # noqa: S603 — caller controls argv

witan_core/cli.py

@@ -0,0 +1,113 @@
+"""Shared CLI scaffolding for the witan servers' ``setup`` commands.
+
+Uses the ``cli`` extra: ``make_app`` needs cyclopts, and ``report_install``
+uses agent-config-kit's ``InstallResult`` type. This module never imports rich
+itself — the extra bundles it only for ``report_install``'s styled branch,
+which runs on a rich ``Console`` the *caller* passes in (without one it plain
+``print``s), so importing/using ``witan_core.cli`` never requires rich.
+Following the package convention (see ``__init__``), nothing here is re-exported
+from the root package — import from ``witan_core.cli`` directly.
+
+The pieces both ``witan`` (witan-council) and ``witan_code`` carried as
+copy-paste duplicates: the supported-agent constants, the ``--version`` app
+factory, ``--author`` resolution, and the install-result printer. Everything
+else in each server's ``setup`` command is package-local (different bundles,
+different post-install healing) and stays put.
+
+``report_install`` deliberately renders plain text without a ``console`` so
+witan-code's setup can call it without importing rich just for that line.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    import cyclopts
+    from agent_config_kit import InstallResult
+    from rich.console import Console
+
+# The coding agents witan supports installing into. Both servers' `setup`
+# commands mirror this literal for their `--agent` argument; "all" fans out
+# across every detected platform.
+AgentName = Literal["claude", "pi", "copilot", "opencode", "all"]
+
+# Human-readable labels keyed by the AgentName literals (minus "all"), used in
+# install reports. `.get(name, name)` falls back to the raw key.
+AGENT_NAMES: dict[str, str] = {
+    "claude": "Claude Code",
+    "pi": "Pi",
+    "copilot": "GitHub Copilot",
+    "opencode": "OpenCode",
+}
+
+
+def make_app(*, name: str, help_text: str, version_dist: str) -> cyclopts.App:
+    """Build the top-level cyclopts ``App`` for a witan CLI.
+
+    ``version_dist`` is the installed distribution name whose version
+    ``--version`` reports (e.g. ``"witan-council"`` or ``"witan-code"``).
+    """
+    import cyclopts
+    from agent_config_kit.version import resolve_version
+
+    return cyclopts.App(
+        name=name,
+        help=help_text,
+        version=lambda: resolve_version(version_dist),
+    )
+
+
+def resolve_author(author: str | None) -> str:
+    """Resolve the graph-attribution author for a ``setup`` run.
+
+    An explicit value wins; otherwise fall back to ``git config user.name``,
+    then ``$USER``, then ``"unknown"``.
+    """
+    if author is not None:
+        return author
+    try:
+        resolved = subprocess.check_output(
+            ["git", "config", "user.name"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (subprocess.CalledProcessError, OSError):
+        # OSError covers a missing git binary (FileNotFoundError) plus any other
+        # OS-level failure to spawn it (e.g. PermissionError); degrade to the
+        # $USER/"unknown" fallback rather than letting `setup` crash.
+        resolved = ""
+    return resolved or os.environ.get("USER", "unknown")
+
+
+def report_install(
+    name: str,
+    result: InstallResult,
+    *,
+    dry_run: bool,
+    console: Console | None = None,
+) -> None:
+    """Print an agent-config ``InstallResult``.
+
+    With a rich ``console`` the output is styled (witan-council's look); without
+    one it is plain ``print`` (witan-code's look). Keeping both branches here
+    lets the two servers share the printer without witan-code taking on rich for
+    it.
+    """
+    label = AGENT_NAMES.get(name, name)
+    if console is not None:
+        console.print(f"\n[bold]{label}[/bold]")
+        for path in result.planned:
+            tag = " [dim](dry-run)[/dim]" if dry_run else ""
+            console.print(f"  [green]→[/green] {path}{tag}")
+        for path, reason in result.skipped:
+            console.print(f"  [yellow]skip[/yellow] {path} — {reason}")
+    else:
+        print(f"\n{label}")
+        for path in result.planned:
+            tag = " (dry-run)" if dry_run else ""
+            print(f"  -> {path}{tag}")
+        for path, reason in result.skipped:
+            print(f"  skip {path} — {reason}")

witan_core/elicit.py

@@ -0,0 +1,59 @@
+"""Additive MCP elicitation primitives, shared by both witan servers.
+
+FastMCP supports ``ctx.elicit``, but the connected client may not, and many
+tools also run under headless automation (context/checkpoint hooks, background
+indexers). These helpers keep elicitation strictly *additive*: when the client
+can't elicit — or ``ctx`` is absent — they return the caller's ``default`` so
+behavior is exactly what it was before elicitation existed. Only an *explicit*
+user decline changes the outcome.
+
+This module is NOT imported by ``witan_core/__init__`` — it depends on
+``fastmcp`` (the ``mcp`` extra), so importing the base package stays
+dependency-free. Each server composes its own repo-elicitation helpers
+(``repo_or_detect`` / ``choose_repo``) on top of these primitives.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastmcp.server.elicitation import AcceptedElicitation
+
+if TYPE_CHECKING:
+    from fastmcp import Context
+
+
+async def confirm(
+    ctx: Context | None, message: str, *, default_when_unsupported: bool
+) -> bool:
+    """Ask a yes/no question.
+
+    ``accept`` → the chosen bool; ``decline``/``cancel`` → ``False``; and when
+    elicitation is unsupported or errors (headless client, no ``ctx``) →
+    ``default_when_unsupported`` — pick that so the non-interactive path keeps
+    today's behavior (e.g. ``False`` for "don't act", ``True`` for "proceed").
+    """
+    if ctx is None:
+        return default_when_unsupported
+    try:
+        result = await ctx.elicit(message, response_type=bool)
+    except Exception:  # noqa: BLE001 — any elicit failure means "can't ask"
+        return default_when_unsupported
+    if isinstance(result, AcceptedElicitation):
+        return bool(result.data)
+    return False
+
+
+async def text(ctx: Context | None, message: str, *, default: str) -> str:
+    """Ask for a line of text. A non-empty accepted value is returned; a
+    decline/cancel, an empty value, an unsupported client, or no ``ctx`` all
+    fall back to ``default``."""
+    if ctx is None:
+        return default
+    try:
+        result = await ctx.elicit(message, response_type=str)
+    except Exception:  # noqa: BLE001
+        return default
+    if isinstance(result, AcceptedElicitation) and (result.data or "").strip():
+        return result.data.strip()
+    return default

witan_core/maintenance.py

@@ -0,0 +1,90 @@
+"""Throttle + atomic-stamp mechanics for opportunistic store compaction.
+
+Both servers run ``omnigraph optimize`` opportunistically from their ``Stop``
+hook, at most once per interval per store, never blocking the agent. The tricky,
+error-prone parts are shared here; each server wraps them with its own store-key
+type, env var, stamp-file location, and detached command (see
+``witan.maintenance`` / ``witan_code.maintenance``):
+
+- ``resolve_interval`` — parse the throttle window from an env var.
+- ``mark_run`` — write the last-run stamp *atomically* (temp file + ``os.replace``)
+  so a concurrent/interrupted write can't leave a half-written stamp that reads
+  as "never run" and defeats the throttle.
+- ``last_run`` — read it back, treating missing/corrupt as "never run".
+- ``is_due`` — the disabled / remote-store / missing-store / window-elapsed logic.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+# Remote stores (omnigraph-server) are compacted server-side, not by a client
+# hook, so opportunistic optimize never fires for them.
+REMOTE_PREFIXES = ("http://", "https://", "s3://")
+
+# Optimize takes the store's write lock and is ~tens of seconds on a bloated
+# store, so daily is a safe default throttle window.
+DEFAULT_OPTIMIZE_INTERVAL = 24 * 3600.0
+
+
+def resolve_interval(env_var: str, default: float = DEFAULT_OPTIMIZE_INTERVAL) -> float:
+    """Throttle window in seconds from ``env_var``; ``0``/negative disables."""
+    raw = os.environ.get(env_var)
+    if raw is None:
+        return default
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return default
+
+
+def last_run(stamp_file: Path) -> float:
+    """Last-optimize timestamp from ``stamp_file``; ``0.0`` if missing/corrupt."""
+    try:
+        return float(json.loads(stamp_file.read_text()).get("stamp", 0.0))
+    except Exception:  # noqa: BLE001 — missing/corrupt stamp → treat as never run
+        return 0.0
+
+
+def mark_run(stamp_file: Path, when: float) -> None:
+    """Record the last-optimize time atomically.
+
+    Concurrent Stop hooks (or an interrupted write) could otherwise leave a
+    half-written stamp that ``last_run`` reads as "never run", defeating the
+    throttle and letting optimize spawn repeatedly. Write a process-unique temp
+    file and ``os.replace`` it in, so a reader always sees a complete file.
+    """
+    tmp = stamp_file.with_name(f"{stamp_file.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(json.dumps({"stamp": when}))
+        os.replace(tmp, stamp_file)
+    except OSError:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def is_due(
+    *,
+    store: str | Path,
+    stamp_file: Path,
+    interval: float,
+    now: float,
+    require_exists: bool,
+) -> bool:
+    """Whether an opportunistic optimize is due for ``store``.
+
+    False when auto-optimize is disabled (``interval<=0``), the store is remote
+    (maintained server-side), ``require_exists`` and the store doesn't exist
+    yet, or the throttle window hasn't elapsed since ``last_run``.
+    """
+    if interval <= 0:
+        return False
+    if str(store).startswith(REMOTE_PREFIXES):
+        return False
+    if require_exists and not Path(store).exists():
+        return False
+    return now - last_run(stamp_file) >= interval

witan_core/omnigraph.py

@@ -0,0 +1,353 @@
+"""Shared base for the omnigraph CLI subprocess wrapper.
+
+Both servers drive the ``omnigraph`` binary the same way: a per-store advisory
+write lock for local stores, a retry/repair loop for optimistic-concurrency
+drift, a self-backoff for the deployed omnigraph-server's per-actor admission
+cap, and named read/mutate queries. That LOCAL-vs-REMOTE-generic surface lives
+here; each server subclasses to add its own tail:
+
+- ``witan`` adds a write ``guard`` + ``surface_conflict`` (CAS task claims),
+  ``apply_schema``, and the storage-version friendly-error hint.
+- ``witan_code`` adds omnigraph *branch* support (``_extra_args`` override,
+  ``ensure_branch``/…) and bulk ``load``.
+
+Subclass knobs:
+- ``_SETUP_HINT`` — the install command named in the "binary not found" error.
+- ``_STORAGE_MISMATCH_HINT`` — remediation text for a storage-version mismatch;
+  ``None`` (the default) leaves that error on the generic failure path.
+- ``_extra_args(subcommand)`` — extra CLI args injected into every ``_run`` (e.g.
+  ``--branch``); returns ``[]`` by default.
+
+This module is stdlib-only but imports ``fcntl`` (POSIX advisory locks), so it is
+NOT re-exported from ``witan_core``'s package root — import it as
+``witan_core.omnigraph``.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import random
+import re
+import shutil
+import subprocess
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+# omnigraph local stores use optimistic concurrency (Lance manifest versions) and
+# are NOT safe for concurrent writers. We serialize writes with a per-store
+# advisory lock (prevention) and, as a safety net, retry transient "stale view"
+# conflicts and `omnigraph repair` stores already in the drifted state.
+_WRITE_SUBCOMMANDS = {"mutate", "load", "optimize", "cleanup"}
+_RETRYABLE = ("stale view", "manifest table version", "refresh and retry")
+_NEEDS_REPAIR = ("ahead of manifest", "omnigraph repair")
+_MAX_ATTEMPTS = 8
+
+# omnigraph uses strict single-version storage: a release that bumps the
+# internal schema version refuses to open graphs an older binary wrote,
+# raising exactly this pair of substrings wrapped in an unhelpful Rust panic +
+# backtrace. Not retryable/repairable.
+_STORAGE_VERSION_MISMATCH_MARKERS = ("stamped at internal schema", "reads only")
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+# omnigraph-server (remote http(s)/s3 stores) enforces a hard per-actor
+# admission cap — both an in-flight *count* (default 16) and a concurrent
+# *byte* budget — and rejects excess concurrent writes outright (HTTP 429)
+# rather than queuing them. The CLI's error path only surfaces the JSON body's
+# message text, not the `Retry-After: 60` header, so this can't read it and
+# backs off on its own, much shorter, schedule. Independent of _MAX_ATTEMPTS
+# and of surface_conflict (it isn't a compare-and-swap race, just admission
+# control). Lives in the shared base because witan-code also writes to the
+# deployed omnigraph-server.
+_ADMISSION_CAP_MARKERS = ("in-flight count cap", "byte budget exceeded")
+_ADMISSION_CAP_MAX_ATTEMPTS = 6
+_ADMISSION_CAP_BASE_DELAY = 0.25
+_ADMISSION_CAP_MAX_DELAY = 4.0
+
+
+def _admission_cap_backoff(attempt: int) -> float:
+    """Exponential backoff with jitter — plain exponential backoff makes
+    concurrent retries from the same burst (the actual trigger case here)
+    retry in lockstep and re-collide on the cap; jitter breaks that up."""
+    delay = _ADMISSION_CAP_BASE_DELAY * (2 ** (attempt - 1))
+    jitter = random.uniform(0, 0.1 * delay)
+    return min(delay + jitter, _ADMISSION_CAP_MAX_DELAY)
+
+
+class OmnigraphConflict(RuntimeError):
+    """An optimistic-concurrency (Lance manifest version) write conflict that the
+    caller asked to surface instead of retry.
+
+    omnigraph serializes local writes with our advisory flock, but on shared
+    http(s)/s3 stores that lock is skipped and two writers racing the same
+    manifest version make one commit fail with a "stale view" / "manifest table
+    version" error. ``_execute`` normally masks that by re-running the same
+    mutation — fine for an idempotent upsert, WRONG for a compare-and-swap claim
+    where the retry would blindly re-apply the claim over whoever won the race.
+    A caller passing ``surface_conflict=True`` gets this exception instead so it
+    can re-read and decide (see ``task_claim``)."""
+
+
+def _is_storage_version_mismatch(msg: str) -> bool:
+    lowered = msg.lower()
+    return all(marker in lowered for marker in _STORAGE_VERSION_MISMATCH_MARKERS)
+
+
+def _friendly_storage_error(raw: str, hint: str) -> str:
+    """Strip the Rust panic's ANSI codes and backtrace boilerplate ("Location:",
+    "Backtrace omitted...") from a storage-version-mismatch error, keeping just
+    omnigraph's own message, and append the caller's remediation ``hint``."""
+    cleaned = _ANSI_RE.sub("", raw).split("Location:")[0].strip()
+    return f"{cleaned}\n\n{hint}"
+
+
+class OmnigraphClient:
+    """Subprocess wrapper for the omnigraph CLI (shared base)."""
+
+    #: Install command named in the "binary not found" error. Override per server.
+    _SETUP_HINT = "the omnigraph installer (`witan setup` / `witan-code setup`)"
+    #: Remediation text appended to a storage-version-mismatch error. ``None``
+    #: leaves that error on the generic failure path (no friendly rewrite).
+    _STORAGE_MISMATCH_HINT: str | None = None
+
+    def __init__(
+        self,
+        graph_uri: str,
+        queries_dir: Path,
+        token: str | None = None,
+        guard: Callable[[str, dict], dict] | None = None,
+    ) -> None:
+        self.graph_uri = graph_uri
+        self.queries_dir = queries_dir
+        self.token = token
+        self.guard = guard
+        self._binary = self._find_binary()
+
+    # ── Public API ────────────────────────────────────────────────
+
+    def read(
+        self,
+        query_file: str,
+        query_name: str,
+        params: dict,
+    ) -> list[dict]:
+        """Run a named read query. Returns a list of result rows."""
+        result = self._run(
+            "query",
+            "--query",
+            str(self.queries_dir / query_file),
+            query_name,
+            "--params",
+            json.dumps(params),
+            "--format",
+            "json",
+        )
+        if not result.strip():
+            return []
+        try:
+            parsed = json.loads(result)
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(f"omnigraph returned non-JSON: {result!r}") from exc
+        # v0.7.0 wraps results in {rows: [...], columns: [...], ...}
+        rows = parsed.get("rows", parsed) if isinstance(parsed, dict) else parsed
+        # strip alias prefixes: "p.slug" → "slug"
+        return [{k.split(".", 1)[-1]: v for k, v in row.items()} for row in rows]
+
+    def change(
+        self,
+        query_file: str,
+        query_name: str,
+        params: dict,
+        *,
+        surface_conflict: bool = False,
+    ) -> None:
+        """Run a named mutation query.
+
+        The optional ``guard`` runs first: it may raise to reject the write, or
+        return rewritten params (e.g. with secrets redacted) that are what
+        actually get persisted.
+
+        ``surface_conflict``: raise :class:`OmnigraphConflict` on an
+        optimistic-concurrency conflict instead of transparently retrying the
+        write. Callers implementing a compare-and-swap (e.g. ``task_claim``) need
+        this so a lost race is detectable rather than silently clobbered.
+        """
+        if self.guard is not None:
+            params = self.guard(query_name, params)
+        self._run(
+            "mutate",
+            "--query",
+            str(self.queries_dir / query_file),
+            query_name,
+            "--params",
+            json.dumps(params),
+            surface_conflict=surface_conflict,
+        )
+
+    def optimize(self) -> str:
+        """Compact small Lance fragments across every table (non-destructive).
+
+        Every write appends a new tiny Lance fragment + manifest version; an
+        un-compacted store bloats until *opening* it dominates query latency.
+        ``omnigraph optimize`` collapses the fragments. It takes the store's
+        write lock and can run for tens of seconds, so callers throttle it and
+        keep it off the hot path (see each server's ``maintenance``).
+        """
+        return self._run("optimize")
+
+    def cleanup(self, *, keep: int | None = None, older_than: str | None = None) -> str:
+        """Reclaim disk by removing old Lance versions (**destructive**).
+
+        ``optimize`` compacts fragments but leaves old versions behind, so disk
+        stays large until they are GC'd. ``cleanup`` removes them, keeping the
+        most recent ``keep`` versions per table and/or those newer than
+        ``older_than`` (a Go-style duration like ``7d``). At least one bound must
+        be given (omnigraph requires it). ``--confirm`` is passed so it runs.
+        """
+        if keep is None and older_than is None:
+            raise ValueError("cleanup requires keep and/or older_than")
+        args = ["--confirm"]
+        if keep is not None:
+            args += ["--keep", str(keep)]
+        if older_than is not None:
+            args += ["--older-than", older_than]
+        return self._run("cleanup", *args)
+
+    # ── Internals ─────────────────────────────────────────────────
+
+    def _extra_args(self, subcommand: str) -> list[str]:
+        """Extra CLI args injected into every ``_run`` command (after the store
+        flag, before the caller's args). Empty by default; subclasses override
+        (e.g. witan-code injects ``--branch``)."""
+        return []
+
+    def _run(self, subcommand: str, *args: str, surface_conflict: bool = False) -> str:
+        quiet = ["--quiet"] if subcommand in _WRITE_SUBCOMMANDS else []
+        cmd = [
+            self._binary,
+            subcommand,
+            "--store",
+            self.graph_uri,
+            *quiet,
+            *self._extra_args(subcommand),
+            *args,
+        ]
+        return self._execute(
+            cmd,
+            subcommand,
+            is_write=subcommand in _WRITE_SUBCOMMANDS,
+            surface_conflict=surface_conflict,
+        )
+
+    def _execute(
+        self,
+        cmd: list[str],
+        label: str,
+        *,
+        is_write: bool,
+        surface_conflict: bool = False,
+    ) -> str:
+        """Run an omnigraph CLI command under the write lock (for writes) with the
+        retry/repair loop for optimistic-concurrency conflicts."""
+        env = dict(os.environ)
+        if self.token:
+            env["OMNIGRAPH_SERVER_BEARER_TOKEN"] = self.token
+
+        lock_fh = self._acquire_write_lock(is_write)
+        try:
+            attempt = 0
+            admission_cap_attempt = 0
+            while True:
+                try:
+                    result = subprocess.run(
+                        cmd, capture_output=True, text=True, env=env
+                    )
+                except OSError as exc:
+                    raise RuntimeError(
+                        f"omnigraph {label} could not run: {exc}"
+                    ) from exc
+                if result.returncode == 0:
+                    return result.stdout
+                err = result.stderr
+                err_lower = err.lower()
+                if self._STORAGE_MISMATCH_HINT and _is_storage_version_mismatch(err):
+                    raise RuntimeError(
+                        _friendly_storage_error(err, self._STORAGE_MISMATCH_HINT)
+                    ) from None
+                if any(m in err_lower for m in _ADMISSION_CAP_MARKERS):
+                    # Independent budget/backoff from the drift retries below —
+                    # doesn't consume _MAX_ATTEMPTS and ignores surface_conflict.
+                    admission_cap_attempt += 1
+                    if admission_cap_attempt < _ADMISSION_CAP_MAX_ATTEMPTS:
+                        time.sleep(_admission_cap_backoff(admission_cap_attempt))
+                        continue
+                    raise RuntimeError(
+                        f"omnigraph {label} failed after "
+                        f"{_ADMISSION_CAP_MAX_ATTEMPTS} attempts (actor "
+                        f"admission cap exceeded):\n{err.strip()}"
+                    )
+                if surface_conflict and any(m in err_lower for m in _RETRYABLE):
+                    # A compare-and-swap caller wants to lose the race, not
+                    # re-apply its write over the winner. Surface immediately.
+                    raise OmnigraphConflict(err.strip()) from None
+                attempt += 1
+                if attempt < _MAX_ATTEMPTS:
+                    if any(m in err_lower for m in _NEEDS_REPAIR):
+                        self._repair(env)
+                        continue
+                    if any(m in err_lower for m in _RETRYABLE):
+                        time.sleep(0.05 * attempt)
+                        continue
+                raise RuntimeError(
+                    f"omnigraph {label} failed (exit {result.returncode}):\n"
+                    f"{err.strip()}"
+                )
+        finally:
+            if lock_fh is not None:
+                fcntl.flock(lock_fh.fileno(), fcntl.LOCK_UN)
+                lock_fh.close()
+
+    def _acquire_write_lock(self, is_write: bool):
+        """Hold a per-store exclusive lock for writes (local stores)."""
+        if not is_write or self.graph_uri.startswith(("http://", "https://", "s3://")):
+            return None
+        lock_path = Path(f"{self.graph_uri}.lock")
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        fh = open(lock_path, "w")  # noqa: SIM115 — released in _execute's finally
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        return fh
+
+    def _repair(self, env: dict) -> None:
+        """Reconcile manifest/HEAD drift so the retried write can proceed."""
+        subprocess.run(
+            [
+                self._binary,
+                "repair",
+                "--store",
+                self.graph_uri,
+                "--confirm",
+                "--force",
+                "--quiet",
+            ],
+            capture_output=True,
+            text=True,
+            env=env,
+        )
+
+    @classmethod
+    def _find_binary(cls) -> str:
+        binary = shutil.which("omnigraph")
+        if binary is not None:
+            return binary
+        # MCP servers are often launched by a desktop app or IDE extension
+        # whose process doesn't inherit a shell PATH — the `setup` command
+        # always installs to this fixed location, so check it directly rather
+        # than relying on PATH alone.
+        fallback = Path.home() / ".local" / "bin" / "omnigraph"
+        if fallback.exists():
+            return str(fallback)
+        raise RuntimeError(
+            f"omnigraph binary not found. Install via: {cls._SETUP_HINT}"
+        )