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

{cluxion_agentplugin_preprocessing-0.3.1 → cluxion_agentplugin_preprocessing-0.3.3}/LICENSE

@@ -1,6 +1,6 @@
                                  Apache License
                            Version 2.0, January 2004
-                        https://www.apache.org/licenses/
+                        http://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -73,17 +73,18 @@
    3. Grant of Patent License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      patent license to make, have made, use, offer to sell, sell, import,
-      and otherwise transfer the Work, where such license applies only to
-      those patent claims licensable by such Contributor that are necessarily
-      infringed by their Contribution(s) alone or by combination of their
-      Contribution(s) with the Work to which such Contribution(s) was
-      submitted. If You institute patent litigation against any entity
-      (including a cross-claim or counterclaim in a lawsuit) alleging that
-      the Work or a Contribution incorporated within the Work constitutes
-      direct or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate as
-      of the date such litigation is filed.
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
@@ -130,6 +131,9 @@
       any Contribution intentionally submitted for inclusion in the Work
       by You to the Licensor shall be under the terms and conditions of
       this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
@@ -182,16 +186,16 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-      Copyright 2026 Cluxion
+   Copyright [yyyy] [name of copyright owner]
 
-      Licensed under the Apache License, Version 2.0 (the "License");
-      you may not use this file except in compliance with the License.
-      You may obtain a copy of the License at
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
 
-          https://www.apache.org/licenses/LICENSE-2.0
+       http://www.apache.org/licenses/LICENSE-2.0
 
-      Unless required by applicable law or agreed to in writing, software
-      distributed under the License is distributed on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-      See the License for the specific language governing permissions and
-      limitations under the License.
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cluxion_agentplugin_preprocessing-0.3.3/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: cluxion-agentplugin-preprocessing
+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
+Project-URL: Issues, https://github.com/cluxion/cluxion-Agentplugin-preprocessing/issues
+Author-email: cluxion <algocean1204@users.noreply.github.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai-agent,claude-code,cluxion,codex,hermes-agent,plugin,preprocessing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: browser
+Requires-Dist: playwright>=1.49; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Requires-Dist: wheel>=0.45; extra == 'dev'
+Description-Content-Type: text/markdown
+
+========= Written in Korean first, then English ==========
+
+======== 한국어 ========
+
+# cluxion-agentplugin-preprocessing
+
+AI 코딩 에이전트(Hermes Agent, Claude Code, Codex)를 위한 전처리 플러그인입니다. 작업이 시작되기
+*전에* 정리를 해 줍니다: 에이전트가 모르는 것은 모른다고 인정하게 하고, 애매한 요청은 행동하기 전에
+사용자에게 명확히 묻게 하며, 긴 작업을 안정적으로 큐에 넣고, 폭주하는 프로세스가 기기를 다운시키지
+못하게 막고, 대화가 너무 길어지면 자동으로 압축합니다.
+
+## 설치
+
+```bash
+pip install cluxion-agentplugin-preprocessing
+
+# 선택: 사용자 본인의 로그인된 Chrome으로 웹 검색
+pip install 'cluxion-agentplugin-preprocessing[browser]'
+playwright install chromium
+```
+
+### Hermes Agent에서 사용
+
+```bash
+cluxion-preprocess enable     # ~/.hermes/config.yaml 에 플러그인을 추가합니다
+# 그 다음 Hermes 재시작
+```
+
+Hermes를 통해 제공되는 로컬 모델(vLLM/MLX)에서도 동일하게 동작합니다.
+
+## 기능
+
+활성화하면 에이전트가 아래 도구들을 얻고, 자동으로 호출합니다.
+
+- **정직함과 명확화** — 에이전트가 추측하기 전에 먼저 묻고, 근거를 댈 수 없는 답을 지어내지 않습니다.
+- **작업 큐** — 긴 작업을 하나의 프롬프트에 넘치게 담는 대신 추적 가능한 세그먼트로 분할합니다.
+- **자원 가드** — 폭주 프로세스가 RAM을 모두 잡아먹지 못하게 막는 가벼운 감시기. Hermes 세션마다
+  자동으로 시작됩니다.
+- **컨텍스트 압축** — 대화가 모델 컨텍스트의 약 70%를 넘으면, 의도와 최근 대화를 보존하며 압축합니다.
+- **내 Chrome으로 웹 검색** — 본인의 로그인된 브라우저 세션으로 Google / Naver / Perplexity / 사내
+  페이지를 검색합니다(위의 `[browser]` extra 필요).
+
+## 문제 해결
+
+| 증상 | 해결 |
+|---|---|
+| `playwright_not_installed` | `pip install 'cluxion-agentplugin-preprocessing[browser]' && playwright install chromium` |
+| Hermes에 도구가 안 보임 | `cluxion-preprocess enable` 실행 후 Hermes 재시작 |
+
+## 라이선스
+
+Apache-2.0
+
+============ English ==========
+
+# cluxion-agentplugin-preprocessing
+
+A preprocessing plugin for AI coding agents (Hermes Agent, Claude Code, Codex). It tidies
+things up *before* work starts: it makes the agent admit when it doesn't know, asks you to
+clarify vague requests before acting, queues long tasks reliably, keeps runaway processes
+from taking down your machine, and auto-compresses the conversation when it grows too long.
+
+## Install
+
+```bash
+pip install cluxion-agentplugin-preprocessing
+
+# optional: web search through your own logged-in Chrome
+pip install 'cluxion-agentplugin-preprocessing[browser]'
+playwright install chromium
+```
+
+### Use with Hermes Agent
+
+```bash
+cluxion-preprocess enable     # adds the plugin to ~/.hermes/config.yaml
+# then restart Hermes
+```
+
+The tools also work with local models (vLLM/MLX) served through Hermes.
+
+## What you get
+
+Once enabled, your agent gains these tools and calls them automatically:
+
+- **Honesty & clarification** — the agent asks before guessing and won't fake an answer it
+  can't back up.
+- **Work queue** — long tasks are split into tracked segments instead of overflowing a
+  single prompt.
+- **Resource guard** — a lightweight watcher that stops runaway processes from eating all
+  your RAM. It starts automatically with each Hermes session.
+- **Context compression** — shrinks the conversation once it passes ~70% of the model's
+  window, keeping your intent and recent turns.
+- **Web search via your Chrome** — searches Google / Naver / Perplexity / internal pages
+  through your own logged-in browser session (needs the `[browser]` extra above).
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `playwright_not_installed` | `pip install 'cluxion-agentplugin-preprocessing[browser]' && playwright install chromium` |
+| Tools don't appear in Hermes | run `cluxion-preprocess enable`, then restart Hermes |
+
+## License
+
+Apache-2.0

cluxion_agentplugin_preprocessing-0.3.3/README.md

@@ -0,0 +1,106 @@
+========= Written in Korean first, then English ==========
+
+======== 한국어 ========
+
+# cluxion-agentplugin-preprocessing
+
+AI 코딩 에이전트(Hermes Agent, Claude Code, Codex)를 위한 전처리 플러그인입니다. 작업이 시작되기
+*전에* 정리를 해 줍니다: 에이전트가 모르는 것은 모른다고 인정하게 하고, 애매한 요청은 행동하기 전에
+사용자에게 명확히 묻게 하며, 긴 작업을 안정적으로 큐에 넣고, 폭주하는 프로세스가 기기를 다운시키지
+못하게 막고, 대화가 너무 길어지면 자동으로 압축합니다.
+
+## 설치
+
+```bash
+pip install cluxion-agentplugin-preprocessing
+
+# 선택: 사용자 본인의 로그인된 Chrome으로 웹 검색
+pip install 'cluxion-agentplugin-preprocessing[browser]'
+playwright install chromium
+```
+
+### Hermes Agent에서 사용
+
+```bash
+cluxion-preprocess enable     # ~/.hermes/config.yaml 에 플러그인을 추가합니다
+# 그 다음 Hermes 재시작
+```
+
+Hermes를 통해 제공되는 로컬 모델(vLLM/MLX)에서도 동일하게 동작합니다.
+
+## 기능
+
+활성화하면 에이전트가 아래 도구들을 얻고, 자동으로 호출합니다.
+
+- **정직함과 명확화** — 에이전트가 추측하기 전에 먼저 묻고, 근거를 댈 수 없는 답을 지어내지 않습니다.
+- **작업 큐** — 긴 작업을 하나의 프롬프트에 넘치게 담는 대신 추적 가능한 세그먼트로 분할합니다.
+- **자원 가드** — 폭주 프로세스가 RAM을 모두 잡아먹지 못하게 막는 가벼운 감시기. Hermes 세션마다
+  자동으로 시작됩니다.
+- **컨텍스트 압축** — 대화가 모델 컨텍스트의 약 70%를 넘으면, 의도와 최근 대화를 보존하며 압축합니다.
+- **내 Chrome으로 웹 검색** — 본인의 로그인된 브라우저 세션으로 Google / Naver / Perplexity / 사내
+  페이지를 검색합니다(위의 `[browser]` extra 필요).
+
+## 문제 해결
+
+| 증상 | 해결 |
+|---|---|
+| `playwright_not_installed` | `pip install 'cluxion-agentplugin-preprocessing[browser]' && playwright install chromium` |
+| Hermes에 도구가 안 보임 | `cluxion-preprocess enable` 실행 후 Hermes 재시작 |
+
+## 라이선스
+
+Apache-2.0
+
+============ English ==========
+
+# cluxion-agentplugin-preprocessing
+
+A preprocessing plugin for AI coding agents (Hermes Agent, Claude Code, Codex). It tidies
+things up *before* work starts: it makes the agent admit when it doesn't know, asks you to
+clarify vague requests before acting, queues long tasks reliably, keeps runaway processes
+from taking down your machine, and auto-compresses the conversation when it grows too long.
+
+## Install
+
+```bash
+pip install cluxion-agentplugin-preprocessing
+
+# optional: web search through your own logged-in Chrome
+pip install 'cluxion-agentplugin-preprocessing[browser]'
+playwright install chromium
+```
+
+### Use with Hermes Agent
+
+```bash
+cluxion-preprocess enable     # adds the plugin to ~/.hermes/config.yaml
+# then restart Hermes
+```
+
+The tools also work with local models (vLLM/MLX) served through Hermes.
+
+## What you get
+
+Once enabled, your agent gains these tools and calls them automatically:
+
+- **Honesty & clarification** — the agent asks before guessing and won't fake an answer it
+  can't back up.
+- **Work queue** — long tasks are split into tracked segments instead of overflowing a
+  single prompt.
+- **Resource guard** — a lightweight watcher that stops runaway processes from eating all
+  your RAM. It starts automatically with each Hermes session.
+- **Context compression** — shrinks the conversation once it passes ~70% of the model's
+  window, keeping your intent and recent turns.
+- **Web search via your Chrome** — searches Google / Naver / Perplexity / internal pages
+  through your own logged-in browser session (needs the `[browser]` extra above).
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `playwright_not_installed` | `pip install 'cluxion-agentplugin-preprocessing[browser]' && playwright install chromium` |
+| Tools don't appear in Hermes | run `cluxion-preprocess enable`, then restart Hermes |
+
+## License
+
+Apache-2.0

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cluxion-agentplugin-preprocessing"
-version = "0.3.1"
+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.1 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_agentplugin_preprocessing/__init__.py

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

{cluxion_agentplugin_preprocessing-0.3.1 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_agentplugin_preprocessing/guard_watch.py

@@ -51,23 +51,27 @@ def post_tool_call(**_: Any) -> None:
     let the existing owned-only fail-closed enforcement path terminate
     candidates.
     """
-    global _last_watch_at
+    global _last_warning_at, _last_watch_at
 
     now = time.monotonic()
-    with _lock:
-        if _last_watch_at is not None and now - _last_watch_at < _watch_interval_seconds():
-            return
-        _last_watch_at = now
-
     try:
-        result = guard_bridge.auto_enforce([os.getpid()], dry_run=not _auto_apply_enabled())
+        with _lock:
+            if _last_watch_at is not None and now - _last_watch_at < _watch_interval_seconds():
+                return
+            _last_watch_at = now
+            result = guard_bridge.auto_enforce([os.getpid()], dry_run=not _auto_apply_enabled())
+            should_warn = (
+                bool(result.get("triggered", False))
+                and bool(result.get("dry_run", True))
+                and (_last_warning_at is None or now - _last_warning_at >= WARNING_INTERVAL_SECONDS)
+            )
+            if should_warn:
+                _last_warning_at = now
     except Exception as exc:
         _warn(f"cluxion guard watch failed: {exc}")
         return
-    if not result.get("triggered", False) or not result.get("dry_run", True):
-        return
-
-    _warn_triggered(result, now)
+    if should_warn:
+        _warn_triggered(result)
 
 
 def _autostart_enabled() -> bool:
@@ -88,14 +92,7 @@ def _watch_interval_seconds() -> float:
         return DEFAULT_WATCH_INTERVAL_SECONDS
 
 
-def _warn_triggered(result: dict[str, Any], now: float) -> None:
-    global _last_warning_at
-
-    with _lock:
-        if _last_warning_at is not None and now - _last_warning_at < WARNING_INTERVAL_SECONDS:
-            return
-        _last_warning_at = now
-
+def _warn_triggered(result: dict[str, Any]) -> None:
     pids = [str(entry.get("pid")) for entry in result.get("candidates", []) if isinstance(entry, dict)]
     reasons = [str(reason) for reason in result.get("trigger_reasons", [])]
     _warn(

{cluxion_agentplugin_preprocessing-0.3.1 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_agentplugin_preprocessing/schemas.py

@@ -53,6 +53,11 @@ PLAN_SCHEMA = {
             "expected_ram_mb": {"type": "integer", "minimum": 0, "default": 0},
             "context_tokens": {"type": "integer", "minimum": 0, "default": 0},
             "cwd": {"type": "string", "default": ""},
+            "clarification_answers": {
+                "type": "string",
+                "default": "",
+                "description": "Answers that resolve a prior clarification gate; required to enqueue an ambiguous or large task.",
+            },
         },
         "required": ["prompt"],
     },

{cluxion_agentplugin_preprocessing-0.3.1 → cluxion_agentplugin_preprocessing-0.3.3}/src/cluxion_runtime/adapters/contract.py

@@ -25,7 +25,7 @@ def work_item_from_adapter_payload(payload: Mapping[str, object], *, default_sur
         model_route=str(payload.get("model_route", "host/default")),
         expected_ram_mb=max(0, int(payload.get("expected_ram_mb", 0))),
         context_tokens=max(0, int(payload.get("context_tokens", 0))),
-        metadata=_metadata(payload.get("metadata"), payload.get("cwd")),
+        metadata=_metadata(payload.get("metadata"), payload.get("cwd"), payload.get("clarification_answers")),
     )
 
 
@@ -70,12 +70,18 @@ def _priority(value: object) -> WorkPriority:
     return WorkPriority[str(value).upper()]
 
 
-def _metadata(value: object, cwd: object) -> dict[str, str]:
+def _metadata(value: object, cwd: object, clarification_answers: object = None) -> dict[str, str]:
     metadata: dict[str, str] = {}
     if isinstance(value, dict):
         metadata.update({str(key): str(val) for key, val in value.items()})
     if cwd is not None and cwd != "":
         metadata["cwd"] = str(cwd)
+    # Top-level clarification_answers is the documented way the host answers a
+    # clarification gate; without merging it here the gate stays blocked and the
+    # work queue never engages, even for very long prompts. A nested
+    # metadata.clarification_answers (if present) is not overwritten by an empty top-level value.
+    if clarification_answers is not None and str(clarification_answers) != "":
+        metadata["clarification_answers"] = str(clarification_answers)
     return metadata
 
 

{cluxion_agentplugin_preprocessing-0.3.1 → 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: