diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index 285f8b8838..7ccc94349b 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -529,10 +529,21 @@ readback for the original claim receipt, current lease and any verified ready capture without repeating the claim or guard. A Hook response alone does not prove delivery. For this session the repeat hint is suppressed after a tool read is verified against the recorded ready capture. -Follow the captured readiness check for the same Todo and Turn once the active -lease matches. An authorized retry of the same bound capture reuses its -managed claim operation, and the authority owner checks the original lease on -replay. The native session keeps the latest eligible live guard digest +If the hook has no recorded ready capture, its readback provides +`readiness_command` and `ready_context_command_template`. Run the readiness +command from the original workspace after the claim receipt and the active +lease match in Goal, Todo, owner, key and version. The same-Turn guard stages a +private capture separately from the active session journal. Require normal +delivery, the same Goal, Agent, Todo and Turn, and a ready lease proof with the +original key and version. Use the returned digest to fill the template from +that receipt. After staging, the native publisher checks the original claim +receipt and matching active lease under the same local writer lock used by +lease release and replacement. It holds that lock through the journal +commit. If the lease has retired, return the original receipt readback. +The original capture remains readable through `quota context-read`. +An authorized retry of the same bound capture reuses its managed claim +operation, and the authority owner checks the original lease on replay. +The native session keeps the latest eligible live guard digest separately from the capture. Presenting the exact saved decision preserves that binding. Older captures and copies with different bytes remain readable. Preserve any original claim receipt and use `quota should-run` with the same @@ -550,8 +561,14 @@ reader. Quota still checks ownership and lease expiry before reporting readiness 中文:私有原生日志在对绑定 capture 发起领取前先登记自动准备,并在投影前记录已校验的 ready capture。若就绪检查或 Hook 送达中断,Hook 可重复提供原领取回执、当前租约 及 ready capture 的回读入口,不再重复自动领取或准入。Hook 输出本身不足以确认送达。 -观察到针对原 ready capture 的已验证工具读取后,同会话才停止重复提示。活动租约匹配后, -沿同一 Todo 与 Turn 完成就绪检查。对同一绑定 capture 的授权重试复用原受管领取操作, +观察到针对原 ready capture 的已验证工具读取后,同会话才停止重复提示。Hook 尚未登记 +ready capture 时,回读会提供 `readiness_command` 和 `ready_context_command_template`。 +先核对原领取回执与活动租约的 Goal、Todo、归属、键和版本,再在原工作目录执行就绪命令。 +同轮检查会在活动会话日志以外生成私有 capture。确认允许正常交付、Goal、Agent、Todo +及 Turn 一致,且就绪的租约凭证与原键和版本匹配后,用返回的摘要填入同一回执的模板, +再读取校验通过的原生上下文。暂存完成后,发布端在租约释放和换代共用的本地写锁内核对 +原领取回执和当前活动租约,并持锁提交会话日志。租约已退役时提供原回执读回。 +原 capture 仍可通过 `quota context-read` 读取。对同一绑定 capture 的授权重试复用原受管领取操作, 由权威 owner 验证原租约。原生会话独立保存最新合格准入的摘要,重新展示逐字节一致的 快照会保留绑定。旧快照和字节不同的副本仍可读,保留已有领取回执。仍需准备时,用原 Goal、Agent、Todo 和 Turn 运行 `quota should-run`,生成新的 capture,再按当前准入 diff --git a/loopx/cli_commands/quota_native_context.py b/loopx/cli_commands/quota_native_context.py index 412114fd25..bfef3289c7 100644 --- a/loopx/cli_commands/quota_native_context.py +++ b/loopx/cli_commands/quota_native_context.py @@ -8,6 +8,8 @@ import subprocess import tempfile from collections.abc import Callable +from contextlib import AbstractContextManager, nullcontext +from functools import partial from pathlib import Path from typing import Any @@ -20,6 +22,11 @@ QuotaCommandValidationError, QuotaDecisionTransportError, ) +from ..control_plane.turn_driver.codex_execution_preparation import ( + NativeRecoveryLeaseUnavailable, + guard_native_recovery_publication, + require_native_recovery_lease, +) from ..control_plane.turn_driver.decision_capture import ( CONTEXT_CAPTURE_NAVIGATION_GUIDANCE, CONTEXT_CAPTURE_READ_GUIDANCE, @@ -46,13 +53,17 @@ def _saved_context_transport_failure( error: Exception, *, args: argparse.Namespace, receipt: dict[str, Any], recovery: dict[str, Any], reader_argv: list[str], source_unverified: bool = False, + authority_unverified: bool = False, ) -> dict[str, Any]: page_bytes, output_bytes = native_context_page_budget() limit = getattr(args, "max_page_output_bytes", None) if isinstance(limit, int) and limit > 0: output_bytes = min(output_bytes, limit) page_bytes = min(page_bytes, output_bytes) - if source_unverified: + if authority_unverified: + instruction = ("Read the original receipt with recovery.command. The saved capture remains readable, " + "but publishing ready work requires the original current lease.") + elif source_unverified: instruction = ( "The saved source could not be verified. Use recovery.command for diagnostic receipt readback. " "Restore an intact, supported capture and retry context-project with its original Goal, Agent, Turn " @@ -71,13 +82,20 @@ def _saved_context_transport_failure( "heartbeat_receipt": receipt, "capture_sha256": args.capture_sha256, "recovery": {**recovery, "command": context_capture_read_command( Path(recovery["path"]), recovery["sha256"], page_bytes=page_bytes, - max_page_output_bytes=output_bytes, list_fields=not source_unverified, - select=["/heartbeat_receipt"] if source_unverified else None, reader_argv=reader_argv)}, + max_page_output_bytes=output_bytes, list_fields=not (source_unverified or authority_unverified), + select=["/heartbeat_receipt"] if source_unverified or authority_unverified else None, + reader_argv=reader_argv)}, "instruction": instruction} -def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str | None = None) -> dict[str, Any]: - """Present an immutable already-decided quota capture, without authority IO. +def project_saved_context_capture( + args: argparse.Namespace, *, hook_session: str | None = None, + registry_path: Path | None = None, runtime_root_arg: str | None = None, +) -> dict[str, Any]: + """Present an immutable already-decided quota capture. + + Resumed Host preparation rechecks the original claim before publication. + Historical capture projection remains independent of live authority. Publication is delayed until this native tool runs, so the lifecycle owner can select its current continuity basis. Optional codec failure returns the @@ -93,6 +111,7 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str ) reader_argv = current_loopx_cli_argv() + prepared_claim = getattr(args, "prepared_claim_operation_id", None) try: activation = quota_capture.native_context_activation(args) saved_page = bool(getattr(args, "initial_read", False) or getattr(args, "select", None)) @@ -110,7 +129,7 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str if saved_page and args.page_bytes is not None: _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) + private=hook_session is not None or prepared_claim 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") @@ -133,6 +152,28 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str full_reference = dict(reference) version = payload.get("schema_version") complete = version == COMPLETE_TURN_DECISION_VERSION + publication_guard: Callable[[], AbstractContextManager[None]] = nullcontext + + def authority_refusal(error: Exception) -> dict[str, Any]: + return _saved_context_transport_failure(error, args=args, receipt=receipt, + recovery=full_reference, reader_argv=reader_argv, authority_unverified=True) + + if prepared_claim is not None: + from ..history import load_registry + from ..paths import resolve_runtime_root + + try: + if not complete or registry_path is None: + raise ValueError("Native readiness recovery requires a bound complete Turn.") + assert_complete_turn_decision(payload) + registry_path = registry_path.resolve() + runtime_root = resolve_runtime_root(load_registry(registry_path), runtime_root_arg).resolve() + require_native_recovery_lease(payload, claim_operation_id=prepared_claim, + registry_path=registry_path, runtime_root=runtime_root) + except (OSError, RuntimeError, ValueError, TypeError) as exc: + return authority_refusal(exc) + publication_guard = partial(guard_native_recovery_publication, payload, + claim_operation_id=prepared_claim, registry_path=registry_path, runtime_root=runtime_root) try: if not complete and not is_legacy_saved_quota_decision(payload): if activation["enabled"]: @@ -142,7 +183,7 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str goal_id=args.goal_id, agent_id=args.agent_id, capture_sha256=args.capture_sha256, hook_session=hook_session) raise QuotaDecisionTransportError("Unsupported saved quota decision version or mixed Turn binding.") - if complete and not activation["enabled"] and not activation["progressive_enabled"]: + if complete and prepared_claim is None and not activation["enabled"] and not activation["progressive_enabled"]: assert_complete_turn_decision(payload) except (QuotaDecisionTransportError, EffectRuntimeRemoteError, EffectRuntimeStartupError) as exc: return _saved_context_transport_failure(exc, args=args, receipt=receipt, @@ -173,10 +214,13 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str navigation = quota_capture.progressive_context_capture_view(payload, args, runtime_root=Path(getattr(args, "_context_delivery_machine_runtime", path.parent)), directory=None, reader_argv=reader_argv, captured_decision=captured_decision, page_attached=saved_page) - if saved_page: - return _saved_context_read_page(args, navigation, initial_reference=None, - initial_read_plan=None, output_limit=output_limit, reader_argv=reader_argv) - return navigation + with publication_guard(): + if saved_page: + return _saved_context_read_page(args, navigation, initial_reference=None, + initial_read_plan=None, output_limit=output_limit, reader_argv=reader_argv) + return navigation + except NativeRecoveryLeaseUnavailable as exc: + return authority_refusal(exc) except (QuotaDecisionTransportError, OSError, ValueError, EffectRuntimeRemoteError, EffectRuntimeStartupError) as exc: if complete: return _saved_context_transport_failure(exc, args=args, receipt=receipt, @@ -237,7 +281,7 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str progressive_enabled=activation["progressive_enabled"], selection_command_args_template=transport, captured_decision=captured_decision if activation["progressive_enabled"] and (args.initial_read or "sha256" in captured_decision) else None, - hook_session=hook_session, saved_capture=True) + hook_session=hook_session, saved_capture=True, publication_guard=publication_guard) projected = prepared.delivery initial_read_plan = prepared.initial_read_plan native_prepared = True @@ -262,6 +306,8 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str mode, target = native_view["mode"], native_view.get("target") initial_reference = native_view.get("first_read_reference") native_view = model_context_reference(native_view, reader_argv=reader_argv) + except NativeRecoveryLeaseUnavailable as exc: + return authority_refusal(exc) except (EffectRuntimeRemoteError, EffectRuntimeStartupError) as exc: if not complete: raise @@ -287,10 +333,14 @@ def project_saved_context_capture(args: argparse.Namespace, *, hook_session: str "instruction": "Presentation of the original decision only; authority and freshness are unchanged. " + (CONTEXT_CAPTURE_NAVIGATION_GUIDANCE if activation["enabled"] else CONTEXT_CAPTURE_READ_GUIDANCE)} navigation = native_view or result - if saved_page: - return _saved_context_read_page(args, navigation, initial_reference=initial_reference, - initial_read_plan=initial_read_plan, output_limit=output_limit, reader_argv=reader_argv) - return navigation + try: + with nullcontext() if native_prepared else publication_guard(): + if saved_page: + return _saved_context_read_page(args, navigation, initial_reference=initial_reference, + initial_read_plan=initial_read_plan, output_limit=output_limit, reader_argv=reader_argv) + return navigation + except NativeRecoveryLeaseUnavailable as exc: + return authority_refusal(exc) def _handle_context_config( @@ -372,6 +422,8 @@ def _handle_context_hook(args: argparse.Namespace, *, activation: dict[str, Any] and event.get("hook_event_name") in CONTEXT_LIFECYCLE_HOOKS): directory = codex_context_directory(directory=args.codex_context_dir, root=getattr(args, "codex_context_root", None), session=event.get("session_id"), create=True) + scenario = activation["scenario"] + progressive_enabled = activation["progressive_enabled"] payload = codex_context_hook(directory, event) request = None preparation_context = "" @@ -383,15 +435,19 @@ def _handle_context_hook(args: argparse.Namespace, *, activation: dict[str, Any] if "claim_source_sha256" not in request or not request.get("turn_instance_id"): raise LegacyNativePreparationCapture() if request.get("readback_only") is True: - preparation_context = codex_execution_preparation_readback_context(request) or "" + preparation_context = codex_execution_preparation_readback_context( + request, scenario=scenario, context_directory=directory, + progressive_enabled=progressive_enabled, + ) or "" else: capture = Path(tempfile.mkdtemp(prefix="prepared-", dir=directory)) / "ready" receipt = execute_codex_execution_preparation( request, cwd=workspace.resolve(), - scenario=activation["scenario"], + scenario=scenario, capture_directory=capture, context_directory=Path(directory), + progressive_enabled=progressive_enabled, ) record_native_execution_preparation( directory, @@ -434,7 +490,10 @@ def _handle_context_hook(args: argparse.Namespace, *, activation: dict[str, Any] directory, event, readback_for=request["source_sha256"], ) if readback is not None: - preparation_context = codex_execution_preparation_readback_context(readback) or "" + preparation_context = codex_execution_preparation_readback_context( + readback, scenario=scenario, context_directory=directory, + progressive_enabled=progressive_enabled, + ) or "" if preparation_context: existing = payload.get("hookSpecificOutput") existing_context = str(existing.get("additionalContext") or "") if isinstance(existing, dict) else "" @@ -455,6 +514,10 @@ def handle_native_context_command(args: argparse.Namespace, *, print_payload: Ca """Dispatch captured reads and native lifecycle IO before quota authority access.""" from . import quota_capture + if getattr(args, "prepared_claim_operation_id", None) is not None and args.quota_command != "context-project": + print_payload({"ok": False, "reason": "--prepared-claim-operation-id requires quota context-project"}, + args.format, str) + return 1 if getattr(args, "complete_turn", False) and (args.quota_command != "should-run" or args.format != "json"): print_payload({"ok": False, "reason": "--complete-turn requires JSON quota should-run"}, args.format, str) return 1 @@ -540,7 +603,7 @@ def handle_native_context_command(args: argparse.Namespace, *, print_payload: Ca ) return _handle_context_hook(args, activation=activation) if args.quota_command == "context-project": - payload = project_saved_context_capture(args) + payload = project_saved_context_capture(args, registry_path=registry_path, runtime_root_arg=runtime_root_arg) print_payload(payload, args.format, lambda value: str(value.get("command", value.get("reason", "")))) return 0 if payload["ok"] else 1 if args.quota_command == "context-read": diff --git a/loopx/cli_commands/quota_registration.py b/loopx/cli_commands/quota_registration.py index fb37037076..d1fec55ce8 100644 --- a/loopx/cli_commands/quota_registration.py +++ b/loopx/cli_commands/quota_registration.py @@ -253,6 +253,7 @@ def register_quota_command( # immutable view after the model's lifecycle hooks establish continuity. quota_parser.add_argument("--defer-context-presentation", action="store_true", help=argparse.SUPPRESS) quota_parser.add_argument("--prepared-capture-reference", action="store_true", help=argparse.SUPPRESS) + quota_parser.add_argument("--prepared-claim-operation-id", help=argparse.SUPPRESS) from ..control_plane.turn_driver.codex_context import CONTEXT_DELIVERY_SETTINGS, DELTA_DELIVERY_SETTINGS quota_parser.add_argument("--context-delivery", choices=CONTEXT_DELIVERY_SETTINGS, diff --git a/loopx/control_plane/turn_driver/codex_context.py b/loopx/control_plane/turn_driver/codex_context.py index cb05180d90..21e33244c3 100644 --- a/loopx/control_plane/turn_driver/codex_context.py +++ b/loopx/control_plane/turn_driver/codex_context.py @@ -6,8 +6,8 @@ """ from __future__ import annotations -from contextlib import contextmanager -from collections.abc import Iterator, Mapping +from contextlib import AbstractContextManager, contextmanager, nullcontext +from collections.abc import Callable, Iterator, Mapping from dataclasses import dataclass from typing import Any import json @@ -911,7 +911,9 @@ def prepare_codex_context(payload: dict[str, Any], *, directory: str | None, cap selection_command_args_template: str | None = None, captured_decision: dict[str, str] | None = None, hook_session: str | None = None, - saved_capture: bool = False) -> NativeContextPreparation: + saved_capture: bool = False, + publication_guard: Callable[[], AbstractContextManager[None]] = nullcontext, + ) -> NativeContextPreparation: """Commit current recovery before optional projection or candidate updates. Serialization prevents invalidation from moving the epoch during preparation. @@ -943,7 +945,8 @@ def prepare_codex_context(payload: dict[str, Any], *, directory: str | None, cap or (native_session and session != native_session)): if check_saved_source: assert_complete_turn_decision(payload) - return NativeContextPreparation(payload) # Do not replace another session's recovery. + with publication_guard(): + return NativeContextPreparation(payload) # Do not replace another session's recovery. # Native lifecycle events own workspace identity and epoch. # A shell tool may run in another checkout without changing # the host session or losing its previously delivered context. @@ -1016,12 +1019,13 @@ def publish_recovery(reference: dict[str, Any]) -> None: filename="required-context.json", read_guidance=CONTEXT_CAPTURE_PAGE_GUIDANCE) if check_saved_source: state.pop("candidate", None) - if check_saved_source or projected: - publish_recovery(recovery) result: dict[str, Any] = transaction["delivery"] if presentation else transaction result["recovery"] = recovery - read_plan = _record_native_delivery(root, state, result, transaction, request, - directory=directory, progressive=progressive) + with publication_guard(): + if check_saved_source or projected: + publish_recovery(recovery) + read_plan = _record_native_delivery(root, state, result, transaction, request, + directory=directory, progressive=progressive) return NativeContextPreparation(result, read_plan) except (OSError, ValueError, KeyError, TypeError, RecursionError) as exc: if check_saved_source: diff --git a/loopx/control_plane/turn_driver/codex_execution_preparation.py b/loopx/control_plane/turn_driver/codex_execution_preparation.py index 2594a73fcb..7375ead06b 100644 --- a/loopx/control_plane/turn_driver/codex_execution_preparation.py +++ b/loopx/control_plane/turn_driver/codex_execution_preparation.py @@ -9,10 +9,12 @@ import json import shlex import subprocess -from collections.abc import Callable, Mapping, Sequence +from collections.abc import Callable, Iterator, Mapping, Sequence +from contextlib import ExitStack, contextmanager from pathlib import Path from time import monotonic from typing import Any, TYPE_CHECKING +from uuid import uuid4 if TYPE_CHECKING: from ..quota.effect_program import SettlementIdentity @@ -36,6 +38,10 @@ def __init__(self) -> None: ) +class NativeRecoveryLeaseUnavailable(RuntimeError): + """The original lease could not authorize recovery publication.""" + + def compact_execution_preparation_request( payload: Mapping[str, Any], *, claim_source_sha256: str | None = None, ) -> dict[str, Any] | None: @@ -369,12 +375,123 @@ def _native_claim_operation_id(request: Mapping[str, Any]) -> str: return f"todo-claim:codex-capture:{digest}" -def codex_execution_preparation_readback_context(request: Mapping[str, Any]) -> str | None: - """Expose only existing receipt, lease and ready-capture readers after an interrupted preparation.""" +def _native_context_argv(scenario: str, directory: Path, *, progressive_enabled: bool) -> list[str]: + return [ + *(["--codex-app"] if scenario == "codex_app_heartbeat" else ["--runtime-profile", scenario]), + *(["--context-delivery", "on"] if progressive_enabled else + ["--context-delivery", "off", "--delta-delivery", "auto"]), + "--codex-context-dir", str(directory), + ] + + +def _native_readiness_guard( + goal: str, agent: str, todo: str, turn: str, *, context_argv: Sequence[str], +) -> list[str]: + return [ + "quota", "should-run", "--goal-id", goal, "--agent-id", agent, + *context_argv, "--defer-context-presentation", + "--todo-id", todo, "--turn-instance-id", turn, + ] + + + +def require_native_recovery_lease( + payload: Mapping[str, Any], *, claim_operation_id: str, + registry_path: Path, runtime_root: Path, +) -> None: + """Read the original claim and its current lease before publishing ready context.""" + from ..coordination.local_authority import local_authority_is_promoted + from ..effect_runtime import CANONICAL_AUTHORITY_READ_TIMEOUT_SECONDS, effect_runtime_result + from ..work_items.task_lease import inspect_task_lease + + goal = payload.get("goal_id") + preparation = payload.get("execution_preparation") + if (not isinstance(preparation, Mapping) or payload.get("normal_delivery_allowed") is not True + or preparation.get("schema_version") != "execution_preparation_v0" + or preparation.get("state") != "ready" or preparation.get("delivery_allowed") is not True + or not _exact_identity(goal) + or payload.get("registry") != str(registry_path) + or payload.get("runtime_root") != str(runtime_root) + or not claim_operation_id.startswith("todo-claim:codex-capture:") + or not BARE_SHA256_PATTERN.fullmatch(claim_operation_id.removeprefix("todo-claim:codex-capture:"))): + raise ValueError("Native readiness recovery requires the original bound claim.") + + agent, todo = preparation.get("agent_id"), preparation.get("todo_id") + proof = preparation.get("lease_proof") + if (preparation.get("handoff_mode") != "hard_lease" + or not all(_exact_identity(part) for part in (agent, todo)) + or not isinstance(proof, Mapping) + or not _exact_identity(proof.get("idempotency_key")) + or type(proof.get("expected_version")) is not int + or not local_authority_is_promoted(runtime_root=runtime_root, goal_id=goal)): + raise ValueError("Native readiness recovery requires an authoritative lease proof.") + + def matches(lease: object) -> bool: + return (isinstance(lease, Mapping) + and lease.get("status") == "active" + and (lease.get("goal_id"), lease.get("todo_id"), lease.get("owner")) == (goal, todo, agent) + and lease.get("idempotency_key") == proof["idempotency_key"] + and lease.get("version") == proof["expected_version"]) + + original = effect_runtime_result("coordination.local_authority.operation_receipt", { + "schema_version": "loopx_local_coordination_operation_receipt_request_v0", + "runtime_root": str(runtime_root), "goal_id": goal, "operation_id": claim_operation_id, + }, timeout=CANONICAL_AUTHORITY_READ_TIMEOUT_SECONDS) + records = original.get("receipts") if isinstance(original, Mapping) and original.get("status") == "found" else None + record = records[0] if isinstance(records, list) and len(records) == 1 else None + result = record.get("result") if isinstance(record, Mapping) else None + if (not isinstance(result, Mapping) + or record.get("schema_version") != "loopx_coordination_todo_claim_receipt_v0" + or record.get("goal_id") != goal or record.get("operation_id") != claim_operation_id + or result.get("claim_operation_id") != claim_operation_id + or result.get("execution_managed") is not True + or not matches(result.get("lease"))): + raise ValueError("Saved readiness does not match the original claim receipt.") + + current = inspect_task_lease(registry_path=registry_path, runtime_root=runtime_root, goal_id=goal, todo_id=todo) + if current.get("active") is not True or not matches(current.get("lease")): + raise ValueError("The original task lease is no longer current for native readiness recovery.") + + +@contextmanager +def guard_native_recovery_publication( + payload: Mapping[str, Any], *, claim_operation_id: str, + registry_path: Path, runtime_root: Path, +) -> Iterator[None]: + """Serialize the local journal commit with the canonical lease writer.""" + from ...file_lock import exclusive_mutation_file_lock + from ..coordination.shadow_management import ( + require_shadow_primary_write_allowed, + shadow_maintenance_lock_target, + ) + + goal = payload["goal_id"] + with ExitStack() as locks: + try: + locks.enter_context(exclusive_mutation_file_lock( + shadow_maintenance_lock_target(runtime_root, goal), + operation="native-recovery-publication", + )) + require_shadow_primary_write_allowed(runtime_root, goal) + require_native_recovery_lease( + payload, claim_operation_id=claim_operation_id, + registry_path=registry_path, runtime_root=runtime_root, + ) + except (OSError, RuntimeError, ValueError, TypeError) as exc: + raise NativeRecoveryLeaseUnavailable(str(exc)) from exc + yield + + +def codex_execution_preparation_readback_context( + request: Mapping[str, Any], *, scenario: str, context_directory: str | None, progressive_enabled: bool, +) -> str | None: + """Expose the original receipt and the continuation for its exact native Turn.""" goal, agent, todo, turn = (request.get(key) for key in ("goal_id", "agent_id", "todo_id", "turn_instance_id")) route = request.get("authority_route") - if not isinstance(route, Mapping) or not all( - isinstance(part, str) and part for part in (goal, agent, todo, turn) + if ( + not isinstance(route, Mapping) + or not all(_exact_identity(part) for part in (goal, agent, todo, turn)) + or normalize_turn_instance_id(turn) != turn ): return None registry_path, runtime_root = route.get("registry_path"), route.get("runtime_root") @@ -392,7 +509,42 @@ def codex_execution_preparation_readback_context(request: Mapping[str, Any]) -> "receipt_command": shlex.join([*base, "todo", "receipt", "--goal-id", goal, "--operation-id", operation_id]), "lease_command": shlex.join([*base, "task-lease", "inspect", "--goal-id", goal, "--todo-id", todo]), } + guidance = ( + "If a verified ready capture is available, follow its recovery command after matching the original active lease. " + "The ready projection checks the current lease before delivery. Follow its reader after success. " + ) ready_capture = request.get("ready_capture") + if ( + ready_capture is None + and request.get("readback_only") is True + and scenario in {"codex_app_heartbeat", "codex_app_ssh_goal"} + and context_directory is not None + and (session_directory := Path(context_directory)).is_absolute() + and operation_id == _native_claim_operation_id(request) + ): + # A lost readiness result must not replace the live session's claim + # source if the fresh guard finds a retired lease or a different gate. + # The existing capture writer creates this private staging directory. + staged = session_directory / f"readiness-{uuid4().hex}" + guard_context = _native_context_argv(scenario, staged, progressive_enabled=progressive_enabled) + facts["readiness_command"] = shlex.join([ + *base, *_native_readiness_guard(goal, agent, todo, turn, context_argv=guard_context), + "--decision-output-dir", str(staged), "--prepared-capture-reference", + ]) + facts["ready_context_command_template"] = shlex.join([ + *base, "quota", "context-project", "--goal-id", goal, "--agent-id", agent, + "--turn-instance-id", turn, "--capture-file", str(staged / "decision.json"), + "--capture-sha256", "", "--prepared-claim-operation-id", operation_id, + *_native_context_argv(scenario, session_directory, progressive_enabled=progressive_enabled), + ]) + guidance = ( + "Run readiness_command once from the original workspace after the original claim and active lease " + "match in Goal, Todo, owner, key and version. Require normal_delivery_allowed=true and " + "execution_preparation.state=ready for this same Goal, Agent, Todo and Turn, with lease_proof " + "matching the original key and version. Only then substitute the returned capture_sha256 for " + " in this receipt's ready_context_command_template. The projection rechecks the lease. " + "Follow the returned reader before work. " + ) if isinstance(ready_capture, Mapping): ready_path = ready_capture.get("path") ready_sha256 = ready_capture.get("sha256") @@ -421,6 +573,7 @@ def codex_execution_preparation_readback_context(request: Mapping[str, Any]) -> *base, "quota", "context-project", "--capture-file", str(path), "--capture-sha256", ready_sha256, "--goal-id", goal, "--agent-id", agent, "--turn-instance-id", turn, "--context-delivery", "off", "--delta-delivery", "off", + "--prepared-claim-operation-id", operation_id, ]) facts["capture_sha256"] = ready_sha256 facts["context"] = { @@ -430,8 +583,7 @@ def codex_execution_preparation_readback_context(request: Mapping[str, Any]) -> return ( "Automatic preparation started for this captured Turn and may still be finishing. " "Read the original claim receipt and current lease before deciding how to recover. " - "With the matching active lease, follow the current captured same-Todo and same-Turn readiness check before work. " - "If the recovery command returns a projection, follow its reader after the projection succeeds. " + f"{guidance}" "For an authorized retry of this claim, pass the original --claim-operation-id. " "A retired lease requires a fresh eligible capture. " "Receipt: " + json.dumps(facts, ensure_ascii=False, separators=(",", ":")) @@ -445,6 +597,7 @@ def execute_codex_execution_preparation( scenario: str, capture_directory: Path, context_directory: Path, + progressive_enabled: bool = True, timeout: float = 8, runner: CommandRunner | None = None, ) -> dict[str, Any]: @@ -517,13 +670,10 @@ def execute_codex_execution_preparation( if claim_reference != claim_operation_id: raise RuntimeError("Native execution preparation did not recover its original managed claim") guard = [ - "quota", "should-run", - "--goal-id", goal_id, - "--agent-id", agent_id, - *( ["--codex-app"] if scenario == "codex_app_heartbeat" else - ["--runtime-profile", "codex_app_ssh_goal"] ), - "--context-delivery", "on", "--codex-context-dir", str(context_directory), "--defer-context-presentation", - "--todo-id", todo_id, "--turn-instance-id", turn_instance_id, + *_native_readiness_guard( + goal_id, agent_id, todo_id, turn_instance_id, + context_argv=_native_context_argv(scenario, context_directory, progressive_enabled=progressive_enabled), + ), "--decision-output-dir", str(capture_directory), "--prepared-capture-reference", ] # Reserve time for readiness and give it the time the claim left unused. diff --git a/skills/loopx-self-repair/references/repair-patterns.md b/skills/loopx-self-repair/references/repair-patterns.md index e090cd6108..8c05e75f6d 100644 --- a/skills/loopx-self-repair/references/repair-patterns.md +++ b/skills/loopx-self-repair/references/repair-patterns.md @@ -16,6 +16,7 @@ teaches a reusable control-plane lesson. | `typed_adapter_validation_scope_mismatch` | A local adapter type check passes while the same CI entry reports a large legacy dependency error set. | Exact source revisions, configured roots, cold same-environment runs, installation/import paths, and original-root plus adapter counterfactuals. | Adding runtime adapters to a kernel root list expands its import closure; an extra source path can mask that traversal locally. | Preserve the existing kernel gate and its import behavior. Make the additive adapter boundary explicit, retain imported-code debt as unqualified, and prove strict root checking with original diagnostics and core/adapter mutations in an unmasked source installation. Do not globally disable import checks, remove original roots or rewrite historical failures as passes. | | `saved_projection_goal_route_coupling` | A saved context projection fails on conflicting default runtime roots even with native transport disabled, while the same capture remains readable. | Run the shipped projection and returned reader against one digest-bound synthetic capture, with implicit, missing and global registry selectors; retain digest/identity refusals and unchanged runtime snapshots. | Shared CLI registry discovery runs before the saved-view owner validates its source. | Classify the saved presentation at the existing CLI route owner; preserve machine-configuration routing, live authority conflict checks and source/session validation. Reuse the registry-independence integration tests rather than adding a second recovery path or repairing live state. | | `unverified_saved_context_recovery` | A saved complete Turn fails projection validation, but recovery guidance directs the Host to its body or the preceding Turn. | With a matching outer file digest, test each rejected version or inner binding after publishing a preceding Turn. Check implicit lookup and the compact hook before the next attempt, then follow the receipt-only diagnostic and compare the quota ledger. | A pre-verification rejection uses generic recovery or returns before retiring the native lookup. | Retire the same session, Goal and Agent lookup under the native journal lock. Direct the Host to the original receipt and preserve explicit capture reads, verified presentation fallback and legacy behavior. | +| `native_preparation_missing_readiness_route` | A native Hook returns `host_execution_preparation_readback_required` after a claim, with commands for the receipt and lease but no ready capture or readiness command. | Compare the original claim result and active lease on the same Goal and Todo. Use the exact Turn and native profile. In File and SQLite fixtures, interrupt readiness after the ordinary claim and also test releasing the lease before recovery. | The Hook preserved the original mutation but left the Host to reconstruct the continuation. | Expose the existing same-Turn guard with private staging outside the active session lookup. Match the ready lease proof to the original receipt before presenting the digest-bound capture. Verify its settlement identity, original claim receipt and zero additional debit. | | `native_reader_program_route_loss` | A native producer or read uses a selected CLI or interpreter, but returned navigation, continuation or recovery invokes another runtime. | Actual lifecycle capture, generated first-read and recovery instructions, unchanged execution of emitted commands with an isolated competing program, complete source/digest readback and installed-package provenance. | A presentation layer used its generic command-renderer default after the caller had already selected the runtime. | Pass the current program argv through existing CLI, navigation, bounded-result and reader renderers; retain constructor defaults and shell quoting. Include emitted command metadata in native byte-cost estimates. Cover cold guard and saved-context projection before direct first reads, raw/selected/index pagination, quoted aliases, refusal details and source-state immutability through real CLI and isolated wheel entrypoints. Routing preserves the selected program; it does not pin an installation version or prove Host adoption. | | `host_bridge_reader_orphan` | A rejected bridge observation leaves its reader thread and output pipe alive after the child has exited. | Original framing error, cleanup result, child exit, bounded-queue backpressure and reader/pipe state across repeated failures. | Cancellation rejects another malformed frame; the sole consumer leaves while the producer blocks on a full queue, and joining alone cannot release it. | Stop publication, release the waiting producer, join and close through the existing transport helper. Retain cleanup-unconfirmed results and original Host drain ownership; reclaiming a reader does not prove Host exit. Cover malformed JSON and invalid typed observations with real subprocesses, plus existing real Host cancellation and success paths. Do not increase timeouts or fabricate a successful result. | | `codex_strict_result_schema_gap` | A Codex Turn fails with invalid_json_schema before execution, or a strict-schema stop result fails internal evidence validation. | Generated Codex schema, required properties, unsupported conditional keywords, and both CLI/app-server result boundaries. | Optional evidence and conditional schema requirements conflict with strict Structured Outputs; internal stop results prohibit evidence fields. | Require nullable evidence fields on the Codex wire and remove unsupported conditionals. Normalize only stop null placeholders in both Codex transports; reject missing/null profile material evidence and preserve non-null evidence for the existing validator. Cover legacy absence, invalid arrays and an isolated schema-acceptance probe without changing other hosts. | diff --git a/tests/control_plane/test_quota_execution_preparation.py b/tests/control_plane/test_quota_execution_preparation.py index 1d1f0f3a6f..faae79e1e2 100644 --- a/tests/control_plane/test_quota_execution_preparation.py +++ b/tests/control_plane/test_quota_execution_preparation.py @@ -657,6 +657,10 @@ def hook(tool_response=None): "same-execution", "released-execution", "after-ready-same-execution", "after-ready-released-execution", "legacy-same-execution", "legacy-released-execution", "reencoded-released-execution", "legacy-marked-released-execution", + "ssh-same-execution", "delta-only-same-execution", + "released-at-delivery", "ssh-released-at-delivery", "delta-released-at-delivery", "replaced-at-delivery", + "released-during-staging", "ssh-released-during-staging", "delta-released-during-staging", + "replaced-during-staging", ]) def test_native_hook_replays_the_original_claim_after_guard_timeout( tmp_path, monkeypatch, capsys, provider, case, @@ -664,6 +668,8 @@ def test_native_hook_replays_the_original_claim_after_guard_timeout( import io from loopx.cli import main from loopx.control_plane.turn_driver import codex_context, codex_execution_preparation + from tests.control_plane.codex_checkpoint_fixture import selected_context_values + from test_quota_settlement_cli import _spend_run_count tmp_path = tmp_path.resolve() monkeypatch.chdir(tmp_path) @@ -677,15 +683,23 @@ def test_native_hook_replays_the_original_claim_after_guard_timeout( capture = tmp_path / "before-claim" legacy = case.startswith("legacy-") after_ready = case.startswith("after-ready-") - released = not case.endswith("same-execution") + retire_during_staging = case.endswith("-during-staging") + retire_at_delivery = case.endswith("-at-delivery") + refuse_delivery = retire_at_delivery or retire_during_staging + released = not case.endswith("same-execution") and not refuse_delivery + scenario = "codex_app_ssh_goal" if case.startswith("ssh-") else "codex_app_heartbeat" + host = ("--runtime-profile", scenario) + delivery = ("--context-delivery", "off", "--delta-delivery", "auto") if case.startswith("delta-") else ( + "--context-delivery", "on", + ) native_args = () if legacy else ("--defer-context-presentation", "--codex-context-dir", str(native)) - before = _run(tmp_path, monkeypatch, provider, [], "--codex-app", + before = _run(tmp_path, monkeypatch, provider, [], *host, "--turn-instance-id", turn, "--todo-id", TODO, "--decision-output-dir", str(capture), - *native_args, context_delivery="off" if legacy else "on") + *native_args, *delivery[2:], context_delivery="off" if legacy else delivery[1]) assert before["execution_preparation"]["state"] == "claim_required" source = capture / "decision.json" original_bytes = source.read_bytes() - digest = _present_saved_guard(tmp_path, native, capture, "codex_app_heartbeat", turn) + digest = _present_saved_guard(tmp_path, native, capture, scenario, turn) run = codex_execution_preparation._default_runner record_ready = codex_context.record_native_execution_preparation @@ -712,11 +726,11 @@ def interrupt_after_ready(*args, **kwargs): monkeypatch.setattr(codex_context, "record_native_execution_preparation", interrupt_after_ready) registry, runtime = tmp_path / "registry.json", tmp_path / "runtime" command = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json", - "quota", "context-hook", "--codex-app", "--context-delivery", "on", + "quota", "context-hook", *host, *delivery, "--codex-context-dir", str(native)] - def hook(name="PostToolUse"): - data = json.dumps({**event, "hook_event_name": name}).encode() + def hook(name="PostToolUse", tool_response=None): + data = json.dumps({**event, "hook_event_name": name, "tool_response": tool_response}).encode() monkeypatch.setattr(sys, "stdin", io.TextIOWrapper(io.BytesIO(data))) capsys.readouterr() assert main(command) == 0 @@ -764,7 +778,7 @@ def read(*args): else: copy.write_bytes(original_bytes + b" ") copy.chmod(0o600) - presented_digest = _present_saved_guard(tmp_path, native, presented_capture, "codex_app_heartbeat", turn) + presented_digest = _present_saved_guard(tmp_path, native, presented_capture, scenario, turn) assert (presented_digest != digest) == unverified_copy result = hook() resume = hook("SessionStart") @@ -791,6 +805,7 @@ def read(*args): ) if after_ready: assert receipt["context"]["recovery_command"] + assert "readiness_command" not in receipt for command_key in ("receipt_command", "lease_command"): proc = subprocess.run( shlex.split(receipt[command_key]), cwd=tmp_path, capture_output=True, text=True, check=True, @@ -800,12 +815,113 @@ def read(*args): assert not current["active"] and current["lease"]["lease_epoch"] == lease["lease_epoch"] else: assert current["active"] and current["lease"] == lease - ready = read("quota", "should-run", "--goal-id", GOAL, "--agent-id", AGENT, - "--context-delivery", "off", "--codex-app", "--turn-instance-id", turn, "--todo-id", TODO) - assert ready["execution_preparation"]["state"] == "ready" - assert ready["heartbeat_receipt"]["turn_instance_id"] == turn + if after_ready: + resume_command = shlex.split(receipt["context"]["recovery_command"]) + assert resume_command[resume_command.index("--prepared-claim-operation-id") + 1] == original_id + replay = subprocess.run(resume_command, cwd=tmp_path, capture_output=True, text=True, timeout=30) + recovered = json.loads(replay.stdout) + assert recovered["ok"] is (not released) + assert replay.returncode == (1 if released else 0) + if released: + assert "current" in recovered["reason"] and "content" not in recovered + history = subprocess.run(shlex.split(recovered["recovery"]["command"]), + cwd=tmp_path, capture_output=True, text=True, check=True, timeout=30) + assert selected_context_values(json.loads(history.stdout)["content"])[ + "/heartbeat_receipt"]["settlement_identity"] == before["heartbeat_receipt"]["settlement_identity"] + else: + source_marker = native / "claim-source.json" + marker_before = source_marker.read_bytes() + guard = shlex.split(receipt["readiness_command"]) + assert "should-run" in guard and "--begin-turn" not in guard + assert guard[guard.index("--registry") + 1] == str(registry) + assert guard[guard.index("--runtime-root") + 1] == str(runtime) + assert guard[guard.index("--context-delivery") + 1] == delivery[1] + prepared = subprocess.run(guard, cwd=tmp_path, capture_output=True, text=True, timeout=30) + ready = json.loads(prepared.stdout) + assert source_marker.read_bytes() == marker_before + if released: + assert ready.get("normal_delivery_allowed") is not True + assert ready.get("execution_preparation", {}).get("state") != "ready" + lease_check = read("task-lease", "inspect", "--goal-id", GOAL, "--todo-id", TODO) + assert lease_check["lease"] == current["lease"] and not lease_check["active"] + hook(tool_response=ready) + assert len(claims) == len(guards) == 1 + else: + assert prepared.returncode == 0 and ready["normal_delivery_allowed"] is True, ready + assert ready["selected_todo"] == {"todo_id": TODO} + assert ready["heartbeat_receipt"] == {"turn_instance_id": turn} + assert ready["execution_preparation"]["state"] == "ready" + assert ready["execution_preparation"]["lease_proof"] == { + "idempotency_key": lease["idempotency_key"], "expected_version": lease["version"], + } + projection = shlex.split(receipt["ready_context_command_template"].replace( + "", ready["capture_sha256"])) + assert projection[projection.index("--prepared-claim-operation-id") + 1] == original_id + release = ["task-lease", "release", "--goal-id", GOAL, "--todo-id", TODO, "--owner", AGENT, + "--expected-version", str(lease["version"]), "--idempotency-key", lease["idempotency_key"]] + replacement_args = ["task-lease", "acquire", "--goal-id", GOAL, "--todo-id", TODO, + "--owner", AGENT, "--idempotency-key", "replacement-lease", "--ttl-seconds", "3600"] + if retire_at_delivery: + retired = read(*release) + if case == "replaced-at-delivery": + replacement = read(*replacement_args, "--expected-version", str(retired["lease"]["version"])) + assert replacement["lease"]["lease_epoch"] != lease["lease_epoch"] + if retire_during_staging: + # Stage through the real publisher and let a separate canonical writer + # finish before the publication transaction can validate its lease. + run_projection = """ +import json +import subprocess +import sys +from loopx.control_plane.quota import turn_envelope +from loopx.entrypoint import main +projection, release, replace = json.loads(sys.argv[1]) +prefix = projection[:projection.index("quota")] +prepare = turn_envelope.prepare_context_delivery +def stage_then_release(*args, **kwargs): + staged = prepare(*args, **kwargs) + result = subprocess.run([*prefix, *release], capture_output=True, check=True, timeout=20) + retired = json.loads(result.stdout)["lease"] + assert retired["status"] == "released" + if replace: + replaced = subprocess.run([*prefix, *replace, "--expected-version", str(retired["version"])], + capture_output=True, check=True, timeout=20) + assert json.loads(replaced.stdout)["lease"]["lease_epoch"] != retired["lease_epoch"] + return staged +turn_envelope.prepare_context_delivery = stage_then_release +raise SystemExit(main(projection[projection.index("--registry"):])) +""" + replace = replacement_args if case == "replaced-during-staging" else [] + projection = [sys.executable, "-c", run_projection, json.dumps([projection, release, replace])] + projected = subprocess.run(projection, cwd=tmp_path, capture_output=True, text=True, timeout=30) + view = json.loads(projected.stdout) + assert view["ok"] is (not refuse_delivery) and view["recovery"]["command"], projected.stderr + assert projected.returncode == (1 if refuse_delivery else 0) + if refuse_delivery: + assert "current" in view["reason"] and "content" not in view + assert source_marker.read_bytes() == marker_before + assert view["heartbeat_receipt"]["settlement_identity"] == before["heartbeat_receipt"]["settlement_identity"] + if retire_during_staging: + assert "recovery" not in codex_context._state(native) + reader = shlex.split(view["recovery"]["command"]) + if not refuse_delivery: + reader += ["--select", "/interaction_contract/cli_channel/settlement_plan/identity", + "--select", "/heartbeat_receipt/settlement_identity"] + selected = subprocess.run(reader, cwd=tmp_path, capture_output=True, text=True, check=True, timeout=30) + page = json.loads(selected.stdout) + assert page["eof"] + facts = selected_context_values(page["content"]) + identity = json.loads(original_bytes)["heartbeat_receipt"]["settlement_identity"] + if refuse_delivery: + assert facts["/heartbeat_receipt"]["settlement_identity"] == identity + else: + assert facts["/interaction_contract/cli_channel/settlement_plan/identity"] == identity + assert facts["/heartbeat_receipt/settlement_identity"] == identity + assert hook(tool_response=page) == {} + assert len(claims) == len(guards) == 1 readback = read("todo", "receipt", "--goal-id", GOAL, "--operation-id", original_id) assert readback["cursor"] == original["cursor"] and readback["receipts"] == original["receipts"] + assert _spend_run_count(runtime, goal_id=GOAL) == 0 @pytest.mark.parametrize("provider", ["file", "sqlite"])