sidegraph 0.17.2__tar.gz → 0.17.3__tar.gz

{sidegraph-0.17.2 → sidegraph-0.17.3}/.github/workflows/ci.yml

@@ -201,6 +201,7 @@ jobs:
             tests/test_hot_index_facts.py `
             tests/test_delivery_evidence.py tests/test_delivery_stats.py tests/test_delivery_surfaces.py `
             tests/test_git_output_utf8.py `
+            tests/test_githooks_atomic_lock.py::test_windows_pid_probe_is_never_a_signal_from_python `
             tests/test_health_check_skill.py `
             $privateTests
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

{sidegraph-0.17.2 → sidegraph-0.17.3}/CHANGELOG.md

@@ -7,6 +7,23 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.17.3] — 2026-10-26
+
+### Fixed
+
+- Graph refresh hooks acquire both the runner lock and stale-breaker gate with exclusive
+  shell PID files. Concurrent hooks remain serialized on systems whose external `mkdir`
+  can report success to two racing callers, while live legacy directory locks are respected.
+- Installer cleanup coordinates with the same breaker gate and preserves a lock whose owner
+  changed during its PID check. Optional native-lock failures no longer prevent publishing
+  an updated helper, and a failed gate PID write no longer leaves a permanent gate.
+- Doctor detects the complete older directory-lock helper; plain `sidegraph-init` repairs
+  it while keeping hook bytes and the recorded choice. Automatic detection conservatively
+  preserves unfamiliar scripts and quoted examples. Run `sidegraph-init` after upgrading
+  in each clone that uses the old helper.
+- Native Windows installer cleanup leaves PID-bearing locks untouched, instead of using
+  Python signal probes on process ids from a potentially different POSIX-shell namespace.
+
 ## [0.17.2] — 2026-10-25
 
 ### Fixed

{sidegraph-0.17.2 → sidegraph-0.17.3}/CLAUDE.md

@@ -13,7 +13,7 @@ task-aware retrieval + decision memory riding on the engine's entity graph.
 continuing participant in the project. A core feature must preserve, organize, or deliver
 accumulated project understanding. Document search by itself is not the product.
 
-Sidegraph is pre-1.0 (v0.17.2) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.17.3) — the full loop (capture, ratification, mistakes-first
 retrieval, refactor-surviving re-anchoring, semantic docs layer, mind-model domains, and the
 facts evidence layer) ships and is exercised end-to-end, but interfaces may still move before
 a stable release. See

{sidegraph-0.17.2 → sidegraph-0.17.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.17.2
+Version: 0.17.3
 Summary: Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine.
 Project-URL: Homepage, https://github.com/SantyagoSeaman/sidegraph
 Project-URL: Repository, https://github.com/SantyagoSeaman/sidegraph

{sidegraph-0.17.2 → sidegraph-0.17.3}/docs/guides/troubleshooting.md

@@ -222,8 +222,11 @@ entity file is skipped, an anchor to the same name mints a second entity; once t
 
 ### refresh-helper-outdated
 
-A git hook runs a graph refresh helper that starts Graphify without `GRAPHIFY_NO_AUTO_REFRESH=1`
-(an older Sidegraph wrote it). Graphify 0.9.87 and later refresh the agent skills they installed,
+A git hook runs an older graph refresh helper that uses directory-based locking, or starts
+Graphify without `GRAPHIFY_NO_AUTO_REFRESH=1`.
+The directory lock can admit overlapping rebuilds with uutils `mkdir`; the replacement uses
+exclusive PID files for both the runner lock and the stale-breaker gate.
+Graphify 0.9.87 and later refresh the agent skills they installed,
 such as `~/.claude/skills/graphify/`, on the first run after a Graphify upgrade unless that
 variable is set. One hook that runs the helper is enough for the check to fire, and a recorded "no"
 does not silence it. Run `sidegraph-init` with no flag: it rewrites the helper and keeps your

{sidegraph-0.17.2 → sidegraph-0.17.3}/docs/integrations/graphify.md

@@ -242,13 +242,25 @@ the `/graphify` skill's `--update` form).
   [above](#linked-worktrees-read-the-main-checkouts-graph)), so a commit in one does nothing.
   Rebuilding there as well costs about 18 MB and 43 s for a cold build on one field corpus with
   25 worktrees, and agents commit in worktrees constantly.
-- **In the background, one at a time.** Git never waits for the rebuild. A lock directory keeps
+- **In the background, one at a time.** Git never waits for the rebuild. An exclusively created PID file keeps
   one rebuild running; a hook that fires while it runs makes it go once more when it finishes, so
   the graph never settles on a tree older than the last request. A lock left by a job that died
   is detected and cleared: by its pid, or, when the job died before writing one (a full disk, a
-  quota), by its age, ten minutes. `sidegraph-init --hooks` clears such a lock at once. One risk
+  quota), by its age, ten minutes. Re-running `sidegraph-init --hooks` refreshes the helper and clears a dead lock;
+  a fresh lock without a PID is kept until the ten-minute grace period expires. One risk
   remains: after a reboot a pid can belong to a live, unrelated process, and the hook then waits
   until that process exits.
+  Plain `sidegraph-init` also repairs an outdated helper in use, keeping the recorded choice.
+  Older helpers used lock directories; the new helper respects a live old runner and can
+  recover its stale directory. Both the lock and the stale-breaker gate now use shell
+  exclusive creation, so locking does not depend on external `mkdir`.
+  Installer cleanup takes the same breaker gate before removing a dead runner lock. A small
+  native OS lock on `sidegraph-graph-refresh.repair` serializes installers while they recover
+  a dead gate; the coordination file stays in the common git directory to keep a stable inode.
+  Where native locks are unsupported, helper publication still proceeds and optional installer
+  cleanup is skipped. On Windows, PID-bearing locks are left to the POSIX helper to recover,
+  because its PIDs need not be native Windows PIDs. Installing or repairing a helper does not
+  itself start a rebuild.
 - **Where the output goes.** The last rebuild's output is `sidegraph-graph-refresh.log` in the
   common git directory (`.git/` in a normal clone).
 - **No `sidegraph-sync` in the hook.** The next memory call notices the new graph version and

{sidegraph-0.17.2 → sidegraph-0.17.3}/docs/reference/cli.md

@@ -1562,7 +1562,7 @@ plain-text line):
 | `orphaned-record` | an open (`proposed`/`accepted`) decision or fact whose every Tier-2 (leaf) anchor is `orphaned`, so retrieval reaches it only through its file or domain; one finding per record, at its canonical file, naming how many leaf anchors it has. Statuses come from `index.db` and read "as of last sync", so the check is skipped while the statuses are not computed for the current graph (see *Skipped checks* below; run `sidegraph-sync`). It is the record-level view of `orphaned-binding` (any record it flags has orphaned bindings, which that code already reports), so it adds no new reason for `--check` to exit `2`. The fix is to rebuild a stale graph, then `sidegraph-sync`; otherwise re-anchor the record with `add_anchors` or the `heal-anchors` skill, or supersede it if the code is gone. Needs a usable `index.db` |
 | `store-uncommitted` | store files nobody committed for at least 24 hours: records, bindings, entities, an archive segment or the root files (`format`, `.gitignore`, `stamping_live_since`) that `git status` shows as new, modified or deleted. One finding, at the store path, naming how many files there are, how old the oldest is and what kinds they are (a new `archive/` segment beside deleted records reads as "a compaction"). A new record or entity file is aged by its ULID name, which a `git stash` cannot rewrite; a modified file, or anything under `bindings/`, by its modification time; a deleted file by its subdirectory's, a lower bound. Entries fully staged in the index are not counted, so a `--check` run in a pre-commit hook does not block the commit that fixes the problem. **`--check` exits `2` on it.** The fix is to commit the store in a pull request. Silent, and not run, outside a git repository, with no `git`, or when git is slower than 2 seconds |
 | `plugin-off-in-subdirectories` | Claude Code sessions started below the repository root run without the Sidegraph plugin. Claude Code reads the project settings (`.claude/settings.json`) of the launch directory only, and the repository root's `.claude/settings.local.json` for every launch inside the repository; `enabledPlugins` merges key by key (user settings, then project, then local). Two problems, reported as up to two findings: (a) the plugin is enabled only in the root's `.claude/settings.json`, so every directory below the root without its own enabling settings runs without it (reported at that file); (b) nested directories with a `.claude/settings.json` or `.claude/settings.local.json` of their own that sets `enabledPlugins` and whose merge leaves the plugin off (reported at the first such directory, naming how many there are; a nested settings file without `enabledPlugins` cannot change the merge, so it is not counted). The walk covers every directory that holds a tracked file (one `git ls-files` over the index, a few tens of milliseconds on a large repository) and looks for the two settings files in each directly, so a repository that ignores `.claude/` is covered. User settings are read from `$CLAUDE_CONFIG_DIR/settings.json` when that variable is set and non-empty, else from `~/.claude/settings.json`. Silent when the plugin is not enabled for a launch at the root at all, and not run outside a git repository, with no `git`, or when `git ls-files` takes longer than 5 seconds. **`--check` exits `2` on it**, like any finding; enabling the plugin at user scope or in the root's `.claude/settings.local.json` clears it |
-| `refresh-helper-outdated` | a git hook runs a graph refresh helper whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (an older Sidegraph wrote it), so Graphify 0.9.87 and later can rewrite the agent skills they installed on the first rebuild after an upgrade. Advisory, per clone (the helper lives in `.git/hooks`); **`--check` exits `2` on it**, like any finding. One hook that runs the helper is enough, and a recorded decline does not silence it. The fix is `sidegraph-init` (no flag), which refreshes the helper and keeps a recorded hook choice. Silent outside a git repository, with no helper, or when no hook runs it |
+| `refresh-helper-outdated` | a git hook runs an older graph refresh helper that uses directory-based locking (unsafe with uutils `mkdir`), or whose Graphify line lacks `GRAPHIFY_NO_AUTO_REFRESH=1` (Graphify 0.9.87 and later can rewrite installed agent skills after an upgrade). Advisory, per clone (the helper lives in `.git/hooks`); **`--check` exits `2` on it**, like any finding. One hook that runs the helper is enough, and a recorded decline does not silence it. The fix is `sidegraph-init` (no flag), which refreshes the helper and keeps a recorded hook choice. Silent outside a git repository, with no helper, or when no hook runs it |
 | `engine-version` | the graph was built by a Graphify release this Sidegraph was not tested with (its `graph.graphify_version` stamp is neither absent nor in the tested set), so anchors and domains may read differently. Advisory; **`--check` exits `2` on it**, like any finding. Pin Graphify to a tested release listed under [Engine version pinning](../integrations/graphify.md#engine-version-pinning), then rebuild the graph. It also fires for a mention-edge graph (Graphify 0.9.62 or later) over a store without a minimum Sidegraph version; follow the [0.14 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.14.md). A malformed marker leaves this second case silent. Silent without a readable graph |
 | `store-not-migrated` | the store uses the pre-0.17 layout (a format marker below major 2) and holds at least one record of any kind (initiatives included). One finding, at the store path, naming `sidegraph-migrate` (run on the default branch, after the team checklist in the [0.17 migration guide](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/guides/migrating-to-0.17.md)) and the `sidegraph:compact` skill. Degraded; **`--check` exits `2` on it**, like any finding. Silent on an empty store and on a store that is already format 2 |
 | `maintenance-due` | a format-2 store that `sidegraph-compact` would tidy: more than 200 per-record files, or a legacy `archive/` segment it would delete, or a misplaced or duplicated shard line, or a stray shard file. `sidegraph-verify` does not report these; maintenance heals them. A segment kept because one of its lines is not safe to delete does not count. Advisory; **`--check` exits `2` on it**, like any finding. Run `sidegraph-compact` on the default branch. Silent on a store that is not format 2 |

{sidegraph-0.17.2 → sidegraph-0.17.3}/docs/reference/hooks.md

@@ -402,6 +402,13 @@ raises costs only its own line.
     > installed on the first rebuild after an upgrade. Ask the user to run `sidegraph-init`,
     > which refreshes the helper and keeps their recorded hook choice; do not run it unasked.
 
+    A helper using the old directory-based lock is also reported: uutils `mkdir` can admit
+    overlapping rebuilds. `sidegraph-init` replaces it with exclusive PID-file locking while
+    preserving hook bytes and the recorded choice. The outdated-helper check recognizes concrete defects in simple shell helpers,
+    rather than comparing the whole template. It conservatively skips unfamiliar scripts with
+    heredocs or multiline quotes. This controls automatic defect repair; an ordinary init
+    that refreshes a fully installed hook still rewrites its managed helper.
+
     It also sends a notice for the person. See
     [`refresh-helper-outdated`](../guides/troubleshooting.md#refresh-helper-outdated).
 15. **Refresh-hook line.** When no git hook keeps the graph fresh, one line tells the model to

{sidegraph-0.17.2 → sidegraph-0.17.3}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "type": "module",
   "exports": "./index.js"
 }

{sidegraph-0.17.2 → sidegraph-0.17.3}/plugin/sidegraph/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sidegraph",
   "displayName": "Sidegraph",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Durable decision/lessons memory over your code graph — ADRs, gotchas, and constraints that survive refactors, retrieved mistakes-first.",
   "author": { "name": "SantyagoSeaman", "url": "https://github.com/SantyagoSeaman" },
   "homepage": "https://github.com/SantyagoSeaman/sidegraph",

{sidegraph-0.17.2 → sidegraph-0.17.3}/plugin/sidegraph/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sidegraph",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Durable decision/lessons memory over your code graph — ADRs, gotchas, and constraints that survive refactors, retrieved mistakes-first.",
   "license": "Apache-2.0",
   "skills": "./skills/",

{sidegraph-0.17.2 → sidegraph-0.17.3}/plugin/sidegraph/.muse-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "name": "sidegraph",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Durable decisions, facts and lessons over your code graph.",
   "compat": {
     "source": "native",

{sidegraph-0.17.2 → sidegraph-0.17.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sidegraph"
-version = "0.17.2"
+version = "0.17.3"
 description = "Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine."
 readme = "README.md"
 requires-python = ">=3.13"

{sidegraph-0.17.2 → sidegraph-0.17.3}/src/sidegraph/__init__.py

@@ -30,7 +30,7 @@ if TYPE_CHECKING:
     )
     from .store import Store
 
-__version__ = "0.17.2"
+__version__ = "0.17.3"
 
 # name -> the submodule that defines it
 _LAZY = {

{sidegraph-0.17.2 → sidegraph-0.17.3}/src/sidegraph/cli.py

@@ -416,11 +416,14 @@ def _hook_graph_problem(
 
 
 def _refresh_outdated_helper(info: githooks.RepoInfo) -> bool:
-    """Rewrite the helper alone when a hook runs it and it runs Graphify without
+    """Rewrite a helper in use with the old directory lock or a Graphify run without
     ``GRAPHIFY_NO_AUTO_REFRESH=1``; ``True`` when it did. The helper is per repository, so this
     holds whatever graph the store reads; the recorded choice and the hook files are not touched.
     see design/superpowers/specs/2026-10-14-graphify-upgrade-design.md (D7)"""
-    if githooks.helper_is_current(info) is not False or not githooks.helper_in_use(info):
+    old_lock = githooks.helper_uses_directory_lock(info)
+    if (
+        githooks.helper_is_current(info) is not False and not old_lock
+    ) or not githooks.helper_in_use(info):
         return False
     graphify = shutil.which("graphify")
     try:
@@ -428,10 +431,13 @@ def _refresh_outdated_helper(info: githooks.RepoInfo) -> bool:
     except OSError as e:
         print(f"graph refresh hook: could not refresh the helper ({e})")
         return False
-    print(
-        "graph refresh hook: refreshed the helper, which ran Graphify without "
-        f"{githooks.GRAPH_REBUILD_ENV}"
-    )
+    if old_lock:
+        print("graph refresh hook: refreshed the helper, which used directory-based locking")
+    else:
+        print(
+            "graph refresh hook: refreshed the helper, which ran Graphify without "
+            f"{githooks.GRAPH_REBUILD_ENV}"
+        )
     return True
 
 

{sidegraph-0.17.2 → sidegraph-0.17.3}/src/sidegraph/githooks.py

@@ -27,8 +27,10 @@ import shlex
 import shutil
 import stat
 import subprocess
+import sys
 import tempfile
 import time
+from collections.abc import Iterator
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
@@ -76,17 +78,14 @@ _GIT_TIMEOUT = 10.0
 # wrote its pid; only its age says so. The helper breaks one after this long (``-mmin +10``).
 _STALE_LOCK_SECONDS = 600
 
-# The helper, verbatim from the reviewed design (D5): the "want" flag, ``take``, the ``.gate``
-# stale-breaker and ``me=$(exec sh -c 'echo $PPID')`` are the tested locking and are not to be
-# edited. One review amendment: a lock with no pid (its owner died, or could not write, between
-# ``mkdir`` and ``echo``) is broken once it is ten minutes old, the age checked again under the
-# gate; before, it blocked every rebuild for good. ``@GRAPHIFY@`` is the one substitution: the
-# path found at install time, quoted, or ''. A second amendment sets ``GRAPHIFY_NO_AUTO_REFRESH=1``
-# on the rebuild line (design/superpowers/specs/2026-10-14-graphify-upgrade-design.md, D7).
+# D5's want flag, stale-breaker gate and runner PID are preserved. The lock and gate
+# now use the shell's noclobber redirection (O_EXCL), independently of external mkdir.
+# Old directory locks are read during upgrade; fresh incomplete owners are left alone.
+# @GRAPHIFY@ is the install-time fallback, and every rebuild disables skill auto-refresh.
 _HELPER_TEMPLATE = r"""#!/bin/sh
 # Installed by sidegraph-init: keeps graphify-out/graph.json current for Sidegraph.
 # Main checkout only: a linked worktree reads the main checkout's graph. The rebuild runs
-# in the background so git never waits. A "want" flag plus a lock directory run one rebuild
+# in the background so git never waits. A "want" flag plus an exclusive PID file run one rebuild
 # at a time and never miss a request that arrives during one.
 hook=$1; shift
 [ "$(git rev-parse --path-format=absolute --git-dir 2>/dev/null)" = \
@@ -102,19 +101,23 @@ log=$common/sidegraph-graph-refresh.log
 : > "$want" 2>/dev/null || exit 0
 (
   me=$(exec sh -c 'echo $PPID')
-  take() { mkdir "$lock" 2>/dev/null && echo "$me" > "$lock/pid"; }
+  take() { (set -C; echo "$me" > "$lock") 2>/dev/null; }
+  read_pid() {
+    if [ -d "$lock" ]; then cat "$lock/pid" 2>/dev/null; else cat "$lock" 2>/dev/null; fi
+  }
   if ! take; then
-    pid=$(cat "$lock/pid" 2>/dev/null)
+    pid=$(read_pid)
     if [ -n "$pid" ]; then
       kill -0 "$pid" 2>/dev/null && exit 0      # a runner is alive; it will see $want
     else                                        # the owner is mid-write, or died there
       [ -n "$(find "$lock" -maxdepth 0 -mmin +10 2>/dev/null)" ] || exit 0
     fi
-    mkdir "$lock.gate" 2>/dev/null || exit 0    # one stale-breaker at a time
-    [ "$(cat "$lock/pid" 2>/dev/null)" = "$pid" ] &&
+    (set -C; : > "$lock.gate") 2>/dev/null || exit 0
+    (echo "$me" > "$lock.gate") 2>/dev/null || :  # PID write failure must not leak the gate
+    [ "$(read_pid)" = "$pid" ] &&
       { [ -n "$pid" ] || [ -n "$(find "$lock" -maxdepth 0 -mmin +10 2>/dev/null)" ]; } &&
       rm -rf "$lock"
-    rmdir "$lock.gate"; take || exit 0
+    rm -f "$lock.gate"; take || exit 0
   fi
   cd "$top" || { rm -rf "$lock"; exit 0; }
   while :; do
@@ -466,28 +469,125 @@ def _has_graphify_hook(info: RepoInfo) -> bool:
 
 
 def _lock_is_dead(lock: Path) -> bool:
-    """Whether the helper's lock directory belongs to a job that is gone: its pid no longer runs,
-    or it has no usable pid and is over ten minutes old. A pid that runs, even another user's, and
+    """Whether the helper's PID file or legacy lock directory belongs to a job that is gone:
+    its pid no longer runs, or it has no usable pid and is over ten minutes old. A pid that runs,
+    even another user's, and
     a recent pid-less lock (an owner still writing) are live. A pid can be reused by a live
     process after a reboot, which this cannot tell from the runner."""
     try:
-        age = time.time() - lock.stat().st_mtime
+        before = lock.stat()
+        age = time.time() - before.st_mtime
     except OSError:
         return False
     try:
-        text = (lock / "pid").read_text().strip()
+        text = (lock / "pid" if lock.is_dir() else lock).read_text().strip()
     except OSError:
         text = ""
     pid = int(text) if text.isdigit() else 0
     if pid <= 0:
-        return age > _STALE_LOCK_SECONDS
+        dead = age > _STALE_LOCK_SECONDS
+    else:
+        if sys.platform == "win32":
+            # These are POSIX-shell PIDs. Windows kill(pid, 0) is not a liveness probe,
+            # and MSYS/native PID namespaces differ: leave recovery to the shell helper.
+            return False
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            dead = True
+        except OSError:  # PermissionError: the process exists
+            return False
+        else:
+            return False
+    if not dead:
+        return False
+    # A live owner may finish and a fresh runner may acquire the path during kill(0).
+    # Under the breaker gate, only an unchanged dead owner can now safely be removed.
     try:
-        os.kill(pid, 0)
-    except ProcessLookupError:
-        return True
-    except OSError:  # PermissionError: the process exists
+        after = lock.stat()
+    except OSError:
         return False
-    return False
+    return (before.st_dev, before.st_ino, before.st_mtime_ns, before.st_ctime_ns) == (
+        after.st_dev,
+        after.st_ino,
+        after.st_mtime_ns,
+        after.st_ctime_ns,
+    )
+
+
+def _remove_lock(path: Path) -> None:
+    """Remove a PID file or legacy directory, without following a symlink."""
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path, ignore_errors=True)
+    else:
+        with contextlib.suppress(OSError):
+            path.unlink()
+
+
+@contextlib.contextmanager
+def _repair_guard(info: RepoInfo) -> Iterator[bool]:
+    """Serialize installers while repairing a dead breaker gate; the OS releases on exit.
+
+    Keep the coordination file: unlinking an advisory lock lets another installer lock a
+    different inode. A busy installer skips cleanup; the one holding the guard handles it.
+    """
+    try:
+        handle = (info.common / f"{HELPER_NAME}.repair").open("a+b")
+    except OSError:
+        yield False
+        return
+    with handle:
+        if sys.platform == "win32":
+            import msvcrt
+
+            if handle.tell() == 0:
+                handle.write(b"\0")
+                handle.flush()
+            handle.seek(0)
+            try:
+                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+            except OSError:
+                yield False
+                return
+            try:
+                yield True
+            finally:
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            try:
+                fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except OSError:
+                yield False
+                return
+            try:
+                yield True
+            finally:
+                fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+def _repair_dead_locks(info: RepoInfo) -> None:
+    """Clear dead locks under the helper's own breaker gate, never from a stale snapshot."""
+    with _repair_guard(info) as held:
+        if not held:
+            return
+        gate = info.common / f"{HELPER_NAME}.lock.gate"
+        if _lock_is_dead(gate):
+            _remove_lock(gate)
+        try:
+            handle = gate.open("x")
+        except FileExistsError:
+            return  # a live/fresh gate, or a legacy breaker still using a directory
+        try:
+            with handle:
+                handle.write(f"{os.getpid()}\n")
+            lock = info.common / f"{HELPER_NAME}.lock"
+            if _lock_is_dead(lock):
+                _remove_lock(lock)
+        finally:
+            gate.unlink()
 
 
 # -- install, remove, status -----------------------------------------------------------------
@@ -499,12 +599,8 @@ def install_helper(info: RepoInfo, *, graphify: str | None) -> None:
     stale-breaker gate. For a repository whose hooks call it by hand.
     # see design/superpowers/specs/2026-10-02-graph-refresh-hook-design.md (D2, D5)"""
     info.own_hooks_dir.mkdir(parents=True, exist_ok=True)
-    lock = info.common / f"{HELPER_NAME}.lock"
-    if _lock_is_dead(lock):  # re-running --hooks is the way out of a lock a dead job left
-        shutil.rmtree(lock, ignore_errors=True)
+    _repair_dead_locks(info)
     _publish_file(info.helper, _encode(helper_script(graphify)), 0o755)
-    with contextlib.suppress(OSError):  # a stale stale-breaker's gate (D5)
-        (info.common / f"{HELPER_NAME}.lock.gate").rmdir()
 
 
 def install(info: RepoInfo, *, graphify: str | None) -> InstallReport:
@@ -524,14 +620,15 @@ def install(info: RepoInfo, *, graphify: str | None) -> InstallReport:
 
 def remove(info: RepoInfo) -> RemoveReport:
     """Take Sidegraph out: the block from each hook, then (once) the helper, the want flag, any
-    lock and gate, and the recorded choice. The rebuild log is left for the owner to read.
+    lock and gate, and the recorded choice. The rebuild log and native repair coordination
+    file stay: unlinking that file could let simultaneous installers lock different inodes.
     # see design/superpowers/specs/2026-10-02-graph-refresh-hook-design.md (D3)"""
     hooks = tuple(_strip(info.own_hooks_dir / hook, hook) for hook in HOOKS)
     helper_removed = info.helper.exists()
     info.helper.unlink(missing_ok=True)
     (info.common / f"{HELPER_NAME}.want").unlink(missing_ok=True)
     for leftover in ("lock", "lock.gate"):
-        shutil.rmtree(info.common / f"{HELPER_NAME}.{leftover}", ignore_errors=True)
+        _remove_lock(info.common / f"{HELPER_NAME}.{leftover}")
     record_choice(info.top, declined=False)
     return RemoveReport(hooks, helper_removed)
 
@@ -604,3 +701,28 @@ def helper_in_use(info: RepoInfo) -> bool:
     ``hooks_dir`` calls it (``_runs_helper``), so a partly wired repository counts. Read-only.
     # see design/superpowers/specs/2026-10-14-graphify-upgrade-design.md (D7)"""
     return info.helper.is_file() and any(_runs_helper(info.hooks_dir / hook) for hook in HOOKS)
+
+
+_DIRECTORY_LOCK = re.compile(
+    r'^\s*(?:take\(\)\s*\{\s*)?mkdir\s+(?:"\$lock(?:\.gate)?"|\$lock(?:\.gate)?)(?=\s|;|$)'
+)
+
+
+def helper_uses_directory_lock(info: RepoInfo) -> bool:
+    """Recognize shipped take()/standalone mkdir acquisitions, not arbitrary shell code.
+
+    Preserve unfamiliar helpers with heredocs/multiline quotes. Known old helpers have
+    simple acquisition lines; there is no need to parse arbitrary command/argument positions.
+    """
+    try:
+        installed = _decode(info.helper.read_bytes())
+    except OSError:
+        return False
+    if "<<" in installed:
+        return False
+    try:
+        if any("\n" in word for word in shlex.split(installed.replace("\\\n", ""), comments=True)):
+            return False
+    except ValueError:
+        return False
+    return any(_DIRECTORY_LOCK.match(line) for line in installed.splitlines())

{sidegraph-0.17.2 → sidegraph-0.17.3}/src/sidegraph/integrity.py

@@ -735,7 +735,7 @@ def _detect_store_files_skipped(inputs: Inputs) -> Problem | None:
 
 
 def _detect_refresh_helper_outdated(inputs: Inputs) -> Problem | None:
-    """A hook git runs calls a helper that runs Graphify without ``GRAPHIFY_NO_AUTO_REFRESH=1``
+    """A hook calls a helper with directory-based locking or missing ``GRAPHIFY_NO_AUTO_REFRESH=1``
     (an earlier ``sidegraph-init`` wrote it). Not run outside a git repository, with no helper, or
     when no hook calls it (``refresh-hook-missing`` says that); one hook that calls it is enough,
     so a partly wired repository and a recorded decline do not hide it. The fix is plain
@@ -751,8 +751,33 @@ def _detect_refresh_helper_outdated(inputs: Inputs) -> Problem | None:
     current = githooks.helper_is_current(info)
     if current is None or not githooks.helper_in_use(info):
         raise _NotRun
-    if current:
+    old_lock = githooks.helper_uses_directory_lock(info)
+    if current and not old_lock:
         return None
+    if old_lock:
+        return Problem(
+            check="refresh-helper-outdated",
+            severity="advisory",
+            summary="graph refresh helper uses directory-based locking",
+            fix="sidegraph-init",
+            line=(
+                "Sidegraph: the graph refresh helper uses directory-based locking, which can "
+                "allow overlapping rebuilds with uutils mkdir. Ask the user to run "
+                "`sidegraph-init`, which refreshes the helper and keeps their recorded hook "
+                "choice; do not run it unasked."
+            ),
+            notice=(
+                "Sidegraph: the graph refresh helper uses directory-based locking, which can "
+                "allow overlapping rebuilds with uutils mkdir. Refresh it with `sidegraph-init`."
+            ),
+            findings=(
+                (
+                    str(info.helper),
+                    "the installed graph refresh helper uses directory-based "
+                    "locking; run `sidegraph-init` to refresh it",
+                ),
+            ),
+        )
     return Problem(
         check="refresh-helper-outdated",
         severity="advisory",

sidegraph-0.17.3/tests/githooks_legacy_helper.py

@@ -0,0 +1,46 @@
+"""The public 0.17.2 directory-lock helper, frozen for upgrade regression tests."""
+
+LEGACY_HELPER = r"""#!/bin/sh
+# Installed by sidegraph-init: keeps graphify-out/graph.json current for Sidegraph.
+# Main checkout only: a linked worktree reads the main checkout's graph. The rebuild runs
+# in the background so git never waits. A "want" flag plus a lock directory run one rebuild
+# at a time and never miss a request that arrives during one.
+hook=$1; shift
+[ "$(git rev-parse --path-format=absolute --git-dir 2>/dev/null)" = \
+  "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" ] || exit 0
+case $hook in post-checkout) [ "$3" = 1 ] && [ "$1" != "$2" ] || exit 0 ;; esac
+top=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || exit 0
+graphify=$(command -v graphify 2>/dev/null) || graphify=@GRAPHIFY@
+[ -n "$graphify" ] && [ -x "$graphify" ] || exit 0
+lock=$common/sidegraph-graph-refresh.lock
+want=$common/sidegraph-graph-refresh.want
+log=$common/sidegraph-graph-refresh.log
+: > "$want" 2>/dev/null || exit 0
+(
+  me=$(exec sh -c 'echo $PPID')
+  take() { mkdir "$lock" 2>/dev/null && echo "$me" > "$lock/pid"; }
+  if ! take; then
+    pid=$(cat "$lock/pid" 2>/dev/null)
+    if [ -n "$pid" ]; then
+      kill -0 "$pid" 2>/dev/null && exit 0      # a runner is alive; it will see $want
+    else                                        # the owner is mid-write, or died there
+      [ -n "$(find "$lock" -maxdepth 0 -mmin +10 2>/dev/null)" ] || exit 0
+    fi
+    mkdir "$lock.gate" 2>/dev/null || exit 0    # one stale-breaker at a time
+    [ "$(cat "$lock/pid" 2>/dev/null)" = "$pid" ] &&
+      { [ -n "$pid" ] || [ -n "$(find "$lock" -maxdepth 0 -mmin +10 2>/dev/null)" ]; } &&
+      rm -rf "$lock"
+    rmdir "$lock.gate"; take || exit 0
+  fi
+  cd "$top" || { rm -rf "$lock"; exit 0; }
+  while :; do
+    while [ -e "$want" ]; do
+      rm -f "$want"
+      GRAPHIFY_NO_AUTO_REFRESH=1 PYTHONHASHSEED=0 "$graphify" update . > "$log" 2>&1
+    done
+    rm -rf "$lock"; [ -e "$want" ] || break; take || break
+  done
+) </dev/null >/dev/null 2>&1 &
+exit 0
+"""

{sidegraph-0.17.2 → sidegraph-0.17.3}/tests/githooks_support.py

@@ -255,27 +255,6 @@ def have_shell(name: str) -> bool:
     return shutil.which(name) is not None
 
 
-def _mkdir_is_uutils() -> bool:
-    """True when ``mkdir`` on PATH is uutils coreutils, the default on Ubuntu 26.04."""
-    try:
-        out = subprocess.run(
-            ["mkdir", "--version"], capture_output=True, text=True, timeout=5
-        ).stdout
-    except (OSError, subprocess.SubprocessError):
-        return False
-    return "uutils" in out
-
-
-# uutils ``mkdir`` 0.10 is not atomic under a race: two callers creating one directory can both
-# exit 0, so the helper's mkdir lock lets two rebuilds run at once. The overlap tests are expected
-# to fail there until the helper takes its lock without an external mkdir.
-NON_ATOMIC_MKDIR = pytest.mark.xfail(
-    _mkdir_is_uutils(),
-    reason="uutils mkdir lets two racing callers both succeed; the helper lock relies on mkdir",
-    strict=False,
-)
-
-
 # -- helpers shared by test_githooks and the private lock-race tests ------------------------
 
 SHELLS = [

{sidegraph-0.17.2 → sidegraph-0.17.3}/tests/test_githooks.py

@@ -20,7 +20,6 @@ from tests.githooks_support import (
     CREATED_HEADER,
     HELPER_NAME,
     HOOKS,
-    NON_ATOMIC_MKDIR,
     SHELLS,
     STALE_STATES,
     Sandbox,
@@ -462,13 +461,11 @@ def test_the_rebuild_is_graphify_update_with_a_pinned_hash_seed_and_a_log(sandbo
 # tests/private/test_githooks.py; the two cases here keep the lock contract in every PR run.
 
 
-@NON_ATOMIC_MKDIR
 @pytest.mark.slow
 def test_t9_two_simultaneous_calls_never_overlap_on_a_fresh_lock(sandbox, monkeypatch):
     fresh_lock_burst(sandbox, monkeypatch, "sh", 2)
 
 
-@NON_ATOMIC_MKDIR
 @pytest.mark.slow
 def test_t9_two_simultaneous_calls_never_overlap_on_a_dead_pid_lock(sandbox, monkeypatch):
     stale_lock_burst(sandbox, monkeypatch, "sh", 2, "dead pid")
@@ -566,8 +563,8 @@ def test_a_pid_write_that_fails_does_not_block_later_rebuilds(sandbox):
     )
     assert done.returncode == 0
     lock = info.common / f"{HELPER_NAME}.lock"
-    wait_for(lambda: (lock / "pid").exists(), what="the lock the failed write left")
-    assert (lock / "pid").read_bytes() == b""
+    wait_for(lock.is_file, what="the lock the failed write left")
+    assert lock.read_bytes() == b""
     age(lock)
     commit(repo)
     starts = await_rebuilds(sandbox, info.common)