cluxion-agentplugin-preprocessing 0.3.2__tar.gz → 0.3.3__tar.gz

{cluxion_agentplugin_preprocessing-0.3.2 → cluxion_agentplugin_preprocessing-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cluxion-agentplugin-preprocessing
-Version: 0.3.2
+Version: 0.3.3
 Summary: Universal agent plugin for Cluxion preprocessing, honesty contracts, clarification, Rust work queue, and resource-aware harness handoff.
 Project-URL: Homepage, https://github.com/cluxion/cluxion-Agentplugin-preprocessing
 Project-URL: Repository, https://github.com/cluxion/cluxion-Agentplugin-preprocessing

{cluxion_agentplugin_preprocessing-0.3.2 → cluxion_agentplugin_preprocessing-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cluxion-agentplugin-preprocessing"
-version = "0.3.2"
+version = "0.3.3"
 description = "Universal agent plugin for Cluxion preprocessing, honesty contracts, clarification, Rust work queue, and resource-aware harness handoff."
 readme = "README.md"
 requires-python = ">=3.11"

{cluxion_agentplugin_preprocessing-0.3.2 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_agentplugin_preprocessing/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = ["__version__"]

{cluxion_agentplugin_preprocessing-0.3.2 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_runtime/core/dispatch_store.py

@@ -5,11 +5,18 @@ from __future__ import annotations
 import json
 import os
 import time
+from collections.abc import Iterator
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
 from tempfile import NamedTemporaryFile
 from typing import TYPE_CHECKING
 
+try:
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover - exercised only on non-POSIX platforms.
+    _fcntl = None
+
 if TYPE_CHECKING:
     from cluxion_runtime.core.types import HarnessPlan, QueueSegment
 
@@ -63,48 +70,43 @@ def persist_dispatch_bundle(plan: HarnessPlan, *, dispatch_dir: Path | None = No
             pass
     target_dir.mkdir(parents=True, exist_ok=True)
     path = _bundle_path(plan.item.work_id, target_dir)
-    _atomic_write_json(path, bundle)
+    with _exclusive_bundle_lock(path):
+        _atomic_write_json(path, bundle)
     return path
 
 
 def load_dispatch_bundle(work_id: str, *, dispatch_dir: Path | None = None) -> dict[str, object]:
     """Read the dispatch bundle for a work_id."""
     path = _bundle_path(work_id, default_dispatch_dir() if dispatch_dir is None else dispatch_dir)
-    if not path.exists():
-        raise DispatchStoreError(f"dispatch bundle not found: {work_id}")
-    try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        raise DispatchStoreError(f"dispatch bundle is invalid JSON: {work_id}") from exc
-    if not isinstance(payload, dict):
-        raise DispatchStoreError(f"dispatch bundle must be an object: {work_id}")
-    return payload
+    return _load_dispatch_bundle_from_path(path, work_id)
 
 
 def next_dispatch_step(work_id: str, *, dispatch_dir: Path | None = None) -> dict[str, object]:
     """Mark the next queued segment as running and return the payload for Hermes."""
     target_dir = default_dispatch_dir() if dispatch_dir is None else dispatch_dir
-    bundle = load_dispatch_bundle(work_id, dispatch_dir=target_dir)
-    steps = _steps(bundle)
-    for step in steps:
-        if step.get("status") in {"queued", "retry_wait"}:
-            step["status"] = "running"
-            step["updated_at"] = time.time()
-            _atomic_write_json(_bundle_path(work_id, target_dir), bundle)
-            return {
-                "work_id": work_id,
-                "ready": True,
-                "step": _public_step(step),
-                "remaining": _remaining_count(steps),
-                "synthesis_ready": False,
-            }
-    return {
-        "work_id": work_id,
-        "ready": False,
-        "step": {},
-        "remaining": _remaining_count(steps),
-        "synthesis_ready": all(step.get("status") == "succeeded" for step in steps),
-    }
+    path = _bundle_path(work_id, target_dir)
+    with _exclusive_bundle_lock(path):
+        bundle = _load_dispatch_bundle_from_path(path, work_id)
+        steps = _steps(bundle)
+        for step in steps:
+            if step.get("status") in {"queued", "retry_wait"}:
+                step["status"] = "running"
+                step["updated_at"] = time.time()
+                _atomic_write_json(path, bundle)
+                return {
+                    "work_id": work_id,
+                    "ready": True,
+                    "step": _public_step(step),
+                    "remaining": _remaining_count(steps),
+                    "synthesis_ready": False,
+                }
+        return {
+            "work_id": work_id,
+            "ready": False,
+            "step": {},
+            "remaining": _remaining_count(steps),
+            "synthesis_ready": all(step.get("status") == "succeeded" for step in steps),
+        }
 
 
 def record_dispatch_result(
@@ -118,23 +120,25 @@ def record_dispatch_result(
 ) -> dict[str, object]:
     """Store the segment result produced by the Hermes model."""
     target_dir = default_dispatch_dir() if dispatch_dir is None else dispatch_dir
-    bundle = load_dispatch_bundle(work_id, dispatch_dir=target_dir)
-    steps = _steps(bundle)
-    for step in steps:
-        if step.get("step_id") == step_id:
-            step["status"] = "succeeded" if succeeded else "failed"
-            step["result"] = result
-            step["error"] = error
-            step["updated_at"] = time.time()
-            _atomic_write_json(_bundle_path(work_id, target_dir), bundle)
-            return {
-                "work_id": work_id,
-                "step_id": step_id,
-                "recorded": True,
-                "status": step["status"],
-                "remaining": _remaining_count(steps),
-                "synthesis_ready": all(item.get("status") == "succeeded" for item in steps),
-            }
+    path = _bundle_path(work_id, target_dir)
+    with _exclusive_bundle_lock(path):
+        bundle = _load_dispatch_bundle_from_path(path, work_id)
+        steps = _steps(bundle)
+        for step in steps:
+            if step.get("step_id") == step_id:
+                step["status"] = "succeeded" if succeeded else "failed"
+                step["result"] = result
+                step["error"] = error
+                step["updated_at"] = time.time()
+                _atomic_write_json(path, bundle)
+                return {
+                    "work_id": work_id,
+                    "step_id": step_id,
+                    "recorded": True,
+                    "status": step["status"],
+                    "remaining": _remaining_count(steps),
+                    "synthesis_ready": all(item.get("status") == "succeeded" for item in steps),
+                }
     raise DispatchStoreError(f"dispatch step not found: {work_id}/{step_id}")
 
 
@@ -246,6 +250,34 @@ def _bundle_path(work_id: str, dispatch_dir: Path) -> Path:
     return dispatch_dir / f"{safe}.json"
 
 
+def _load_dispatch_bundle_from_path(path: Path, work_id: str) -> dict[str, object]:
+    if not path.exists():
+        raise DispatchStoreError(f"dispatch bundle not found: {work_id}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise DispatchStoreError(f"dispatch bundle is invalid JSON: {work_id}") from exc
+    if not isinstance(payload, dict):
+        raise DispatchStoreError(f"dispatch bundle must be an object: {work_id}")
+    return payload
+
+
+@contextmanager
+def _exclusive_bundle_lock(path: Path) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if _fcntl is None:
+        # Non-POSIX platforms keep atomic rename but skip advisory locking.
+        yield
+        return
+    lock_path = path.with_name(f"{path.name}.lock")
+    with lock_path.open("a+b") as lock_file:
+        _fcntl.flock(lock_file.fileno(), _fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            _fcntl.flock(lock_file.fileno(), _fcntl.LOCK_UN)
+
+
 def _atomic_write_json(path: Path, payload: dict[str, object]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     with NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:

{cluxion_agentplugin_preprocessing-0.3.2 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_runtime/resources/py_queue.py

@@ -12,9 +12,17 @@ import json
 import os
 import sqlite3
 import time
+from collections.abc import Iterator
+from contextlib import contextmanager
 from pathlib import Path
+from tempfile import NamedTemporaryFile
 from typing import Any
 
+try:
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover - exercised only on non-POSIX platforms.
+    _fcntl = None
+
 
 def run(command: str, payload: dict[str, Any]) -> dict[str, Any]:
     store_dir = Path(payload.get("store_dir") or _default_store())
@@ -41,10 +49,11 @@ def _default_store() -> str:
 
 def _open_db(store_dir: Path) -> sqlite3.Connection:
     store_dir.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(store_dir / "work_queue.sqlite")
+    conn = sqlite3.connect(store_dir / "work_queue.sqlite", timeout=30.0)
     conn.executescript(
         """
         PRAGMA journal_mode=WAL;
+        -- NORMAL+WAL can lose the latest commit on OS crash, but avoids corruption and keeps queue throughput balanced.
         PRAGMA synchronous=NORMAL;
         CREATE TABLE IF NOT EXISTS work_queue (
             work_id TEXT PRIMARY KEY,
@@ -64,6 +73,10 @@ def _open_db(store_dir: Path) -> sqlite3.Connection:
     return conn
 
 
+def _begin_immediate(conn: sqlite3.Connection) -> None:
+    conn.execute("BEGIN IMMEDIATE")
+
+
 def _ok(data: dict[str, Any]) -> dict[str, Any]:
     return {"ok": True, **data}
 
@@ -83,6 +96,7 @@ def _enqueue(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
     metadata_json = json.dumps(payload.get("metadata", {}), ensure_ascii=False)
     now = time.time()
     with _open_db(store_dir) as conn:
+        _begin_immediate(conn)
         sequence = conn.execute("SELECT COALESCE(MAX(sequence), 0) + 1 FROM work_queue").fetchone()[0]
         conn.execute(
             """INSERT INTO work_queue (work_id, prompt, surface, priority, status, metadata_json, sequence, created_at, updated_at)
@@ -99,6 +113,7 @@ def _enqueue(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
 def _dequeue(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
     now = time.time()
     with _open_db(store_dir) as conn:
+        _begin_immediate(conn)
         row = conn.execute(
             """SELECT work_id, prompt, surface, priority, metadata_json FROM work_queue
                WHERE status = 'pending' ORDER BY priority ASC, sequence ASC LIMIT 1"""
@@ -165,9 +180,13 @@ def _read_bundle(path: Path) -> dict[str, Any]:
 
 def _write_atomic(path: Path, payload: dict[str, Any]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
-    temp = path.with_suffix(".json.tmp")
-    temp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    temp.rename(path)
+    with NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+        json.dump(payload, handle, ensure_ascii=False, indent=2)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+        temporary = Path(handle.name)
+    temporary.replace(path)
 
 
 def _steps(bundle: dict[str, Any]) -> list[dict[str, Any]]:
@@ -186,7 +205,8 @@ def _persist(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
     if "bundle" not in payload:
         raise RuntimeError("missing bundle")
     path = _bundle_path(store_dir, work_id)
-    _write_atomic(path, payload["bundle"])
+    with _exclusive_bundle_lock(path):
+        _write_atomic(path, payload["bundle"])
     return _ok({"stored": True, "path": str(path)})
 
 
@@ -207,31 +227,32 @@ def _public_step(step: dict[str, Any]) -> dict[str, Any]:
 def _next_step(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
     work_id = _require_str(payload, "work_id")
     path = _bundle_path(store_dir, work_id)
-    bundle = _read_bundle(path)
-    steps = _steps(bundle)
-    for step in steps:
-        if step.get("status") in ("queued", "retry_wait"):
-            step["status"] = "running"
-            step["updated_at"] = time.time()
-            _write_atomic(path, bundle)
-            return _ok(
-                {
-                    "work_id": work_id,
-                    "ready": True,
-                    "step": _public_step(step),
-                    "remaining": _remaining(steps),
-                    "synthesis_ready": False,
-                }
-            )
-    return _ok(
-        {
-            "work_id": work_id,
-            "ready": False,
-            "step": {},
-            "remaining": _remaining(steps),
-            "synthesis_ready": all(s.get("status") == "succeeded" for s in steps),
-        }
-    )
+    with _exclusive_bundle_lock(path):
+        bundle = _read_bundle(path)
+        steps = _steps(bundle)
+        for step in steps:
+            if step.get("status") in ("queued", "retry_wait"):
+                step["status"] = "running"
+                step["updated_at"] = time.time()
+                _write_atomic(path, bundle)
+                return _ok(
+                    {
+                        "work_id": work_id,
+                        "ready": True,
+                        "step": _public_step(step),
+                        "remaining": _remaining(steps),
+                        "synthesis_ready": False,
+                    }
+                )
+        return _ok(
+            {
+                "work_id": work_id,
+                "ready": False,
+                "step": {},
+                "remaining": _remaining(steps),
+                "synthesis_ready": all(s.get("status") == "succeeded" for s in steps),
+            }
+        )
 
 
 def _record_step(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
@@ -239,28 +260,45 @@ def _record_step(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
     step_id = _require_str(payload, "step_id")
     failed = bool(payload.get("failed", False))
     path = _bundle_path(store_dir, work_id)
-    bundle = _read_bundle(path)
-    steps = _steps(bundle)
-    for step in steps:
-        if step.get("step_id") == step_id:
-            step["status"] = "failed" if failed else "succeeded"
-            step["result"] = payload.get("result", "")
-            step["error"] = payload.get("error", "")
-            step["updated_at"] = time.time()
-            _write_atomic(path, bundle)
-            return _ok(
-                {
-                    "work_id": work_id,
-                    "step_id": step_id,
-                    "recorded": True,
-                    "status": step["status"],
-                    "remaining": _remaining(steps),
-                    "synthesis_ready": all(s.get("status") == "succeeded" for s in steps),
-                }
-            )
+    with _exclusive_bundle_lock(path):
+        bundle = _read_bundle(path)
+        steps = _steps(bundle)
+        for step in steps:
+            if step.get("step_id") == step_id:
+                step["status"] = "failed" if failed else "succeeded"
+                step["result"] = payload.get("result", "")
+                step["error"] = payload.get("error", "")
+                step["updated_at"] = time.time()
+                _write_atomic(path, bundle)
+                return _ok(
+                    {
+                        "work_id": work_id,
+                        "step_id": step_id,
+                        "recorded": True,
+                        "status": step["status"],
+                        "remaining": _remaining(steps),
+                        "synthesis_ready": all(s.get("status") == "succeeded" for s in steps),
+                    }
+                )
     raise RuntimeError(f"dispatch step not found: {work_id}/{step_id}")
 
 
+@contextmanager
+def _exclusive_bundle_lock(path: Path) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if _fcntl is None:
+        # Non-POSIX platforms keep atomic rename but skip advisory locking.
+        yield
+        return
+    lock_path = path.with_name(f"{path.name}.lock")
+    with lock_path.open("a+b") as lock_file:
+        _fcntl.flock(lock_file.fileno(), _fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            _fcntl.flock(lock_file.fileno(), _fcntl.LOCK_UN)
+
+
 def _brief(store_dir: Path, payload: dict[str, Any]) -> dict[str, Any]:
     work_id = _require_str(payload, "work_id")
     bundle = _read_bundle(_bundle_path(store_dir, work_id))

{cluxion_agentplugin_preprocessing-0.3.2 → cluxion_agentplugin_preprocessing-0.3.3}/tests/runtime/test_dispatch_store.py

@@ -1,9 +1,15 @@
+"""Concurrency coverage for the file-backed dispatch store."""
+
 from __future__ import annotations
 
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import suppress
 from typing import TYPE_CHECKING
 
 import pytest
 
+from cluxion_runtime.core import dispatch_store
 from cluxion_runtime.core.dispatch_store import (
     DispatchStoreError,
     build_briefing_payload,
@@ -21,6 +27,7 @@ if TYPE_CHECKING:
     from cluxion_runtime.core.types import HarnessPlan
 
 _SNAPSHOT = ResourceSnapshot(total_ram_mb=48_000, available_ram_mb=40_000, swap_used_mb=0, cpu_percent=20.0)
+_RACE_TIMEOUT_SECONDS = 0.25
 
 
 @pytest.fixture(scope="module")
@@ -51,6 +58,29 @@ def _drain_ids(work_id: str, dispatch_dir: Path) -> list[str]:
         record_dispatch_result(work_id, step_id, result=f"done:{step_id}", dispatch_dir=dispatch_dir)
 
 
+def _run_concurrently(worker_count: int, worker) -> list[object]:
+    start = threading.Barrier(worker_count)
+
+    def run(index: int) -> object:
+        start.wait()
+        return worker(index)
+
+    with ThreadPoolExecutor(max_workers=worker_count) as executor:
+        return list(executor.map(run, range(worker_count)))
+
+
+def _stall_dispatch_writes(monkeypatch: pytest.MonkeyPatch) -> None:
+    original_write = dispatch_store._atomic_write_json
+    write_barrier = threading.Barrier(2)
+
+    def write(path: Path, payload: dict[str, object]) -> None:
+        with suppress(threading.BrokenBarrierError):
+            write_barrier.wait(timeout=_RACE_TIMEOUT_SECONDS)
+        original_write(path, payload)
+
+    monkeypatch.setattr(dispatch_store, "_atomic_write_json", write)
+
+
 def test_persist_skips_plans_without_queue(tmp_path: Path) -> None:
     plan = build_harness_plan(WorkItem("w-short", "작업: 작은 버그를 고쳐줘."), snapshot=_SNAPSHOT)
     assert plan.execution.queue_required is False
@@ -78,6 +108,22 @@ def test_next_marks_step_running_on_disk(tmp_path: Path, queued_plan: HarnessPla
     assert statuses.count("running") == 1
 
 
+def test_concurrent_next_dispatch_steps_do_not_claim_same_step(
+    tmp_path: Path, queued_plan: HarnessPlan, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Concurrent queue-next calls must not overwrite each other's running marker."""
+    persist_dispatch_bundle(queued_plan, dispatch_dir=tmp_path)
+    _stall_dispatch_writes(monkeypatch)
+
+    results = _run_concurrently(2, lambda _index: next_dispatch_step("w-queued", dispatch_dir=tmp_path))
+    step_ids = [str(result["step"]["step_id"]) for result in results if result["ready"]]
+
+    assert len(step_ids) == 2
+    assert len(set(step_ids)) == 2
+    statuses = [step["status"] for step in load_dispatch_bundle("w-queued", dispatch_dir=tmp_path)["steps"]]
+    assert statuses.count("running") == 2
+
+
 def test_next_reports_not_ready_when_nothing_queued(tmp_path: Path, queued_plan: HarnessPlan) -> None:
     persist_dispatch_bundle(queued_plan, dispatch_dir=tmp_path)
     while next_dispatch_step("w-queued", dispatch_dir=tmp_path)["ready"]:
@@ -101,6 +147,32 @@ def test_full_drain_unlocks_briefing(tmp_path: Path, queued_plan: HarnessPlan) -
         assert f"done:{step_id}" in str(briefing["briefing_prompt"])
 
 
+def test_concurrent_record_dispatch_results_preserve_both_updates(
+    tmp_path: Path, queued_plan: HarnessPlan, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Concurrent queue-record calls for different steps must both persist."""
+    persist_dispatch_bundle(queued_plan, dispatch_dir=tmp_path)
+    step_ids = [
+        str(next_dispatch_step("w-queued", dispatch_dir=tmp_path)["step"]["step_id"]),
+        str(next_dispatch_step("w-queued", dispatch_dir=tmp_path)["step"]["step_id"]),
+    ]
+    _stall_dispatch_writes(monkeypatch)
+
+    _run_concurrently(
+        2,
+        lambda index: record_dispatch_result(
+            "w-queued",
+            step_ids[index],
+            result=f"done:{index}",
+            dispatch_dir=tmp_path,
+        ),
+    )
+
+    steps = {str(step["step_id"]): step for step in load_dispatch_bundle("w-queued", dispatch_dir=tmp_path)["steps"]}
+    assert steps[step_ids[0]]["result"] == "done:0"
+    assert steps[step_ids[1]]["result"] == "done:1"
+
+
 def test_record_unknown_step_raises(tmp_path: Path, queued_plan: HarnessPlan) -> None:
     persist_dispatch_bundle(queued_plan, dispatch_dir=tmp_path)
     with pytest.raises(DispatchStoreError):

cluxion_agentplugin_preprocessing-0.3.3/tests/runtime/test_py_queue_concurrency.py

@@ -0,0 +1,160 @@
+"""Concurrency coverage for the pure-Python queue fallback."""
+
+from __future__ import annotations
+
+import json
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from cluxion_runtime.resources import py_queue
+
+_RACE_TIMEOUT_SECONDS = 0.25
+
+
+def _run_concurrently(worker_count: int, worker) -> list[object]:
+    start = threading.Barrier(worker_count)
+
+    def run(index: int) -> object:
+        start.wait()
+        return worker(index)
+
+    with ThreadPoolExecutor(max_workers=worker_count) as executor:
+        return list(executor.map(run, range(worker_count)))
+
+
+def _bundle(step_count: int) -> dict[str, Any]:
+    return {
+        "work_id": "py-race",
+        "steps": [
+            {
+                "step_id": f"s{index}",
+                "segment_id": f"g{index}",
+                "checksum": f"c{index}",
+                "token_estimate": 10,
+                "content": f"segment {index}",
+                "status": "queued",
+                "result": "",
+                "error": "",
+            }
+            for index in range(step_count)
+        ],
+    }
+
+
+def _store_payload(store_dir: Path, **payload: Any) -> dict[str, Any]:
+    return {"store_dir": str(store_dir), **payload}
+
+
+def _dispatch_bundle_path(store_dir: Path, work_id: str) -> Path:
+    return store_dir / "dispatch" / f"{work_id}.json"
+
+
+def _read_dispatch_bundle(store_dir: Path, work_id: str) -> dict[str, Any]:
+    return json.loads(_dispatch_bundle_path(store_dir, work_id).read_text(encoding="utf-8"))
+
+
+def _stall_bundle_writes(monkeypatch: pytest.MonkeyPatch) -> None:
+    original_write = py_queue._write_atomic
+    write_barrier = threading.Barrier(2)
+
+    def write(path: Path, payload: dict[str, Any]) -> None:
+        with suppress(threading.BrokenBarrierError):
+            write_barrier.wait(timeout=_RACE_TIMEOUT_SECONDS)
+        original_write(path, payload)
+
+    monkeypatch.setattr(py_queue, "_write_atomic", write)
+
+
+def test_python_queue_concurrent_next_steps_do_not_claim_same_step(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Python fallback queue-next serializes JSON bundle updates."""
+    store_dir = tmp_path / "queue"
+    py_queue.run("persist", _store_payload(store_dir, work_id="py-race", bundle=_bundle(2)))
+    _stall_bundle_writes(monkeypatch)
+
+    results = _run_concurrently(2, lambda _index: py_queue.run("next", _store_payload(store_dir, work_id="py-race")))
+    step_ids = [str(result["step"]["step_id"]) for result in results if result["ready"]]
+
+    assert len(step_ids) == 2
+    assert len(set(step_ids)) == 2
+    statuses = [step["status"] for step in _read_dispatch_bundle(store_dir, "py-race")["steps"]]
+    assert statuses.count("running") == 2
+
+
+def test_python_queue_concurrent_record_steps_preserve_both_updates(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Python fallback queue-record serializes JSON bundle updates."""
+    store_dir = tmp_path / "queue"
+    py_queue.run("persist", _store_payload(store_dir, work_id="py-race", bundle=_bundle(2)))
+    step_ids = [
+        str(py_queue.run("next", _store_payload(store_dir, work_id="py-race"))["step"]["step_id"]),
+        str(py_queue.run("next", _store_payload(store_dir, work_id="py-race"))["step"]["step_id"]),
+    ]
+    _stall_bundle_writes(monkeypatch)
+
+    _run_concurrently(
+        2,
+        lambda index: py_queue.run(
+            "record",
+            _store_payload(
+                store_dir,
+                work_id="py-race",
+                step_id=step_ids[index],
+                result=f"done:{index}",
+            ),
+        ),
+    )
+
+    steps = {step["step_id"]: step for step in _read_dispatch_bundle(store_dir, "py-race")["steps"]}
+    assert steps[step_ids[0]]["result"] == "done:0"
+    assert steps[step_ids[1]]["result"] == "done:1"
+
+
+def test_python_queue_concurrent_dequeue_serializes_select_update(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Python fallback dequeue uses a transaction so two workers cannot claim one row."""
+    store_dir = tmp_path / "queue"
+    for index in range(2):
+        py_queue.run(
+            "enqueue",
+            _store_payload(store_dir, work_id=f"w{index}", prompt=f"prompt {index}", priority=index),
+        )
+
+    original_open_db = py_queue._open_db
+    select_barrier = threading.Barrier(2)
+
+    class SlowConnection:
+        def __init__(self, conn) -> None:
+            self._conn = conn
+
+        def __enter__(self):
+            self._conn.__enter__()
+            return self
+
+        def __exit__(self, exc_type, exc, tb) -> bool | None:
+            return self._conn.__exit__(exc_type, exc, tb)
+
+        def execute(self, sql: str, parameters: tuple[object, ...] = ()):
+            if "SELECT work_id, prompt, surface, priority, metadata_json FROM work_queue" in sql:
+                with suppress(threading.BrokenBarrierError):
+                    select_barrier.wait(timeout=_RACE_TIMEOUT_SECONDS)
+            return self._conn.execute(sql, parameters)
+
+    def open_db(path: Path) -> SlowConnection:
+        return SlowConnection(original_open_db(path))
+
+    monkeypatch.setattr(py_queue, "_open_db", open_db)
+
+    results = _run_concurrently(2, lambda _index: py_queue.run("dequeue", _store_payload(store_dir)))
+    work_ids = [str(result["item"]["work_id"]) for result in results if result["ready"]]
+
+    assert len(work_ids) == 2
+    assert len(set(work_ids)) == 2