From 66819c7c2dde25fa6f75c9f60c0772a79db868a7 Mon Sep 17 00:00:00 2001 From: huangruiteng Date: Fri, 2 Oct 2026 19:47:03 +0800 Subject: [PATCH 1/5] refactor(chat): localize Codex work-step presentation Signed-off-by: huangruiteng --- loopx/chat_agent.py | 2 +- loopx/presentation/README.md | 5 +++++ loopx/{chat_activity.py => presentation/codex_activity.py} | 0 tests/test_chat_activity.py | 2 +- 4 files changed, 7 insertions(+), 2 deletions(-) rename loopx/{chat_activity.py => presentation/codex_activity.py} (100%) diff --git a/loopx/chat_agent.py b/loopx/chat_agent.py index edb369f3e9..41b7fa3ee6 100644 --- a/loopx/chat_agent.py +++ b/loopx/chat_agent.py @@ -13,7 +13,7 @@ from pathlib import Path from typing import Any, Callable, Iterator -from .chat_activity import CodexActivitySteps +from .presentation.codex_activity import CodexActivitySteps from .chat import ( CHAT_AGENT_RESPONSE_SCHEMA_VERSION, CHAT_REVIEW_CLOSE_TAG, diff --git a/loopx/presentation/README.md b/loopx/presentation/README.md index 391c4849a6..01a49912d4 100644 --- a/loopx/presentation/README.md +++ b/loopx/presentation/README.md @@ -19,6 +19,11 @@ Python code that starts as a user-visible capability may keep a thin facade under `loopx.capabilities.*`, but the reusable display implementation should live here. +`codex_activity.py` projects Codex host items into redacted, owner-visible Turn +steps. It owns display normalization only; step completion does not establish +Goal acceptance or execution authority. The Chat adapter consumes this projection +without exposing a separate top-level module. + ## Explore Result Layer Only the display side of software-exploration topology belongs here: diff --git a/loopx/chat_activity.py b/loopx/presentation/codex_activity.py similarity index 100% rename from loopx/chat_activity.py rename to loopx/presentation/codex_activity.py diff --git a/tests/test_chat_activity.py b/tests/test_chat_activity.py index 9b0b142a6b..2713dfc4c3 100644 --- a/tests/test_chat_activity.py +++ b/tests/test_chat_activity.py @@ -7,7 +7,7 @@ import pytest from pathlib import Path -from loopx.chat_activity import ( +from loopx.presentation.codex_activity import ( COMMAND_VERBS, REASONING_UPDATE_INTERVAL_SEC, STEP_KINDS, From c77a3eb7b9a2fc6508f61b89476215c2bd0fdcc6 Mon Sep 17 00:00:00 2001 From: huangruiteng Date: Fri, 2 Oct 2026 19:58:58 +0800 Subject: [PATCH 2/5] refactor(turn): reuse exact settlement readback in recovery adapters Signed-off-by: huangruiteng --- loopx/cli_commands/turn.py | 66 +++++++++++--------------------------- 1 file changed, 18 insertions(+), 48 deletions(-) diff --git a/loopx/cli_commands/turn.py b/loopx/cli_commands/turn.py index 9a0d8192c4..d1dc9717ca 100644 --- a/loopx/cli_commands/turn.py +++ b/loopx/cli_commands/turn.py @@ -21,6 +21,7 @@ ) from ..control_plane.quota.heartbeat_receipt import ensure_turn_heartbeat_settlement_receipt from ..control_plane.quota.settlement import ( + QuotaSettlementReadback, SettlementIdentity, SettlementStepKind, read_heartbeat_settlement, @@ -405,6 +406,19 @@ def require_effect_ref( f"{step_kind.value} effect ref does not match Turn identity" ) + def read_exact_settlement() -> QuotaSettlementReadback: + readback = read_heartbeat_settlement( + runtime_root, + goal_id=settlement_identity.goal_id, + agent_id=settlement_identity.agent_id, + todo_id=settlement_identity.todo_id, + turn_instance_id=settlement_identity.turn_instance_id, + replan_obligation_id=settlement_identity.replan_obligation_id, + ) + if readback is None: + raise RuntimeError(EXACT_SETTLEMENT_READBACK_NOT_FOUND) + return readback + def append_settlement_event( effect_payload: Mapping[str, object], *, @@ -710,18 +724,7 @@ def spend(*, effect_ref: str) -> dict[str, object]: or spent.get("idempotent_replay") or spent.get("receipt_repair_required") ): - readback = read_heartbeat_settlement( - runtime_root, - goal_id=settlement_identity.goal_id, - agent_id=settlement_identity.agent_id, - todo_id=settlement_identity.todo_id, - turn_instance_id=settlement_identity.turn_instance_id, - replan_obligation_id=settlement_identity.replan_obligation_id, - ) - if readback is None: - raise RuntimeError( - EXACT_SETTLEMENT_READBACK_NOT_FOUND - ) + readback = read_exact_settlement() event = readback.spend_event if event is None: append_settlement_event( @@ -804,18 +807,7 @@ def writeback_resolver(effect_ref: str) -> dict[str, object]: effect_ref, SettlementStepKind.DURABLE_WRITEBACK, ) - readback = read_heartbeat_settlement( - runtime_root, - goal_id=settlement_identity.goal_id, - agent_id=settlement_identity.agent_id, - todo_id=settlement_identity.todo_id, - turn_instance_id=settlement_identity.turn_instance_id, - replan_obligation_id=settlement_identity.replan_obligation_id, - ) - if readback is None: - raise RuntimeError( - EXACT_SETTLEMENT_READBACK_NOT_FOUND - ) + readback = read_exact_settlement() run = readback.writeback_run event = readback.writeback_event if run is None and event is None: @@ -848,18 +840,7 @@ def writeback_resolver(effect_ref: str) -> dict[str, object]: def spend_resolver(effect_ref: str) -> dict[str, object]: try: require_effect_ref(effect_ref, SettlementStepKind.QUOTA_SPEND) - readback = read_heartbeat_settlement( - runtime_root, - goal_id=settlement_identity.goal_id, - agent_id=settlement_identity.agent_id, - todo_id=settlement_identity.todo_id, - turn_instance_id=settlement_identity.turn_instance_id, - replan_obligation_id=settlement_identity.replan_obligation_id, - ) - if readback is None: - raise RuntimeError( - EXACT_SETTLEMENT_READBACK_NOT_FOUND - ) + readback = read_exact_settlement() run = readback.spend_run event = readback.spend_event if run is not None and run.get("effect_ref") != effect_ref: @@ -896,18 +877,7 @@ def terminal_closeout_resolver(effect_ref: str) -> dict[str, object]: effect_ref, SettlementStepKind.TERMINAL_CLOSEOUT, ) - readback = read_heartbeat_settlement( - runtime_root, - goal_id=settlement_identity.goal_id, - agent_id=settlement_identity.agent_id, - todo_id=settlement_identity.todo_id, - turn_instance_id=settlement_identity.turn_instance_id, - replan_obligation_id=settlement_identity.replan_obligation_id, - ) - if readback is None: - raise RuntimeError( - EXACT_SETTLEMENT_READBACK_NOT_FOUND - ) + readback = read_exact_settlement() event = readback.completion_event completion = terminal_completion_readback() if event is None and completion is None: From 8859e092cd87cf85e249c748f0f79674bf04f64a Mon Sep 17 00:00:00 2001 From: huangruiteng Date: Fri, 2 Oct 2026 19:58:58 +0800 Subject: [PATCH 3/5] test(release): reconcile state routes and projection fixtures Signed-off-by: huangruiteng --- .../shared-runtime-material-projection-smoke.py | 6 +++--- examples/core-control-plane-diagrams-smoke.py | 2 +- examples/fresh-clone-quickstart-smoke.py | 2 +- examples/loopx-chat-actions-smoke.py | 3 ++- examples/multi-goal-same-repo-smoke.py | 4 +++- examples/project/bootstrap-force-preserve-todos-smoke.py | 3 ++- 6 files changed, 12 insertions(+), 8 deletions(-) diff --git a/examples/control_plane/shared-runtime-material-projection-smoke.py b/examples/control_plane/shared-runtime-material-projection-smoke.py index 2acbb2fa11..a315869694 100644 --- a/examples/control_plane/shared-runtime-material-projection-smoke.py +++ b/examples/control_plane/shared-runtime-material-projection-smoke.py @@ -344,8 +344,8 @@ def exercise_route_edges(root: Path) -> None: write_target(target_a, source_registry=ambiguous_registry, goal=ambiguous_goal) write_target(target_b, source_registry=ambiguous_registry, goal=ambiguous_goal) os.environ["LOOPX_RUNTIME_ROOT"] = str(target_a) - original_default = route_module.select_default_runtime_root - route_module.select_default_runtime_root = lambda: target_b + original_default = route_module.paths.DEFAULT_RUNTIME_ROOT + route_module.paths.DEFAULT_RUNTIME_ROOT = target_b try: ambiguous = record_operator_gate( ambiguous_registry, @@ -353,7 +353,7 @@ def exercise_route_edges(root: Path) -> None: sync_global=True, ) finally: - route_module.select_default_runtime_root = original_default + route_module.paths.DEFAULT_RUNTIME_ROOT = original_default if original_runtime is None: os.environ.pop("LOOPX_RUNTIME_ROOT", None) else: diff --git a/examples/core-control-plane-diagrams-smoke.py b/examples/core-control-plane-diagrams-smoke.py index 6ce4080db2..c4c170874f 100644 --- a/examples/core-control-plane-diagrams-smoke.py +++ b/examples/core-control-plane-diagrams-smoke.py @@ -47,7 +47,7 @@ def main() -> None: assert "Core Pattern Map" in docs["interaction-catalog.md"] assert "State Definitions" in docs["state-definitions.md"] assert "Canonical State Bodies" in docs["state-definitions.md"] - assert "Derived Runtime States" in docs["state-definitions.md"] + assert "Runtime Decisions, Phases, And Read Conditions" in docs["state-definitions.md"] assert "State Machines" in docs["state-machine.md"] for section in ( "Todo Lifecycle Machine", diff --git a/examples/fresh-clone-quickstart-smoke.py b/examples/fresh-clone-quickstart-smoke.py index 6ab746185f..9b391cb591 100644 --- a/examples/fresh-clone-quickstart-smoke.py +++ b/examples/fresh-clone-quickstart-smoke.py @@ -148,7 +148,7 @@ def main() -> int: assert "loopx-project.github.io/loopx/install.sh" in bootstrap["archive_fallback_install_command"], bootstrap assert "loopx doctor" in bootstrap["install_repair_command"], bootstrap assert (project / ".loopx" / "registry.json").is_file(), bootstrap - assert (project / ".codex" / "goals" / GOAL_ID / "ACTIVE_GOAL_STATE.md").is_file(), bootstrap + assert (project / ".loopx" / "goals" / GOAL_ID / "ACTIVE_GOAL_STATE.md").is_file(), bootstrap registry = project / ".loopx" / "registry.json" status = run_loopx("--registry", str(registry), "status", cwd=project, env=cli_env) diff --git a/examples/loopx-chat-actions-smoke.py b/examples/loopx-chat-actions-smoke.py index 45a45fdeae..14d35d35ae 100644 --- a/examples/loopx-chat-actions-smoke.py +++ b/examples/loopx-chat-actions-smoke.py @@ -393,7 +393,8 @@ def assert_http_action_api(root: Path) -> None: ) assert history_after_goal["goals"][0]["display_name"] == "New Goal", history_after_goal assert new_goal["coordination"]["registered_agents"] == ["codex"], new_goal - new_state = state_path.parent.parent / "new-goal" / "ACTIVE_GOAL_STATE.md" + assert new_goal["state_file"] == ".loopx/goals/new-goal/ACTIVE_GOAL_STATE.md", new_goal + new_state = registry_path.parent.parent / new_goal["state_file"] assert new_state.exists(), new_state new_state_text = new_state.read_text(encoding="utf-8") assert new_state_text.count("Verify the new Goal projection") == 1 diff --git a/examples/multi-goal-same-repo-smoke.py b/examples/multi-goal-same-repo-smoke.py index 03774f2d84..1a53af9281 100644 --- a/examples/multi-goal-same-repo-smoke.py +++ b/examples/multi-goal-same-repo-smoke.py @@ -153,7 +153,9 @@ def main() -> int: assert "project_local_goal_state_not_detected" in external_map["residual_risks"], external_map registry = json.loads(registry_path.read_text(encoding="utf-8")) - registry["goals"][2]["state_file"] = f".codex/goals/{MAIN_GOAL}/ACTIVE_GOAL_STATE.md" + registry["goals"][2]["state_file"] = next( + goal["state_file"] for goal in registry["goals"] if goal["id"] == MAIN_GOAL + ) registry_path.write_text(json.dumps(registry, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") duplicate_payload = run_cli(root, registry_path, "registry", check=False) assert duplicate_payload["ok"] is False, duplicate_payload diff --git a/examples/project/bootstrap-force-preserve-todos-smoke.py b/examples/project/bootstrap-force-preserve-todos-smoke.py index d1a464fe86..69bd8dceec 100644 --- a/examples/project/bootstrap-force-preserve-todos-smoke.py +++ b/examples/project/bootstrap-force-preserve-todos-smoke.py @@ -35,7 +35,6 @@ def main() -> int: with tempfile.TemporaryDirectory(prefix="loopx-bootstrap-preserve-") as tmp: project = Path(tmp) / "project" project.mkdir() - state_file = project / ".codex/goals/bootstrap-preserve-fixture/ACTIVE_GOAL_STATE.md" initial = run_cli( "bootstrap", @@ -49,6 +48,8 @@ def main() -> int: ) assert initial["ok"] is True, initial assert initial["state_action"] == "created", initial + state_file = Path(initial["state_file"]) + assert state_file == (project / ".loopx/goals/bootstrap-preserve-fixture/ACTIVE_GOAL_STATE.md").resolve() todo_state = "# Active Goal State\n\n## Agent Todo\n\n- [ ] Preserve this during reconnect.\n" state_file.write_text(todo_state, encoding="utf-8") From 12fb0902933eca60343ff18a96b3fe1eb5adb767 Mon Sep 17 00:00:00 2001 From: huangruiteng Date: Fri, 2 Oct 2026 20:19:34 +0800 Subject: [PATCH 4/5] docs(cli): include local performance diagnosis in command reference Signed-off-by: huangruiteng --- loopx/help_surface.py | 4 ++++ man/loopx.1 | 3 +++ 2 files changed, 7 insertions(+) diff --git a/loopx/help_surface.py b/loopx/help_surface.py index 67e10046ff..1c8dca0293 100644 --- a/loopx/help_surface.py +++ b/loopx/help_surface.py @@ -90,6 +90,10 @@ def register_command_reference(subparsers: argparse._SubParsersAction) -> None: "command": "loopx diagnose --goal-id ", "purpose": "Build a compact evidence packet when behavior is surprising.", }, + { + "command": "loopx performance-diagnosis --help", + "purpose": "Plan an explicit local capture or inspect an existing profile without executing or uploading it.", + }, { "command": "loopx review-packet --goal-id ", "purpose": "Render a handoff or review packet with any required evidence-log reads.", diff --git a/man/loopx.1 b/man/loopx.1 index f512ee7866..fe84cbc48a 100644 --- a/man/loopx.1 +++ b/man/loopx.1 @@ -72,6 +72,9 @@ Open Goal Studio, ask the read\-only Agent for a bounded Todo, and approve its p \fBloopx diagnose \-\-goal\-id \fR Build a compact evidence packet when behavior is surprising. .TP +\fBloopx performance\-diagnosis \-\-help\fR +Plan an explicit local capture or inspect an existing profile without executing or uploading it. +.TP \fBloopx review\-packet \-\-goal\-id \fR Render a handoff or review packet with any required evidence\-log reads. .TP From 85fe93be2b1449f553c0affc38624d0036e39ee2 Mon Sep 17 00:00:00 2001 From: huangruiteng Date: Fri, 2 Oct 2026 20:21:44 +0800 Subject: [PATCH 5/5] docs(cli): place optional profiling in maintainer command group Signed-off-by: huangruiteng --- loopx/help_surface.py | 8 ++++---- man/loopx.1 | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/loopx/help_surface.py b/loopx/help_surface.py index 1c8dca0293..12e143a0f0 100644 --- a/loopx/help_surface.py +++ b/loopx/help_surface.py @@ -90,10 +90,6 @@ def register_command_reference(subparsers: argparse._SubParsersAction) -> None: "command": "loopx diagnose --goal-id ", "purpose": "Build a compact evidence packet when behavior is surprising.", }, - { - "command": "loopx performance-diagnosis --help", - "purpose": "Plan an explicit local capture or inspect an existing profile without executing or uploading it.", - }, { "command": "loopx review-packet --goal-id ", "purpose": "Render a handoff or review packet with any required evidence-log reads.", @@ -334,6 +330,10 @@ def register_command_reference(subparsers: argparse._SubParsersAction) -> None: }, {"command": "loopx multi-agent", "purpose": "Launch visible role-scoped Codex TUI agents."}, {"command": "loopx canary", "purpose": "Plan or run catalog-informed smoke profiles."}, + { + "command": "loopx performance-diagnosis --help", + "purpose": "Plan an explicit local capture or inspect an existing profile without executing or uploading it.", + }, { "command": "loopx promotion-readiness", "purpose": "Record release-scoped canary readiness evidence in the shared runtime ledger.", diff --git a/man/loopx.1 b/man/loopx.1 index fe84cbc48a..daab1ab594 100644 --- a/man/loopx.1 +++ b/man/loopx.1 @@ -72,9 +72,6 @@ Open Goal Studio, ask the read\-only Agent for a bounded Todo, and approve its p \fBloopx diagnose \-\-goal\-id \fR Build a compact evidence packet when behavior is surprising. .TP -\fBloopx performance\-diagnosis \-\-help\fR -Plan an explicit local capture or inspect an existing profile without executing or uploading it. -.TP \fBloopx review\-packet \-\-goal\-id \fR Render a handoff or review packet with any required evidence\-log reads. .TP @@ -276,6 +273,9 @@ Launch visible role\-scoped Codex TUI agents. \fBloopx canary\fR Plan or run catalog\-informed smoke profiles. .TP +\fBloopx performance\-diagnosis \-\-help\fR +Plan an explicit local capture or inspect an existing profile without executing or uploading it. +.TP \fBloopx promotion\-readiness\fR Record release\-scoped canary readiness evidence in the shared runtime ledger. .TP