From 4e4ef3f701eb06436aa7cc37c347ae94e8c402c9 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:57:47 +0800 Subject: [PATCH] Capture C1 composition failures as receipt diagnostics Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- docs/reference/required-work-context.md | 9 ++ loopx/cli_commands/quota_failure_report.py | 24 +++-- loopx/cli_commands/quota_native_context.py | 2 + loopx/cli_commands/quota_presentation.py | 14 +-- loopx/cli_commands/quota_result_delivery.py | 1 - .../test_quota_decision_capture.py | 96 +++++++++++++++++-- 6 files changed, 122 insertions(+), 24 deletions(-) diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index ab659774ba..18b87360bc 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -503,6 +503,15 @@ cannot be combined with socket handoff. Ordinary callers keep their existing presentation, and context delivery off keeps its original pending Goal reads. Unbound staged replans retain their existing review-owned original Goal read. +If complete Turn composition fails after quota admission, the capture contains +the failure and original receipts for `quota context-read`. `quota context-project` +refuses the diagnostic capture. A saved diagnostic carries no executable input +or native claim source. Reconcile the original Turn receipt before recovery. + +中文:额度 guard 已准入、完整 Turn 组合随后失败时,capture 保留失败与原回执, +可通过 `quota context-read` 读回。`quota context-project` 会拒绝该诊断 +capture,活跃会话的认领来源保持原样。恢复前先核对原 Turn 回执。 + After a Host claim, the ready guard uses the private `--prepared-capture-reference` route. It publishes the complete decision and returns its writer digest with the fields needed to verify the same Todo and diff --git a/loopx/cli_commands/quota_failure_report.py b/loopx/cli_commands/quota_failure_report.py index dad6aceb8b..1de65a1b0b 100644 --- a/loopx/cli_commands/quota_failure_report.py +++ b/loopx/cli_commands/quota_failure_report.py @@ -499,19 +499,12 @@ def _bounded_quota_transport_failure( return result if _failure_output_size(result) <= limit else _compact_quota_failure() -def quota_decision_transport_failure_payload( +def quota_decision_transport_diagnostic( args: argparse.Namespace, committed: Mapping[str, object], error: Exception, - *, - capture_directory: Path | None, - capture_sha256: str | None = None, ) -> dict[str, object]: - """Report a post-guard failure with the original receipt and capture. - - The saved digest, when available, comes from publication rather than - reopening the path to establish a new identity. - """ + """Keep receipt evidence from a failed delivery without projecting work.""" typed_transport = isinstance(error, QuotaDecisionTransportError) reason = ( " ".join(str(error).split())[:500] if typed_transport @@ -539,6 +532,19 @@ def quota_decision_transport_failure_payload( if not typed_transport: failure["error_class"] = type(error).__name__ failure.update(verbose_debug_fields(error, verbose=bool(getattr(args, "verbose", False)))) + return failure + + +def quota_decision_transport_failure_payload( + args: argparse.Namespace, + committed: Mapping[str, object], + error: Exception, + *, + capture_directory: Path | None, + capture_sha256: str | None = None, +) -> dict[str, object]: + """Report the failure with the digest returned by the capture writer.""" + failure = quota_decision_transport_diagnostic(args, committed, error) limit = getattr(args, "max_page_output_bytes", None) if args.format == "json" else None reader = getattr(args, "_quota_failure_reader", None) if limit is not None: diff --git a/loopx/cli_commands/quota_native_context.py b/loopx/cli_commands/quota_native_context.py index 478882e7f7..412114fd25 100644 --- a/loopx/cli_commands/quota_native_context.py +++ b/loopx/cli_commands/quota_native_context.py @@ -111,6 +111,8 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str _validate_context_page_window(args.offset, args.page_bytes, output_limit) path, _, payload = _read_capture(args.capture_file, args.capture_sha256, private=hook_session is not None) + if payload.get("ok") is False: + raise ValueError("The saved capture is diagnostic. Read it with quota context-read.") identity = payload.get("agent_identity") receipt = payload.get("heartbeat_receipt") if (payload.get("ok") is not True or not isinstance(identity, dict) or not isinstance(receipt, dict) diff --git a/loopx/cli_commands/quota_presentation.py b/loopx/cli_commands/quota_presentation.py index 278ce35319..c4ff6a54dc 100644 --- a/loopx/cli_commands/quota_presentation.py +++ b/loopx/cli_commands/quota_presentation.py @@ -12,7 +12,6 @@ def compose_quota_work_contract(payload: dict[str, object], args: argparse.Namespace, *, scheduler_context: Mapping[str, object] | SchedulerExecutionContextResolution | None, capture_directory: Path | None, - native_context: bool, record_capture: Callable[[dict[str, object], str], None] | None = None) -> dict[str, object]: """Compose every decided should-run source once before capture and display.""" if args.quota_command != "should-run" or not isinstance(payload.get("interaction_contract"), Mapping): @@ -26,15 +25,16 @@ def compose_quota_work_contract(payload: dict[str, object], args: argparse.Names composed_settlement=True) except (EffectRuntimeRemoteError, EffectRuntimeStartupError) as exc: from .quota_capture import capture_decision + from .quota_failure_report import quota_decision_transport_diagnostic - # Admission already happened. Keep its source/receipt; never emit a - # false v1, discard the receipt or rerun the guard to recover context. + error = QuotaDecisionTransportError("Complete Turn context could not be composed.") + # Admission may be durable. Retain its receipts through the existing + # failure projection so saved-context readers cannot deliver the + # unsigned input or register it as a current native claim source. capture_decision( - capture_directory, payload, args=args, native_context=native_context, record_capture=record_capture, + capture_directory, quota_decision_transport_diagnostic(args, payload, error), record_capture=record_capture, ) - raise QuotaDecisionTransportError( - "Complete Turn context could not be composed. Read the saved original decision and receipt; do not rerun admission." - ) from exc + raise error from exc def project_scheduler_observation(payload: Mapping[str, object]) -> dict[str, object]: diff --git a/loopx/cli_commands/quota_result_delivery.py b/loopx/cli_commands/quota_result_delivery.py index 0054760a7b..ccad2d22f9 100644 --- a/loopx/cli_commands/quota_result_delivery.py +++ b/loopx/cli_commands/quota_result_delivery.py @@ -323,7 +323,6 @@ def _publish_quota_result( args, scheduler_context=scheduler_context, capture_directory=capture_directory, - native_context=native_context, record_capture=record_capture, ) captured_digest = capture_decision( diff --git a/tests/control_plane/test_quota_decision_capture.py b/tests/control_plane/test_quota_decision_capture.py index b397265326..dfdadc24bd 100644 --- a/tests/control_plane/test_quota_decision_capture.py +++ b/tests/control_plane/test_quota_decision_capture.py @@ -854,6 +854,87 @@ def test_refused_selection_handoff_is_typed_and_keeps_the_committed_capture(tmp_ assert _heartbeat_receipt_count(runtime, TURN_ID) >= 1 +@pytest.mark.parametrize('provider', ['file', 'sqlite']) +@pytest.mark.parametrize('delivery', ['off', 'on']) +def test_failed_complete_composition_captures_only_recovery_evidence( + tmp_path, monkeypatch, capsys, provider, delivery, +): + from loopx.cli import main + from loopx.control_plane.effect_runtime import EffectRuntimeStartupError + from loopx.control_plane.quota import turn_envelope + from loopx.control_plane.turn_driver import codex_context + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + from tests.control_plane.test_quota_settlement_cli import _spend_run_count + + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_fixture(tmp_path) + project = project.resolve() + monkeypatch.chdir(project) + state = _configure_read_only_todo(project) + mode = 'hard_lease' if delivery == 'on' else 'soft_claim' + initialize_canonical_source_fixture(runtime, GOAL_ID, state_path=state, provider=provider, handoff_mode=mode) + original_state = state.read_bytes() + capture, native = tmp_path / 'failure', tmp_path / 'native' + delivery_args = ['--codex-app', '--context-delivery', delivery] + if delivery == 'on': + native.mkdir(mode=0o700) + session = 'composition-failure-session' + monkeypatch.setenv('CODEX_THREAD_ID', session) + assert codex_context.codex_context_hook(str(native), { + 'session_id': session, 'cwd': str(project), 'hook_event_name': 'SessionStart', 'source': 'startup', + }) == {} + delivery_args += ['--codex-context-dir', str(native)] + native_before = {path.name: path.read_bytes() for path in native.glob('*') if path.is_file()} + binding = ['--goal-id', GOAL_ID, '--agent-id', AGENT_ID, '--turn-instance-id', TURN_ID] + captured = [] + run_typed = turn_envelope._turn_envelope_result + + def interrupt_compose(action, **kwargs): + if action == 'compose_complete': + captured.append(kwargs['payload']) + raise EffectRuntimeStartupError('fixture composition unavailable', diagnostic_code='fixture_unavailable') + return run_typed(action, **kwargs) + + with monkeypatch.context() as fault: + fault.setattr(turn_envelope, '_turn_envelope_result', interrupt_compose) + code = main(['--registry', str(registry), '--runtime-root', str(runtime), '--format', 'json', + 'quota', 'should-run', *binding, '--todo-id', TODO_ID, *delivery_args, '--decision-output-dir', str(capture)]) + failure = json.loads(capsys.readouterr().out) + assert code == 1 and failure['ok'] is False + assert failure['error_code'] == 'quota_decision_transport_failed' + assert len(captured) == 1 and captured[0]['ok'] is True + original_receipt = captured[0]['heartbeat_receipt'] + assert failure['heartbeat_receipt'] == original_receipt + assert original_receipt['settlement_identity']['todo_id'] == TODO_ID + if delivery == 'on': + assert captured[0]['execution_preparation']['state'] == 'claim_required' + before_readback = _heartbeat_receipt_count(runtime, TURN_ID) + assert before_readback == 1 + + saved = capture / 'decision.json' + reference = failure['captured_decision'] + assert saved.read_bytes() and reference['sha256'] == sha256(saved.read_bytes()).hexdigest() + code, projection = _run_cli(registry, runtime, 'quota', 'context-project', *binding, *delivery_args, + '--capture-file', reference['path'], '--capture-sha256', reference['sha256'], cwd=project) + assert code == 1 and projection['ok'] is False + assert 'diagnostic' in projection['reason'] + diagnostic = json.loads(saved.read_bytes()) + assert diagnostic['ok'] is False and diagnostic['should_run'] is False + assert 'interaction_contract' not in diagnostic and 'execution_preparation' not in diagnostic + assert diagnostic['heartbeat_receipt'] == original_receipt + reader = shlex.split(reference['command']) + code, page = _run_cli(registry, runtime, *reader[reader.index('quota'):], + '--select', '/heartbeat_receipt', cwd=project) + assert code == 0 and page['ok'] and page['eof'] + assert json.loads(page['content'])['selections'] == [ + {'pointer': '/heartbeat_receipt', 'value': original_receipt}, + ] + assert {path.name: path.read_bytes() for path in native.glob('*') if path.is_file()} == native_before + assert _heartbeat_receipt_count(runtime, TURN_ID) == before_readback + assert _spend_run_count(runtime) == 0 + assert state.read_bytes() == original_state + + @pytest.mark.parametrize('provider', ['file', 'sqlite']) @pytest.mark.parametrize('turn_envelope', [False, True]) def test_native_recovery_failure_keeps_original_receipt_and_capture( @@ -877,10 +958,7 @@ def test_native_recovery_failure_keeps_original_receipt_and_capture( def refuse_recovery(payload, **kwargs): saved = kwargs['capture_directory'] / 'decision.json' - attempts.append(saved.read_bytes()) - if turn_envelope: - assert payload['schema_version'] == 'loopx_turn_envelope_v0' - assert 'heartbeat_receipt' not in payload + attempts.append((payload, saved.read_bytes())) raise QuotaDecisionTransportError( 'Current context recovery could not be published or safely invalidated. ' 'Read the saved original decision/receipt; do not rerun admission.' @@ -900,15 +978,19 @@ def refuse_recovery(payload, **kwargs): assert code == 1 and failure['ok'] is False assert failure['error_code'] == 'quota_decision_transport_failed' assert failure['status'] == 'decision_transport_failed' + assert failure['reason'].startswith('Current context recovery could not be published') saved = list(captures.glob('*/decision.json')) assert len(saved) == len(attempts) == 1 - assert saved[0].read_bytes() == attempts[0] - original = json.loads(attempts[0]) + projected, raw = attempts[0] + assert saved[0].read_bytes() == raw + original = json.loads(raw) assert original['ok'] is True + assert projected['schema_version'] == original['schema_version'] == 'loopx_turn_envelope_v1' + assert projected['heartbeat_receipt'] == original['heartbeat_receipt'] assert failure['heartbeat_receipt'] == original['heartbeat_receipt'] assert failure['rollout_event'] == original['rollout_event'] assert failure['captured_decision']['path'] == str(saved[0]) - assert failure['captured_decision']['sha256'] == sha256(attempts[0]).hexdigest() + assert failure['captured_decision']['sha256'] == sha256(raw).hexdigest() assert _heartbeat_receipt_count(runtime, TURN_ID) == 1 assert _spend_run_count(runtime) == 0 assert state.read_bytes() == original_state