codex-bot 0.3.1__tar.gz → 0.4.0__tar.gz

{codex_bot-0.3.1 → codex_bot-0.4.0}/.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 env/
 venv/
 .venv/
+.venv-*/
 ENV/
 
 # --- Build & Distribution ---
@@ -49,6 +50,7 @@ docs/_build/
 .mypy_cache/
 .ruff_cache/
 .uv-cache/
+.uv-cache-*/
 .dmypy.json
 dmypy.json
 .pyre/
@@ -72,3 +74,7 @@ sandbox/
 # Agent instructions (local-only, points to local knowledge graph)
 AGENTS.md
 CLAUDE.md
+
+# Generated local navigation artifacts
+/graphify-out/
+/project_structure.txt

{codex_bot-0.3.1 → codex_bot-0.4.0}/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-10-09
+
+### Added
+
+- Versioned agent skill for projects using `codex-bot`, with an offline install, update, status, and delete command.
+- Maintained project skill and English/Russian consumer installation guides.
+
+### Changed
+
+- Moved maintained repository guidance to `docs/agent-skills/` and stopped tracking local Claude configuration and generated navigation artifacts.
+- Restricted source distributions to release files and excluded local caches, virtual environments, and generated graph output from Git tracking.
+- Updated the locked `codex-core` dependency from 0.4.0 to 0.5.0.
+- Raised the `aiohttp` and `pydantic-settings` minimum versions, aligned generated project dependencies, and refreshed vulnerable locked runtime, development, and documentation dependencies.
+
+### Fixed
+
+- Aligned the package's `__license__` attribute with its Apache-2.0 license and removed obsolete stream type-checker suppressions.
+- Kept Telegram feature discovery usable without the optional Redis dependencies by loading stream integrations only when Redis handlers are registered.
+
+## [0.3.1] - 2026-05-21
+
+### Changed
+
+- Updated stream router and dispatcher integration for `codex-platform` 0.5.2.
+- Raised the development `pygments` floor to 2.20.0.
+
+### Fixed
+
+- Added recovery of stale pending Redis stream messages so unacknowledged events can be processed again.
+
 ## [0.3.0] - 2026-04-23
 
 ### Changed

{codex_bot-0.3.1 → codex_bot-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codex-bot
-Version: 0.3.1
+Version: 0.4.0
 Summary: Feature-based Aiogram framework library — reusable infrastructure for Telegram bots
 Project-URL: Homepage, https://github.com/codexdlc/codex-bot
 Project-URL: Documentation, https://codexdlc.github.io/codex-bot/
@@ -22,9 +22,9 @@ Classifier: Topic :: Communications :: Chat
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.12
 Requires-Dist: aiogram<4.0,>=3.27.0
-Requires-Dist: aiohttp>=3.13.4
+Requires-Dist: aiohttp>=3.14.3
 Requires-Dist: jinja2>=3.1.0
-Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: questionary>=2.0.0
@@ -141,6 +141,8 @@ if __name__ == "__main__":
 
 ## Documentation
 
+Repository contributors can use the [project agent skill](docs/agent-skills/codex-bot/SKILL.md). To install the versioned library skill in a consuming project, see the [agent skill guide](docs/en_EN/guide/agent-skills.md).
+
 Full documentation with architecture diagrams, API reference, and guides:
 
 **[https://codexdlc.github.io/codex-bot/](https://codexdlc.github.io/codex-bot/)**

{codex_bot-0.3.1 → codex_bot-0.4.0}/README.md

@@ -51,6 +51,8 @@ if __name__ == "__main__":
 
 ## Documentation
 
+Repository contributors can use the [project agent skill](docs/agent-skills/codex-bot/SKILL.md). To install the versioned library skill in a consuming project, see the [agent skill guide](docs/en_EN/guide/agent-skills.md).
+
 Full documentation with architecture diagrams, API reference, and guides:
 
 **[https://codexdlc.github.io/codex-bot/](https://codexdlc.github.io/codex-bot/)**

codex_bot-0.4.0/docs/agent-skills/codex-bot/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: codex-bot-project
+description: Use when changing codex-bot source, templates, or public API in this repository.
+---
+
+# codex-bot project work
+
+This is the canonical source of the `codex-bot` Python package. Read the relevant implementation and tests before changing behavior. Library usage instructions for consumers live in `src/codex_bot/agent_skills/resources/`; installed copies in other projects are managed outputs.
+
+- For feature scaffolding or CLI changes, read [feature workflow](references/feature-workflow.md).
+- For routing, orchestration, DTOs, or sender changes, read [runtime contracts](references/runtime-contracts.md).
+- For agent-skill delivery changes, read [skill delivery](references/skill-delivery.md).
+
+Run focused tests for changed behavior. The project configuration is `pyproject.toml`; the source package is under `src/codex_bot`. Follow the root `AGENTS.md` graphify instructions after code changes.

codex_bot-0.4.0/docs/agent-skills/codex-bot/references/feature-workflow.md

@@ -0,0 +1,7 @@
+# Feature generation and discovery
+
+`codex_bot.cli.main` exposes `startproject`, `create-feature`, migration, and inspect commands. `startproject` renders files from `src/codex_bot/templates/project`; `create-feature` renders `telegram` or `redis` templates. Check the command implementation and template source together before changing generated output.
+
+`FeatureDiscoveryService` in `src/codex_bot/engine/discovery/service.py` imports configured feature modules by convention. Telegram and Redis features use `features.telegram.<name>.feature_setting` and `features.redis.<name>.feature_setting`. When a feature's package layout changes, check discovery and generated templates together; tests in `tests/test_templates.py`, `tests/test_template_consistency.py`, and `tests/integration/test_templates_e2e.py` cover generated projects.
+
+The CLI's `--force` option can overwrite existing project files. Inspect its actual merge behavior before changing it or recommending it for an existing user project.

codex_bot-0.4.0/docs/agent-skills/codex-bot/references/runtime-contracts.md

@@ -0,0 +1,9 @@
+# Runtime contracts
+
+`BaseBotOrchestrator` in `src/codex_bot/base/base_orchestrator.py` accepts a request-scoped `Director` and returns `ViewResultDTO` or `UnifiedViewDTO` from `render_content`. Keep per-request mutable data in arguments or the director, since orchestrator instances may be shared.
+
+`ViewResultDTO` and `UnifiedViewDTO` in `src/codex_bot/base/view_dto.py` are frozen Pydantic models. Use `model_copy(update=...)` to derive a changed view. `ViewSender.send` needs `chat_id` and `session_key`; it persists message coordinates through `SenderManager`. It does not handle `alert_text`, which the callback handler must answer.
+
+`BotBuilder` in `src/codex_bot/engine/factory/bot_builder.py` registers core middleware before project middleware. Changes to middleware registration affect request context and should be checked in `tests/engine/factory/test_bot_builder.py` and relevant middleware tests. `BaseStateManager` stores feature drafts under `draft:<feature_key>` and clears only its namespace.
+
+`ThrottlingMiddleware` in `src/codex_bot/engine/middlewares/throttling.py` uses Redis `SET` with `nx=True` and a millisecond TTL for atomic rate limiting. Preserve that single-operation check when changing throttling; an `EXISTS` then `SET` sequence would permit concurrent requests through.

codex_bot-0.4.0/docs/agent-skills/codex-bot/references/skill-delivery.md

@@ -0,0 +1,7 @@
+# Shipped agent skill
+
+Canonical consumer instructions live in `src/codex_bot/agent_skills/resources/`. The `python -m codex_bot.agent_skills` installer copies those resources into a consuming project's `.agents/skills/codex-bot/`, records managed hashes, and adds a bounded root `AGENTS.md` pointer. Consumer copies and manifests are managed; application-specific guidance belongs in a separate project skill.
+
+When changing the public API, inspect the corresponding consumer reference for stale examples. When changing delivery, run `tests/agent_skills/test_installer.py`, build a wheel, inspect its payload, and test the module command from an isolated install. Installation and update must not replace local edits to managed files.
+
+The source distribution uses an explicit include list in `pyproject.toml`. When adding release assets, check both the source archive and the wheel built from it. Local agent settings, generated graphs, caches, and `project_structure.txt` must stay outside both Git tracking and release artifacts; maintained skills under `docs/agent-skills` and packaged skill resources remain versioned.

codex_bot-0.4.0/docs/en_EN/guide/agent-skills.md

@@ -0,0 +1,16 @@
+# Agent skill for consuming projects
+
+`codex-bot` includes an optional offline skill for coding agents. It is packaged in the core Python distribution; no running Telegram bot or extra dependency is needed to install the guidance. Run these commands with the Python environment where `codex-bot` is installed and point `--project` to an existing project root:
+
+```shell
+python -m codex_bot.agent_skills status --project /path/to/bot
+python -m codex_bot.agent_skills install --project /path/to/bot
+python -m codex_bot.agent_skills update --project /path/to/bot
+python -m codex_bot.agent_skills delete --project /path/to/bot
+```
+
+Installation creates `.agents/skills/codex-bot/`, a `.manifest.json` containing the installed package version and file hashes, and a bounded pointer in the project's root `AGENTS.md`. Existing project instructions outside that block are preserved. `status` exits 0 only if the installation matches the installed package and its files. It exits 1 if absent, stale, modified, or corrupt.
+
+After upgrading the package, run `update` to refresh the skill. Update and delete refuse to change locally modified managed files; copy your edits into a separate project-owned skill first. The installer also refuses unowned destination collisions and symlinks or Windows reparse points in the target path. It stages writes with rollback for ordinary filesystem errors; it does not promise crash-safe multi-file transactions or safe concurrent installer runs.
+
+The repository's own maintenance skill is [separate](../../agent-skills/codex-bot/SKILL.md). Consumer-specific rules should not be written into the managed library skill.

{codex_bot-0.3.1 → codex_bot-0.4.0}/docs/en_EN/roadmap.md

@@ -2,6 +2,8 @@
 
 The development path of **codex-bot** from a base framework to a complete Telegram development ecosystem.
 
+Release 0.4.0 adds managed agent skills, offline skill installation, and dependency and packaging maintenance. See the [installation guide](guide/agent-skills.md). The unchecked items below are future work, without assigned release versions.
+
 ---
 
 ## ✅ Phase 1: Foundation (v0.1.0) — COMPLETED
@@ -10,7 +12,7 @@ The development path of **codex-bot** from a base framework to a complete Telegr
 - [x] Basic Redis Integration: FSM and Storage.
 - [x] CLI: `startproject` command and base templates.
 
-## 🏗️ Phase 2: Protocols & Standardization (v0.2.0) — CURRENT
+## 🏗️ Phase 2: Protocols & Standardization — IN PROGRESS
 - [x] **Smart Merge**: Safe integration into existing projects via CLI.
 - [x] **FSM Isolation**: Namespacing feature data (BaseStateManager).
 - [x] **Smart Resolver**: `director.resolve()` pattern for navigation control.
@@ -19,20 +21,20 @@ The development path of **codex-bot** from a base framework to a complete Telegr
 - [x] **Metadata-Driven Navigation**: Full support for `__next_scene__`. [**(Backlog)**](./tasks/backlog.md)
 - [ ] **Redis Stream FSM Integration**: Automatic Director injection in Redis handlers. [**(Task #004b)**](./tasks/004_high_redis_fsm_integration.md)
 
-## 🧩 Phase 3: DX & Tooling (v0.3.0) — PLANNED
+## 🧩 Phase 3: DX & Tooling — PLANNED
 - [ ] **In-Bot Guide System**: Interactive documentation navigator. [**(Task #003)**](./tasks/003_high_in_bot_guide_system.md)
 - [ ] **Status Commands**: Built-in system health diagnostics (DB, Redis, API).
 - [ ] **Strict Typing**: Transition to Enums for states and transitions.
 - [ ] **Contextual Hints**: Educational mode in CLI during feature creation.
 
-## 🚀 Phase 4: Scaling & Infrastructure (v0.4.0) — PLANNED
+## 🚀 Phase 4: Scaling & Infrastructure — PLANNED
 - [ ] **Webhooks Service**: Native support for incoming webhooks (FastAPI/Aiohttp). [**(Task #009)**](./tasks/009_high_webhook_server.md)
 - [ ] **Docker Infrastructure**: Ready-to-use containerization templates. [**(Task #002)**](./tasks/002_med_docker_infrastructure.md)
 - [ ] **Smart Recovery**: Automated retry logic for API and DB.
 - [ ] **Animation Engine**: Expanding the library of visual waiting effects.
 - [ ] **SQLAlchemy Sender Storage**: Persistent UI coordinate storage without Redis. [**(Task #007)**](./tasks/007_med_sqlalchemy_sender_storage.md)
 
-## 📡 Phase 5: Event-Driven Ecosystem (v0.5.0+) — PLANNED
+## 📡 Phase 5: Event-Driven Ecosystem — PLANNED
 - [ ] **Multi-Broker Support**: Adapters for RabbitMQ and Kafka with unified router syntax. [**(Task #008)**](./tasks/008_high_multi_broker_support.md)
 - [ ] **Remote FSM Management**: User state management via brokers without Aiogram involvement.
 - [ ] **Smart Routing**: Automated message distribution between multiple bot instances.

codex_bot-0.4.0/docs/ru_RU/guide/agent-skills.md

@@ -0,0 +1,14 @@
+# Навык для проектов на codex-bot
+
+Пакет `codex-bot` содержит необязательный навык для кодовых агентов и автономный офлайн-установщик. Запускайте его через Python окружения, где установлен пакет; `--project` должен указывать на существующий корень проекта:
+
+```shell
+python -m codex_bot.agent_skills status --project /path/to/bot
+python -m codex_bot.agent_skills install --project /path/to/bot
+python -m codex_bot.agent_skills update --project /path/to/bot
+python -m codex_bot.agent_skills delete --project /path/to/bot
+```
+
+Установщик создаёт `.agents/skills/codex-bot/`, манифест с версией пакета и хешами файлов, а также ограниченный маркерами указатель в корневом `AGENTS.md`. Остальные инструкции проекта сохраняются. `status` возвращает код 0 только для актуальной и целой установки. После обновления пакета вызовите `update`. Команды `update` и `delete` отказываются перезаписывать локально изменённые управляемые файлы: сначала перенесите собственные правила в отдельный проектный навык.
+
+Установщик отклоняет конфликтующие неуправляемые файлы, ссылки и Windows reparse points. Обычные ошибки записи обрабатываются откатом; гарантий атомарности при падении процесса или одновременных запусках нет. Навык для разработки самой библиотеки находится [отдельно](../../agent-skills/codex-bot/SKILL.md).

{codex_bot-0.3.1 → codex_bot-0.4.0}/docs/ru_RU/roadmap.md

@@ -2,6 +2,8 @@
 
 Путь развития **codex-bot** от базового фреймворка до полноценной экосистемы разработки Telegram-ботов.
 
+Выпуск 0.4.0 добавляет управляемые навыки агента, их офлайн-установку и обновления зависимостей и упаковки. См. [инструкцию установки](guide/agent-skills.md). Незавершённые пункты ниже остаются планами без привязки к номерам выпусков.
+
 ---
 
 ## ✅ Фаза 1: Фундамент (v0.1.0) — ЗАВЕРШЕНО
@@ -10,7 +12,7 @@
 - [x] Базовая интеграция с Redis (FSM и Сторадж).
 - [x] CLI: Команда `startproject` и базовые шаблоны.
 
-## 🏗️ Фаза 2: Протоколы и Стандартизация (v0.2.0) — ТЕКУЩАЯ
+## 🏗️ Фаза 2: Протоколы и Стандартизация — В РАБОТЕ
 - [x] **Smart Merge**: Безопасная интеграция в существующие проекты через CLI.
 - [x] **Изоляция FSM**: Namespacing данных фич (BaseStateManager).
 - [x] **Умный Резолвер**: Паттерн `director.resolve()` для управления навигацией.
@@ -19,20 +21,20 @@
 - [x] **Metadata-Driven Navigation**: Полная поддержка `__next_scene__`. [**(Бэклог)**](./tasks/backlog.md)
 - [x] **Интеграция Redis Stream с FSM**: Автоматическая инъекция Director в Redis-хендлеры. [**(Задача #004b)**](./tasks/004_high_redis_fsm_integration.md)
 
-## 🧩 Фаза 3: DX & Tooling (v0.3.0) — В ПЛАНАХ
+## 🧩 Фаза 3: DX & Tooling — В ПЛАНАХ
 - [ ] **Система Гидов**: Интерактивный навигатор по документации прямо в боте. [**(Задача #003)**](./tasks/003_high_in_bot_guide_system.md)
 - [ ] **Команды Статуса**: Встроенная диагностика здоровья системы (БД, Redis, API).
 - [ ] **Строгая Типизация**: Полный переход на Enums для состояний и переходов.
 - [ ] **Контекстные подсказки**: Обучающий режим в CLI при создании фич.
 
-## 🚀 Фаза 4: Масштабирование и Инфраструктура (v0.4.0) — В ПЛАНАХ
+## 🚀 Фаза 4: Масштабирование и Инфраструктура — В ПЛАНАХ
 - [ ] **Webhooks Service**: Нативная поддержка входящих вебхуков (FastAPI/Aiohttp). [**(Задача #009)**](../en_EN/tasks/009_high_webhook_server.md)
 - [ ] **Инфраструктура Docker**: Готовые шаблоны контейнеризации. [**(Задача #002)**](./tasks/002_med_docker_infrastructure.md)
 - [ ] **Smart Recovery**: Автоматическая логика повторов (Retries) для API и БД.
 - [ ] **SQLAlchemy Sender Storage**: Персистентное хранение координат UI без Redis. [**(Задача #007)**](../en_EN/tasks/007_med_sqlalchemy_sender_storage.md)
 - [ ] **Animation Engine**: Расширение библиотеки визуальных эффектов ожидания.
 
-## 📡 Фаза 5: Event-Driven Ecosystem (v0.5.0+) — БУДУЩЕЕ
+## 📡 Фаза 5: Event-Driven Ecosystem — БУДУЩЕЕ
 - [ ] **Multi-Broker Support**: Адаптеры для RabbitMQ и Kafka с унифицированным синтаксисом роутеров. [**(Задача #008)**](../en_EN/tasks/008_high_multi_broker_support.md)
 - [ ] **Remote FSM Management**: Управление состоянием пользователя через брокеры без участия aiogram.
 - [ ] **Smart Routing**: Автоматическое распределение сообщений между разными инстансами бота.

{codex_bot-0.3.1 → codex_bot-0.4.0}/mkdocs.yml

@@ -50,6 +50,7 @@ nav:
   - Guide (EN):
       - Overview: en_EN/README.md
       - Getting Started: en_EN/guide/getting_started.md
+      - Agent Skill: en_EN/guide/agent-skills.md
       - Architecture: en_EN/architecture/README.md
       - Roadmap: en_EN/roadmap.md
       - CLI Engine: en_EN/architecture/cli/README.md
@@ -74,6 +75,7 @@ nav:
   - Руководство (RU):
       - Обзор: ru_RU/README.md
       - Начало работы: ru_RU/guide/getting_started.md
+      - Навык агента: ru_RU/guide/agent-skills.md
       - Обзор архитектуры: ru_RU/architecture/README.md
       - Роадмап: ru_RU/roadmap.md
       - Движок CLI: ru_RU/architecture/cli/README.md

{codex_bot-0.3.1 → codex_bot-0.4.0}/pyproject.toml

@@ -23,9 +23,9 @@ classifiers = [
 ]
 dependencies = [
     "aiogram>=3.27.0,<4.0",
-    "aiohttp>=3.13.4",
+    "aiohttp>=3.14.3",
     "pydantic>=2.0,<3.0",
-    "pydantic-settings>=2.0",
+    "pydantic-settings>=2.14.2",
     "jinja2>=3.1.0",
     "python-dotenv>=1.0.0",
     "questionary>=2.0.0",
@@ -85,6 +85,22 @@ source = "vcs"
 [tool.hatch.build.targets.wheel]
 packages = ["src/codex_bot"]
 
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/docs",
+    "/tools",
+    "/pyproject.toml",
+    "/uv.lock",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/NOTICE",
+    "/mkdocs.yml",
+    "/.python-version",
+]
+
 [tool.ruff]
 target-version = "py312"
 line-length = 120

{codex_bot-0.3.1 → codex_bot-0.4.0}/src/codex_bot/__init__.py

@@ -15,7 +15,7 @@ except importlib.metadata.PackageNotFoundError:
     __version__ = "unknown"
 
 __author__ = "Codex Team"
-__license__ = "MIT"
+__license__ = "Apache-2.0"
 
 from codex_bot.base.base_orchestrator import BaseBotOrchestrator, PayloadT
 from codex_bot.director.director import Director

codex_bot-0.4.0/src/codex_bot/agent_skills/__init__.py

@@ -0,0 +1 @@
+# empty module

codex_bot-0.4.0/src/codex_bot/agent_skills/__main__.py

@@ -0,0 +1,4 @@
+from codex_bot.agent_skills.cli import main
+
+if __name__ == "__main__":
+    main()

codex_bot-0.4.0/src/codex_bot/agent_skills/cli.py

@@ -0,0 +1,39 @@
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from codex_bot.agent_skills.fs_transaction import FSError
+from codex_bot.agent_skills.orchestrator import OrchestratorError, check_status, perform_delete, perform_install
+
+
+def main(args: Sequence[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="python -m codex_bot.agent_skills")
+    parser.add_argument("action", choices=["install", "update", "delete", "status"])
+    parser.add_argument("--project", required=True, help="Path to project root")
+
+    parsed = parser.parse_args(args)
+
+    project_dir = Path(parsed.project).absolute()
+    if not project_dir.is_dir():
+        print(f"Error: Project directory does not exist or is not a directory: {project_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        if parsed.action == "install":
+            perform_install(project_dir, update=False)
+            print("Installed successfully.")
+        elif parsed.action == "update":
+            perform_install(project_dir, update=True)
+            print("Updated successfully.")
+        elif parsed.action == "delete":
+            perform_delete(project_dir)
+            print("Deleted successfully.")
+        elif parsed.action == "status":
+            is_valid, msg = check_status(project_dir)
+            print(msg)
+            if not is_valid:
+                sys.exit(1)
+    except (OrchestratorError, FSError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)

codex_bot-0.4.0/src/codex_bot/agent_skills/fs_transaction.py

@@ -0,0 +1,174 @@
+"""Same-volume staged writes with best-effort rollback after ordinary I/O errors."""
+
+import errno
+import os
+import shutil
+import stat
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+
+
+class FSError(Exception):
+    pass
+
+
+def validate_no_symlinks(path: Path) -> Path:
+    """Inspect every existing component with lstat, including dangling links."""
+    path = path.absolute()
+    parts = list(reversed((path, *path.parents)))
+    for index, part in enumerate(parts):
+        try:
+            info = part.lstat()
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            raise FSError(f"Cannot inspect {part}: {exc}") from exc
+        if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & getattr(
+            stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0
+        ):
+            raise FSError(f"Symlink or reparse point detected: {part}")
+        if index < len(parts) - 1 and not stat.S_ISDIR(info.st_mode):
+            raise FSError(f"Non-directory ancestor: {part}")
+    return path
+
+
+def check_regular_file(path: Path) -> None:
+    validate_no_symlinks(path)
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        raise FSError(f"Cannot inspect {path}: {exc}") from exc
+    if not stat.S_ISREG(info.st_mode):
+        raise FSError(f"Not a regular file: {path}")
+
+
+class FSTransaction:
+    def __init__(self, project_dir: Path):
+        self.project_dir = validate_no_symlinks(project_dir)
+        if not self.project_dir.is_dir():
+            raise FSError("Project is not a directory")
+        self.temp_dir = Path(tempfile.mkdtemp(prefix=".codex-bot-tx-", dir=self.project_dir))
+        self.backup_dir = self.temp_dir / "backup"
+        self.stage_dir = self.temp_dir / "stage"
+        self.backup_dir.mkdir()
+        self.stage_dir.mkdir()
+        self.to_write: list[tuple[Path, bytes]] = []
+        self.to_delete: list[Path] = []
+        self.to_prune: list[Path] = []
+        self._created_dirs: list[Path] = []
+        self._removed_dirs: list[Path] = []
+        self._snapshots: dict[Path, Path | None] = {}
+        self._retain = False
+
+    def _target(self, target: Path) -> Path:
+        target = validate_no_symlinks(target)
+        if not target.is_relative_to(self.project_dir) or target.is_relative_to(self.temp_dir):
+            raise FSError("Target outside project or inside transaction directory")
+        check_regular_file(target)
+        return target
+
+    def stage_write(self, target: Path, content: bytes) -> None:
+        self.to_write.append((self._target(target), content))
+
+    def stage_delete(self, target: Path) -> None:
+        target = self._target(target)
+        if target.exists():
+            self.to_delete.append(target)
+
+    def stage_prune_empty(self, directory: Path) -> None:
+        directory = validate_no_symlinks(directory)
+        if not directory.is_relative_to(self.project_dir) or directory == self.project_dir:
+            raise FSError("Unsafe directory cleanup target")
+        self.to_prune.append(directory)
+
+    def _make_parent(self, parent: Path) -> None:
+        missing: list[Path] = []
+        current = parent
+        while not current.exists():
+            missing.append(current)
+            current = current.parent
+        for directory in reversed(missing):
+            directory.mkdir()
+            self._created_dirs.append(directory)
+
+    def apply(self) -> None:
+        targets = list(dict.fromkeys([*self.to_delete, *(p for p, _ in self.to_write)]))
+        if len(targets) != len(self.to_delete) + len(self.to_write):
+            raise FSError("A target appears in multiple operations")
+        try:
+            # Snapshot every existing destination before the first mutation.
+            for index, target in enumerate(targets):
+                self._target(target)
+                backup = None
+                if target.exists():
+                    backup = self.backup_dir / f"backup_{index}"
+                    shutil.copy2(target, backup)
+                self._snapshots[target] = backup
+            for index, (_, data) in enumerate(self.to_write):
+                (self.stage_dir / f"write_stg_{index}").write_bytes(data)
+            for target in self.to_delete:
+                target.unlink()
+            for index, (target, _) in enumerate(self.to_write):
+                self._make_parent(target.parent)
+                os.replace(self.stage_dir / f"write_stg_{index}", target)
+            for directory in sorted(set(self.to_prune), key=lambda p: len(p.parts), reverse=True):
+                validate_no_symlinks(directory)
+                try:
+                    directory.rmdir()
+                    self._removed_dirs.append(directory)
+                except FileNotFoundError:
+                    pass
+                except OSError as exc:
+                    if exc.errno not in {errno.ENOTEMPTY, errno.EEXIST} and getattr(exc, "winerror", None) != 145:
+                        raise
+        except Exception as exc:
+            try:
+                self.rollback()
+            except FSError as recovery:
+                self._retain = True
+                raise FSError(
+                    f"Transaction failed: {exc}. Recovery failed: {recovery}. Backups retained at {self.temp_dir}"
+                ) from exc
+            raise FSError(f"Transaction failed and was rolled back: {exc}") from exc
+
+    def rollback(self) -> None:
+        errors: list[str] = []
+        for directory in reversed(self._removed_dirs):
+            try:
+                directory.mkdir(exist_ok=True)
+            except Exception as exc:
+                errors.append(f"{directory}: {exc}")
+        for target, backup in reversed(list(self._snapshots.items())):
+            try:
+                if backup is None:
+                    if target.exists():
+                        target.unlink()
+                else:
+                    self._make_parent(target.parent)
+                    # Copy leaves the sole recovery copy intact if restoration fails.
+                    shutil.copy2(backup, target)
+            except Exception as exc:
+                errors.append(f"{target}: {exc}")
+        for directory in reversed(self._created_dirs):
+            with suppress(OSError):
+                directory.rmdir()
+        if errors:
+            raise FSError("; ".join(errors))
+
+    def cleanup(self) -> None:
+        if self._retain:
+            return
+        root = self.temp_dir.absolute()
+        if root.parent != self.project_dir or not root.name.startswith(".codex-bot-tx-"):
+            raise FSError("Unsafe transaction cleanup path")
+        validate_no_symlinks(root)
+        shutil.rmtree(root)
+
+    def __enter__(self) -> "FSTransaction":
+        return self
+
+    def __exit__(self, _type: object, _value: object, _traceback: object) -> None:
+        self.cleanup()