witan-code 0.20.0__tar.gz → 0.20.1__tar.gz

{witan_code-0.20.0 → witan_code-0.20.1}/.gitignore

@@ -28,6 +28,10 @@ build/
 _bin/
 # omnigraph cluster state (populated by `omnigraph cluster import`)
 __cluster/
+# The witan UI bundle, written by `npm run build` in mcp/servers/witan/ui/.
+# A build output, so not committed — hatch's `artifacts` setting in that
+# package's pyproject.toml is what gets it into the sdist and the wheel anyway.
+mcp/servers/witan/witan/ui_dist/
 
 # MCP server logs / caches
 .mcp-cache/

{witan_code-0.20.0 → witan_code-0.20.1}/CHANGELOG.md

@@ -6,7 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
 a MINOR bump may include breaking changes).
 
-## [Unreleased]
+<!-- scriv-insert-here -->
+
+## [0.20.1] - 2026-09-22
+
+### Fixed
+
+- **Parallel agents in one worktree no longer race each other's code-graph
+  writes.** The PostToolUse `reindex-hook` indexed each edited file in the
+  foreground, one process per Edit/Write, so a session fanning out subagents
+  in one worktree put that many uncoordinated writers on one branch view.
+  Against a deployed graph they lost each other's optimistic-concurrency races
+  until the retry budget ran out (Sentry WITAN-12). Both hooks now put their
+  target on a per-checkout queue (SessionStart queues the project dir,
+  PostToolUse the edited file) and a single detached drainer applies it,
+  indexing each queued target once however many times it was queued.
+
+  The index now lands a few seconds after the edit instead of before the hook
+  returns. Outside a git checkout the hook still indexes in the foreground.
+
+  The per-checkout state is keyed on the git toplevel rather than
+  `CLAUDE_PROJECT_DIR`, so a session started in a monorepo subdirectory shares
+  its edits' lock. A SessionStart refresh that finds an indexer already
+  running is queued rather than dropped.
+
+  The lock is now a kernel `flock` handed to the drainer, so a killed indexer
+  no longer leaves the checkout locked until someone removes the lock by hand.
+  The lock, the queue and the last drainer's log live in a private 0700
+  `$TMPDIR/witan-code-<uid>/` rather than loose in a shared `/tmp`.
 
 ## [0.20.0] - 2026-09-21
 

{witan_code-0.20.0 → witan_code-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.20.0
+Version: 0.20.1
 Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
 Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
 Project-URL: Repository, https://github.com/mitodl/agent-kit

witan_code-0.20.1/changelog.d/README.md

@@ -0,0 +1,13 @@
+# Changelog fragments
+
+Each user-visible change gets its own fragment file here instead of an edit
+to `../CHANGELOG.md` — parallel branches editing the same lines in one shared
+file is what caused the version/changelog drift `bin/check_versions.py`
+exists to catch.
+
+Add one with `just changelog witan-code` (or `uvx scriv@1.8.0 create` from
+this directory's parent), fill in whichever category section(s) apply, and
+commit the file alongside your change. `just bump witan-code <part>` folds
+every pending fragment into `../CHANGELOG.md` under the new version heading
+and deletes them — it refuses to run if this directory holds nothing but this
+README.

{witan_code-0.20.0 → witan_code-0.20.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.20.0"
+version = "0.20.1"
 description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -225,7 +225,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.20.0"
+current_version = "0.20.1"
 allow_dirty = true
 
 [[tool.bumpversion.files]]
@@ -233,6 +233,14 @@ filename = "pyproject.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 
+[tool.scriv]
+format = "md"
+fragment_directory = "changelog.d"
+categories = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Performance", "Security", "Notes"]
+md_header_level = "2"
+md_html_anchors = false
+entry_title_template = "[{{ version }}] - {{ date.strftime('%Y-%m-%d') }}"
+
 # witan_code/queries/, witan_code/schema/, witan_code/queries_ts/,
 # witan_code/skills/, and witan_code/extensions/ are all discovered
 # automatically via packages = ["witan_code"] — including for a

{witan_code-0.20.0 → witan_code-0.20.1}/tests/test_context.py

@@ -8,6 +8,7 @@ check, store-exists branching), not the underlying query.
 import os
 import shutil
 import subprocess
+import tempfile
 import time
 from pathlib import Path
 
@@ -17,9 +18,11 @@ from witan_code import context
 
 
 def _lock(tmp_path, monkeypatch, project_dir):
+    """The busy marker `indexing_in_progress` reads; create it to fake a run."""
     monkeypatch.setenv("TMPDIR", str(tmp_path))
+    monkeypatch.setattr(tempfile, "tempdir", str(tmp_path))
     monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(project_dir))
-    return context._lock_path(project_dir)
+    return context._busy_path(project_dir)
 
 
 def _stub_store_stats(monkeypatch, health=None):
@@ -313,7 +316,7 @@ def test_the_bridge_verdict_is_cached_across_processes(tmp_path, monkeypatch):
 
 
 def test_lock_path_does_not_collide_on_sanitization(tmp_path, monkeypatch):
-    monkeypatch.setenv("TMPDIR", str(tmp_path))
+    monkeypatch.setattr(tempfile, "tempdir", str(tmp_path))
 
     a = context._lock_path(Path("/tmp/a/b"))
     b = context._lock_path(Path("/tmp/a_b"))
@@ -324,7 +327,7 @@ def test_lock_path_does_not_collide_on_sanitization(tmp_path, monkeypatch):
 def test_lock_path_name_is_bounded_regardless_of_project_dir_length(
     tmp_path, monkeypatch
 ):
-    monkeypatch.setenv("TMPDIR", str(tmp_path))
+    monkeypatch.setattr(tempfile, "tempdir", str(tmp_path))
     long_dir = Path("/" + ("deeply-nested-directory-" * 20) + "/checkout")
 
     lock = context._lock_path(long_dir)

witan_code-0.20.1/tests/test_hooks.py

@@ -0,0 +1,368 @@
+"""Unit tests for the SessionStart/PostToolUse hook logic in hooks.py.
+
+``indexer.index_path`` and process spawning are monkeypatched throughout:
+these tests exercise hooks.py's own orchestration (git-repo check, queueing,
+the lock handoff, stdin-JSON parsing, path resolution), not the real indexer
+or a real detached drainer. The lock itself is real: a kernel flock.
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+
+import pytest
+
+from witan_code import context, hooks
+
+
+@pytest.fixture
+def _state(tmp_path, monkeypatch):
+    tmp = tmp_path / "tmp"
+    tmp.mkdir()
+    monkeypatch.setenv("TMPDIR", str(tmp))
+    monkeypatch.setattr(tempfile, "tempdir", str(tmp))
+    return tmp
+
+
+@pytest.fixture
+def _repo(tmp_path, monkeypatch, _state):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    subprocess.run(["git", "init", "-q", str(repo)], check=True)
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(repo))
+    return hooks.repo_module.root(repo)
+
+
+@pytest.fixture
+def _spawned(monkeypatch):
+    calls = []
+    monkeypatch.setattr(
+        hooks, "popen_detached", lambda argv, **kw: calls.append((argv, kw))
+    )
+    return calls
+
+
+@pytest.fixture
+def _indexed(monkeypatch):
+    calls = []
+    monkeypatch.setattr(hooks.indexer, "index_path", lambda p, force: calls.append(p))
+    return calls
+
+
+def _payload(path) -> str:
+    return f'{{"tool_input": {{"file_path": "{path}"}}}}'
+
+
+# ── session_init ──────────────────────────────────────────────────────────────
+
+
+def test_session_init_noop_outside_git_repo(tmp_path, monkeypatch, _state, _spawned):
+    non_repo = tmp_path / "not-a-repo"
+    non_repo.mkdir()
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(non_repo))
+
+    hooks.session_init()
+
+    assert _spawned == []
+
+
+def test_session_init_queues_the_project_and_hands_the_lock_to_a_drainer(
+    _repo, _spawned
+):
+    hooks.session_init()
+
+    assert len(_spawned) == 1
+    argv, kwargs = _spawned[0]
+    assert argv[1:5] == ["-m", "witan_code", "_drain-pending", str(_repo)]
+    assert kwargs["pass_fds"] == (int(argv[5]),)
+    assert hooks._take_pending(_repo) == [_repo]
+    # Busy from the moment the lock is taken, before the drainer is even up.
+    assert context.indexing_in_progress() is True
+
+
+def test_session_init_in_a_subdirectory_shares_the_toplevel_s_lock(
+    _repo, monkeypatch, _spawned
+):
+    """A session started in a monorepo subdirectory must not get a lock of its
+    own: its full index and the edits' drainer write the same branch view."""
+    sub = _repo / "services" / "api"
+    sub.mkdir(parents=True)
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(sub))
+    held = hooks._try_lock(_repo)
+
+    hooks.session_init()
+
+    os.close(held)
+    assert _spawned == []
+    assert hooks._take_pending(_repo) == [sub]  # queued, not dropped
+
+
+def test_session_init_survives_a_failed_spawn(_repo, monkeypatch):
+    def _boom(*a, **k):
+        raise OSError("cannot spawn")
+
+    monkeypatch.setattr(hooks, "popen_detached", _boom)
+
+    hooks.session_init()
+
+    fd = hooks._try_lock(_repo)
+    assert fd is not None  # released for the next hook
+    os.close(fd)
+    assert hooks._has_pending(_repo)  # and the refresh is still queued
+    assert context.indexing_in_progress() is False
+
+
+# ── reindex_hook outside a repo ───────────────────────────────────────────────
+
+
+def test_reindex_hook_noop_on_empty_payload(_indexed):
+    hooks.reindex_hook("")
+    assert _indexed == []
+
+
+def test_reindex_hook_noop_on_malformed_json(_indexed):
+    hooks.reindex_hook("not json")
+    assert _indexed == []
+
+
+def test_reindex_hook_noop_without_tool_input(_indexed):
+    hooks.reindex_hook('{"tool_name": "Edit"}')
+    assert _indexed == []
+
+
+def test_reindex_hook_noop_when_file_missing(tmp_path, _indexed):
+    hooks.reindex_hook(_payload(tmp_path / "does-not-exist.py"))
+    assert _indexed == []
+
+
+def test_reindex_hook_outside_a_repo_indexes_in_the_foreground(tmp_path, _indexed):
+    target = tmp_path / "a.py"
+    target.write_text("def f(): pass")
+
+    hooks.reindex_hook(_payload(target))
+
+    assert _indexed == [target]
+
+
+def test_reindex_hook_resolves_relative_path_against_cwd(
+    tmp_path, monkeypatch, _indexed
+):
+    monkeypatch.chdir(tmp_path)
+    target = tmp_path / "b.py"
+    target.write_text("def g(): pass")
+
+    hooks.reindex_hook('{"tool_input": {"path": "b.py"}}')
+
+    assert _indexed == [target]
+
+
+def test_reindex_hook_swallows_index_failure(tmp_path, monkeypatch):
+    target = tmp_path / "c.py"
+    target.write_text("def h(): pass")
+
+    def _boom(p, force):
+        raise RuntimeError("parse error")
+
+    monkeypatch.setattr(hooks.indexer, "index_path", _boom)
+
+    hooks.reindex_hook(
+        f'{{"tool_input": {{"filename": "{target}"}}}}'
+    )  # must not raise
+
+
+# ── reindex_hook inside a repo ────────────────────────────────────────────────
+
+
+def test_reindex_hook_in_a_repo_queues_and_spawns_a_drainer(_repo, _spawned, _indexed):
+    target = _repo / "a.py"
+    target.write_text("def f(): pass")
+
+    hooks.reindex_hook(_payload(target))
+
+    assert _indexed == []  # the drainer writes, not the hook
+    assert [argv[1:5] for argv, _ in _spawned] == [
+        ["-m", "witan_code", "_drain-pending", str(_repo)]
+    ]
+    assert hooks._take_pending(_repo) == [target]
+
+
+def test_reindex_hook_leaves_the_path_to_a_running_drainer(_repo, _spawned):
+    target = _repo / "a.py"
+    target.write_text("def f(): pass")
+    held = hooks._try_lock(_repo)
+
+    hooks.reindex_hook(_payload(target))
+
+    os.close(held)
+    assert _spawned == []
+    assert hooks._take_pending(_repo) == [target]
+
+
+# ── drain_pending ─────────────────────────────────────────────────────────────
+
+
+def test_drain_pending_indexes_each_queued_target_once_and_releases(_repo, _indexed):
+    a, b = _repo / "a.py", _repo / "b.py"
+    for path in (a, b):
+        path.write_text("x = 1")
+    for path in (a, b, a, a):
+        hooks._enqueue(_repo, path)
+
+    hooks.drain_pending(_repo, hooks._try_lock(_repo))
+
+    assert _indexed == [a, b]
+    assert not hooks._has_pending(_repo)
+    assert not context._busy_path(_repo).exists()
+    fd = hooks._try_lock(_repo)
+    assert fd is not None
+    os.close(fd)
+
+
+def test_drain_pending_picks_up_a_target_queued_while_it_held_the_lock(
+    _repo, monkeypatch
+):
+    a, b = _repo / "a.py", _repo / "b.py"
+    for path in (a, b):
+        path.write_text("x = 1")
+    hooks._enqueue(_repo, a)
+    indexed = []
+
+    def _index(p, force):
+        indexed.append(p)
+        if p == a:
+            # An edit landing mid-drain: its hook finds the lock held and
+            # leaves the path to this drainer's re-check.
+            assert hooks._try_lock(_repo) is None
+            hooks._enqueue(_repo, b)
+
+    monkeypatch.setattr(hooks.indexer, "index_path", _index)
+
+    hooks.drain_pending(_repo, hooks._try_lock(_repo))
+
+    assert indexed == [a, b]
+
+
+def test_drain_pending_marks_the_checkout_busy_while_it_works(_repo, monkeypatch):
+    a = _repo / "a.py"
+    a.write_text("x = 1")
+    hooks._enqueue(_repo, a)
+    seen = []
+    monkeypatch.setattr(
+        hooks.indexer,
+        "index_path",
+        lambda p, force: seen.append(context.indexing_in_progress()),
+    )
+
+    hooks.drain_pending(_repo, hooks._try_lock(_repo))
+
+    assert seen == [True]
+    assert context.indexing_in_progress() is False
+
+
+def test_drain_pending_skips_a_target_deleted_since_it_was_queued(_repo, _indexed):
+    hooks._enqueue(_repo, _repo / "gone.py")
+
+    hooks.drain_pending(_repo, hooks._try_lock(_repo))
+
+    assert _indexed == []
+    assert not hooks._has_pending(_repo)
+
+
+def test_drain_pending_continues_past_a_failing_target(_repo, monkeypatch):
+    a, b = _repo / "a.py", _repo / "b.py"
+    for path in (a, b):
+        path.write_text("x = 1")
+        hooks._enqueue(_repo, path)
+    indexed = []
+
+    def _index(p, force):
+        if p == a:
+            raise RuntimeError("write authority changed during preparation")
+        indexed.append(p)
+
+    monkeypatch.setattr(hooks.indexer, "index_path", _index)
+
+    hooks.drain_pending(_repo, hooks._try_lock(_repo))
+
+    assert indexed == [b]
+    fd = hooks._try_lock(_repo)
+    assert fd is not None  # released despite the failure
+    os.close(fd)
+
+
+# ── lock and state ────────────────────────────────────────────────────────────
+
+
+def test_a_killed_holder_does_not_leave_the_checkout_locked(_repo):
+    """The reason the lock is a flock: the kernel drops it with the process,
+    so nothing has to decide whether a recorded holder is still alive."""
+    holder = subprocess.Popen(
+        [
+            sys.executable,
+            "-c",
+            "import fcntl, os, sys, time; "
+            "fd = os.open(sys.argv[1], os.O_RDWR | os.O_CREAT); "
+            "fcntl.flock(fd, fcntl.LOCK_EX); print('held', flush=True); "
+            "time.sleep(60)",
+            str(context._lock_path(_repo)),
+        ],
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    assert holder.stdout.readline().strip() == "held"
+    assert hooks._try_lock(_repo) is None
+
+    holder.kill()
+    holder.wait()
+
+    fd = hooks._try_lock(_repo)
+    assert fd is not None
+    os.close(fd)
+
+
+def test_state_dir_is_private(_state):
+    path = context.state_dir()
+
+    assert path.stat().st_mode & 0o777 == 0o700
+    assert path.stat().st_uid == os.getuid()
+
+
+def test_state_dir_tightens_an_existing_directory_s_mode(_state):
+    path = _state / f"witan-code-{os.getuid()}"
+    path.mkdir(mode=0o777)
+    path.chmod(0o777)
+
+    assert context.state_dir().stat().st_mode & 0o777 == 0o700
+
+
+def test_state_dir_refuses_a_symlink_planted_in_its_place(_state, tmp_path):
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    (_state / f"witan-code-{os.getuid()}").symlink_to(elsewhere)
+
+    with pytest.raises(PermissionError):
+        context.state_dir()
+
+
+def test_sessions_with_different_witan_overrides_get_separate_drainers(
+    _repo, monkeypatch
+):
+    """The drainer indexes with its spawner's environment, so an edit made
+    under ``WITAN_TARGET=qa`` must not be applied by a drainer spawned without
+    it."""
+    monkeypatch.delenv("WITAN_TARGET", raising=False)
+    held = hooks._try_lock(_repo)
+
+    monkeypatch.setenv("WITAN_TARGET", "qa")
+    other = hooks._try_lock(_repo)
+
+    assert other is not None
+    os.close(other)
+    os.close(held)
+
+
+def test_a_path_with_a_newline_is_not_queued(_repo):
+    hooks._enqueue(_repo, _repo / "a\nb.py")
+
+    assert not hooks._has_pending(_repo)

witan_code-0.20.1/tests/test_refusal_audit.py

@@ -0,0 +1,48 @@
+"""witan-code's own refusals declare the log-safety their messages actually have.
+
+Counterpart to ``mcp/servers/witan/tests/test_refusal_audit.py``; see that
+module's docstring for why the table in witan-core's suite cannot cover these.
+
+See ``witan_core.refusal.Refusal.log_safe_message``.
+"""
+
+import pytest
+
+from witan_code.ingest import IngestRefused
+from witan_code.store import ClusterGraphMissing
+
+EXPECTED_LOG_SAFE = {
+    # A repo, a graph id and a provisioning hint. The message whose absence
+    # made Production's 27% `code_store_views` failure rate undiagnosable.
+    ClusterGraphMissing: True,
+    # WITHHELD. `_step_field` raises it as `f"...got {value!r}."` over the
+    # caller's own step, and two more sites raise `IngestRefused(str(exc))`
+    # over an arbitrary upstream exception.
+    IngestRefused: False,
+}
+
+
+@pytest.mark.parametrize(("cls", "expected"), list(EXPECTED_LOG_SAFE.items()))
+def test_refusal_opt_in_matches_the_audit(cls, expected):
+    assert cls.log_safe_message is expected
+
+
+def test_every_witan_code_refusal_is_in_the_table():
+    """A new refusal here has to be read before it can opt in."""
+    from witan_core.refusal import Refusal
+
+    def walk(base):
+        for sub in base.__subclasses__():
+            yield sub
+            yield from walk(sub)
+
+    ours = {
+        sub
+        for sub in walk(Refusal)
+        if sub.__module__.startswith("witan_code.")
+        and sub.__dict__.get("log_safe_message") is True
+    }
+    assert ours <= set(EXPECTED_LOG_SAFE), (
+        f"opted in without an audit entry: "
+        f"{sorted(c.__name__ for c in ours - set(EXPECTED_LOG_SAFE))}"
+    )

{witan_code-0.20.0 → witan_code-0.20.1}/witan_code/cli.py

@@ -885,9 +885,10 @@ def session_init_cmd() -> None:
     """Seed/refresh the whole repo's code graph in the background (SessionStart hook).
 
     Detached and non-blocking — returns immediately regardless of repo size.
-    A per-repo lock (shared with ``inject-context``'s "indexing in progress"
-    check) prevents overlapping sessions from indexing at once. Registered as
-    the bare ``SessionStart`` hook command; not usually run by hand.
+    The refresh goes on the same per-checkout queue as ``reindex-hook``'s
+    edits, so one drainer at a time writes the checkout's code graph.
+    Registered as the bare ``SessionStart`` hook command; not usually run by
+    hand.
     """
     from . import hooks as hooks_module
 
@@ -897,12 +898,12 @@ def session_init_cmd() -> None:
         pass
 
 
-@app.command(name="_index-and-unlock", show=False)
-def _index_and_unlock_cmd(target: Path, lock: Path) -> None:
-    """Internal — run only by the detached child ``session-init`` spawns."""
+@app.command(name="_drain-pending", show=False)
+def _drain_pending_cmd(checkout: Path, lock_fd: int) -> None:
+    """Internal — run only by the detached drainer the two hooks spawn."""
     from . import hooks as hooks_module
 
-    hooks_module.index_and_unlock(target, lock)
+    hooks_module.drain_pending(checkout, lock_fd)
 
 
 @app.command(name="reindex-hook")
@@ -910,9 +911,11 @@ def reindex_hook_cmd() -> None:
     """Incrementally reindex the file named in stdin's hook JSON (PostToolUse hook).
 
     Reads the Claude Code hook payload from stdin, extracts
-    ``tool_input.file_path`` (or ``path``/``filename``), and reindexes it if
-    it exists and is a known source type — foreground and fast (one file), so
-    the agent sees the change land immediately. Best-effort: a missing or
+    ``tool_input.file_path`` (or ``path``/``filename``), and queues it for
+    reindexing if it exists. One detached drainer per checkout applies the
+    queue, so parallel agents editing one worktree do not race each other's
+    writes to its branch view. Logs from the last drainer are kept in
+    ``$TMPDIR/witan-code-<uid>/``. Best-effort: a missing or
     malformed payload is a silent no-op. Registered as the bare
     ``PostToolUse`` (matcher ``Edit|Write``) hook command; not usually run by
     hand.