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

{witan_code-0.19.1 → 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.19.1 → witan_code-0.20.1}/CHANGELOG.md

@@ -6,7 +6,75 @@ 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
+
+### Changed
+
+- **Branch work goes through omnigraph 0.11 GQ statements, not the branch
+  CLI.** `list_branches`, `ensure_branch` and `delete_branch` now issue
+  `branch list` / `branch create` / `branch delete` on the same query and
+  mutate routes as every other read and write, so they share its transport,
+  retry policy and error classification. Against the cluster that removes a
+  subprocess per call, including on a branched client, which the named-query
+  path still cannot route over HTTP. Cedar still scopes these as branch
+  actions rather than as the route's `change`, so no actor gains authority it
+  did not have (verified against a 0.11.0 server running the code-graph
+  bundle).
+
+  Three behaviours of 0.11 this depends on, all measured against the 0.11.0
+  binary and server:
+
+  - A branch name must be QUOTED in the statement; an unquoted `act-x/v` is a
+    parse error. A `"` inside the quotes, on the other hand, PARSES fine (GQ
+    honours `\"`) and is then refused by the storage layer, so the guard is
+    against a statement that means something other than what was asked, not
+    against a syntax error. Names are checked against omnigraph's own rule,
+    which is Unicode `Alphabetic` or numeric plus `.`, `-`, `_` per
+    `/`-separated segment. That admits `café`, `act-x/дом`, and the combining
+    vowel signs of Indic, Hebrew and Arabic scripts (`कि`, `אָ`) that Python's
+    `\w` and `str.isalnum` both reject. A narrower charset would have made the
+    reaper refuse to delete views omnigraph created quite happily.
+  - A duplicate `branch create` answers HTTP 409, which `classify_status`
+    reads as retryable by status. So does the transient write-authority
+    precondition, and the two are indistinguishable. `ensure_branch` surfaces
+    conflicts and does its own re-list-and-retry, which resolves the first
+    without giving up the retry the second needs. That retry carries its own
+    backoff, because the engine's does not run under `surface_conflict`.
+  - `branch list` returns a `rows` envelope of `{"name": ...}`, not the old
+    `{"branches": [...]}`.
+
+- **Require `witan-core>=0.38`**, for `OmnigraphClient.statement`. The failure
+  without it is a runtime `AttributeError` on the first `list_branches()`, not
+  an import error, so `just check-core-floor` cannot catch it.
 
 ## [0.19.1] - 2026-09-18
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.19.1
+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
@@ -26,7 +26,7 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
 Requires-Dist: tree-sitter-typescript<0.24,>=0.23
 Requires-Dist: tree-sitter-yaml<0.8,>=0.7
 Requires-Dist: tree-sitter<0.26,>=0.25
-Requires-Dist: witan-core[cli,observability,remote,sentry]<1,>=0.37
+Requires-Dist: witan-core[cli,observability,remote,sentry]<1,>=0.38
 Provides-Extra: tasks
 Requires-Dist: fastmcp-tasks<5,>=4; extra == 'tasks'
 Description-Content-Type: text/markdown

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.19.1 → witan_code-0.20.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.19.1"
+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"
@@ -142,7 +142,7 @@ dependencies = [
     # parses the keyed `code-schema.pg`, and it restores the null fields 0.11
     # drops from query rows. An older witan-core imports fine and then fails
     # on the first schema init.
-    "witan-core[cli,remote,observability,sentry]>=0.37,<1",
+    "witan-core[cli,remote,observability,sentry]>=0.38,<1",
     "fastmcp>=4,<5",
     "cyclopts>=4,<5",
     # [targets.<name>] override models (config.py) — also transitively pulled
@@ -225,7 +225,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.19.1"
+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.19.1 → witan_code-0.20.1}/tests/test_branches.py

@@ -6,6 +6,8 @@ import subprocess
 
 import pytest
 
+from witan_core.omnigraph import OmnigraphConflict
+
 from witan_code import repo as repo_module
 
 from .conftest import SAMPLE, requires_stack
@@ -194,18 +196,36 @@ def test_a_view_opened_by_two_callers_at_once_is_not_an_error(tmp_path, monkeypa
 
 @requires_stack
 @pytest.mark.parametrize(
-    ("error", "listed"),
+    ("exc", "listed"),
     [
-        ("omnigraph branch failed (exit 1):\npermission denied", ["main"]),
+        (
+            RuntimeError("omnigraph mutate failed (exit 1):\npermission denied"),
+            ["main"],
+        ),
         # The message alone is not trusted: the branch has to actually be there.
         (
-            "omnigraph branch failed (exit 1):\nbranch 'feature_race' already exists",
+            RuntimeError(
+                "omnigraph mutate failed (exit 1):\n"
+                "branch 'feature_race' already exists"
+            ),
+            ["main"],
+        ),
+        # What the cluster raises for the same race. 0.11 answers a duplicate
+        # create with HTTP 409, `classify_status` reads a 409 as retryable, and
+        # `ensure_branch`'s `surface_conflict=True` is what turns that into this
+        # rather than a retry budget spent re-racing. `OmnigraphConflict` is a
+        # `RuntimeError`, so the recovery clause sees both shapes the same way —
+        # and still re-lists before deciding.
+        (
+            OmnigraphConflict(
+                "branch 'feature_race' already exists (HTTP 409, conflict)"
+            ),
             ["main"],
         ),
     ],
 )
 def test_a_create_failure_that_is_not_the_race_still_raises(
-    tmp_path, monkeypatch, error, listed
+    tmp_path, monkeypatch, exc, listed
 ):
     from witan_code import config as cfg_module
     from witan_code.graph import OmnigraphClient
@@ -217,12 +237,62 @@ def test_a_create_failure_that_is_not_the_race_still_raises(
     monkeypatch.setattr(client, "list_branches", lambda: listed)
 
     def fail(*_args, **_kwargs):
-        raise RuntimeError(error)
+        raise exc
 
-    monkeypatch.setattr(client, "_run", fail)
+    monkeypatch.setattr(client, "statement", fail)
     with pytest.raises(RuntimeError) as excinfo:
         client.ensure_branch()
-    assert str(excinfo.value) == error
+    assert excinfo.value is exc
+
+
+@requires_stack
+def test_a_conflicting_create_is_retried_a_bounded_number_of_spaced_times(
+    tmp_path, monkeypatch
+):
+    """The transient half of the 409, which the already-exists tests cannot see.
+
+    0.11 answers the write-authority precondition with a 409 as well, and
+    `classify_status` keys on the status, so `ensure_branch` cannot tell it
+    from a duplicate create. It retries for that one, and the retry has to be
+    both BOUNDED (a permanently conflicted graph must fail, not hang) and
+    SPACED (`_retry_loop` raises on the first retryable under
+    `surface_conflict`, before its own `time.sleep`, so three attempts inside
+    one listing round trip would be no wait at all for a writer mid-commit).
+
+    Neither property is visible in the other tests: they stub `list_branches`
+    to a fixed value and never count.
+    """
+    from witan_code import config as cfg_module
+    from witan_code import graph as graph_module
+    from witan_code.graph import OmnigraphClient
+
+    monkeypatch.setenv("WITAN_CODE_DIR", str(tmp_path / "code"))
+    client = OmnigraphClient(
+        str(tmp_path / "store"), cfg_module.load().queries_dir, branch="feature_race"
+    )
+    monkeypatch.setattr(client, "list_branches", lambda: ["main"])
+    slept: list[float] = []
+    monkeypatch.setattr(graph_module.time, "sleep", slept.append)
+
+    attempts = []
+
+    def always_conflicts(*_args, **_kwargs):
+        attempts.append(None)
+        raise OmnigraphConflict(
+            "write authority 'graph_head:main' changed during preparation "
+            "(HTTP 409, conflict)"
+        )
+
+    monkeypatch.setattr(client, "statement", always_conflicts)
+
+    with pytest.raises(OmnigraphConflict):
+        client.ensure_branch()
+
+    assert len(attempts) == graph_module._ENSURE_BRANCH_ATTEMPTS
+    assert slept == [
+        graph_module._ENSURE_BRANCH_BACKOFF_SECONDS * n
+        for n in range(1, graph_module._ENSURE_BRANCH_ATTEMPTS)
+    ], "retries must be spaced, not merely counted"
 
 
 @requires_stack

{witan_code-0.19.1 → 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)