From eb7869be74bd11aa1eabdf363d39ea6ad5c3931f Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 05:18:21 +0800 Subject: [PATCH 01/10] fix(qualification): distinguish ordinary completion from terminal closeout Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../model-behavior-qualification-v0.md | 7 ++ .../terminal_settlement_tool_behavior.py | 41 +++++---- .../test_terminal_settlement_tool_behavior.py | 84 +++++++++++++++++-- 3 files changed, 111 insertions(+), 21 deletions(-) diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index a5aec6d1a6..a7fcbd9987 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -301,6 +301,13 @@ target. The terminal-settlement scenario requires the model to validate a real fixture artifact, then follow the quota-projected `durable_writeback -> quota_spend -> terminal_closeout` sequence under one stable effect identity; a premature no-follow-up or spend-before-writeback fails. +The plan's conditional ordinary Todo completion may run during validation, +before writeback and spend. The actor requires the original Goal/Agent/Todo/Turn +arguments and its committed validation receipt; ordinary completion does not +qualify terminal closeout. `--no-follow-up` still requires both matching +writeback and spend receipts. This follows the shared +[quota-bound completion contract](../canonical-terminal-review.md#quota-bound-cli-completion) +without changing the portfolio, repeats, contrasts or settlement order. For selected-Todo and terminal qualification, a standalone `cat` may read up to eight workspace-confined files, optionally diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index 0d588b9232..8bf78cb703 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -893,10 +893,14 @@ def qualify( "once with `cat`; the host validates that tool result. Do not " "run python, jq, test, echo, another validation command, or " "re-read the workspace afterward. Use one command per tool " - "call. The tool call immediately after the proof read must " - "fill and execute quota-projected next_cli_actions[0] from " - "the proof's typed fields, then follow the ordered settlement " - "plan." + "call. After the proof read, follow the quota-projected " + "settlement plan, including the validation step's " + "command_condition. Ordinary Todo completion validates the " + "deliverable before writeback/spend; it is distinct from " + "the final --no-follow-up closeout after spend. Preserve " + "the projected Goal, Agent, Todo and Turn arguments. Fill " + "the writeback placeholders from the proof's typed fields " + "and choose each later command from the latest tool result." ), }, {"role": "user", "content": fixture.task_body}, @@ -975,20 +979,27 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: kind = "quota_spend" output = json.dumps(payload, ensure_ascii=False, sort_keys=True) elif command_kind == "todo" and command_action == "complete": - if not state.spend_committed: - raise ValueError("terminal_closeout_before_spend") - if ( - not tokens - or not _matches_identity(tokens, state) - or "--no-follow-up" not in tokens - ): - raise ValueError("terminal_closeout_contract_mismatch") + terminal = "--no-follow-up" in tokens + if terminal: + if not state.spend_committed: + raise ValueError("terminal_closeout_before_spend") + if not _matches_identity(tokens, state): + raise ValueError("terminal_closeout_contract_mismatch") + else: + if not state.proof_read: + raise ValueError("completion_before_validation") + if state.writeback_committed: + raise ValueError("completion_after_writeback") + if not _matches_identity(tokens, state): + raise ValueError("completion_identity_mismatch") payload = _execute_cli(tool_call.command, state) receipt_steps = _settlement_receipt_steps(payload) - if receipt_steps != _EXPECTED_RECEIPT_STEPS: - raise ValueError("terminal_closeout_receipt_mismatch") + expected_steps = _EXPECTED_RECEIPT_STEPS if terminal else _EXPECTED_RECEIPT_STEPS[:1] + if receipt_steps != expected_steps: + raise ValueError("terminal_closeout_receipt_mismatch" if terminal + else "completion_receipt_mismatch") state.receipt_steps = receipt_steps - kind = "terminal_closeout" + kind = "terminal_closeout" if terminal else "todo_completion" output = json.dumps(payload, ensure_ascii=False, sort_keys=True) else: output = _execute_workspace_read(tool_call.command, state=state) diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index 0ff61d1423..96296e8889 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -2,6 +2,7 @@ import json from collections.abc import Mapping +from functools import partial from pathlib import Path from typing import Any @@ -54,7 +55,9 @@ def _spend_action(request: Mapping[str, Any]) -> ScriptedExecToolAction: ) -def _terminal_action(request: Mapping[str, Any]) -> ScriptedExecToolAction: +def _completion_action( + request: Mapping[str, Any], *, kind: str = "terminal_closeout", +) -> ScriptedExecToolAction: packet = _latest_quota_packet(request) steps = packet["interaction_contract"]["cli_channel"]["settlement_plan"][ "ordered_steps" @@ -62,7 +65,7 @@ def _terminal_action(request: Mapping[str, Any]) -> ScriptedExecToolAction: command = next( item["command_template"] for item in steps - if item["kind"] == "terminal_closeout" + if item["kind"] == kind ) return ScriptedExecToolAction( command=command.replace('"${LOOPX_TURN:?}"', "turn-test-001").replace( @@ -113,8 +116,9 @@ def _reentry_quota_action(request: Mapping[str, Any]) -> ScriptedExecToolAction: @pytest.mark.parametrize("cat_options", ["", "-- "]) @pytest.mark.parametrize("batch_read", [False, True]) +@pytest.mark.parametrize("ordinary_completion", [False, True]) def test_real_tool_loop_settles_final_todo_after_spend( - tmp_path: Path, cat_options: str, batch_read: bool, + tmp_path: Path, cat_options: str, batch_read: bool, ordinary_completion: bool, ) -> None: fixture = _build_fixture(tmp_path / "oracle") transport = ScriptedDoubaoExecTransport( @@ -130,9 +134,10 @@ def test_real_tool_loop_settles_final_todo_after_spend( "fixture/settlement-proof.json" if batch_read else f"cat {cat_options}fixture/settlement-proof.json" )), + *([partial(_completion_action, kind="validation")] if ordinary_completion else []), _writeback_action, _spend_action, - _terminal_action, + _completion_action, ] ) @@ -149,6 +154,7 @@ def test_real_tool_loop_settles_final_todo_after_spend( assert receipt["observed_tool_sequence"] == [ "quota_should_run", "delivery_validation", + *(["todo_completion"] if ordinary_completion else []), "durable_writeback", "quota_spend", "terminal_closeout", @@ -178,7 +184,8 @@ def test_real_tool_loop_settles_final_todo_after_spend( system_prompt = first["messages"][0]["content"] assert QUOTA_FIRST_TOOL_INSTRUCTION in system_prompt assert "the host validates that tool result" in system_prompt - assert "immediately after the proof read" in system_prompt + assert "validation step's command_condition" in system_prompt + assert "distinct from the final --no-follow-up closeout after spend" in system_prompt assert first["messages"][1] == {"role": "user", "content": fixture.task_body} assert TERMINAL_SETTLEMENT_FIXTURE_TODO_ID not in fixture.task_body quota_result = _latest_quota_packet(transport.requests[2]) @@ -187,6 +194,71 @@ def test_real_tool_loop_settles_final_todo_after_spend( ) +@pytest.mark.parametrize( + ("read_proof", "foreign_actor", "expected_failure"), + [(False, False, "completion_before_validation"), + (True, True, "completion_identity_mismatch")], +) +def test_ordinary_completion_cannot_bypass_validation_or_identity( + tmp_path: Path, read_proof: bool, foreign_actor: bool, expected_failure: str, +) -> None: + fixture = _build_fixture(tmp_path / "oracle") + + def completion(request: Mapping[str, Any]) -> ScriptedExecToolAction: + command = _completion_action(request, kind="validation").command + if foreign_actor: + command = command.replace("--agent-id codex-terminal-settlement", "--agent-id foreign-agent") + return ScriptedExecToolAction(command=command) + + transport = ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command.replace( + '"${LOOPX_TURN:?}"', "turn-test-001", + )), + *([ScriptedExecToolAction(command="cat fixture/settlement-proof.json")] if read_proof else []), + completion, + ]) + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=transport, + ).qualify(qualification_id="ordinary-completion-refusal", fixture_root=tmp_path / "actor") + assert receipt["qualification_passed"] is False + assert receipt["failure_code"] == expected_failure + assert receipt["settlement_receipt_steps"] == [] + assert receipt["terminal_order_observed"] is False + + +def test_ordinary_completion_requires_its_actual_validation_receipt( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + from loopx.control_plane.testing import terminal_settlement_tool_behavior as terminal + + fixture = _build_fixture(tmp_path / "oracle") + execute = terminal._execute_cli + + def missing_validation_receipt(command, state): + payload = execute(command, state) + if "todo complete" in command: + assert payload["status"] == "done" + assert payload["settlement_result"]["receipts"][0]["step_kind"] == "validation" + payload["settlement_result"]["receipts"] = [] + return payload + + monkeypatch.setattr(terminal, "_execute_cli", missing_validation_receipt) + transport = ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command.replace( + '"${LOOPX_TURN:?}"', "turn-test-001", + )), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), + partial(_completion_action, kind="validation"), + ]) + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=transport, + ).qualify(qualification_id="ordinary-completion-missing-receipt", fixture_root=tmp_path / "actor") + assert receipt["qualification_passed"] is False + assert receipt["failure_code"] == "completion_receipt_mismatch" + assert receipt["settlement_receipt_steps"] == [] + assert receipt["terminal_order_observed"] is False + + @pytest.mark.parametrize("batch_read", [False, True]) def test_tool_loop_rejects_terminal_closeout_before_spend( tmp_path: Path, batch_read: bool, @@ -205,7 +277,7 @@ def test_tool_loop_rejects_terminal_closeout_before_spend( "fixture/settlement-proof.json" if batch_read else "cat fixture/settlement-proof.json" )), - _terminal_action, + _completion_action, ] ) From 87aa11688f6b413d891b520f7e9b71e951cc4b53 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 05:21:19 +0800 Subject: [PATCH 02/10] fix(qualification): retain original settlement plan across validation receipts Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../model-behavior-qualification-v0.md | 3 ++- .../terminal_settlement_tool_behavior.py | 10 +++++++--- .../test_terminal_settlement_tool_behavior.py | 20 +++++++++++++++++++ 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index a7fcbd9987..58a65d810f 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -305,7 +305,8 @@ The plan's conditional ordinary Todo completion may run during validation, before writeback and spend. The actor requires the original Goal/Agent/Todo/Turn arguments and its committed validation receipt; ordinary completion does not qualify terminal closeout. `--no-follow-up` still requires both matching -writeback and spend receipts. This follows the shared +writeback and spend receipts. Later receipts advance the original Turn's plan; +they do not discard its identity-bound command templates. This follows the shared [quota-bound completion contract](../canonical-terminal-review.md#quota-bound-cli-completion) without changing the portfolio, repeats, contrasts or settlement order. diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index 8bf78cb703..6eb183b569 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -884,8 +884,11 @@ def qualify( "role": "system", "content": ( "You are Codex running one LoopX heartbeat. Follow the " - "production heartbeat task and choose each next action " - "from the latest tool result. " + "production heartbeat task. Retain the settlement plan " + "returned by the original quota guard for this same Turn; " + "use each later committed receipt to choose its next " + "remaining step. A receipt without command templates does " + "not replace that plan. " f"{QUOTA_FIRST_TOOL_INSTRUCTION}" "The exec tool's current workspace is the connected goal " "project root, so task " @@ -900,7 +903,8 @@ def qualify( "the final --no-follow-up closeout after spend. Preserve " "the projected Goal, Agent, Todo and Turn arguments. Fill " "the writeback placeholders from the proof's typed fields " - "and choose each later command from the latest tool result." + "in the original next_cli_actions[0]; execute the complete " + "projected command, not a bare command name or help lookup." ), }, {"role": "user", "content": fixture.task_body}, diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index 96296e8889..b67f26a99c 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -186,6 +186,7 @@ def test_real_tool_loop_settles_final_todo_after_spend( assert "the host validates that tool result" in system_prompt assert "validation step's command_condition" in system_prompt assert "distinct from the final --no-follow-up closeout after spend" in system_prompt + assert "A receipt without command templates does not replace that plan" in system_prompt assert first["messages"][1] == {"role": "user", "content": fixture.task_body} assert TERMINAL_SETTLEMENT_FIXTURE_TODO_ID not in fixture.task_body quota_result = _latest_quota_packet(transport.requests[2]) @@ -226,6 +227,25 @@ def completion(request: Mapping[str, Any]) -> ScriptedExecToolAction: assert receipt["terminal_order_observed"] is False +def test_ordinary_completion_does_not_authorize_an_unscoped_writeback(tmp_path: Path) -> None: + fixture = _build_fixture(tmp_path / "oracle") + transport = ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command.replace( + '"${LOOPX_TURN:?}"', "turn-test-001", + )), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), + partial(_completion_action, kind="validation"), + ScriptedExecToolAction(command="loopx refresh-state"), + ]) + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=transport, + ).qualify(qualification_id="ordinary-completion-unscoped-writeback", fixture_root=tmp_path / "actor") + assert receipt["qualification_passed"] is False + assert receipt["failure_code"] == "writeback_identity_mismatch" + assert receipt["settlement_receipt_steps"] == ["validation"] + assert receipt["terminal_order_observed"] is False + + def test_ordinary_completion_requires_its_actual_validation_receipt( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, ) -> None: From 74f11111daf8822a5618391c8557bb0db4e95381 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 05:41:47 +0800 Subject: [PATCH 03/10] fix(settlement): return completion continuation and isolate qualification drafts Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- docs/reference/canonical-terminal-review.md | 6 + .../canonical-terminal-review.zh-CN.md | 4 + .../model-behavior-qualification-v0.md | 8 + loopx/cli_commands/todo.py | 28 +- .../terminal_settlement_tool_behavior.py | 337 ++++++++++-------- .../test_terminal_settlement_tool_behavior.py | 147 +++++++- 6 files changed, 381 insertions(+), 149 deletions(-) diff --git a/docs/reference/canonical-terminal-review.md b/docs/reference/canonical-terminal-review.md index d3f04b0b1b..9a29abf580 100644 --- a/docs/reference/canonical-terminal-review.md +++ b/docs/reference/canonical-terminal-review.md @@ -137,6 +137,12 @@ a changed route uses `semantic_closeout` with an evidence-linked vision decision on the same Turn; no fresh guard or binding is needed. Projecting a command does not execute it or establish acceptance. +Successful Turn-bound ordinary completion returns verified settlement progress +and, while writeback remains due, the existing same-identity settlement plan and +next writeback command. That material-closeout plan includes the shared vision +authoring schema; callers need not reconstruct identities or guess a JSON +format after completion. It grants no new execution or terminal authority. + The shared Todo summary keeps missing-successor diagnostics and counts, but its warning is review guidance, not an obligation to create a successor or terminate a completed stage. Review remaining authorized Goal acceptance and the runnable diff --git a/docs/reference/canonical-terminal-review.zh-CN.md b/docs/reference/canonical-terminal-review.zh-CN.md index 947bae1755..68f7a6058e 100644 --- a/docs/reference/canonical-terminal-review.zh-CN.md +++ b/docs/reference/canonical-terminal-review.zh-CN.md @@ -105,6 +105,10 @@ Goal、Agent、Todo 和 Turn。只有当前契约允许最终范围收尾时， `todo_deliverable_complete`，必需的验证不会随条件省略。符合准入的 `in_flight_continuation` 保留未交付 Todo 为 open，不会伪造通过验证的完成。 +带原 Turn 身份的普通完成成功后，返回已验证的结算进度；仍待写回时，一并返回 +既有同身份结算计划和下一条写回命令。该语义收尾计划包含共享的 vision authoring +格式，调用者无需在完成后重建身份或猜测 JSON 结构；它不授予新的执行或终态权限。 + 共享 Todo 摘要仍保留缺少后继的诊断和计数，但告警是复核引导，不要求制造后继或 终结已完成阶段。先复核剩余的授权 Goal 验收与可执行任务；范围内仍有工作时继续 已有任务或重规划。队列为空本身不能证明最终范围可以收尾。图校验、空前沿重规划 diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index 58a65d810f..ac29e2e5fa 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -309,6 +309,14 @@ writeback and spend receipts. Later receipts advance the original Turn's plan; they do not discard its identity-bound command templates. This follows the shared [quota-bound completion contract](../canonical-terminal-review.md#quota-bound-cli-completion) without changing the portfolio, repeats, contrasts or settlement order. +After the proof is read, a terminal actor may author a project draft in +`.scratch/` using the existing OS-isolated shell. Original fixture inputs and +authority stores remain protected; private host data and external networking +are unavailable. LoopX mutations still use one direct, identity-bound CLI call +at a time; the draft shell cannot invoke LoopX. The original ten-call limit and +all committed receipt checks remain. Explicit foreign routes or Turn identities +fail rather than being repaired, and failure receipts retain fixture-owned +codes rather than echoing CLI errors or model-authored JSON. For selected-Todo and terminal qualification, a standalone `cat` may read up to eight workspace-confined files, optionally diff --git a/loopx/cli_commands/todo.py b/loopx/cli_commands/todo.py index 9c5a8765b8..1acc087a0d 100644 --- a/loopx/cli_commands/todo.py +++ b/loopx/cli_commands/todo.py @@ -21,9 +21,12 @@ from ..control_plane.quota.settlement import ( QuotaSettlementReadback, SettlementIdentity, + SettlementStepKind, build_turn_scoped_cli_settlement_plan, + attach_settlement_progress, read_heartbeat_settlement, settlement_result_payload, + settlement_step_command, ) from ..control_plane.runtime.time import chronology_key from ..control_plane.todos.markdown import render_todo_markdown @@ -134,6 +137,7 @@ def _todo_settlement_plan( identity: SettlementIdentity, *, args: argparse.Namespace, registry_path: Path, runtime_root: Path, goal_ref: dict[str, str] | None, + quota_spend_source: str = "heartbeat", ) -> dict[str, object]: """Render the native plan with the original route and supplied lease facts.""" actor_args = "" @@ -156,7 +160,7 @@ def _todo_settlement_plan( replan_obligation_id=identity.replan_obligation_id, turn_instance_id=identity.turn_instance_id, command_prefix=prefix, scoped_cli_args="", lifecycle_actor_args=actor_args, writeback_path_args=path_args, - goal_ref=goal_ref, + goal_ref=goal_ref, quota_spend_source=quota_spend_source, ).as_dict() from ..capabilities.explore.turn_context import project_settlement_attachment @@ -633,6 +637,8 @@ def handle_todo_command( no_follow_up=bool(args.no_follow_up), ) if completion_error is not None: + progress = settlement_readback.progress + assert progress is not None settlement_result = settlement_readback.settlement payload = { "ok": False, @@ -652,6 +658,7 @@ def handle_todo_command( registry_path=registry_path, runtime_root=runtime_root, goal_ref=goal_ref, + quota_spend_source=progress["quota_spend_source"], ), "error": completion_error, } @@ -825,6 +832,25 @@ def handle_todo_command( payload["ok"] = False payload["receipt_repair_required"] = True payload["error"] = settlement_result.failure.reason + elif not args.no_follow_up: + attach_settlement_progress( + payload, settlement_readback, registry_path=registry_path, + runtime_root=runtime_root, goal_ref=goal_ref, + ) + progress = settlement_readback.progress + assert progress is not None + if progress.get("next_step") == "durable_writeback": + identity = settlement_readback.identity.value + assert identity is not None + plan = _todo_settlement_plan( + identity, args=args, registry_path=registry_path, + runtime_root=runtime_root, goal_ref=goal_ref, + quota_spend_source=progress["quota_spend_source"], + ) + payload["settlement_plan"] = plan + payload["next_cli_actions"] = [settlement_step_command( + plan, SettlementStepKind.DURABLE_WRITEBACK, + )] if ( args.todo_command == "complete" and payload.get("ok") diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index 6eb183b569..7135ca3242 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -5,6 +5,7 @@ import shlex import subprocess from collections.abc import Mapping +from contextlib import ExitStack from dataclasses import dataclass, field from hashlib import sha256 from pathlib import Path @@ -30,6 +31,7 @@ loopx_command_tokens, ) from .selected_todo_tool_behavior import bounded_workspace_read_plan +from .vision_shell_host import VisionShellHost TERMINAL_SETTLEMENT_TOOL_BEHAVIOR_RECEIPT_SCHEMA_VERSION = ( "terminal_settlement_tool_behavior_receipt_v0" @@ -66,6 +68,14 @@ ] +class _TerminalToolViolation(ValueError): + """A fixture-owned invariant code, never provider or CLI error text.""" + + +def _terminal_failure_code(error: Exception) -> str: + return str(error) if isinstance(error, _TerminalToolViolation) else "tool_execution_failed" + + @dataclass(frozen=True) class _TerminalSettlementFixture: task_body: str @@ -108,6 +118,7 @@ class _QualificationState: proof_read: bool = False writeback_committed: bool = False spend_committed: bool = False + workspace_shell_executed: bool = False receipt_steps: list[str] = field(default_factory=list) seen_clock: bool = False @@ -611,7 +622,9 @@ def _matches_identity(tokens: list[str], state: _QualificationState) -> bool: and argument_value(tokens, "--agent-id") == TERMINAL_SETTLEMENT_FIXTURE_AGENT_ID and argument_value(tokens, "--todo-id") == TERMINAL_SETTLEMENT_FIXTURE_TODO_ID - and argument_value(tokens, "--turn-instance-id") + and argument_value(tokens, "--turn-instance-id") in { + state.turn_instance_id, "$LOOPX_TURN", "${LOOPX_TURN}", "${LOOPX_TURN:?}", + } ) @@ -654,10 +667,10 @@ def _quota_contract(packet: Mapping[str, Any]) -> dict[str, Any]: def _settlement_receipt_steps(payload: Mapping[str, Any]) -> list[str]: settlement = payload.get("settlement_result") if not isinstance(settlement, Mapping) or settlement.get("ok") is not True: - raise ValueError("settlement result is missing or failed") + raise _TerminalToolViolation("settlement result is missing or failed") receipts = settlement.get("receipts") if not isinstance(receipts, list): - raise ValueError("settlement receipts are missing") + raise _TerminalToolViolation("settlement receipts are missing") return [ str(item.get("step_kind")) for item in receipts @@ -667,6 +680,24 @@ def _settlement_receipt_steps(payload: Mapping[str, Any]) -> list[str]: def _execute_cli(command: str, state: _QualificationState) -> dict[str, Any]: tokens = loopx_command_tokens(command) + fixture = state.fixture + routes = { + "--runtime-root": {fixture.runtime_root.resolve()}, + "--project": {fixture.project_root.resolve()}, + "--state-file": {(fixture.project_root / ".codex/goals" / + TERMINAL_SETTLEMENT_FIXTURE_GOAL_ID / "ACTIVE_GOAL_STATE.md").resolve()}, + "--registry": {fixture.global_registry_path.resolve(), + (fixture.project_root / ".loopx/registry.json").resolve()}, + } + for option, allowed in routes.items(): + supplied = argument_value(tokens or [], option) + if supplied and (fixture.project_root / supplied).resolve() not in allowed: + raise _TerminalToolViolation("fixture_route_mismatch") + vision = argument_value(tokens or [], "--agent-vision-json") + if vision: + draft = (state.fixture.project_root / vision).resolve() + if not draft.is_relative_to(state.fixture.project_root.resolve()) or not draft.is_file(): + raise _TerminalToolViolation("vision_draft_outside_workspace") if tokens and "--format" not in tokens: command = shlex.join([tokens[0], "--format", "json", *tokens[1:]]) output = execute_loopx_cli( @@ -689,12 +720,14 @@ def _execute_workspace_read( *, state: _QualificationState, ) -> str: + if state.quota_packet is None: + raise _TerminalToolViolation("workspace_read_before_quota") plan = bounded_workspace_read_plan( command, fixture=cast(Any, state.fixture), ) if not plan: - raise ValueError("command is not one bounded workspace read") + raise _TerminalToolViolation("command is not one bounded workspace read") outputs: list[str] = [] status = 0 proof_read = False @@ -759,7 +792,7 @@ def _receipt( "filesystem_writes_executed": True, "writes_limited_to_temporary_fixture": True, "external_writes_executed": False, - "shell_commands_executed": False, + "shell_commands_executed": state.workspace_shell_executed, "read_only_host_commands_executed": True, }, } @@ -884,18 +917,19 @@ def qualify( "role": "system", "content": ( "You are Codex running one LoopX heartbeat. Follow the " - "production heartbeat task. Retain the settlement plan " - "returned by the original quota guard for this same Turn; " - "use each later committed receipt to choose its next " - "remaining step. A receipt without command templates does " - "not replace that plan. " + "production heartbeat task. Retain the original quota " + "identity and settlement plan. A later same-Turn " + "settlement_plan supplies remaining commands and authoring " + "schema; use committed receipts to choose the next step. " + "A receipt without command templates does not replace " + "that plan. " f"{QUOTA_FIRST_TOOL_INSTRUCTION}" "The exec tool's current workspace is the connected goal " "project root, so task " "paths are directly addressable. Read the exact proof target " "once with `cat`; the host validates that tool result. Do not " - "run python, jq, test, echo, another validation command, or " - "re-read the workspace afterward. Use one command per tool " + "run another validation command or " + "re-read the original inputs afterward. Use one command per tool " "call. After the proof read, follow the quota-projected " "settlement plan, including the validation step's " "command_condition. Ordinary Todo completion validates the " @@ -903,8 +937,14 @@ def qualify( "the final --no-follow-up closeout after spend. Preserve " "the projected Goal, Agent, Todo and Turn arguments. Fill " "the writeback placeholders from the proof's typed fields " - "in the original next_cli_actions[0]; execute the complete " + "in the current same-Turn plan's durable_writeback command; execute the complete " "projected command, not a bare command name or help lookup." + " If a vision packet is needed, use the plan's " + "vision_authoring schema and author a project draft under " + "`.scratch/`. Draft shell calls are OS-isolated: original " + "inputs, authority stores, private host data and network " + "access are protected. Run every LoopX command directly, " + "one per tool call; draft shells cannot invoke LoopX." ), }, {"role": "user", "content": fixture.task_body}, @@ -922,125 +962,142 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: failure_code=failure_code, ) - for _ in range(TERMINAL_SETTLEMENT_TOOL_BEHAVIOR_MAX_CALLS): - step = self._client.next_step(state.messages) - tool_call = step.tool_call - if tool_call is None: - return receipt( - passed=False, - failure_code=( - "model_returned_before_terminal_closeout" - if state.spend_committed - else "model_returned_without_settlement" - ), + workspace_shell: VisionShellHost | None = None + with ExitStack() as resources: + for _ in range(TERMINAL_SETTLEMENT_TOOL_BEHAVIOR_MAX_CALLS): + step = self._client.next_step(state.messages) + tool_call = step.tool_call + if tool_call is None: + return receipt( + passed=False, + failure_code=( + "model_returned_before_terminal_closeout" + if state.spend_committed + else "model_returned_without_settlement" + ), + ) + tokens = loopx_command_tokens(tool_call.command) + command_kind, command_action = ( + _command_path(tokens) if tokens else ("workspace_read", None) ) - tokens = loopx_command_tokens(tool_call.command) - command_kind, command_action = ( - _command_path(tokens) if tokens else ("workspace_read", None) - ) - kind = "unexpected_command" - output = "" - failure_code: str | None = None - try: - if command_kind == "quota" and command_action == "should-run": - if state.quota_packet is not None: - raise ValueError("repeated_quota_should_run") - payload = _execute_cli(tool_call.command, state) - state.quota_packet = payload - state.contract = _quota_contract(payload) - kind = "quota_should_run" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - elif command_kind == "refresh_state": - if state.quota_packet is None: - raise ValueError("writeback_before_quota") - if not state.proof_read: - raise ValueError("writeback_before_validation") - if not tokens or not _matches_identity(tokens, state): - raise ValueError("writeback_identity_mismatch") - payload = _execute_cli(tool_call.command, state) - receipt_steps = _settlement_receipt_steps(payload) - if receipt_steps != _EXPECTED_RECEIPT_STEPS[:2]: - raise ValueError("writeback_receipt_mismatch") - state.writeback_committed = True - state.receipt_steps = receipt_steps - kind = "durable_writeback" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - elif command_kind == "quota" and command_action == "spend-slot": - if not state.writeback_committed: - raise ValueError("quota_spend_before_writeback") - if not tokens or not _matches_identity(tokens, state): - raise ValueError("quota_spend_identity_mismatch") - if "--execute" not in tokens or argument_value( - tokens, "--source" - ) != "heartbeat": - raise ValueError("quota_spend_contract_mismatch") - payload = _execute_cli(tool_call.command, state) - receipt_steps = _settlement_receipt_steps(payload) - if receipt_steps != _EXPECTED_RECEIPT_STEPS[:3]: - raise ValueError("quota_spend_receipt_mismatch") - state.spend_committed = True - state.receipt_steps = receipt_steps - kind = "quota_spend" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - elif command_kind == "todo" and command_action == "complete": - terminal = "--no-follow-up" in tokens - if terminal: - if not state.spend_committed: - raise ValueError("terminal_closeout_before_spend") - if not _matches_identity(tokens, state): - raise ValueError("terminal_closeout_contract_mismatch") - else: + kind = "unexpected_command" + output = "" + failure_code: str | None = None + try: + if command_kind == "quota" and command_action == "should-run": + if state.quota_packet is not None: + raise _TerminalToolViolation("repeated_quota_should_run") + payload = _execute_cli(tool_call.command, state) + state.quota_packet = payload + state.contract = _quota_contract(payload) + kind = "quota_should_run" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + elif command_kind == "refresh_state": + if state.quota_packet is None: + raise _TerminalToolViolation("writeback_before_quota") if not state.proof_read: - raise ValueError("completion_before_validation") - if state.writeback_committed: - raise ValueError("completion_after_writeback") - if not _matches_identity(tokens, state): - raise ValueError("completion_identity_mismatch") - payload = _execute_cli(tool_call.command, state) - receipt_steps = _settlement_receipt_steps(payload) - expected_steps = _EXPECTED_RECEIPT_STEPS if terminal else _EXPECTED_RECEIPT_STEPS[:1] - if receipt_steps != expected_steps: - raise ValueError("terminal_closeout_receipt_mismatch" if terminal - else "completion_receipt_mismatch") - state.receipt_steps = receipt_steps - kind = "terminal_closeout" if terminal else "todo_completion" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - else: - output = _execute_workspace_read(tool_call.command, state=state) - kind = "delivery_validation" if state.proof_read else "workspace_read" - except (RuntimeError, ValueError, json.JSONDecodeError) as exc: - failure_code = str(exc) + raise _TerminalToolViolation("writeback_before_validation") + if not tokens or not _matches_identity(tokens, state): + raise _TerminalToolViolation("writeback_identity_mismatch") + payload = _execute_cli(tool_call.command, state) + receipt_steps = _settlement_receipt_steps(payload) + if receipt_steps != _EXPECTED_RECEIPT_STEPS[:2]: + raise _TerminalToolViolation("writeback_receipt_mismatch") + state.writeback_committed = True + state.receipt_steps = receipt_steps + kind = "durable_writeback" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + elif command_kind == "quota" and command_action == "spend-slot": + if not state.writeback_committed: + raise _TerminalToolViolation("quota_spend_before_writeback") + if not tokens or not _matches_identity(tokens, state): + raise _TerminalToolViolation("quota_spend_identity_mismatch") + if "--execute" not in tokens or argument_value( + tokens, "--source" + ) != "heartbeat": + raise _TerminalToolViolation("quota_spend_contract_mismatch") + payload = _execute_cli(tool_call.command, state) + receipt_steps = _settlement_receipt_steps(payload) + if receipt_steps != _EXPECTED_RECEIPT_STEPS[:3]: + raise _TerminalToolViolation("quota_spend_receipt_mismatch") + state.spend_committed = True + state.receipt_steps = receipt_steps + kind = "quota_spend" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + elif command_kind == "todo" and command_action == "complete": + terminal = "--no-follow-up" in tokens + if terminal: + if not state.spend_committed: + raise _TerminalToolViolation("terminal_closeout_before_spend") + if not _matches_identity(tokens, state): + raise _TerminalToolViolation("terminal_closeout_contract_mismatch") + else: + if not state.proof_read: + raise _TerminalToolViolation("completion_before_validation") + if state.writeback_committed: + raise _TerminalToolViolation("completion_after_writeback") + if not _matches_identity(tokens, state): + raise _TerminalToolViolation("completion_identity_mismatch") + payload = _execute_cli(tool_call.command, state) + receipt_steps = _settlement_receipt_steps(payload) + expected_steps = _EXPECTED_RECEIPT_STEPS if terminal else _EXPECTED_RECEIPT_STEPS[:1] + if receipt_steps != expected_steps: + raise _TerminalToolViolation("terminal_closeout_receipt_mismatch" if terminal + else "completion_receipt_mismatch") + state.receipt_steps = receipt_steps + kind = "terminal_closeout" if terminal else "todo_completion" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + else: + read_plan = bounded_workspace_read_plan(tool_call.command, fixture=cast(Any, fixture)) + if read_plan or not state.proof_read or state.writeback_committed: + output = _execute_workspace_read(tool_call.command, state=state) + kind = "delivery_validation" if state.proof_read else "workspace_read" + else: + if workspace_shell is None: + def reject_nested_cli(_argv: list[str], _cwd: Path, _output: str) -> str: + raise ValueError("Run each original LoopX command directly, outside the draft shell") + workspace_shell = VisionShellHost( + fixture.project_root, reject_nested_cli, turn_instance_id=state.turn_instance_id, + ) + resources.callback(workspace_shell.close) + state.workspace_shell_executed = True + output, exit_code = workspace_shell.execute(tool_call.command) + if exit_code: + raise _TerminalToolViolation("workspace_authoring_failed") + kind = "workspace_authoring" + except (RuntimeError, ValueError, json.JSONDecodeError) as exc: + failure_code = _terminal_failure_code(exc) - step_receipt = { - "ordinal": len(state.steps) + 1, - "kind": kind if failure_code is None else failure_code, - "command_digest": digest_text(tool_call.command), - } - if failure_code is not None: - step_receipt["redacted_command_shape"] = _redacted_command_shape( - tool_call.command + step_receipt = { + "ordinal": len(state.steps) + 1, + "kind": kind if failure_code is None else failure_code, + "command_digest": digest_text(tool_call.command), + } + if failure_code is not None: + step_receipt["redacted_command_shape"] = _redacted_command_shape( + tool_call.command + ) + state.steps.append(step_receipt) + if failure_code is not None: + return receipt(passed=False, failure_code=failure_code) + if kind == "terminal_closeout": + return receipt(passed=True, failure_code=None) + state.messages.extend( + [ + { + "role": "assistant", + "content": step.assistant_content, + "tool_calls": [tool_call.provider_value], + }, + { + "role": "tool", + "tool_call_id": tool_call.call_id, + "content": output, + }, + ] ) - state.steps.append(step_receipt) - if failure_code is not None: - return receipt(passed=False, failure_code=failure_code) - if kind == "terminal_closeout": - return receipt(passed=True, failure_code=None) - state.messages.extend( - [ - { - "role": "assistant", - "content": step.assistant_content, - "tool_calls": [tool_call.provider_value], - }, - { - "role": "tool", - "tool_call_id": tool_call.call_id, - "content": output, - }, - ] - ) - return receipt(passed=False, failure_code="tool_call_budget_exhausted") + return receipt(passed=False, failure_code="tool_call_budget_exhausted") def qualify_reentry( self, @@ -1145,12 +1202,12 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: failure_code: str | None = None try: if state.terminal_quota_observed: - raise ValueError("model_called_tool_after_terminal_quota") + raise _TerminalToolViolation("model_called_tool_after_terminal_quota") if command_kind == "refresh_state": - raise ValueError("repeated_refresh_state") + raise _TerminalToolViolation("repeated_refresh_state") if command_kind == "todo" and command_action == "complete": if not tokens: - raise ValueError("lifecycle_settlement_command_malformed") + raise _TerminalToolViolation("lifecycle_settlement_command_malformed") todo_id = argument_value(tokens, "--todo-id") or "" expected_action = fixture.projected_actions_by_todo.get(todo_id) expected_tokens = ( @@ -1159,7 +1216,7 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: else None ) if todo_id in state.settled_todo_ids: - raise ValueError("repeated_lifecycle_settlement") + raise _TerminalToolViolation("repeated_lifecycle_settlement") if ( expected_tokens is None or argument_value(tokens, "--goal-id") @@ -1176,7 +1233,7 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: or "--no-follow-up" not in tokens or "--note" in tokens ): - raise ValueError("lifecycle_settlement_identity_mismatch") + raise _TerminalToolViolation("lifecycle_settlement_identity_mismatch") payload = _execute_reentry_cli(tool_call.command, state=state) if not ( payload.get("ok") is True @@ -1185,7 +1242,7 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: and payload.get("completion_recovery") == "lifecycle_reentry_terminal_closeout" ): - raise ValueError("lifecycle_settlement_execution_failed") + raise _TerminalToolViolation("lifecycle_settlement_execution_failed") state.settled_todo_ids.append(todo_id) kind = "todo_lifecycle_settlement" output = json.dumps(payload, ensure_ascii=False, sort_keys=True) @@ -1193,32 +1250,32 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: if len(state.settled_todo_ids) != len( fixture.projected_actions_by_todo ): - raise ValueError("quota_reentry_before_lifecycle_settlement") + raise _TerminalToolViolation("quota_reentry_before_lifecycle_settlement") if not tokens or ( argument_value(tokens, "--goal-id") != TERMINAL_SETTLEMENT_REENTRY_FIXTURE_GOAL_ID or argument_value(tokens, "--agent-id") != TERMINAL_SETTLEMENT_REENTRY_FIXTURE_AGENT_ID ): - raise ValueError("quota_reentry_identity_mismatch") + raise _TerminalToolViolation("quota_reentry_identity_mismatch") payload = _execute_reentry_cli( tool_call.command, state=state, accepted_return_codes=(0, 1), ) if payload.get("should_run") is not False: - raise ValueError("quota_reentry_did_not_terminate") + raise _TerminalToolViolation("quota_reentry_did_not_terminate") state.terminal_quota_observed = True kind = "terminal_quota_reentry" output = json.dumps(payload, ensure_ascii=False, sort_keys=True) elif command_kind == "todo" and command_action == "add": - raise ValueError("invented_lifecycle_successor") + raise _TerminalToolViolation("invented_lifecycle_successor") elif command_kind == "quota" and command_action == "spend-slot": - raise ValueError("unexpected_quota_spend") + raise _TerminalToolViolation("unexpected_quota_spend") else: - raise ValueError("unexpected_command") + raise _TerminalToolViolation("unexpected_command") except (RuntimeError, ValueError, json.JSONDecodeError) as exc: - failure_code = str(exc) + failure_code = _terminal_failure_code(exc) step_receipt = { "ordinal": len(state.steps) + 1, diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index b67f26a99c..e7bd864720 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -1,6 +1,7 @@ from __future__ import annotations import json +import shlex from collections.abc import Mapping from functools import partial from pathlib import Path @@ -19,6 +20,7 @@ DoubaoTerminalSettlementToolBehaviorActor, _build_fixture, ) +from loopx.control_plane.testing.vision_shell_host import shell_isolation_available def _latest_quota_packet(request: Mapping[str, Any]) -> dict[str, Any]: @@ -37,6 +39,16 @@ def _latest_quota_packet(request: Mapping[str, Any]) -> dict[str, Any]: def _writeback_action(request: Mapping[str, Any]) -> ScriptedExecToolAction: packet = _latest_quota_packet(request) command = packet["interaction_contract"]["cli_channel"]["next_cli_actions"][0] + for message in reversed(request["messages"]): + if message["role"] != "tool": + continue + try: + result = json.loads(message["content"]) + except json.JSONDecodeError: + continue + if isinstance(result, dict) and result.get("settlement_plan") and result.get("next_cli_actions"): + command = result["next_cli_actions"][0] + break command = ( command.replace("", "terminal_settlement_validated") .replace("", "single_surface") @@ -193,23 +205,35 @@ def test_real_tool_loop_settles_final_todo_after_spend( assert quota_result["selected_todo"]["todo_id"] == ( TERMINAL_SETTLEMENT_FIXTURE_TODO_ID ) + if ordinary_completion: + results = [json.loads(message["content"]) for message in transport.requests[-1]["messages"] + if message["role"] == "tool" and message["content"].startswith("{")] + completed = next(result for result in results if result.get("status") == "done") + assert completed["settlement_progress"]["next_step"] == "durable_writeback" + plan = completed["settlement_plan"] + assert plan["identity"] == completed["settlement_identity"] + writeback = next(step for step in plan["ordered_steps"] if step["kind"] == "durable_writeback") + assert writeback["vision_authoring"]["schema_version"] == "goal_vision_replan_contract_v0" + assert completed["next_cli_actions"] == [writeback["command_template"]] + assert completed["settlement_result"]["receipts"][0]["step_kind"] == "validation" @pytest.mark.parametrize( - ("read_proof", "foreign_actor", "expected_failure"), - [(False, False, "completion_before_validation"), - (True, True, "completion_identity_mismatch")], + ("read_proof", "drift_option", "expected_failure"), + [(False, None, "completion_before_validation"), + (True, "--agent-id", "completion_identity_mismatch"), + (True, "--turn-instance-id", "completion_identity_mismatch")], ) def test_ordinary_completion_cannot_bypass_validation_or_identity( - tmp_path: Path, read_proof: bool, foreign_actor: bool, expected_failure: str, + tmp_path: Path, read_proof: bool, drift_option: str | None, expected_failure: str, ) -> None: fixture = _build_fixture(tmp_path / "oracle") def completion(request: Mapping[str, Any]) -> ScriptedExecToolAction: - command = _completion_action(request, kind="validation").command - if foreign_actor: - command = command.replace("--agent-id codex-terminal-settlement", "--agent-id foreign-agent") - return ScriptedExecToolAction(command=command) + tokens = shlex.split(_completion_action(request, kind="validation").command) + if drift_option: + tokens[tokens.index(drift_option) + 1] = "foreign-identity" + return ScriptedExecToolAction(command=shlex.join(tokens)) transport = ScriptedDoubaoExecTransport([ ScriptedExecToolAction(command=fixture.quota_guard_command.replace( @@ -246,6 +270,113 @@ def test_ordinary_completion_does_not_authorize_an_unscoped_writeback(tmp_path: assert receipt["terminal_order_observed"] is False +def test_terminal_fixture_requires_quota_before_reading_proof(tmp_path: Path) -> None: + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", + transport=ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), + ]), + ).qualify(qualification_id="read-before-quota", fixture_root=tmp_path / "actor") + assert receipt["failure_code"] == "workspace_read_before_quota" + assert receipt["qualification_passed"] is False + assert receipt["settlement_receipt_steps"] == [] + + +@pytest.mark.parametrize("option", ["--registry", "--runtime-root", "--project", "--state-file"]) +def test_terminal_fixture_rejects_foreign_routes(tmp_path: Path, option: str) -> None: + fixture = _build_fixture(tmp_path / "oracle") + outside = tmp_path / "owner-state.json" + outside.write_text("Owner state must remain unchanged.\n") + + def completion(request): + tokens = shlex.split(_completion_action(request, kind="validation").command) + if option in tokens: + tokens[tokens.index(option) + 1] = str(outside) + else: + tokens += [option, str(outside)] + return ScriptedExecToolAction(command=shlex.join(tokens)) + + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), completion, + ]), + ).qualify(qualification_id="foreign-route", fixture_root=tmp_path / "actor") + assert receipt["failure_code"] == "fixture_route_mismatch" + assert receipt["qualification_passed"] is False + assert receipt["settlement_receipt_steps"] == [] + assert outside.read_text() == "Owner state must remain unchanged.\n" + + +def test_terminal_failure_receipt_does_not_echo_cli_or_model_text( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + from loopx.control_plane.testing import terminal_settlement_tool_behavior as terminal + + fixture = _build_fixture(tmp_path / "oracle") + execute = terminal._execute_cli + + def failed_writeback(command, state): + if "refresh-state" in command: + raise RuntimeError("private-model-payload-and-private-file-name") + return execute(command, state) + + monkeypatch.setattr(terminal, "_execute_cli", failed_writeback) + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), _writeback_action, + ]), + ).qualify(qualification_id="redacted-cli-failure", fixture_root=tmp_path / "actor") + assert receipt["qualification_passed"] is False + assert receipt["failure_code"] == "tool_execution_failed" + assert "private-model-payload" not in json.dumps(receipt) + + +@pytest.mark.skipif(not shell_isolation_available(), reason="Draft authoring requires native OS isolation") +@pytest.mark.parametrize("draft_target", [".scratch/vision.json", "fixture/settlement-proof.json", "outside"]) +def test_terminal_native_draft_preserves_proof_and_authority(tmp_path: Path, draft_target: str) -> None: + fixture = _build_fixture(tmp_path / "oracle") + outside = tmp_path / "owner-private.json" + outside.write_text("Owner artifact.\n") + target = str(outside) if draft_target == "outside" else draft_target + vision = { + "schema_version": "goal_vision_replan_contract_v0", "state": "vision_closed", + "vision_patch": {"acceptance_summary": "Original proof and Todo completion independently validated."}, + "path_delta": {"outcome": "no_change", "prior_assumption": "Final delivery required validation.", + "observed_reality": "The proof was read and original Todo validation committed.", + "retained": ["Original validated delivery"], "evidence_refs": ["fixture-settlement-proof"]}, + } + + def writeback(request): + return ScriptedExecToolAction(command=_writeback_action(request).command + + " --agent-vision-json .scratch/vision.json") + + def completion(request): + tokens = shlex.split(_completion_action(request, kind="validation").command) + tokens[tokens.index("--turn-instance-id") + 1] = "${LOOPX_TURN:?}" + return ScriptedExecToolAction(command=shlex.join(tokens)) + + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), + completion, + ScriptedExecToolAction(command="cat > " + shlex.quote(target) + " <<'JSON'\n" + + json.dumps(vision) + "\nJSON"), + writeback, _spend_action, _completion_action, + ]), + ).qualify(qualification_id="native-terminal-draft", fixture_root=tmp_path / "actor") + passed = draft_target == ".scratch/vision.json" + assert receipt["qualification_passed"] is passed, receipt + assert receipt["boundary"]["shell_commands_executed"] is True + assert receipt["settlement_receipt_steps"] == ( + ["validation", "durable_writeback", "quota_spend", "terminal_closeout"] if passed else ["validation"] + ) + assert (tmp_path / "actor/project/fixture/settlement-proof.json").read_bytes() == fixture.proof_target.read_bytes() + assert outside.read_text() == "Owner artifact.\n" + + def test_ordinary_completion_requires_its_actual_validation_receipt( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, ) -> None: From 551c5250c09e130506436e7e749aeadab04dc6a7 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 05:46:12 +0800 Subject: [PATCH 04/10] refactor(qualification): separate action handling and retain original host routes Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../terminal_settlement_tool_behavior.py | 196 ++++++++++-------- 1 file changed, 113 insertions(+), 83 deletions(-) diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index 7135ca3242..8ce95803b3 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -689,8 +689,13 @@ def _execute_cli(command: str, state: _QualificationState) -> dict[str, Any]: "--registry": {fixture.global_registry_path.resolve(), (fixture.project_root / ".loopx/registry.json").resolve()}, } + guard_registry = argument_value(loopx_command_tokens(fixture.quota_guard_command) or [], "--registry") for option, allowed in routes.items(): supplied = argument_value(tokens or [], option) + # Bind the exact host reference emitted by the original task (such as + # $HOME's registry) to this isolated fixture, as the CLI bridge does. + if option == "--registry" and supplied == guard_registry: + continue if supplied and (fixture.project_root / supplied).resolve() not in allowed: raise _TerminalToolViolation("fixture_route_mismatch") vision = argument_value(tokens or [], "--agent-vision-json") @@ -863,6 +868,108 @@ def _reentry_receipt( } +def _execute_todo_completion( + command: str, tokens: list[str], state: _QualificationState, +) -> tuple[str, str]: + terminal = "--no-follow-up" in tokens + if terminal: + if not state.spend_committed: + raise _TerminalToolViolation("terminal_closeout_before_spend") + if not _matches_identity(tokens, state): + raise _TerminalToolViolation("terminal_closeout_contract_mismatch") + else: + if not state.proof_read: + raise _TerminalToolViolation("completion_before_validation") + if state.writeback_committed: + raise _TerminalToolViolation("completion_after_writeback") + if not _matches_identity(tokens, state): + raise _TerminalToolViolation("completion_identity_mismatch") + payload = _execute_cli(command, state) + receipt_steps = _settlement_receipt_steps(payload) + expected_steps = _EXPECTED_RECEIPT_STEPS if terminal else _EXPECTED_RECEIPT_STEPS[:1] + if receipt_steps != expected_steps: + raise _TerminalToolViolation("terminal_closeout_receipt_mismatch" if terminal + else "completion_receipt_mismatch") + state.receipt_steps = receipt_steps + kind = "terminal_closeout" if terminal else "todo_completion" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + return output, kind + + +def _execute_terminal_cli( + command: str, tokens: list[str], state: _QualificationState, +) -> tuple[str, str] | None: + command_kind, command_action = _command_path(tokens) + if command_kind == "quota" and command_action == "should-run": + if state.quota_packet is not None: + raise _TerminalToolViolation("repeated_quota_should_run") + payload = _execute_cli(command, state) + state.quota_packet = payload + state.contract = _quota_contract(payload) + kind = "quota_should_run" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + elif command_kind == "refresh_state": + if state.quota_packet is None: + raise _TerminalToolViolation("writeback_before_quota") + if not state.proof_read: + raise _TerminalToolViolation("writeback_before_validation") + if not tokens or not _matches_identity(tokens, state): + raise _TerminalToolViolation("writeback_identity_mismatch") + payload = _execute_cli(command, state) + receipt_steps = _settlement_receipt_steps(payload) + if receipt_steps != _EXPECTED_RECEIPT_STEPS[:2]: + raise _TerminalToolViolation("writeback_receipt_mismatch") + state.writeback_committed = True + state.receipt_steps = receipt_steps + kind = "durable_writeback" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + elif command_kind == "quota" and command_action == "spend-slot": + if not state.writeback_committed: + raise _TerminalToolViolation("quota_spend_before_writeback") + if not tokens or not _matches_identity(tokens, state): + raise _TerminalToolViolation("quota_spend_identity_mismatch") + if "--execute" not in tokens or argument_value( + tokens, "--source" + ) != "heartbeat": + raise _TerminalToolViolation("quota_spend_contract_mismatch") + payload = _execute_cli(command, state) + receipt_steps = _settlement_receipt_steps(payload) + if receipt_steps != _EXPECTED_RECEIPT_STEPS[:3]: + raise _TerminalToolViolation("quota_spend_receipt_mismatch") + state.spend_committed = True + state.receipt_steps = receipt_steps + kind = "quota_spend" + output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + elif command_kind == "todo" and command_action == "complete": + return _execute_todo_completion(command, tokens, state) + else: + return None + return output, kind + + +def _execute_terminal_workspace( + command: str, state: _QualificationState, workspace_shell: VisionShellHost | None, resources: ExitStack, +) -> tuple[str, str, VisionShellHost | None]: + read_plan = bounded_workspace_read_plan(command, fixture=cast(Any, state.fixture)) + if read_plan or not state.proof_read or state.writeback_committed: + output = _execute_workspace_read(command, state=state) + kind = "delivery_validation" if state.proof_read else "workspace_read" + else: + if workspace_shell is None: + def reject_nested_cli(_argv: list[str], _cwd: Path, _output: str) -> str: + raise ValueError("Run each original LoopX command directly, outside the draft shell") + workspace_shell = VisionShellHost( + state.fixture.project_root, reject_nested_cli, turn_instance_id=state.turn_instance_id, + ) + resources.callback(workspace_shell.close) + state.workspace_shell_executed = True + output, exit_code = workspace_shell.execute(command) + if exit_code: + raise _TerminalToolViolation("workspace_authoring_failed") + kind = "workspace_authoring" + return output, kind, workspace_shell + + class DoubaoTerminalSettlementToolBehaviorActor: """Prove the model follows the real post-spend terminal closeout plan.""" @@ -977,94 +1084,17 @@ def receipt(*, passed: bool, failure_code: str | None) -> dict[str, Any]: ), ) tokens = loopx_command_tokens(tool_call.command) - command_kind, command_action = ( - _command_path(tokens) if tokens else ("workspace_read", None) - ) kind = "unexpected_command" output = "" failure_code: str | None = None try: - if command_kind == "quota" and command_action == "should-run": - if state.quota_packet is not None: - raise _TerminalToolViolation("repeated_quota_should_run") - payload = _execute_cli(tool_call.command, state) - state.quota_packet = payload - state.contract = _quota_contract(payload) - kind = "quota_should_run" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - elif command_kind == "refresh_state": - if state.quota_packet is None: - raise _TerminalToolViolation("writeback_before_quota") - if not state.proof_read: - raise _TerminalToolViolation("writeback_before_validation") - if not tokens or not _matches_identity(tokens, state): - raise _TerminalToolViolation("writeback_identity_mismatch") - payload = _execute_cli(tool_call.command, state) - receipt_steps = _settlement_receipt_steps(payload) - if receipt_steps != _EXPECTED_RECEIPT_STEPS[:2]: - raise _TerminalToolViolation("writeback_receipt_mismatch") - state.writeback_committed = True - state.receipt_steps = receipt_steps - kind = "durable_writeback" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - elif command_kind == "quota" and command_action == "spend-slot": - if not state.writeback_committed: - raise _TerminalToolViolation("quota_spend_before_writeback") - if not tokens or not _matches_identity(tokens, state): - raise _TerminalToolViolation("quota_spend_identity_mismatch") - if "--execute" not in tokens or argument_value( - tokens, "--source" - ) != "heartbeat": - raise _TerminalToolViolation("quota_spend_contract_mismatch") - payload = _execute_cli(tool_call.command, state) - receipt_steps = _settlement_receipt_steps(payload) - if receipt_steps != _EXPECTED_RECEIPT_STEPS[:3]: - raise _TerminalToolViolation("quota_spend_receipt_mismatch") - state.spend_committed = True - state.receipt_steps = receipt_steps - kind = "quota_spend" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) - elif command_kind == "todo" and command_action == "complete": - terminal = "--no-follow-up" in tokens - if terminal: - if not state.spend_committed: - raise _TerminalToolViolation("terminal_closeout_before_spend") - if not _matches_identity(tokens, state): - raise _TerminalToolViolation("terminal_closeout_contract_mismatch") - else: - if not state.proof_read: - raise _TerminalToolViolation("completion_before_validation") - if state.writeback_committed: - raise _TerminalToolViolation("completion_after_writeback") - if not _matches_identity(tokens, state): - raise _TerminalToolViolation("completion_identity_mismatch") - payload = _execute_cli(tool_call.command, state) - receipt_steps = _settlement_receipt_steps(payload) - expected_steps = _EXPECTED_RECEIPT_STEPS if terminal else _EXPECTED_RECEIPT_STEPS[:1] - if receipt_steps != expected_steps: - raise _TerminalToolViolation("terminal_closeout_receipt_mismatch" if terminal - else "completion_receipt_mismatch") - state.receipt_steps = receipt_steps - kind = "terminal_closeout" if terminal else "todo_completion" - output = json.dumps(payload, ensure_ascii=False, sort_keys=True) + handled = _execute_terminal_cli(tool_call.command, tokens, state) if tokens else None + if handled is not None: + output, kind = handled else: - read_plan = bounded_workspace_read_plan(tool_call.command, fixture=cast(Any, fixture)) - if read_plan or not state.proof_read or state.writeback_committed: - output = _execute_workspace_read(tool_call.command, state=state) - kind = "delivery_validation" if state.proof_read else "workspace_read" - else: - if workspace_shell is None: - def reject_nested_cli(_argv: list[str], _cwd: Path, _output: str) -> str: - raise ValueError("Run each original LoopX command directly, outside the draft shell") - workspace_shell = VisionShellHost( - fixture.project_root, reject_nested_cli, turn_instance_id=state.turn_instance_id, - ) - resources.callback(workspace_shell.close) - state.workspace_shell_executed = True - output, exit_code = workspace_shell.execute(tool_call.command) - if exit_code: - raise _TerminalToolViolation("workspace_authoring_failed") - kind = "workspace_authoring" + output, kind, workspace_shell = _execute_terminal_workspace( + tool_call.command, state, workspace_shell, resources, + ) except (RuntimeError, ValueError, json.JSONDecodeError) as exc: failure_code = _terminal_failure_code(exc) From 0c68c10339c2a123e2a80bcbc766260c6b93e33e Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:00:08 +0800 Subject: [PATCH 05/10] fix(qualification): reject ambiguous fixture route arguments Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../terminal_settlement_tool_behavior.py | 5 +++++ .../test_terminal_settlement_tool_behavior.py | 18 +++++++++++++++--- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index 8ce95803b3..cb8a16000b 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -689,6 +689,11 @@ def _execute_cli(command: str, state: _QualificationState) -> dict[str, Any]: "--registry": {fixture.global_registry_path.resolve(), (fixture.project_root / ".loopx/registry.json").resolve()}, } + scoped = {*routes, "--goal-id", "--agent-id", "--todo-id", "--turn-instance-id", "--agent-vision-json"} + if any(token.partition("=")[1] and token.partition("=")[0] in scoped for token in tokens or []): + raise _TerminalToolViolation("nonliteral_fixture_argument") + if any((tokens or []).count(option) > 1 for option in scoped): + raise _TerminalToolViolation("duplicate_fixture_argument") guard_registry = argument_value(loopx_command_tokens(fixture.quota_guard_command) or [], "--registry") for option, allowed in routes.items(): supplied = argument_value(tokens or [], option) diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index e7bd864720..24307fa834 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -283,14 +283,24 @@ def test_terminal_fixture_requires_quota_before_reading_proof(tmp_path: Path) -> @pytest.mark.parametrize("option", ["--registry", "--runtime-root", "--project", "--state-file"]) -def test_terminal_fixture_rejects_foreign_routes(tmp_path: Path, option: str) -> None: +@pytest.mark.parametrize("spelling", ["separate", "inline", "duplicate"]) +def test_terminal_fixture_rejects_foreign_routes(tmp_path: Path, option: str, spelling: str) -> None: fixture = _build_fixture(tmp_path / "oracle") outside = tmp_path / "owner-state.json" outside.write_text("Owner state must remain unchanged.\n") def completion(request): tokens = shlex.split(_completion_action(request, kind="validation").command) - if option in tokens: + if spelling == "duplicate": + if option not in tokens: + tokens += [option, str(tmp_path / "actor/project")] + tokens += [option, str(outside)] + elif spelling == "inline": + if option in tokens: + index = tokens.index(option) + del tokens[index:index + 2] + tokens += [option + "=" + str(outside)] + elif option in tokens: tokens[tokens.index(option) + 1] = str(outside) else: tokens += [option, str(outside)] @@ -302,7 +312,9 @@ def completion(request): ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), completion, ]), ).qualify(qualification_id="foreign-route", fixture_root=tmp_path / "actor") - assert receipt["failure_code"] == "fixture_route_mismatch" + assert receipt["failure_code"] == {"separate": "fixture_route_mismatch", + "inline": "nonliteral_fixture_argument", + "duplicate": "duplicate_fixture_argument"}[spelling] assert receipt["qualification_passed"] is False assert receipt["settlement_receipt_steps"] == [] assert outside.read_text() == "Owner state must remain unchanged.\n" From a08e8891ebc954d10ef44345024ab74c0fd5e90c Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:10:08 +0800 Subject: [PATCH 06/10] fix(settlement): explain existing typed coverage observation requirements Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../model-behavior-qualification-v0.md | 4 +++ loopx/control_plane/quota/settlement_plan.ts | 3 +++ .../test_terminal_settlement_tool_behavior.py | 25 ++++++++++++++++--- 3 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index ac29e2e5fa..9198b7ae20 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -317,6 +317,10 @@ at a time; the draft shell cannot invoke LoopX. The original ten-call limit and all committed receipt checks remain. Explicit foreign routes or Turn identities fail rather than being repaired, and failure receipts retain fixture-owned codes rather than echoing CLI errors or model-authored JSON. +The shared plan also names the existing scope-input requirements for typed +`no_followup` and `exploration_exhausted` observations. A Todo's completion is +not itself evidence that a coverage scope is exhausted; the CLI still rejects +missing coverage inputs before writeback. For selected-Todo and terminal qualification, a standalone `cat` may read up to eight workspace-confined files, optionally diff --git a/loopx/control_plane/quota/settlement_plan.ts b/loopx/control_plane/quota/settlement_plan.ts index 8681ffc6eb..c66755d40c 100644 --- a/loopx/control_plane/quota/settlement_plan.ts +++ b/loopx/control_plane/quota/settlement_plan.ts @@ -29,6 +29,9 @@ export function turnScopedCliSettlementPlan(params: JsonObject): SettlementPlan "continue authorized work within existing limits or report a genuine typed blocker. " + "Set --delivery-boundary " + DELIVERY_BOUNDARIES.join("|") + " for the applicable case above. " + "Typed evidence: --progress-result-class " + PROGRESS_RESULT_CLASSES.join("|") + + ". For no_followup or exploration_exhausted, also pass --progress-coverage-scope-id; " + + "exploration_exhausted also needs --progress-coverage-complete. " + + "Todo completion alone does not establish scope coverage" + ". For blocked outcome_gap, --progress-work-item-id must match this plan's Todo/obligation id " + "and --progress-blocker-id names the blocker. Repeat --progress-evidence-id for evidence. " + "IDs are 1-128 characters, start with an ASCII letter/digit, then letters/digits or ._:/- " + diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index 24307fa834..418294ed1f 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -346,8 +346,13 @@ def failed_writeback(command, state): @pytest.mark.skipif(not shell_isolation_available(), reason="Draft authoring requires native OS isolation") -@pytest.mark.parametrize("draft_target", [".scratch/vision.json", "fixture/settlement-proof.json", "outside"]) -def test_terminal_native_draft_preserves_proof_and_authority(tmp_path: Path, draft_target: str) -> None: +@pytest.mark.parametrize(("draft_target", "coverage_observation"), [ + (".scratch/vision.json", False), (".scratch/vision.json", True), + ("fixture/settlement-proof.json", False), ("outside", False), +]) +def test_terminal_native_draft_preserves_proof_and_authority( + tmp_path: Path, draft_target: str, coverage_observation: bool, +) -> None: fixture = _build_fixture(tmp_path / "oracle") outside = tmp_path / "owner-private.json" outside.write_text("Owner artifact.\n") @@ -359,10 +364,22 @@ def test_terminal_native_draft_preserves_proof_and_authority(tmp_path: Path, dra "observed_reality": "The proof was read and original Todo validation committed.", "retained": ["Original validated delivery"], "evidence_refs": ["fixture-settlement-proof"]}, } + if coverage_observation: + vision["state"] = "no_followup" + vision["path_delta"]["outcome"] = "stop" + vision["path_delta"]["stopped"] = vision["path_delta"].pop("retained") def writeback(request): - return ScriptedExecToolAction(command=_writeback_action(request).command + - " --agent-vision-json .scratch/vision.json") + command = _writeback_action(request).command + " --agent-vision-json .scratch/vision.json" + if coverage_observation: + packet = _latest_quota_packet(request) + step = packet["interaction_contract"]["cli_channel"]["settlement_plan"]["ordered_steps"][1] + assert "--progress-coverage-scope-id" in step["precondition"] + assert "--progress-coverage-complete" in step["precondition"] + command += (" --progress-result-class no_followup" + " --progress-coverage-scope-id terminal-settlement-fixture" + " --progress-evidence-id fixture-settlement-proof") + return ScriptedExecToolAction(command=command) def completion(request): tokens = shlex.split(_completion_action(request, kind="validation").command) From 19843e124bcf9877698d5dee07ee1567d3d4ae3b Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:24:12 +0800 Subject: [PATCH 07/10] fix(qualification): return pure CLI input rejections within the original call budget Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- docs/reference/canonical-terminal-review.md | 4 +- .../canonical-terminal-review.zh-CN.md | 3 +- .../model-behavior-qualification-v0.md | 7 ++ .../cli_commands/project_lifecycle_inputs.py | 12 +++- .../terminal_settlement_tool_behavior.py | 7 ++ loopx/control_plane/todos/markdown.py | 4 ++ .../test_terminal_settlement_tool_behavior.py | 64 ++++++++++++++++--- 7 files changed, 88 insertions(+), 13 deletions(-) diff --git a/docs/reference/canonical-terminal-review.md b/docs/reference/canonical-terminal-review.md index 9a29abf580..8f382fd755 100644 --- a/docs/reference/canonical-terminal-review.md +++ b/docs/reference/canonical-terminal-review.md @@ -141,7 +141,9 @@ Successful Turn-bound ordinary completion returns verified settlement progress and, while writeback remains due, the existing same-identity settlement plan and next writeback command. That material-closeout plan includes the shared vision authoring schema; callers need not reconstruct identities or guess a JSON -format after completion. It grants no new execution or terminal authority. +format after completion. CLI Markdown shows the verified progress and next +writeback command; JSON carries the full plan and authoring schema. This grants +no new execution or terminal authority. The shared Todo summary keeps missing-successor diagnostics and counts, but its warning is review guidance, not an obligation to create a successor or terminate diff --git a/docs/reference/canonical-terminal-review.zh-CN.md b/docs/reference/canonical-terminal-review.zh-CN.md index 68f7a6058e..a54adfd794 100644 --- a/docs/reference/canonical-terminal-review.zh-CN.md +++ b/docs/reference/canonical-terminal-review.zh-CN.md @@ -107,7 +107,8 @@ Goal、Agent、Todo 和 Turn。只有当前契约允许最终范围收尾时， 带原 Turn 身份的普通完成成功后，返回已验证的结算进度；仍待写回时，一并返回 既有同身份结算计划和下一条写回命令。该语义收尾计划包含共享的 vision authoring -格式，调用者无需在完成后重建身份或猜测 JSON 结构；它不授予新的执行或终态权限。 +格式，调用者无需在完成后重建身份或猜测 JSON 结构。CLI Markdown 展示已验证进度和 +下一条写回命令，JSON 保留完整计划与 authoring 格式；它不授予新的执行或终态权限。 共享 Todo 摘要仍保留缺少后继的诊断和计数，但告警是复核引导，不要求制造后继或 终结已完成阶段。先复核剩余的授权 Goal 验收与可执行任务；范围内仍有工作时继续 diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index 9198b7ae20..6d6e00a9a9 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -309,6 +309,13 @@ writeback and spend receipts. Later receipts advance the original Turn's plan; they do not discard its identity-bound command templates. This follows the shared [quota-bound completion contract](../canonical-terminal-review.md#quota-bound-cli-completion) without changing the portfolio, repeats, contrasts or settlement order. +The refresh CLI's pure progress-input decoder identifies invalid argument +combinations before dispatch or authority writes. Its structured rejection is +returned to the same model, which may correct its input within the original +ten-call budget. Rejected calls remain counted and commit no settlement step; +the actor never retries a command or restarts a scenario automatically. Other +non-zero CLI results and fixture identity, route or ordering violations still +fail immediately; non-zero execution alone does not prove rollback. After the proof is read, a terminal actor may author a project draft in `.scratch/` using the existing OS-isolated shell. Original fixture inputs and authority stores remain protected; private host data and external networking diff --git a/loopx/cli_commands/project_lifecycle_inputs.py b/loopx/cli_commands/project_lifecycle_inputs.py index c2be3d66ea..e35c71d04d 100644 --- a/loopx/cli_commands/project_lifecycle_inputs.py +++ b/loopx/cli_commands/project_lifecycle_inputs.py @@ -24,6 +24,12 @@ } +class ProgressObservationArgumentError(ValueError): + """A pure argument rejection, before refresh dispatch or authority writes.""" + + code = "progress_observation_invalid_arguments" + + def split_explore_result_input(vision_packet, result_path, *, scope_context=None): """Transport explicit attachments; the capability owns validation/conflicts. @@ -100,12 +106,12 @@ def inline_progress_observation( if not any(value is not None for value in fields.values()) and not evidence_ids: return None if not fields["result_class"]: - raise ValueError("typed progress observation requires --progress-result-class") + raise ProgressObservationArgumentError("typed progress observation requires --progress-result-class") if fields["result_class"] in { ProgressResultClass.EXPLORATION_EXHAUSTED.value, ProgressResultClass.NO_FOLLOWUP.value, } and not fields["coverage_scope_id"]: - raise ValueError( + raise ProgressObservationArgumentError( f"--progress-result-class {fields['result_class']} requires " "--progress-coverage-scope-id" ) @@ -113,7 +119,7 @@ def inline_progress_observation( fields["result_class"] == ProgressResultClass.EXPLORATION_EXHAUSTED.value and fields["coverage_complete"] is not True ): - raise ValueError( + raise ProgressObservationArgumentError( "--progress-result-class exploration_exhausted requires " "--progress-coverage-complete" ) diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index cb8a16000b..7e846d62e1 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -718,6 +718,7 @@ def _execute_cli(command: str, state: _QualificationState) -> dict[str, Any]: "--registry": str(state.fixture.global_registry_path), "--turn-instance-id": state.turn_instance_id, }, + accepted_return_codes=(0, 1) if _command_path(tokens or [])[0] == "refresh_state" else (0,), ) payload = json.loads(output) if not isinstance(payload, dict): @@ -921,6 +922,12 @@ def _execute_terminal_cli( if not tokens or not _matches_identity(tokens, state): raise _TerminalToolViolation("writeback_identity_mismatch") payload = _execute_cli(command, state) + if (payload.get("ok") is False and payload.get("appended") is False + and payload.get("error_code") == "progress_observation_invalid_arguments"): + # Only the CLI's pure input decoder emits this code, before refresh + # dispatch. Give the same model its real tool error within the + # original call budget; do not retry or count a committed effect. + return json.dumps(payload, ensure_ascii=False, sort_keys=True), "progress_observation_invalid_arguments" receipt_steps = _settlement_receipt_steps(payload) if receipt_steps != _EXPECTED_RECEIPT_STEPS[:2]: raise _TerminalToolViolation("writeback_receipt_mismatch") diff --git a/loopx/control_plane/todos/markdown.py b/loopx/control_plane/todos/markdown.py index 5702c9cd4d..5b547812a3 100644 --- a/loopx/control_plane/todos/markdown.py +++ b/loopx/control_plane/todos/markdown.py @@ -4,6 +4,7 @@ import shlex from typing import Any +from ..quota.settlement import render_settlement_progress_markdown from .contract import TODO_STATUS_OPEN, todo_marker_for_status @@ -311,6 +312,9 @@ def render_todo_markdown(payload: dict[str, Any]) -> str: lines.extend(_render_settlement_plan(payload["settlement_plan"])) if not payload.get("error") and payload.get("execution_managed"): lines.extend(["", f"- claim_operation_id: `{payload['claim_operation_id']}`"]) + if not payload.get("error"): + lines.extend(render_settlement_progress_markdown(payload)) + if not payload.get("error") and (payload.get("execution_managed") or payload.get("settlement_progress")): for command in payload.get("next_cli_actions", []): lines.extend(["", "```sh", command, "```"]) correctness = payload.get("local_state_write_correctness") diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index 418294ed1f..7b8f5e5038 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -21,6 +21,7 @@ _build_fixture, ) from loopx.control_plane.testing.vision_shell_host import shell_isolation_available +from loopx.control_plane.todos.markdown import render_todo_markdown def _latest_quota_packet(request: Mapping[str, Any]) -> dict[str, Any]: @@ -216,6 +217,9 @@ def test_real_tool_loop_settles_final_todo_after_spend( assert writeback["vision_authoring"]["schema_version"] == "goal_vision_replan_contract_v0" assert completed["next_cli_actions"] == [writeback["command_template"]] assert completed["settlement_result"]["receipts"][0]["step_kind"] == "validation" + markdown = render_todo_markdown(completed) + assert "writeback_required" in markdown + assert completed["next_cli_actions"][0] in markdown @pytest.mark.parametrize( @@ -346,12 +350,13 @@ def failed_writeback(command, state): @pytest.mark.skipif(not shell_isolation_available(), reason="Draft authoring requires native OS isolation") -@pytest.mark.parametrize(("draft_target", "coverage_observation"), [ - (".scratch/vision.json", False), (".scratch/vision.json", True), - ("fixture/settlement-proof.json", False), ("outside", False), +@pytest.mark.parametrize(("draft_target", "coverage_observation", "correct_input"), [ + (".scratch/vision.json", False, False), (".scratch/vision.json", True, False), + (".scratch/vision.json", True, True), + ("fixture/settlement-proof.json", False, False), ("outside", False, False), ]) def test_terminal_native_draft_preserves_proof_and_authority( - tmp_path: Path, draft_target: str, coverage_observation: bool, + tmp_path: Path, draft_target: str, coverage_observation: bool, correct_input: bool, ) -> None: fixture = _build_fixture(tmp_path / "oracle") outside = tmp_path / "owner-private.json" @@ -369,16 +374,32 @@ def test_terminal_native_draft_preserves_proof_and_authority( vision["path_delta"]["outcome"] = "stop" vision["path_delta"]["stopped"] = vision["path_delta"].pop("retained") - def writeback(request): + def authority_files(): + root = tmp_path / "actor" + return {str(path.relative_to(root)): path.read_bytes() + for tree in (root / "runtime", root / "project/.codex", root / "project/.loopx", root / "home") + for path in tree.rglob("*") if path.is_file()} + + before_rejection = {} + + def writeback(request, *, omit_scope=False): + if correct_input and not omit_scope: + rejected = json.loads(request["messages"][-1]["content"]) + assert rejected["ok"] is False and rejected["appended"] is False + assert rejected["error_code"] == "progress_observation_invalid_arguments" + assert "--progress-coverage-scope-id" in rejected["error"] + assert authority_files() == before_rejection command = _writeback_action(request).command + " --agent-vision-json .scratch/vision.json" if coverage_observation: packet = _latest_quota_packet(request) step = packet["interaction_contract"]["cli_channel"]["settlement_plan"]["ordered_steps"][1] assert "--progress-coverage-scope-id" in step["precondition"] assert "--progress-coverage-complete" in step["precondition"] - command += (" --progress-result-class no_followup" - " --progress-coverage-scope-id terminal-settlement-fixture" - " --progress-evidence-id fixture-settlement-proof") + command += " --progress-result-class no_followup --progress-evidence-id fixture-settlement-proof" + if not omit_scope: + command += " --progress-coverage-scope-id terminal-settlement-fixture" + if omit_scope: + before_rejection.update(authority_files()) return ScriptedExecToolAction(command=command) def completion(request): @@ -393,6 +414,7 @@ def completion(request): completion, ScriptedExecToolAction(command="cat > " + shlex.quote(target) + " <<'JSON'\n" + json.dumps(vision) + "\nJSON"), + *([partial(writeback, omit_scope=True)] if correct_input else []), writeback, _spend_action, _completion_action, ]), ).qualify(qualification_id="native-terminal-draft", fixture_root=tmp_path / "actor") @@ -404,6 +426,32 @@ def completion(request): ) assert (tmp_path / "actor/project/fixture/settlement-proof.json").read_bytes() == fixture.proof_target.read_bytes() assert outside.read_text() == "Owner artifact.\n" + if correct_input: + assert receipt["tool_call_count"] == 8 + assert receipt["observed_tool_sequence"].count("progress_observation_invalid_arguments") == 1 + + +def test_terminal_input_rejections_do_not_reset_the_call_budget(tmp_path: Path) -> None: + fixture = _build_fixture(tmp_path / "oracle") + + def rejected_writeback(request): + return ScriptedExecToolAction(command=_writeback_action(request).command + + " --progress-result-class no_followup") + + transport = ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), + partial(_completion_action, kind="validation"), + *([rejected_writeback] * 7), + ]) + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=transport, + ).qualify(qualification_id="bounded-input-correction", fixture_root=tmp_path / "actor") + assert receipt["qualification_passed"] is False + assert receipt["failure_code"] == "tool_call_budget_exhausted" + assert receipt["tool_call_count"] == 10 + assert receipt["observed_tool_sequence"].count("progress_observation_invalid_arguments") == 7 + assert receipt["settlement_receipt_steps"] == ["validation"] def test_ordinary_completion_requires_its_actual_validation_receipt( From bab3acff3feca549292b685041af2ca6853ff2ac Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:35:38 +0800 Subject: [PATCH 08/10] fix(qualification): preserve failed CLI exit status despite committed JSON output Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../model-behavior-qualification-v0.md | 4 ++ .../testing/model_tool_behavior.py | 9 +++- .../terminal_settlement_tool_behavior.py | 33 ++++++++---- .../test_terminal_settlement_tool_behavior.py | 50 +++++++++++++++++++ 4 files changed, 84 insertions(+), 12 deletions(-) diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index 6d6e00a9a9..a2290a9093 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -316,6 +316,10 @@ ten-call budget. Rejected calls remain counted and commit no settlement step; the actor never retries a command or restarts a scenario automatically. Other non-zero CLI results and fixture identity, route or ordering violations still fail immediately; non-zero execution alone does not prove rollback. +The shared CLI transport retains the process exit code and transient stdout; +even a non-zero process that emitted valid committed-receipt JSON fails unless +it is that exact pre-dispatch input rejection. Raw stdout is never copied into +durable qualification receipts. After the proof is read, a terminal actor may author a project draft in `.scratch/` using the existing OS-isolated shell. Original fixture inputs and authority stores remain protected; private host data and external networking diff --git a/loopx/control_plane/testing/model_tool_behavior.py b/loopx/control_plane/testing/model_tool_behavior.py index 836ee061a3..4dedde4734 100644 --- a/loopx/control_plane/testing/model_tool_behavior.py +++ b/loopx/control_plane/testing/model_tool_behavior.py @@ -554,13 +554,18 @@ def execute_loopx_cli( bounded_detail = ( detail if len(detail) <= 1_000 else detail[:500] + "\n...\n" + detail[-500:] ) - raise LoopxCliExecutionError(completed.returncode, bounded_detail) + raise LoopxCliExecutionError( + completed.returncode, bounded_detail, stdout=completed.stdout, + ) return completed.stdout class LoopxCliExecutionError(RuntimeError): """An executed CLI returned nonzero; this does not imply state rollback.""" - def __init__(self, returncode: int, detail: str) -> None: + def __init__(self, returncode: int, detail: str, *, stdout: str = "") -> None: super().__init__(f"LoopX CLI command failed with exit={returncode}: {detail}") self.returncode = returncode + # Transient tool feedback only. Durable receipts must never serialize + # this raw output or infer rollback from the presence of valid JSON. + self.stdout = stdout diff --git a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py index 7e846d62e1..2afcfa995f 100644 --- a/loopx/control_plane/testing/terminal_settlement_tool_behavior.py +++ b/loopx/control_plane/testing/terminal_settlement_tool_behavior.py @@ -25,6 +25,7 @@ from .model_tool_behavior import ( DoubaoExecToolClient, QUOTA_FIRST_TOOL_INSTRUCTION, + LoopxCliExecutionError, argument_value, digest_text, execute_loopx_cli, @@ -710,16 +711,28 @@ def _execute_cli(command: str, state: _QualificationState) -> dict[str, Any]: raise _TerminalToolViolation("vision_draft_outside_workspace") if tokens and "--format" not in tokens: command = shlex.join([tokens[0], "--format", "json", *tokens[1:]]) - output = execute_loopx_cli( - command, - source_root=state.fixture.source_root, - project_root=state.fixture.project_root, - argument_overrides={ - "--registry": str(state.fixture.global_registry_path), - "--turn-instance-id": state.turn_instance_id, - }, - accepted_return_codes=(0, 1) if _command_path(tokens or [])[0] == "refresh_state" else (0,), - ) + try: + output = execute_loopx_cli( + command, + source_root=state.fixture.source_root, + project_root=state.fixture.project_root, + argument_overrides={ + "--registry": str(state.fixture.global_registry_path), + "--turn-instance-id": state.turn_instance_id, + }, + ) + except LoopxCliExecutionError as exc: + if exc.returncode != 1 or _command_path(tokens or [])[0] != "refresh_state": + raise + try: + rejected = json.loads(exc.stdout) + except (json.JSONDecodeError, TypeError): + raise exc from None + if not (isinstance(rejected, dict) and rejected.get("ok") is False + and rejected.get("appended") is False + and rejected.get("error_code") == "progress_observation_invalid_arguments"): + raise + return rejected payload = json.loads(output) if not isinstance(payload, dict): raise ValueError("LoopX command output must be an object") diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index 7b8f5e5038..d0394e9096 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -454,6 +454,56 @@ def rejected_writeback(request): assert receipt["settlement_receipt_steps"] == ["validation"] +@pytest.mark.parametrize("payload_ok", [False, True]) +def test_nonzero_after_actual_writeback_cannot_advance_to_spend( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, payload_ok: bool, +) -> None: + from loopx.control_plane.quota.settlement import read_heartbeat_settlement + from loopx.control_plane.testing import terminal_settlement_tool_behavior as terminal + from loopx.control_plane.testing.model_tool_behavior import LoopxCliExecutionError + + fixture = _build_fixture(tmp_path / "oracle") + execute = terminal.execute_loopx_cli + committed = {} + + def fail_after_writeback(command, **kwargs): + output = execute(command, **kwargs) + if "refresh-state" in command: + payload = json.loads(output) + assert payload["ok"] is True + committed.update(payload["settlement_identity"]) + # Inject only a post-effect process failure; the actual CLI above + # produced the independent writeback and committed receipt. + payload["ok"] = payload_ok + raise LoopxCliExecutionError(1, "synthetic post-effect failure", stdout=json.dumps(payload)) + return output + + monkeypatch.setattr(terminal, "execute_loopx_cli", fail_after_writeback) + transport = ScriptedDoubaoExecTransport([ + ScriptedExecToolAction(command=fixture.quota_guard_command), + ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), + partial(_completion_action, kind="validation"), _writeback_action, + _spend_action, _completion_action, + ]) + receipt = DoubaoTerminalSettlementToolBehaviorActor( + api_key="test-only-placeholder", transport=transport, + ).qualify(qualification_id="nonzero-after-writeback", fixture_root=tmp_path / "actor") + assert receipt["qualification_passed"] is False + assert receipt["failure_code"] == "tool_execution_failed" + assert receipt["tool_call_count"] == len(transport.requests) == 4 + assert receipt["settlement_receipt_steps"] == ["validation"] + assert "synthetic post-effect" not in json.dumps(receipt) + # Independent canonical readback proves that the failure did not roll back + # the real write; neither a debit nor terminal effect followed it. + readback = read_heartbeat_settlement( + tmp_path / "actor/runtime", goal_id=committed["goal_id"], + agent_id=committed["agent_id"], todo_id=committed["todo_id"], + turn_instance_id=committed["turn_instance_id"], + ) + assert readback is not None + assert readback.progress["next_step"] == "quota_spend" + + def test_ordinary_completion_requires_its_actual_validation_receipt( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, ) -> None: From f1f6f52b09bb0abab85559ed8d56c5355883eb15 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:38:52 +0800 Subject: [PATCH 09/10] test(qualification): inject failed process status after real CLI writeback Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../test_terminal_settlement_tool_behavior.py | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/tests/control_plane/test_terminal_settlement_tool_behavior.py b/tests/control_plane/test_terminal_settlement_tool_behavior.py index d0394e9096..3cfdc1115a 100644 --- a/tests/control_plane/test_terminal_settlement_tool_behavior.py +++ b/tests/control_plane/test_terminal_settlement_tool_behavior.py @@ -2,6 +2,7 @@ import json import shlex +import subprocess from collections.abc import Mapping from functools import partial from pathlib import Path @@ -459,26 +460,26 @@ def test_nonzero_after_actual_writeback_cannot_advance_to_spend( tmp_path: Path, monkeypatch: pytest.MonkeyPatch, payload_ok: bool, ) -> None: from loopx.control_plane.quota.settlement import read_heartbeat_settlement - from loopx.control_plane.testing import terminal_settlement_tool_behavior as terminal - from loopx.control_plane.testing.model_tool_behavior import LoopxCliExecutionError - fixture = _build_fixture(tmp_path / "oracle") - execute = terminal.execute_loopx_cli + execute = subprocess.run committed = {} - def fail_after_writeback(command, **kwargs): - output = execute(command, **kwargs) - if "refresh-state" in command: - payload = json.loads(output) + def fail_after_writeback(argv, *args, **kwargs): + completed = execute(argv, *args, **kwargs) + if isinstance(argv, list) and "loopx.cli" in argv and "refresh-state" in argv: + assert completed.returncode == 0 + payload = json.loads(completed.stdout) assert payload["ok"] is True committed.update(payload["settlement_identity"]) # Inject only a post-effect process failure; the actual CLI above # produced the independent writeback and committed receipt. payload["ok"] = payload_ok - raise LoopxCliExecutionError(1, "synthetic post-effect failure", stdout=json.dumps(payload)) - return output + return subprocess.CompletedProcess( + completed.args, 1, json.dumps(payload), "synthetic post-effect failure", + ) + return completed - monkeypatch.setattr(terminal, "execute_loopx_cli", fail_after_writeback) + monkeypatch.setattr(subprocess, "run", fail_after_writeback) transport = ScriptedDoubaoExecTransport([ ScriptedExecToolAction(command=fixture.quota_guard_command), ScriptedExecToolAction(command="cat fixture/settlement-proof.json"), From 61416f0223d3d484f74faee9df323ff652e0483c Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:42:13 +0800 Subject: [PATCH 10/10] docs(qualification): scope Turn refusal evidence after the initial guard Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../protocols/model-behavior-qualification-v0.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/protocols/model-behavior-qualification-v0.md b/docs/reference/protocols/model-behavior-qualification-v0.md index a2290a9093..2ce05f8e91 100644 --- a/docs/reference/protocols/model-behavior-qualification-v0.md +++ b/docs/reference/protocols/model-behavior-qualification-v0.md @@ -325,9 +325,12 @@ After the proof is read, a terminal actor may author a project draft in authority stores remain protected; private host data and external networking are unavailable. LoopX mutations still use one direct, identity-bound CLI call at a time; the draft shell cannot invoke LoopX. The original ten-call limit and -all committed receipt checks remain. Explicit foreign routes or Turn identities -fail rather than being repaired, and failure receipts retain fixture-owned -codes rather than echoing CLI errors or model-authored JSON. +all committed receipt checks remain. Explicit foreign routes fail rather than +being repaired. After the initial quota guard, completion, writeback and spend +must retain the fixture Turn. The initial guard's host Turn reference is rebound +by the existing CLI bridge; it is not a foreign-Turn refusal test. Failure +receipts retain fixture-owned codes rather than echoing CLI errors or +model-authored JSON. The shared plan also names the existing scope-input requirements for typed `no_followup` and `exploration_exhausted` observations. A Todo's completion is not itself evidence that a coverage scope is exhausted; the CLI still rejects