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

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

@@ -8,6 +8,54 @@ a MINOR bump may include breaking changes).
 
 ## [Unreleased]
 
+## [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
+
+### Changed
+
+- **Require `witan-core>=0.37`.** This keeps fresh `witan-code` installs on the
+  current shared core release alongside `witan-council`.
+
 ## [0.19.0] - 2026-09-16
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.19.0
+Version: 0.20.0
 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.36
+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.19.0 → witan_code-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.19.0"
+version = "0.20.0"
 description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -137,12 +137,12 @@ dependencies = [
     # ★ >=0.35 IS AN IMPORT FLOOR too: `store.py` and `ingest.py` import
     # `witan_core.refusal`, added in witan-core 0.35.0 in the same change.
     #
-    # ★ >=0.36 IS A FORMAT FLOOR, and the silent kind: nothing new is imported,
-    # but 0.36.0 is the release that installs omnigraph 0.11, the only binary
-    # that parses the keyed `code-schema.pg`, and restores the null fields 0.11
+    # ★ >=0.37 KEEPS BOTH SERVERS ON THE CURRENT SHARED CORE RELEASE. It also
+    # preserves >=0.36's format floor: omnigraph 0.11 is the only binary that
+    # 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.36,<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.0"
+current_version = "0.20.0"
 allow_dirty = true
 
 [[tool.bumpversion.files]]

{witan_code-0.19.0 → witan_code-0.20.0}/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.0 → witan_code-0.20.0}/tests/test_reaper.py

@@ -17,7 +17,11 @@ import pytest
 
 from witan_code import config as cfg_module
 from witan_code import reaper as reaper_module
-from witan_code.graph import OmnigraphClient
+from witan_code.graph import (
+    OmnigraphClient,
+    UnquotableBranchName,
+    _gq_branch_name,
+)
 from witan_code.reaper import ViewAge, reap, select_stale
 
 from .conftest import requires_omnigraph
@@ -207,6 +211,49 @@ def test_one_undeletable_view_does_not_strand_the_sweep():
     assert report.failed == [("act-alice/ancient", "branch is locked")]
 
 
+def test_a_name_the_client_cannot_quote_is_recorded_rather_than_raised():
+    """The same rule, for the one failure this client can produce BEFORE it
+    reaches the engine. `branch list` returns whatever any client ever created,
+    so a name outside `_QUOTABLE_BRANCH` is reachable here and nowhere else.
+
+    It is pinned because the exception TYPE is load-bearing and invisible: the
+    handler above catches `RuntimeError`, `select_stale` sorts oldest-first,
+    and a sibling type would therefore abort the sweep at the oldest poison
+    name, stranding every newer stale view behind it and returning no report at
+    all.
+    """
+
+    class _WithAnUnquotableName(_FakeClient):
+        def list_branches(self):
+            return ['act-alice/we"ird', "act-bob/older"]
+
+        def branch_last_write(self, name):
+            # Oldest first out of `select_stale`, so the bad one is reached
+            # before the good one, which is the case that used to strand.
+            return NOW - (500 * DAY if '"' in name else 400 * DAY)
+
+        def delete_branch(self, name):
+            _gq_branch_name(name)  # what the real client does first
+            super().delete_branch(name)
+
+    report = reap(
+        _WithAnUnquotableName(is_remote=False),
+        graph="local",
+        now=NOW,
+        max_idle=14,
+        apply=True,
+    )
+
+    assert report.deleted == ["act-bob/older"]
+    assert [view for view, _ in report.failed] == ['act-alice/we"ird']
+
+
+def test_the_unquotable_name_error_is_a_runtime_error():
+    """What the test above rests on, stated directly so a change to the class
+    fails here rather than as a stranded sweep."""
+    assert issubclass(UnquotableBranchName, RuntimeError)
+
+
 def test_a_disabled_window_ages_nothing_rather_than_ageing_and_discarding():
     """`select_stale` would return nothing anyway — but only after a
     `commit list` subprocess per view. On a shared graph carrying every

{witan_code-0.19.0 → witan_code-0.20.0}/tests/test_store.py

@@ -5,6 +5,7 @@ reads and per-entry Path construction. That makes their edge cases (an empty
 store, an unreadable one, a dangling symlink) worth pinning explicitly.
 """
 
+import json
 import os
 import threading
 import time
@@ -613,6 +614,67 @@ def test_the_local_fallback_hint_names_the_setting_actually_routing(monkeypatch)
     assert "code_server" not in str(exc.value)
 
 
+class _NotFoundConnection:
+    """An omnigraph-server that serves no graph, answering as 0.11.0 does.
+
+    Body and status measured against a real `omnigraph-server --cluster`
+    (0.11.0, 2026-09-21): `POST /graphs/nosuch/query` with a `branch list`
+    statement answers `404 {"error": "graph 'nosuch' not found", "code":
+    "not_found"}`.
+    """
+
+    def __init__(self, host, port=None, timeout=None, context=None):
+        self.host = host
+
+    def connect(self):
+        pass
+
+    def request(self, method, path, body=None, headers=None):
+        pass
+
+    def getresponse(self):
+        class _Response:
+            status = 404
+            will_close = False
+
+            def read(self):
+                return json.dumps(
+                    {"error": "graph 'nosuch' not found", "code": "not_found"}
+                ).encode()
+
+            def getheader(self, _name, default=None):
+                return default
+
+        return _Response()
+
+    def close(self):
+        pass
+
+
+def test_a_missing_cluster_graph_is_still_recognised_over_http(monkeypatch):
+    """★ THE WORDING `_NOT_FOUND_RE` KEYS ON NOW ARRIVES FROM THE SERVER.
+
+    `list_branches` was unconditionally a subprocess, so `_NOT_FOUND_RE` was
+    tuned against what the CLI printed (see the comment above it). It is a
+    `branch list` statement now, so a remote client takes the pooled transport
+    and this discrimination runs on the HTTP body instead. If the server ever
+    stops quoting the id, every missing graph files as `ClusterUnreachable`
+    rather than `ClusterGraphMissing`, which is the exact confusion those two
+    types exist to prevent — and nothing else in the suite would notice,
+    because every other probe test fakes the client.
+    """
+    monkeypatch.setattr(http_module.http.client, "HTTPSConnection", _NotFoundConnection)
+    monkeypatch.setattr(http_module.http.client, "HTTPConnection", _NotFoundConnection)
+    monkeypatch.setenv("WITAN_CODE_SERVER", "https://omnigraph.test")
+    from witan_code import config as cfg_module
+
+    cfg = cfg_module.load()
+    ref = store_module.StoreRef(uri="https://omnigraph.test", graph_id="nosuch")
+
+    with pytest.raises(store_module.ClusterGraphMissing):
+        store_module.probe_cluster_graph(ref, "code-nosuch", cfg)
+
+
 def test_a_failed_listing_is_not_cached(monkeypatch):
     """A transient outage must not pin an error for the whole TTL — the next
     call has to be able to succeed."""

{witan_code-0.19.0 → witan_code-0.20.0}/witan_code/graph.py

@@ -9,10 +9,12 @@ bulk ``load`` used to write thousands of symbol/edge records in one call.
 from __future__ import annotations
 
 import json
+import time
+import unicodedata
 from pathlib import Path
 
 from witan_core.omnigraph import OmnigraphClient as _BaseOmnigraphClient
-from witan_core.omnigraph import _is_storage_version_mismatch
+from witan_core.omnigraph import OmnigraphConflict, _is_storage_version_mismatch
 
 from witan_core import chunking
 from . import config as cfg_module
@@ -22,6 +24,7 @@ from . import views
 __all__ = [
     "OmnigraphClient",
     "SharedGraphWriteRefused",
+    "UnquotableBranchName",
     "check_writable",
     "is_stale_schema",
     "owns_view",
@@ -38,6 +41,100 @@ class SharedGraphWriteRefused(RuntimeError):
     """A writer tried to write a view of a shared graph it does not own."""
 
 
+class UnquotableBranchName(RuntimeError):
+    """A branch name that cannot be written into a GQ branch statement.
+
+    A ``RuntimeError`` on purpose: the names that reach :func:`_gq_branch_name`
+    from outside this package come from ``branch list``, so the reaper meets
+    them one at a time and must record the bad one in ``report.failed`` and
+    carry on. Its handler catches ``RuntimeError``, and a sibling type would
+    abort the whole sweep at the oldest poison name, stranding every newer
+    stale view behind it.
+    """
+
+
+#: Punctuation a branch name may carry: what omnigraph allows inside a segment,
+#: plus the ``/`` that separates them.
+_BRANCH_PUNCTUATION = frozenset("._-/")
+
+#: Unicode categories that are alphabetic to the ENGINE but not to Python.
+#: omnigraph validates a segment as "alphanumeric, '.', '-', '_'", where
+#: "alphanumeric" is Rust's ``char::is_alphanumeric``, whose alphabetic half is
+#: the Unicode ``Alphabetic`` property. That property includes
+#: ``Other_Alphabetic`` — the combining vowel signs of Indic, Hebrew and Arabic
+#: scripts — which ``str.isalnum`` and ``\w`` both exclude. Measured against
+#: 0.11.0: ``branch create "कि"`` (U+0915 Lo, U+093F Mc) succeeds.
+_BRANCH_COMBINING_CATEGORIES = frozenset({"Mn", "Mc"})
+
+#: How many times :meth:`OmnigraphClient.ensure_branch` re-lists and retries
+#: after a 409, and how long it spaces them. Small on purpose: the
+#: duplicate-create case resolves on the SECOND listing, and the transient
+#: precondition it also covers is a writer mid-commit rather than a queue to
+#: wait out. The sleep is not optional though — see ``ensure_branch``, the
+#: engine's own backoff does not run under ``surface_conflict``.
+_ENSURE_BRANCH_ATTEMPTS = 3
+_ENSURE_BRANCH_BACKOFF_SECONDS = 0.05
+
+
+def _is_quotable_branch(name: str) -> bool:
+    """Whether every character of ``name`` is one omnigraph accepts.
+
+    Deliberately the ENGINE'S rule rather than witan-code's own sanitizers.
+    Every name this package builds is inside it either way, so the only names
+    this decides are the ones ``branch list`` returns, which are whatever any
+    client ever created. A guard NARROWER than the engine refuses those, which
+    is not a theoretical loss: it is the reaper declining to delete a view
+    omnigraph made quite happily, and ``config.sanitize_slug`` only collapses
+    ``[/:]+``, so a bridge view for a repo with such a name is one witan-code
+    builds itself.
+
+    Not a regex, because the character class cannot be written as one without
+    either ``regex``'s ``\\p{Alphabetic}`` (not a dependency) or a hand-rolled
+    range table that would rot against each Unicode revision.
+
+    Still narrower than the engine in one harmless direction: ``..`` passes
+    here and omnigraph refuses it (``Branch name cannot contain '..'``), which
+    only changes which layer reports it.
+    """
+    return bool(name) and all(
+        char.isalnum()
+        or char in _BRANCH_PUNCTUATION
+        or unicodedata.category(char) in _BRANCH_COMBINING_CATEGORIES
+        for char in name
+    )
+
+
+def _gq_branch_name(name: str) -> str:
+    """``name`` as a GQ string literal, or raise :class:`UnquotableBranchName`.
+
+    A branch statement needs its name QUOTED. Verified against the 0.11.0
+    binary: ``branch create act-x/feat_y from main`` is a ``parse error``, and
+    ``branch create "act-x/feat_y" from main`` succeeds.
+
+    GQ *does* honour ``\\"`` inside the quotes, so the danger is not that a
+    ``"`` fails to parse. It is that it parses fine and the statement then
+    means something other than what the caller asked. What refuses
+    ``"we\\"ird"`` is the storage layer, one level down and after the parse:
+    ``storage: Ref is invalid: Branch segment 'we"ird.<ulid>' contains invalid
+    characters``. So :func:`_is_quotable_branch`, which admits no ``"`` and no
+    ``\\``, is what keeps a name from reaching that point at all. Nor can
+    anything it admits smuggle in a second statement: every character it
+    accepts is alphanumeric, a combining mark, or one of ``._-/``, and none of
+    those is a quote, a backslash, a separator or whitespace.
+
+    Unreachable for a name this package built. The ones that do not come from
+    here are whatever ``branch list`` returns, which is whatever any client
+    ever created on the store.
+    """
+    if not _is_quotable_branch(name):
+        raise UnquotableBranchName(
+            f"branch name {name!r} cannot be written as an omnigraph GQ "
+            "statement: it has characters outside the alphanumerics, combining "
+            "marks and `._-/` that omnigraph allows in a branch name."
+        )
+    return f'"{name}"'
+
+
 def owns_view(
     *,
     is_remote: bool,
@@ -210,44 +307,110 @@ class OmnigraphClient(_BaseOmnigraphClient):
     # ── Branch operations ─────────────────────────────────────────
 
     def list_branches(self) -> list[str]:
-        """Names of all branches on this store (includes ``main``)."""
-        result = self._run("branch", "list", "--json")
+        """Names of all branches on this store (includes ``main``).
+
+        0.11's ``branch list`` GQ statement on the canonical read route
+        (upstream RFC 0055), not an ``omnigraph branch list`` subprocess, so
+        branch reads share the transport, retry policy and error
+        classification of every other read — see
+        :meth:`~witan_core.omnigraph.OmnigraphClient.statement`. Against the
+        cluster that is an HTTP POST rather than a process, including on a
+        branched client, which the named-query path still cannot use.
+
+        One row per branch, ``{"name": ...}``, under the same ``rows``
+        envelope a named read returns — verified identical on both transports
+        against the 0.11.0 binary and the 0.11.0 server.
+        """
+        result = self.statement(
+            "query", "branch list", "--format", "json", label="branch list"
+        )
         try:
             parsed = json.loads(result)
         except json.JSONDecodeError:
             return []
-        rows = parsed.get("branches", parsed) if isinstance(parsed, dict) else parsed
+        rows = parsed.get("rows", parsed) if isinstance(parsed, dict) else parsed
         if not isinstance(rows, list):
             return []
-        out: list[str] = []
-        for row in rows:
-            name = row.get("name") if isinstance(row, dict) else row
-            if isinstance(name, str):
-                out.append(name)
-        return out
+        return [
+            row["name"]
+            for row in rows
+            if isinstance(row, dict) and isinstance(row.get("name"), str)
+        ]
 
     def ensure_branch(self) -> None:
         """Create ``self.branch`` from main if it doesn't exist yet.
 
         Needed before the first *read* on a new branch — reads never fork
         (only ``load --from`` does), so a read against a missing branch errors.
+
+        ★ TWO DIFFERENT 409s ARRIVE HERE AND ONLY ONE IS THIS METHOD'S RACE.
+        0.11 answers a duplicate create with ``branch 'x' already exists``, and
+        it answers a lost write-authority precondition (``write authority
+        'graph_head:main' changed during preparation``) with a 409 too.
+        ``classify_status`` keys on the status, so it cannot tell them apart,
+        and reads both as RETRYABLE.
+
+        Neither default is right on its own. Retrying silently would spend the
+        whole budget, backoff sleeps included, re-racing a branch that is
+        already there; ``surface_conflict=True`` alone would turn the genuinely
+        transient precondition into a hard failure of ``code_store_open``,
+        where the old CLI path rode it out. So conflicts are surfaced AND the
+        retry is put back here, around a fresh listing, which is what makes the
+        duplicate case resolve as "it exists, we are done" instead of as
+        another doomed attempt.
+
+        ★ INCLUDING THE BACKOFF, which does not survive ``surface_conflict``.
+        ``_retry_loop`` raises on the FIRST retryable classification when it is
+        set, before it increments the attempt counter and before its
+        ``time.sleep``, so the engine's schedule never runs. Left to the
+        listing round trip alone the three attempts here would fall inside
+        ~10ms, which is no wait at all for a writer that is mid-commit: the
+        transient case would fail about as reliably as it did before the retry
+        was restored. The sleep below is what makes these attempts SPACED
+        rather than merely counted.
+
+        The CLI path produces neither 409: its already-exists is prose matching
+        no marker, classifies FATAL, and lands in the ``RuntimeError`` clause.
         """
-        if self.branch is None or self.branch in self.list_branches():
+        if self.branch is None:
             return
-        try:
-            self._run("branch", "create", self.branch, "--from", "main")
-        except RuntimeError as exc:
-            # Two concurrent `code_store_open` calls for one view both see it
-            # missing, and the second create fails. The branch exists either
-            # way, which is all this method promises. Re-listing confirms that
-            # rather than trusting the message alone.
-            if "already exists" not in str(exc) or self.branch not in (
-                self.list_branches()
-            ):
-                raise
+        create = f"branch create {_gq_branch_name(self.branch)} from main"
+        conflict: RuntimeError | None = None
+        for attempt in range(_ENSURE_BRANCH_ATTEMPTS):
+            if attempt:
+                time.sleep(_ENSURE_BRANCH_BACKOFF_SECONDS * attempt)
+            if self.branch in self.list_branches():
+                return
+            try:
+                self.statement(
+                    "mutate", create, label="branch create", surface_conflict=True
+                )
+                return
+            except OmnigraphConflict as exc:
+                conflict = exc
+            except RuntimeError as exc:
+                # The CLI's own already-exists. Two concurrent
+                # `code_store_open` calls for one view both saw it missing and
+                # both tried to create it. Anything else is a real failure.
+                if "already exists" not in str(exc):
+                    raise
+                conflict = exc
+        # The message alone is never trusted: the branch has to actually be
+        # there, which is all this method promises. `conflict` cannot be None:
+        # every iteration either returns, re-raises, or assigns it.
+        if self.branch not in self.list_branches():
+            raise conflict
 
     def delete_branch(self, name: str) -> None:
-        self._run("branch", "delete", name, "--yes")
+        # `--yes` is for the CLI path only, where a destructive write against a
+        # non-local scope refuses without it; the HTTP route has no prompt to
+        # skip and ignores flags entirely.
+        self.statement(
+            "mutate",
+            f"branch delete {_gq_branch_name(name)}",
+            "--yes",
+            label="branch delete",
+        )
 
     def branch_last_write(self, name: str) -> float | None:
         """When ``name`` was last written, as epoch seconds, or ``None``.
@@ -305,15 +468,14 @@ class OmnigraphClient(_BaseOmnigraphClient):
     def _extra_args(self, subcommand: str) -> list[str]:
         # optimize/cleanup compact the whole store (every branch), not a single
         # one, so they never take --branch even on a branched client. `commit`
-        # and `branch` name their branch positionally or as their own flag, so
-        # injecting this client's would either duplicate the flag or silently
-        # retarget the call.
-        if self.branch is None or subcommand in (
-            "branch",
-            "commit",
-            "optimize",
-            "cleanup",
-        ):
+        # names its branch as its own flag, so injecting this client's would
+        # either duplicate it or silently retarget the call.
+        #
+        # `branch` is NOT in this list any more because nothing runs it: branch
+        # work goes through `statement`, which bypasses `_extra_args` entirely
+        # (a GQ branch statement takes no --branch). Re-adding the subcommand
+        # here would be dead code, not a safety net.
+        if self.branch is None or subcommand in ("commit", "optimize", "cleanup"):
             return []
         if subcommand == "load":
             return ["--branch", self.branch, "--from", "main"]

{witan_code-0.19.0 → witan_code-0.20.0}/witan_code/store.py

@@ -562,7 +562,7 @@ def probe_cluster_graph(ref: StoreRef, what: str, cfg: cfg_module.Config) -> Sto
     records into one error per subprocess and reports success having written
     nothing.
 
-    Asks a GRAPH-scoped question (``branch list --graph <id>``, the cheapest
+    Asks a GRAPH-scoped question (the ``branch list`` statement, the cheapest
     one that has to reach the store to be answered) rather than the
     server-scoped ``graphs list``. That is not a detail: ``graphs list`` is a
     management-surface action that no ordinary client can use against the
@@ -572,6 +572,18 @@ def probe_cluster_graph(ref: StoreRef, what: str, cfg: cfg_module.Config) -> Sto
     ``read`` on that graph, which every actor the v1 Cedar bundle grants — CI,
     users, service and admin alike — already holds.
 
+    ★ AND IT STILL NEEDS ONLY ``read`` NOW THAT IT IS A GQ STATEMENT ON
+    ``/query`` RATHER THAN A CLI SUBCOMMAND, which is not obvious: the WRITE
+    statements on ``/mutate`` are authorized as their own branch actions
+    (``branch delete`` checks ``branch_delete``, not the route's ``change``),
+    so a reader could reasonably expect ``branch list`` to check a matching
+    ``branch_list``. It does not. Measured against a 0.11.0 server running
+    this bundle: an actor in no group gets ``policy denied action 'read'`` for
+    ``branch list``, the identical wording an ordinary named read gets, while
+    the same actor's ``branch create`` is denied as ``branch_create``. Had it
+    gone the other way, every read-only actor would be failing this write-path
+    preflight.
+
     On the DIRECT path it also inherits
     :class:`~witan_core.omnigraph.OmnigraphClient`'s connect-retry budget, so a
     server mid-restart is ridden out rather than counted as an absent graph.