diff --git a/demo/auto_research/demo_e2e.py b/demo/auto_research/demo_e2e.py
index 7fdbaebb2c..b4b181ba13 100644
--- a/demo/auto_research/demo_e2e.py
+++ b/demo/auto_research/demo_e2e.py
@@ -124,7 +124,7 @@ def _seed_visible_demo_control_plane(
     control_project = demo_root / "visible-control-plane"
     control_registry = demo_root / "visible-control-plane.registry.json"
     control_runtime = demo_root / "visible-control-plane.runtime"
-    bootstrap_project(
+    bootstrap = bootstrap_project(
         project=control_project,
         registry_path=control_registry,
         runtime_root=control_runtime,
@@ -146,7 +146,7 @@ def _seed_visible_demo_control_plane(
         dry_run=False,
         sync_global=False,
     )
-    state_file = control_project / ".codex" / "goals" / goal_id / "ACTIVE_GOAL_STATE.md"
+    state_file = Path(str(bootstrap["state_file"]))
     if state_file.exists():
         updated_state, state_changed = replace_next_action_section(
             state_file.read_text(encoding="utf-8"),
diff --git a/docs/book/chapters/00-reading-guide.md b/docs/book/chapters/00-reading-guide.md
index a79ed105c1..e41f1aa8c2 100644
--- a/docs/book/chapters/00-reading-guide.md
+++ b/docs/book/chapters/00-reading-guide.md
@@ -108,7 +108,7 @@ lifecycle 选择，不是所有贡献的默认终点。
 
 ## 版本基线
 
-当前内容面向 LoopX release `v1.2.3`；本地命令示例已按 `loopx 1.2.3` 的
+当前内容面向 LoopX release `v1.2.4`；本地命令示例已按 `loopx 1.2.4` 的
 公开 CLI 与协议表面复核。该版本要求 Python 3.11+ 与 Node.js 22.22.3+。LoopX 会自动管理
 空闲后退出的 TypeScript Effect runtime，用户不需要手工维护 daemon。
 
diff --git a/docs/book/en/chapters/00-reading-guide.md b/docs/book/en/chapters/00-reading-guide.md
index 5cb62c845f..45434401a7 100644
--- a/docs/book/en/chapters/00-reading-guide.md
+++ b/docs/book/en/chapters/00-reading-guide.md
@@ -120,8 +120,8 @@ Do not bypass a newer permission or lifecycle check just to make an older exampl
 
 ## Version baseline
 
-This book targets LoopX release `v1.2.3`. Local command examples were checked against
-the public `loopx 1.2.3` CLI and protocol surface. It requires Python 3.11+ and Node.js 22.22.3+.
+This book targets LoopX release `v1.2.4`. Local command examples were checked against
+the public `loopx 1.2.4` CLI and protocol surface. It requires Python 3.11+ and Node.js 22.22.3+.
 LoopX starts and reuses its managed, idle-exiting TypeScript Effect runtime automatically; users do not
 operate that runtime as a manual daemon.
 
diff --git a/docs/book/en/index.md b/docs/book/en/index.md
index 2a61908580..c39bfd0cda 100644
--- a/docs/book/en/index.md
+++ b/docs/book/en/index.md
@@ -79,7 +79,7 @@ versioned or optional functionality, not the default shape of every contribution
 - Source format: Markdown
 - Site generator: MkDocs Material
 - Hosting: GitHub Pages
-- LoopX release anchor: `v1.2.3`
+- LoopX release anchor: `v1.2.4`
 - Runtime prerequisites: Python 3.11+ and Node.js 22.22.3+
 
 The official public protocols remain authoritative for protocol facts. Commands that change across
diff --git a/docs/book/index.md b/docs/book/index.md
index e20f3e22f2..8eaa803c43 100644
--- a/docs/book/index.md
+++ b/docs/book/index.md
@@ -70,7 +70,7 @@ Extension 只是可独立版本化和交付的一种路径。
 - 正文格式：Markdown；
 - 站点生成器：MkDocs Material；
 - 在线发布：GitHub Pages；
-- LoopX 发布锚点：`v1.2.3`；
+- LoopX 发布锚点：`v1.2.4`；
 - 运行时前提：Python 3.11+ 与 Node.js 22.22.3+。
 
 协议解释以 LoopX 官方公开合同为事实源。易变化的命令仍以对应发布物、官方文档和当前
diff --git a/examples/auto-research-worker-loop-smoke.py b/examples/auto-research-worker-loop-smoke.py
index 4effdc7bca..813ee67cba 100644
--- a/examples/auto-research-worker-loop-smoke.py
+++ b/examples/auto-research-worker-loop-smoke.py
@@ -75,7 +75,7 @@ def main() -> int:
         state_file = (
             temp
             / "visible-control-plane"
-            / ".codex"
+            / ".loopx"
             / "goals"
             / GOAL_ID
             / "ACTIVE_GOAL_STATE.md"
diff --git a/loopx/__init__.py b/loopx/__init__.py
index d0e107bed8..6d4ff29458 100644
--- a/loopx/__init__.py
+++ b/loopx/__init__.py
@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "1.2.3"
+__version__ = "1.2.4"
diff --git a/loopx/control_plane/testing/cli_output_budget.py b/loopx/control_plane/testing/cli_output_budget.py
index 473d7bc5c2..bef3e8a80d 100644
--- a/loopx/control_plane/testing/cli_output_budget.py
+++ b/loopx/control_plane/testing/cli_output_budget.py
@@ -597,6 +597,12 @@ class CliOutputCommandClassification:
 # here. Tests fail closed when help adds a command without a budget or a named
 # cold-path exception.
 CLI_OUTPUT_COMMAND_CLASSIFICATIONS: tuple[CliOutputCommandClassification, ...] = (
+    CliOutputCommandClassification(
+        command_id="migrate-local-state",
+        qualification="explicit_cold_path_exception",
+        surface_id=None,
+        rationale="explicit offline local-state migration preview, execution, and receipt-bound rollback",
+    ),
     CliOutputCommandClassification(
         command_id="doctor",
         qualification="explicit_cold_path_exception",
diff --git a/loopx/help_surface.py b/loopx/help_surface.py
index 9306bd21c2..67e10046ff 100644
--- a/loopx/help_surface.py
+++ b/loopx/help_surface.py
@@ -126,6 +126,10 @@ def register_command_reference(subparsers: argparse._SubParsersAction) -> None:
                 "command": "loopx machine-config --help",
                 "purpose": "Inspect typed machine policy, preview changes, and apply an exact plan revision.",
             },
+            {
+                "command": "loopx migrate-local-state --help",
+                "purpose": "Preview an explicit local-state path migration or receipt-bound rollback; stop writers before execution.",
+            },
             {"command": "loopx todo --help", "purpose": "Show todo lifecycle commands."},
             {
                 "command": "loopx task-lease --help",
diff --git a/man/loopx.1 b/man/loopx.1
index c345a28ba9..f512ee7866 100644
--- a/man/loopx.1
+++ b/man/loopx.1
@@ -1,4 +1,4 @@
-.TH LOOPX 1 "" "LoopX 1.2.3" "User Commands"
+.TH LOOPX 1 "" "LoopX 1.2.4" "User Commands"
 .SH NAME
 loopx \- control-plane helper for long-running agent work
 .SH SYNOPSIS
@@ -99,6 +99,9 @@ Prepare, inspect, or adopt one explicit cross\-agent Todo handoff.
 \fBloopx machine\-config \-\-help\fR
 Inspect typed machine policy, preview changes, and apply an exact plan revision.
 .TP
+\fBloopx migrate\-local\-state \-\-help\fR
+Preview an explicit local\-state path migration or receipt\-bound rollback; stop writers before execution.
+.TP
 \fBloopx todo \-\-help\fR
 Show todo lifecycle commands.
 .TP
diff --git a/pyproject.toml b/pyproject.toml
index 01be99e01d..aeae149dff 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopx"
-version = "1.2.3"
+version = "1.2.4"
 description = "A Loop Engineering control plane for long-running agent goals (requires Node.js 22.22.3+)."
 readme = "README.md"
 requires-python = ">=3.11"