code-context-control 2.118.0__tar.gz → 2.118.2__tar.gz

{code_context_control-2.118.0 → code_context_control-2.118.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.118.0
+Version: 2.118.2
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.118.0 → code_context_control-2.118.2}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.118.0"
+__version__ = "2.118.2"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

{code_context_control-2.118.0 → code_context_control-2.118.2}/cli/hub_server.py

@@ -32,6 +32,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 from core.ide import PROFILES, detect_ide, get_profile, load_ide_config, normalize_ide_name
 from services import access_guard
 from services.activity_log import ActivityLog
+from services.atomic_json import write_json_atomic
 from services.project_manager import ProjectManager
 from services.tool_classifier import CATEGORIES
 
@@ -3078,9 +3079,10 @@ def api_projects_config_put():
         else:
             merged[key] = val
     cfg[section] = merged
-    tmp = cfg_file.with_name("config.json.tmp")
-    tmp.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
-    os.replace(tmp, cfg_file)
+    # Not `config.json.tmp`: the CLI (services.access_guard) and the mobile
+    # API write this same file, and the hub itself is threaded — one shared
+    # temp name is a name they all pick at once. See services.atomic_json.
+    write_json_atomic(cfg_file, cfg, trailing_newline=False)
     try:
         ActivityLog(str(resolved)).log("hub_config_write", {
             "section": section, "keys": sorted(values.keys()), "source": "hub"})

{code_context_control-2.118.0 → code_context_control-2.118.2}/code_context_control.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.118.0
+Version: 2.118.2
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.118.0 → code_context_control-2.118.2}/code_context_control.egg-info/SOURCES.txt

@@ -189,6 +189,7 @@ services/agent_locks.py
 services/agents.py
 services/artifact_defs.py
 services/artifact_store.py
+services/atomic_json.py
 services/auto_memory.py
 services/background_service.py
 services/benchmark_dashboard.py
@@ -299,6 +300,7 @@ tests/test_aider_polyglot.py
 tests/test_antigravity_transition.py
 tests/test_artifact_store.py
 tests/test_artifact_tool.py
+tests/test_atomic_json.py
 tests/test_background_service.py
 tests/test_bitbucket_cli_smoke.py
 tests/test_bitbucket_client.py

{code_context_control-2.118.0 → code_context_control-2.118.2}/oracle/services/mobile_api.py

@@ -56,6 +56,7 @@ from oracle.config import ORACLE_DIR, load_config
 from oracle.services import api_auth, discovery_audit
 from oracle.services.api_auth import extract_bearer
 from oracle.services.tool_registry import _c3_version
+from services.atomic_json import write_json_atomic
 
 # 2: /info reports EFFECTIVE capabilities (filtered by the config switches)
 # rather than a static list, so a client can gate its UI instead of probing.
@@ -2090,10 +2091,11 @@ def _write_override_section(project: Path, section: dict) -> dict:
         else:
             block[key] = value
     cfg["override"] = block
-    tmp = cfg_file.with_name(f"{cfg_file.name}.tmp")
-    tmp.write_text(json.dumps(cfg, indent=2, ensure_ascii=False),
-                   encoding="utf-8")
-    tmp.replace(cfg_file)
+    # Shared with the CLI and the hub, and served from a threaded API, so the
+    # publish goes through the one race-safe writer rather than a temp name
+    # every writer of this file would pick. See services.atomic_json.
+    write_json_atomic(cfg_file, cfg, ensure_ascii=False,
+                      trailing_newline=False)
     return block
 
 

{code_context_control-2.118.0 → code_context_control-2.118.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.118.0"
+version = "2.118.2"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.118.0 → code_context_control-2.118.2}/services/access_guard.py

@@ -20,6 +20,8 @@ import re
 from dataclasses import dataclass
 from pathlib import Path
 
+from services.atomic_json import write_json_atomic
+
 # ── Rule model ──────────────────────────────────────────────────────────────
 
 _KIND_DENY = "deny"
@@ -1473,11 +1475,17 @@ def _load_config_for_write(cfg: Path) -> tuple:
 
 
 def _write_scope_config(cfg: Path, data: dict) -> None:
-    """Atomic same-directory replace; privileged internal write."""
-    cfg.parent.mkdir(parents=True, exist_ok=True)
-    tmp = cfg.with_name(cfg.name + ".tmp")
-    tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
-    os.replace(tmp, cfg)
+    """Atomic same-directory replace; privileged internal write.
+
+    The CLI, the hub and the mobile API all reach this for the same scope
+    file, so the publish is via ``services.atomic_json`` — a shared
+    ``config.json.tmp`` is a name they would collide on. The fsync matters
+    more here than anywhere else in the codebase: a truncated ``config.json``
+    comes back from ``load_all`` in its ``corrupt`` list, every path then
+    fails closed with ``<corrupt-config>``, and the session can no longer run
+    the command that would fix it.
+    """
+    write_json_atomic(cfg, data)
 
 
 def seed_default_global_rules() -> dict:

{code_context_control-2.118.0 → code_context_control-2.118.2}/services/agent_locks.py

@@ -41,6 +41,7 @@ import time
 import uuid
 from pathlib import Path
 
+from services.atomic_json import write_json_atomic
 from services.task_store import _FileLock
 
 SCHEMA_VERSION = 1
@@ -219,10 +220,15 @@ class LockStore:
         return doc
 
     def _save(self, doc: dict) -> None:
-        self.data_dir.mkdir(parents=True, exist_ok=True)
-        tmp = self.state_file.with_name(self.state_file.name + ".tmp")
-        tmp.write_text(json.dumps(doc, indent=2) + "\n", encoding="utf-8")
-        os.replace(tmp, self.state_file)
+        # The `_FileLock` guard serialises the read-modify-write, but only
+        # among callers that take it — and it is advisory, held per process.
+        # The publish itself has to be safe on its own: a shared
+        # `locks.json.tmp` is one name every writer on the box picks, and two
+        # of them landing together either publishes a half-written lease file
+        # or raises WinError 5 (see services.atomic_json). Losing this write
+        # means losing live leases, which is exactly what `_load` refuses to
+        # do when it quarantines a corrupt file instead of resetting it.
+        write_json_atomic(self.state_file, doc)
 
     def _guard(self):
         return _FileLock(self.lock_file)

code_context_control-2.118.2/services/atomic_json.py

@@ -0,0 +1,118 @@
+"""One durable same-directory replace for the small JSON stores C3 writes.
+
+Why this module exists
+----------------------
+C3 keeps a handful of tiny JSON files that more than one writer touches: the
+agent lock store, the per-scope ``config.json`` written by the CLI, the hub
+and the mobile API, and the shell job store. Every one of them had grown the
+same three-line publish step by copy — ``<name>.tmp`` then a single
+``os.replace`` — and on Windows that shape is a live bug rather than a style
+nit:
+
+1. **A shared temp name races on the TEMP, not on the target.**
+   ``os.replace`` is atomic on the destination; nothing at all protects
+   ``<name>.tmp``. Two writers of one path both create it, so one publishes
+   a file the other is still writing, or the replace raises
+   ``PermissionError: [WinError 5] Access is denied`` because the loser still
+   holds a handle to it. Observed for real in the shell job store, where it
+   crashed a supervisor and reported "failed before running" for a command
+   that was fine (fixed there in 2.118.1, PR #157). The other copies had the
+   identical shape and no demonstrated failure only because they are written
+   far less often — the lock store especially is a coin that had not landed
+   on its edge yet.
+2. **A pid alone is not a unique suffix.** Threads share a pid, and the hub,
+   the Oracle and the lock store are all written from threaded servers. Six
+   threads are enough to drive a ``.tmp<pid>`` implementation into both
+   ``PermissionError`` and ``FileNotFoundError`` within a second, so the
+   suffix carries per-WRITE randomness as well.
+3. **One attempt turns a transient sharing violation into a lost write.** An
+   AV scanner or the Search indexer holding the target open for a few
+   milliseconds is ordinary on Windows and clears on its own; a single
+   ``os.replace`` turns it into an exception at the call site.
+
+``cli/_hook_utils._atomic_write_json`` deliberately does NOT import this. A
+PreToolUse hook is a separate, short-lived, single-threaded process that
+imports nothing from ``services`` on purpose, so pid-only is genuinely
+enough there. That one duplication stays.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+from pathlib import Path
+
+# Four attempts across ~0.14s of backoff. Sized for a scanner or indexer
+# holding a handle, not for a lock a peer holds for seconds — a failure that
+# survives this is real and is re-raised.
+REPLACE_ATTEMPTS = 4
+REPLACE_BACKOFF_S = 0.02
+
+
+def atomic_tmp_path(path: Path) -> Path:
+    """``<name>.tmp<pid>-<random>`` beside ``path`` — unique per write."""
+    return path.with_name(f"{path.name}.tmp{os.getpid()}-{secrets.token_hex(4)}")
+
+
+def write_text_atomic(path, text: str, *, encoding: str = "utf-8",
+                      fsync: bool = True) -> None:
+    """Publish ``text`` at ``path``: unique temp, then a retried ``os.replace``.
+
+    ``fsync`` flushes the temp's bytes before the replace, so a crash or power
+    loss between the two cannot publish a zero-length or half-written file.
+    Durable state wants that: a truncated ``config.json`` makes the Access
+    Guard read ``<corrupt-config>`` and fail closed on every subsequent call,
+    which wedges the whole session. Callers whose file is ephemeral spill
+    state pass ``fsync=False`` rather than pay a disk flush per update.
+
+    Newline translation matches ``Path.write_text`` (the default), so this is
+    a drop-in for the ``write_text`` + ``os.replace`` pairs it replaces and
+    does not churn line endings in files already on disk.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = atomic_tmp_path(path)
+    try:
+        with open(tmp, "w", encoding=encoding) as fh:
+            fh.write(text)
+            if fsync:
+                fh.flush()
+                os.fsync(fh.fileno())
+        last_exc: OSError | None = None
+        for attempt in range(REPLACE_ATTEMPTS):
+            try:
+                os.replace(tmp, path)
+                return
+            except PermissionError as exc:
+                last_exc = exc
+                if attempt < REPLACE_ATTEMPTS - 1:
+                    time.sleep(REPLACE_BACKOFF_S * (2 ** attempt))
+        if last_exc is not None:
+            raise last_exc
+    finally:
+        # A successful replace already consumed tmp, so this only fires on the
+        # failure paths — otherwise abandoned temps accumulate next to the
+        # file, and for `.c3/` that means they get indexed and committed.
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except OSError:
+            pass
+
+
+def write_json_atomic(path, data, *, indent: int = 2,
+                      ensure_ascii: bool = True,
+                      trailing_newline: bool = True,
+                      fsync: bool = True) -> None:
+    """``write_text_atomic`` over ``json.dumps``.
+
+    The serialisation knobs exist so each caller keeps the exact bytes it
+    wrote before this module: the point of the change is the publish step,
+    not a reformat of five JSON files that other tools and diffs already read.
+    """
+    text = json.dumps(data, indent=indent, ensure_ascii=ensure_ascii)
+    if trailing_newline:
+        text += "\n"
+    write_text_atomic(path, text, fsync=fsync)

{code_context_control-2.118.0 → code_context_control-2.118.2}/services/shell_output.py

@@ -75,6 +75,8 @@ from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
+from services.atomic_json import write_json_atomic
+
 __all__ = [
     "STORE_ROOT", "RETENTION_DAYS", "RETENTION_BYTES", "HEAD_BYTES", "TAIL_BYTES",
     "TEXT_MAX_BYTES", "DEFAULT_READ_BYTES", "LINE_CLIP_CHARS",
@@ -961,9 +963,21 @@ def _load_meta(path: Path) -> OutputMeta | None:
 
 
 def _write_json_atomic(path: Path, data: dict) -> None:
-    tmp = path.with_name(path.name + ".tmp")
-    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=1), encoding="utf-8")
-    os.replace(tmp, path)
+    """Publish a job record durably — see ``services.atomic_json``.
+
+    This was the first copy of the unique-temp + retried-``os.replace`` shape
+    (2.118.1, PR #157, after a shared ``<name>.tmp`` crashed supervisors on
+    Windows CI with WinError 5 and reported "failed before running" for
+    commands that were fine). The implementation now lives in one place so the
+    lock store and the three ``config.json`` writers share it instead of
+    carrying four more copies of a bug.
+
+    ``fsync=False`` is the one thing kept local: a job record is ephemeral
+    spill state that a crash invalidates anyway, so a disk flush per status
+    update buys nothing. The durable stores take the default.
+    """
+    write_json_atomic(path, data, indent=1, ensure_ascii=False,
+                      trailing_newline=False, fsync=False)
 
 
 def _move(src: Path, dst: Path) -> None:

code_context_control-2.118.2/tests/test_atomic_json.py

@@ -0,0 +1,240 @@
+"""services.atomic_json — the one publish step for C3's small JSON stores.
+
+Every test here fails against the shape these call sites carried before
+(`<name>.tmp` + a single `os.replace`), which is the shape that crashed shell
+job supervisors on Windows with `PermissionError: [WinError 5]`. The point of
+the module is that the lock store and the three `config.json` writers stop
+re-deriving it, so the last class checks each of those call sites actually
+routes through it rather than only the helper being correct in isolation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import threading
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from services import atomic_json as aj  # noqa: E402
+
+
+class TestTempNaming(unittest.TestCase):
+    """The temp must be unique per WRITE, not per path and not per process."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.path = Path(self._tmp.name) / "config.json"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _replace_spy(self):
+        seen: list[str] = []
+        real = os.replace
+
+        def spy(src, dst):
+            seen.append(Path(src).name)
+            return real(src, dst)
+
+        return seen, spy
+
+    def test_temp_is_not_the_shared_name(self):
+        seen, spy = self._replace_spy()
+        with patch.object(aj.os, "replace", spy):
+            aj.write_json_atomic(self.path, {"a": 1})
+        self.assertEqual(len(seen), 1)
+        self.assertNotEqual(seen[0], "config.json.tmp",
+                            "shared temp name — concurrent writers race on it")
+        self.assertTrue(seen[0].startswith("config.json.tmp"))
+        self.assertIn(str(os.getpid()), seen[0])
+
+    def test_temp_differs_between_writes_in_one_process(self):
+        """Threads share a pid, so `.tmp<pid>` collides exactly as `.tmp` did."""
+        seen, spy = self._replace_spy()
+        with patch.object(aj.os, "replace", spy):
+            for i in range(5):
+                aj.write_json_atomic(self.path, {"a": i})
+        self.assertEqual(len(set(seen)), 5, f"temp name reused: {seen}")
+
+
+class TestReplaceRetry(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.path = Path(self._tmp.name) / "config.json"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_transient_permission_error_is_retried(self):
+        calls = {"n": 0}
+        real = os.replace
+
+        def flaky(src, dst):
+            calls["n"] += 1
+            if calls["n"] < 3:            # two transient failures, then success
+                raise PermissionError(5, "Access is denied")
+            return real(src, dst)
+
+        with patch.object(aj.os, "replace", flaky):
+            aj.write_json_atomic(self.path, {"ok": True})
+        self.assertEqual(calls["n"], 3)
+        self.assertEqual(json.loads(self.path.read_text(encoding="utf-8")),
+                         {"ok": True})
+
+    def test_persistent_permission_error_still_raises(self):
+        """Retrying must not turn a real failure into a silently lost write."""
+        def always(src, dst):
+            raise PermissionError(5, "Access is denied")
+
+        with patch.object(aj.os, "replace", always):
+            with self.assertRaises(PermissionError):
+                aj.write_json_atomic(self.path, {"a": 1})
+
+    def test_a_non_permission_oserror_is_not_retried(self):
+        """Only the Windows sharing violation is transient; the rest surface."""
+        calls = {"n": 0}
+
+        def broken(src, dst):
+            calls["n"] += 1
+            raise OSError(22, "Invalid argument")
+
+        with patch.object(aj.os, "replace", broken):
+            with self.assertRaises(OSError):
+                aj.write_json_atomic(self.path, {"a": 1})
+        self.assertEqual(calls["n"], 1)
+
+    def test_no_temp_is_left_behind_when_replace_fails(self):
+        def always(src, dst):
+            raise PermissionError(5, "Access is denied")
+
+        with patch.object(aj.os, "replace", always):
+            with self.assertRaises(PermissionError):
+                aj.write_json_atomic(self.path, {"a": 1})
+        leftovers = list(self.path.parent.glob("config.json.tmp*"))
+        self.assertEqual(leftovers, [], f"orphaned temps: {leftovers}")
+
+
+class TestSerialisationIsPreserved(unittest.TestCase):
+    """Each call site keeps the exact bytes it wrote before the refactor."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.path = Path(self._tmp.name) / "f.json"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_default_is_indent_2_with_trailing_newline(self):
+        aj.write_json_atomic(self.path, {"a": 1})
+        self.assertEqual(self.path.read_text(encoding="utf-8"),
+                         '{\n  "a": 1\n}\n')
+
+    def test_trailing_newline_can_be_suppressed(self):
+        aj.write_json_atomic(self.path, {"a": 1}, trailing_newline=False)
+        self.assertEqual(self.path.read_text(encoding="utf-8"),
+                         '{\n  "a": 1\n}')
+
+    def test_ensure_ascii_false_keeps_non_ascii_literal(self):
+        aj.write_json_atomic(self.path, {"k": "café"}, ensure_ascii=False)
+        self.assertIn("café", self.path.read_text(encoding="utf-8"))
+
+    def test_parent_directory_is_created(self):
+        deep = Path(self._tmp.name) / "a" / "b" / "c.json"
+        aj.write_json_atomic(deep, {"a": 1})
+        self.assertEqual(json.loads(deep.read_text(encoding="utf-8")), {"a": 1})
+
+
+class TestFsync(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.path = Path(self._tmp.name) / "f.json"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_durable_by_default(self):
+        """A truncated config.json fails the guard closed; flush before publish."""
+        with patch.object(aj.os, "fsync") as fs:
+            aj.write_json_atomic(self.path, {"a": 1})
+        self.assertEqual(fs.call_count, 1)
+
+    def test_opt_out_for_ephemeral_state(self):
+        with patch.object(aj.os, "fsync") as fs:
+            aj.write_json_atomic(self.path, {"a": 1}, fsync=False)
+        fs.assert_not_called()
+
+
+class TestConcurrency(unittest.TestCase):
+    def test_threads_never_publish_a_truncated_file(self):
+        """The end-to-end property, and the one `.tmp<pid>` fails."""
+        with tempfile.TemporaryDirectory() as td:
+            path = Path(td) / "locks.json"
+            errors: list[Exception] = []
+
+            def writer(i):
+                try:
+                    for _ in range(20):
+                        aj.write_json_atomic(path, {"writer": i})
+                except Exception as exc:      # noqa: BLE001 — surfaced below
+                    errors.append(exc)
+
+            threads = [threading.Thread(target=writer, args=(i,))
+                       for i in range(6)]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join()
+
+            self.assertEqual(errors, [], f"concurrent writes failed: {errors}")
+            doc = json.loads(path.read_text(encoding="utf-8"))
+            self.assertIn(doc["writer"], range(6))
+            leftovers = list(path.parent.glob("locks.json.tmp*"))
+            self.assertEqual(leftovers, [], f"orphaned temps: {leftovers}")
+
+
+class TestCallSitesUseIt(unittest.TestCase):
+    """The refactor's actual claim: no copy of the shape is left behind.
+
+    A source scan rather than a behavioural probe, because the four sites sit
+    behind a Flask route, an advisory file lock and a scope resolver — and
+    because the thing being asserted IS textual: nobody re-derives the publish
+    step. `cli/_hook_utils` is exempt on purpose (a PreToolUse subprocess
+    imports nothing from `services`).
+    """
+
+    ROOT = Path(__file__).resolve().parents[1]
+    SITES = (
+        "services/agent_locks.py",
+        "services/access_guard.py",
+        "services/shell_output.py",
+        "cli/hub_server.py",
+        "oracle/services/mobile_api.py",
+    )
+
+    def test_each_site_imports_the_helper(self):
+        for rel in self.SITES:
+            with self.subTest(file=rel):
+                src = (self.ROOT / rel).read_text(encoding="utf-8")
+                self.assertIn("from services.atomic_json import", src)
+
+    def test_no_site_still_writes_a_shared_temp(self):
+        for rel in self.SITES:
+            with self.subTest(file=rel):
+                src = (self.ROOT / rel).read_text(encoding="utf-8")
+                for line in src.splitlines():
+                    stripped = line.strip()
+                    if stripped.startswith("#") or '"""' in stripped:
+                        continue          # prose about the old shape is fine
+                    self.assertNotIn('.name + ".tmp"', stripped)
+                    self.assertNotIn('.name}.tmp"', stripped)
+                    self.assertNotIn('"config.json.tmp"', stripped)
+
+
+if __name__ == "__main__":
+    unittest.main()

{code_context_control-2.118.0 → code_context_control-2.118.2}/tests/test_shell_output.py

@@ -723,5 +723,103 @@ class TestUnicodePaths(_StoreCase):
         self.assertEqual(self.store.list(project_path=project, session_id=session), [])
 
 
+class TestAtomicWrite(unittest.TestCase):
+    """`_write_json_atomic` — the job store's publish step.
+
+    Both cases below fail against the pre-2.118.1 version, which used a single
+    shared `<name>.tmp` and attempted `os.replace` exactly once. That is what
+    crashed a supervisor on Windows CI with WinError 5 and reported "failed
+    before running" for a command that was fine.
+    """
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.path = Path(self._tmp.name) / "job.json"
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_temp_name_is_per_process(self):
+        """Two writers must not collide on the temp file itself."""
+        seen = []
+        real = os.replace
+
+        def spy(src, dst):
+            seen.append(Path(src).name)
+            return real(src, dst)
+
+        with patch.object(so.os, "replace", spy):
+            so._write_json_atomic(self.path, {"a": 1})
+        self.assertEqual(len(seen), 1)
+        self.assertNotEqual(seen[0], "job.json.tmp",
+                            "shared temp name — concurrent writers will race")
+        self.assertTrue(seen[0].startswith("job.json.tmp"))
+        self.assertIn(str(os.getpid()), seen[0])
+        # …and unique per WRITE, not just per process: this store is written
+        # from a threaded server, and threads share a pid.
+        seen.clear()
+        with patch.object(so.os, "replace", spy):
+            so._write_json_atomic(self.path, {"a": 2})
+            so._write_json_atomic(self.path, {"a": 3})
+        self.assertEqual(len(set(seen)), 2, f"temp name reused: {seen}")
+
+    def test_transient_permission_error_is_retried(self):
+        calls = {"n": 0}
+        real = os.replace
+
+        def flaky(src, dst):
+            calls["n"] += 1
+            if calls["n"] < 3:          # two transient failures, then success
+                raise PermissionError(5, "Access is denied")
+            return real(src, dst)
+
+        with patch.object(so.os, "replace", flaky):
+            so._write_json_atomic(self.path, {"ok": True})
+        self.assertEqual(calls["n"], 3)
+        self.assertEqual(json.loads(self.path.read_text(encoding="utf-8")),
+                         {"ok": True})
+
+    def test_a_persistent_permission_error_still_raises(self):
+        """Retrying must not swallow a real, non-transient failure."""
+        def always(src, dst):
+            raise PermissionError(5, "Access is denied")
+
+        with patch.object(so.os, "replace", always):
+            with self.assertRaises(PermissionError):
+                so._write_json_atomic(self.path, {"a": 1})
+
+    def test_no_temp_file_is_left_behind_when_replace_fails(self):
+        def always(src, dst):
+            raise PermissionError(5, "Access is denied")
+
+        with patch.object(so.os, "replace", always):
+            with self.assertRaises(PermissionError):
+                so._write_json_atomic(self.path, {"a": 1})
+        leftovers = list(self.path.parent.glob("job.json.tmp*"))
+        self.assertEqual(leftovers, [], f"orphaned temp files: {leftovers}")
+
+    def test_concurrent_writers_all_publish_valid_json(self):
+        """The end-to-end property: N threads hammering one path never leave
+        the target truncated or half-written."""
+        import threading
+        errors = []
+
+        def writer(i):
+            try:
+                for _ in range(20):
+                    so._write_json_atomic(self.path, {"writer": i})
+            except Exception as exc:      # noqa: BLE001 — surfaced below
+                errors.append(exc)
+
+        threads = [threading.Thread(target=writer, args=(i,)) for i in range(6)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        self.assertEqual(errors, [])
+        self.assertIn("writer", json.loads(self.path.read_text(encoding="utf-8")))
+        self.assertEqual(list(self.path.parent.glob("job.json.tmp*")), [])
+
+
 if __name__ == "__main__":
     unittest.main()