devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/telemetry/logging_setup.py

@@ -37,6 +37,27 @@ _CONSOLE_HANDLER_TAG = "devcouncil.console"
 _LOG_FORMAT = "%(asctime)s %(levelname)-7s [%(name)s] %(message)s"
 _DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
 
+# Last (console_level, log_path) we announced, so repeat configure_logging()
+# calls in the same process don't spam identical "Logging configured" lines
+# into the DEBUG file (observed: ~16% of a real log was this one line).
+_last_announced_config: Optional[tuple] = None
+
+# Messages already emitted via warn_once() in this process.
+_warned_once: set = set()
+
+
+def warn_once(target_logger: logging.Logger, message: str) -> None:
+    """Emit ``message`` at WARNING at most once per process.
+
+    For per-task/per-call code paths that detect a PROCESS-level condition (e.g.
+    a risky config value): the first occurrence is signal, the 20th identical
+    line in one run is log spam that buries real warnings.
+    """
+    if message in _warned_once:
+        return
+    _warned_once.add(message)
+    target_logger.warning(message)
+
 # Default file location (relative to a project root) for the durable run log.
 LOG_RELATIVE_PATH = Path(".devcouncil") / "logs" / "devcouncil.log"
 
@@ -65,6 +86,21 @@ def _resolve_console_level(verbosity: int, quiet: bool, log_level: Optional[str]
     return _level_from_verbosity(verbosity, quiet)
 
 
+def _resolve_log_path(project_root: Optional[Path]) -> Path:
+    """Resolve the shared DEBUG log file location.
+
+    ``DEVCOUNCIL_LOG_DIR`` overrides everything — used by the test suite so
+    fixture noise (fake tasks, deliberate failures) never lands in a real
+    project's ``.devcouncil/logs/devcouncil.log``, and available to anyone who
+    wants logs outside the repo (CI, read-only checkouts).
+    """
+    override = os.environ.get("DEVCOUNCIL_LOG_DIR")
+    if override:
+        return Path(override) / "devcouncil.log"
+    base = Path(project_root) if project_root is not None else Path.cwd()
+    return base / LOG_RELATIVE_PATH
+
+
 def _find_tagged_handler(logger: logging.Logger, tag: str) -> Optional[logging.Handler]:
     for handler in logger.handlers:
         if getattr(handler, "_devcouncil_tag", None) == tag:
@@ -72,6 +108,35 @@ def _find_tagged_handler(logger: logging.Logger, tag: str) -> Optional[logging.H
     return None
 
 
+class _CurrentStderrHandler(logging.StreamHandler):
+    """A stderr handler that resolves ``sys.stderr`` at EMIT time, not at creation.
+
+    The handler is installed once per process and reused. A plain
+    ``logging.StreamHandler()`` snapshots ``sys.stderr`` when constructed; in any
+    context that later replaces or closes that stream — test runners, an MCP server
+    re-pointing stdio, agents embedding the CLI — every subsequent record then hits a
+    dead stream and the logging module prints a ``--- Logging error ---`` report to
+    the *current* stderr, polluting agent-facing (e.g. ``--json``) output. Resolving
+    the stream per emit keeps console logging bound to whatever stderr is now."""
+
+    def __init__(self) -> None:
+        import sys
+
+        super().__init__(sys.stderr)
+
+    @property
+    def stream(self):
+        import sys
+
+        return sys.stderr
+
+    @stream.setter
+    def stream(self, value) -> None:  # noqa: ARG002 - always current sys.stderr
+        # Ignore assignments (StreamHandler.__init__ / setStream): this handler is
+        # permanently bound to the CURRENT sys.stderr by design.
+        pass
+
+
 def configure_logging(
     project_root: Optional[Path] = None,
     *,
@@ -97,7 +162,7 @@ def configure_logging(
     # --- Console handler (stderr) -------------------------------------------
     console = _find_tagged_handler(root, _CONSOLE_HANDLER_TAG)
     if console is None:
-        console = logging.StreamHandler()  # defaults to stderr, keeps stdout clean
+        console = _CurrentStderrHandler()  # emit-time stderr, keeps stdout clean
         console._devcouncil_tag = _CONSOLE_HANDLER_TAG  # type: ignore[attr-defined]
         console.setFormatter(formatter)
         root.addHandler(console)
@@ -106,8 +171,7 @@ def configure_logging(
     # --- Rotating file handler (always DEBUG) -------------------------------
     log_path: Optional[Path] = None
     if _find_tagged_handler(root, _FILE_HANDLER_TAG) is None:
-        base = Path(project_root) if project_root is not None else Path.cwd()
-        log_path = base / LOG_RELATIVE_PATH
+        log_path = _resolve_log_path(project_root)
         try:
             log_path.parent.mkdir(parents=True, exist_ok=True)
             file_handler = RotatingFileHandler(
@@ -125,8 +189,7 @@ def configure_logging(
             # than crashing the command the user actually asked for.
             log_path = None
     else:
-        base = Path(project_root) if project_root is not None else Path.cwd()
-        log_path = base / LOG_RELATIVE_PATH
+        log_path = _resolve_log_path(project_root)
 
     # Quieten chatty third-party loggers on the console; the file still gets them.
     for noisy in ("httpx", "httpcore", "urllib3", "asyncio"):
@@ -134,11 +197,15 @@ def configure_logging(
 
     _install_excepthook()
 
-    logging.getLogger(__name__).debug(
-        "Logging configured (console=%s, file=%s)",
-        logging.getLevelName(console_level),
-        log_path,
-    )
+    global _last_announced_config
+    config = (console_level, str(log_path))
+    if config != _last_announced_config:
+        _last_announced_config = config
+        logging.getLogger(__name__).debug(
+            "Logging configured (console=%s, file=%s)",
+            logging.getLevelName(console_level),
+            log_path,
+        )
     return log_path
 
 
@@ -179,7 +246,7 @@ def set_log_dir(project_root: Path) -> Optional[Path]:
     is a cheap no-op. Returns the (re)resolved log path, or ``None`` if it could not be
     created (logging then stays on the previous handler / console).
     """
-    target = Path(project_root) / LOG_RELATIVE_PATH
+    target = _resolve_log_path(project_root)
     root = logging.getLogger()
     existing = _find_tagged_handler(root, _FILE_HANDLER_TAG)
     if existing is not None:

package/src/devcouncil/telemetry/model_pricing.yaml

@@ -31,6 +31,13 @@ openai/gpt-5.5:
 google/gemini-2.5-flash:
   prompt_per_1k: 0.0003
   completion_per_1k: 0.0025
+nvidia/nemotron-3-ultra-550b-a55b:free:
+  prompt_per_1k: 0.0
+  completion_per_1k: 0.0
+# OpenRouter (Alibaba) Qwen3 Max — default planning/review model.
+qwen/qwen3-max:
+  prompt_per_1k: 0.00078
+  completion_per_1k: 0.0039
 # Local Ollama models run on-device and are free. Bare tags (no ``ollama/``
 # prefix) are listed here so the cost reporter shows $0; the cost.py prefix
 # guard covers any other ``ollama/`` or ``ollama:`` model id.

package/src/devcouncil/telemetry/stages.py

@@ -39,6 +39,13 @@ def _safe_trace(
     """Mirror a stage/step boundary to the JSONL trace, swallowing any error."""
     if project_root is None:
         return
+    # Never MATERIALIZE a project root that doesn't exist: TraceLogger mkdirs
+    # .devcouncil/ under the given path, so tracing under a typo'd/absent
+    # --project-root would silently create directories there — and break
+    # commands that first check the root's existence (observed: `lsp inspect`
+    # reporting a missing root as valid because the stage trace created it).
+    if not Path(project_root).exists():
+        return
     try:
         from devcouncil.telemetry.traces import TraceLogger
 
@@ -89,11 +96,29 @@ def log_stage(
         yield
     except BaseException as exc:
         elapsed = time.monotonic() - start
-        logger.error("✖ %s failed (%.2fs): %s", name, elapsed, exc)
+        # Control-flow exceptions are NOT stage failures: typer.Exit(1)/SystemExit
+        # is how a CLI command reports a legitimate non-zero verdict (e.g. `verify
+        # --json` on a blocked task), and logging it as "✖ failed" both misleads
+        # and — because the log line prints after the command's JSON — corrupts
+        # machine-readable output for any consumer parsing stdout+stderr.
+        control_flow = isinstance(exc, (SystemExit, KeyboardInterrupt, GeneratorExit))
+        if not control_flow:
+            # typer/click CLI exits, matched STRUCTURALLY rather than by isinstance:
+            # typer can vendor click (typer._click.exceptions.Exit), which does not
+            # subclass the top-level click.exceptions.Exit, so an import-based
+            # isinstance check silently misses typer.Exit.
+            cls = type(exc)
+            control_flow = cls.__name__ in {"Exit", "Abort"} and "click" in (cls.__module__ or "")
+        if control_flow:
+            logger.debug("· %s exited via control flow (%.2fs): %r", name, elapsed, exc)
+            raise
+        # %r, not %s: common failures (httpx.ReadTimeout, CancelledError) stringify
+        # to an EMPTY message, which logs a useless "failed (0.05s): ."
+        logger.error("✖ %s failed (%.2fs): %r", name, elapsed, exc)
         _safe_trace(
             project_root,
             "stage_failed",
-            {"stage": name, "error": str(exc), "elapsed_s": round(elapsed, 3), **context},
+            {"stage": name, "error": repr(exc), "elapsed_s": round(elapsed, 3), **context},
             run_id=run_id,
             task_id=task_id,
             summary=f"Stage failed: {name}",

package/src/devcouncil/telemetry/tracker.py

@@ -1,11 +1,16 @@
-import json
+import logging
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, cast
 
 from devcouncil.telemetry.pricing import pricing_for_model
+from devcouncil.utils.json_persist import read_json, write_json
+
+logger = logging.getLogger(__name__)
+
 
 class TelemetryTracker:
     def __init__(self, project_root: Path):
+        self.project_root = project_root
         self.log_file = project_root / ".devcouncil" / "logs" / "telemetry.json"
         # log_usage() reloads the ledger immediately before saving (for concurrent-write
         # safety), so any value read here would always be overwritten before use. Start
@@ -16,16 +21,41 @@ class TelemetryTracker:
     def _load(self) -> Dict[str, Any]:
         if self.log_file.exists():
             try:
-                with open(self.log_file, "r") as f:
-                    return json.load(f)
-            except Exception:
-                pass
+                return cast(Dict[str, Any], read_json(self.log_file))
+            except Exception as e:
+                # A corrupt ledger silently resets accumulated cost stats on the next save.
+                logger.warning("Failed to load telemetry ledger %s, starting fresh: %s", self.log_file, e)
         return {"total_cost": 0.0, "total_prompt_tokens": 0, "total_completion_tokens": 0, "models": {}}
 
     def _save(self):
         self.log_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(self.log_file, "w") as f:
-            json.dump(self.stats, f, indent=2)
+        write_json(self.log_file, self.stats)
+
+    def _warn_if_budget_crossed(self, previous_total: float, new_total: float) -> None:
+        """Warn (once, at the crossing) when cumulative spend passes the configured budget.
+
+        WARN-ONLY by design — this never raises and never blocks a run. The budget is
+        ``telemetry.cost_budget_usd`` in .devcouncil/config.yaml (``dev cost budget --set X``);
+        a missing/invalid config or an unset budget silently disables the check. Warning at
+        the crossing (previous < budget <= new) rather than on every over-budget call keeps
+        one model-call-per-warning noise out of long runs.
+        """
+        try:
+            from devcouncil.app.config import load_config
+
+            budget = load_config(self.project_root).telemetry.cost_budget_usd
+        except Exception:
+            return
+        if budget is None or budget <= 0:
+            return
+        if previous_total < budget <= new_total:
+            logger.warning(
+                "Cost budget crossed: cumulative model spend $%.4f now exceeds the "
+                "configured budget of $%.2f (telemetry.cost_budget_usd). Warn-only — "
+                "runs continue. Review with 'dev cost budget' or 'dev cost show'.",
+                new_total,
+                budget,
+            )
 
     def log_usage(self, model: str, usage: Dict[str, int], *, local: bool = False):
         # Re-read the ledger immediately before mutating so the whole load->mutate->save
@@ -35,6 +65,7 @@ class TelemetryTracker:
         # parallelized SkillOpt _evaluate) each load the same baseline and clobber each
         # other's entries on save. Reloading here makes the last writer additive, not lossy.
         self.stats = self._load()
+        previous_total = float(self.stats.get("total_cost", 0.0) or 0.0)
         prompt_tokens = usage.get("prompt_tokens", 0)
         completion_tokens = usage.get("completion_tokens", 0)
 
@@ -49,15 +80,21 @@ class TelemetryTracker:
                 completion_tokens / 1000.0
             ) * rates["completion_per_1k"]
 
-        self.stats["total_cost"] += cost
-        self.stats["total_prompt_tokens"] += prompt_tokens
-        self.stats["total_completion_tokens"] += completion_tokens
+        # .get with defaults: a hand-edited or partially-written telemetry.json must
+        # not crash usage logging — missing keys just restart their counters.
+        self.stats["total_cost"] = float(self.stats.get("total_cost", 0.0) or 0.0) + cost
+        self.stats["total_prompt_tokens"] = int(self.stats.get("total_prompt_tokens", 0) or 0) + prompt_tokens
+        self.stats["total_completion_tokens"] = (
+            int(self.stats.get("total_completion_tokens", 0) or 0) + completion_tokens
+        )
 
-        if model not in self.stats["models"]:
-            self.stats["models"][model] = {"cost": 0.0, "prompt_tokens": 0, "completion_tokens": 0}
+        models = self.stats.setdefault("models", {})
+        if model not in models:
+            models[model] = {"cost": 0.0, "prompt_tokens": 0, "completion_tokens": 0}
 
         self.stats["models"][model]["cost"] += cost
         self.stats["models"][model]["prompt_tokens"] += prompt_tokens
         self.stats["models"][model]["completion_tokens"] += completion_tokens
 
         self._save()
+        self._warn_if_budget_crossed(previous_total, float(self.stats.get("total_cost", 0.0) or 0.0))

package/src/devcouncil/ui/dashboard.py

@@ -2,18 +2,21 @@ from __future__ import annotations
 
 import json
 import secrets
+import socketserver
 import time
 from importlib import resources
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
 from devcouncil.app.project_status import compute_phase
 from devcouncil.integrations.actions import apply_integration_target
 from devcouncil.integrations.check import build_integration_check_report, integration_status_summary
 from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository
+from devcouncil.utils.json_persist import read_json
+from devcouncil.storage.repositories import ArtifactGraphRepository, GapRepository, StateRepository
+from devcouncil.execution.stop_gate_history import read_events as read_stop_gate_events
 from devcouncil.telemetry.traces import TraceEvent, read_trace_events_since
 
 if TYPE_CHECKING:
@@ -38,7 +41,7 @@ def _load_run_manifest(manifest_path: Path) -> dict | None:
     if cached is not None and cached[0] == mtime:
         return dict(cached[1])
     try:
-        manifest = json.loads(manifest_path.read_text(encoding="utf-8")) or {}
+        manifest = read_json(manifest_path) or {}
     except (json.JSONDecodeError, OSError):
         return None
     _RUN_MANIFEST_CACHE[key] = (mtime, manifest)
@@ -132,6 +135,9 @@ def _invalidate_artifact_graph(project_root: Path) -> None:
 _TRACE_EVENTS_LIMIT = 50
 _TRACE_EVENTS_CACHE: dict[str, tuple[int, list[TraceEvent]]] = {}
 
+_DASHBOARD_GAPS_CAP = 50
+_EMPTY_GAPS_SUMMARY = {"total": 0, "blocking": 0, "items": []}
+
 
 def _recent_trace_events_cached(project_root: Path) -> list[TraceEvent]:
     key = str(project_root)
@@ -146,6 +152,28 @@ def _recent_trace_events_cached(project_root: Path) -> list[TraceEvent]:
     return buffer
 
 
+def _dashboard_gaps_summary(session) -> dict:
+    all_gaps = GapRepository(session).get_all()
+    blocking = [gap for gap in all_gaps if gap.blocking]
+    non_blocking = [gap for gap in all_gaps if not gap.blocking]
+    items: list[dict[str, Any]] = []
+    for gap in blocking + non_blocking:
+        if len(items) >= _DASHBOARD_GAPS_CAP:
+            break
+        description = gap.description
+        if len(description) > 200:
+            description = description[:197] + "..."
+        items.append(
+            {
+                "blocking": gap.blocking,
+                "task_id": gap.task_id or "",
+                "gap_type": gap.gap_type,
+                "description": description,
+            }
+        )
+    return {"total": len(all_gaps), "blocking": len(blocking), "items": items}
+
+
 def logo_svg() -> str:
     return resources.files("devcouncil.assets").joinpath(LEGACY_LOGO_ASSET).read_text(encoding="utf-8")
 
@@ -165,6 +193,8 @@ def dashboard_payload(project_root: Path) -> dict:
             "events": [],
             "integrations": _integration_summary_cached(project_root),
             "recent_runs": recent_run_artifacts(project_root),
+            "stop_gate_events": read_stop_gate_events(project_root, limit=30),
+            "gaps": dict(_EMPTY_GAPS_SUMMARY),
         }
     with db.get_session() as session:
         graph = _artifact_graph_cached(project_root, session)
@@ -179,6 +209,8 @@ def dashboard_payload(project_root: Path) -> dict:
             "events": [event.model_dump(by_alias=True) for event in _recent_trace_events_cached(project_root)],
             "integrations": _integration_summary_cached(project_root),
             "recent_runs": recent_run_artifacts(project_root),
+            "stop_gate_events": read_stop_gate_events(project_root, limit=30),
+            "gaps": _dashboard_gaps_summary(session),
         }
 
 
@@ -287,6 +319,21 @@ def dashboard_html(token: str = "") -> str:
         <tbody id="runs"></tbody>
       </table>
     </section>
+    <section style="grid-column: 1 / -1;">
+      <h2>Verification Gaps</h2>
+      <p id="gaps-summary" style="font-size: 13px; margin: 0 0 12px;"></p>
+      <table>
+        <thead><tr><th>Blocking</th><th>Task</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody id="gaps"></tbody>
+      </table>
+    </section>
+    <section style="grid-column: 1 / -1;">
+      <h2>Stop Gate History</h2>
+      <table>
+        <thead><tr><th>When</th><th>Session</th><th>Decision</th><th>Task</th><th>Claim</th></tr></thead>
+        <tbody id="stop-gate"></tbody>
+      </table>
+    </section>
     <section style="grid-column: 1 / -1;"><h2>Recent Trace Events</h2><pre id="events"></pre></section>
   </main>
   <script>
@@ -382,6 +429,37 @@ def dashboard_html(token: str = "") -> str:
       }}));
 
       document.getElementById('events').textContent = JSON.stringify(data.events || [], null, 2);
+
+      const gapsSummary = data.gaps || {{}};
+      document.getElementById('gaps-summary').textContent =
+        `${{gapsSummary.blocking || 0}} blocking / ${{gapsSummary.total || 0}} total` +
+        ((gapsSummary.total || 0) > (gapsSummary.items || []).length
+          ? ` (showing first ${{(gapsSummary.items || []).length}})`
+          : '');
+
+      const gapsBody = document.getElementById('gaps');
+      gapsBody.replaceChildren(...(gapsSummary.items || []).map(gap => {{
+        const row = document.createElement('tr');
+        row.appendChild(setText(document.createElement('td'), gap.blocking ? 'yes' : 'no'));
+        row.appendChild(setText(document.createElement('td'), gap.task_id || ''));
+        row.appendChild(setText(document.createElement('td'), gap.gap_type || ''));
+        const desc = (gap.description || '').slice(0, 120);
+        row.appendChild(setText(document.createElement('td'), desc));
+        return row;
+      }}));
+
+      const stopGateBody = document.getElementById('stop-gate');
+      stopGateBody.replaceChildren(...(data.stop_gate_events || []).map(ev => {{
+        const row = document.createElement('tr');
+        const when = ev.ts ? new Date(ev.ts * 1000).toLocaleString() : '';
+        row.appendChild(setText(document.createElement('td'), when));
+        row.appendChild(setText(document.createElement('td'), ev.session_id || ''));
+        row.appendChild(setText(document.createElement('td'), ev.decision || ''));
+        row.appendChild(setText(document.createElement('td'), ev.task_id || ''));
+        const claim = (ev.claim || '').slice(0, 120);
+        row.appendChild(setText(document.createElement('td'), claim));
+        return row;
+      }}));
     }}
 
     document.addEventListener('click', event => {{
@@ -402,12 +480,46 @@ def dashboard_html(token: str = "") -> str:
 </html>"""
 
 
-def run_dashboard(project_root: Path, host: str = "127.0.0.1", port: int = 8765) -> None:
+if TYPE_CHECKING:
+    _MixinBase = ThreadingHTTPServer
+else:
+    _MixinBase = object
+
+
+class _LoopbackBindMixin(_MixinBase):
+    # HTTPServer.server_bind resolves socket.getfqdn(), which can hang for
+    # tens of seconds on hosts with slow reverse DNS (seen on macOS CI
+    # runners). The dashboard serves loopback only, so skip the lookup.
+    def server_bind(self) -> None:
+        socketserver.TCPServer.server_bind(self)
+        host, port = self.server_address[:2]
+        self.server_name = str(host)
+        self.server_port = int(port)
+
+
+class DashboardHTTPServer(_LoopbackBindMixin, ThreadingHTTPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+
+
+def run_dashboard(
+    project_root: Path,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    *,
+    server_factory: type[ThreadingHTTPServer] | None = None,
+) -> None:
     dashboard_token = secrets.token_urlsafe(24)
 
-    class DashboardServer(ThreadingHTTPServer):
-        allow_reuse_address = True
-        daemon_threads = True
+    if server_factory is None:
+        # Derive the default at call time from the module-global
+        # ThreadingHTTPServer so tests that monkeypatch it still take effect;
+        # real use gets the loopback bind that skips the getfqdn hang.
+        server_factory = type(
+            "DashboardHTTPServer",
+            (_LoopbackBindMixin, ThreadingHTTPServer),
+            {"allow_reuse_address": True, "daemon_threads": True},
+        )
 
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self):  # noqa: N802
@@ -483,5 +595,5 @@ def run_dashboard(project_root: Path, host: str = "127.0.0.1", port: int = 8765)
         def log_message(self, format, *args):  # noqa: A002
             return
 
-    server = DashboardServer((host, port), Handler)
+    server = server_factory((host, port), Handler)
     server.serve_forever()

package/src/devcouncil/utils/fsio.py

@@ -0,0 +1,58 @@
+"""Atomic file-write helpers.
+
+State files (checkpoints, handoff manifests, semantic indexes, OKF bundles)
+must never be left half-written by a crash or SIGKILL mid-write. These helpers
+write to a temp file in the same directory and ``os.replace`` it into place,
+which is atomic on POSIX and Windows (same volume).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Union
+
+PathLike = Union[str, Path]
+
+
+def atomic_write_text(path: PathLike, data: str, *, encoding: str = "utf-8") -> None:
+    """Atomically replace ``path`` with ``data``. Parent dir must exist."""
+    target = Path(path)
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=f".{target.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding=encoding, newline="") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, target)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def atomic_write_bytes(path: PathLike, data: bytes) -> None:
+    """Atomically replace ``path`` with binary ``data``. Parent dir must exist."""
+    target = Path(path)
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=f".{target.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, target)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def atomic_write_json(path: PathLike, payload: Any, *, indent: int = 2, sort_keys: bool = False) -> None:
+    """Serialize ``payload`` to JSON and atomically write it to ``path``."""
+    atomic_write_text(path, json.dumps(payload, indent=indent, sort_keys=sort_keys, default=str) + "\n")