loopx 0.4.8__py3-none-any.whl

loopx/control_plane/scheduler/scheduler_hint.py

@@ -0,0 +1,1284 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+
+from ..runtime.time import now_utc, utc_isoformat
+from ..todos.frontier_deadline import build_frontier_recheck_plan
+from . import ack as scheduler_ack
+from .arbitration import (
+    SchedulerArbitration,
+    SchedulerDisposition,
+    build_scheduler_arbitration,
+)
+from .execution_context import (
+    SchedulerExecutionContextResolution,
+    SchedulerOwner,
+    SchedulerRuntimeProfile,
+    apply_scheduler_execution_context,
+    resolve_scheduler_execution_context,
+)
+from .monitor_wait import (
+    MONITOR_WAIT_HOST_FLOOR_MINUTES,
+    MONITOR_WAIT_PHASE_RANK,  # noqa: F401  # re-exported for compatibility
+    MONITOR_WAIT_PROGRESSION_MINUTES,
+    MonitorWaitPhase,  # noqa: F401  # re-exported for compatibility
+    _parse_monitor_timestamp,  # noqa: F401  # re-exported for compatibility
+    build_monitor_wait_cadence_plan,
+)
+from .state import (
+    CODEX_APP_STATEFUL_BACKOFF_STATE_KEY,
+    CODEX_APP_SURFACE,
+    normalize_scheduler_host_update_failures,
+    normalize_scheduler_rrule,
+    retained_scheduler_host_update_failures,
+    rrule_for_minutes,
+    scheduler_rrule_interval_minutes,
+)
+from .state_transition_rules import (
+    decide_scheduler_cadence_transition,
+    decide_scheduler_host_transition,
+)
+from .time import parse_scheduler_timestamp
+
+SCHEDULER_HINT_SCHEMA_VERSION = "scheduler_hint_v0"
+SCHEDULER_RESET_POLICY_SCHEMA_VERSION = "scheduler_reset_policy_v0"
+SCHEDULER_HINT_DETAIL_SCHEMA_VERSION = "scheduler_hint_detail_v0"
+CODEX_APP_STATEFUL_BACKOFF_SCHEMA_VERSION = "codex_app_stateful_backoff_v0"
+CODEX_APP_SCHEDULER_ACK_HINT_SCHEMA_VERSION = "codex_app_scheduler_ack_hint_v0"
+CODEX_APP_SCHEDULER_FAILURE_HINT_SCHEMA_VERSION = "codex_app_scheduler_failure_hint_v0"
+CODEX_APP_SCHEDULER_FALLBACK_HINT_SCHEMA_VERSION = (
+    "codex_app_scheduler_fallback_hint_v0"
+)
+USER_GATE_NOTIFICATION_COOLDOWN_SCHEMA_VERSION = "user_gate_notification_cooldown_v0"
+CODEX_APP_MAX_INTERVAL_MINUTES = 60
+DEFAULT_ACK_CAPABILITIES = {"shell", "filesystem_read", "filesystem_write"}
+FALLBACK_AUTOMATION_ID_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
+SCHEDULER_BASE_IDENTITY_KEYS = (
+    "goal_id",
+    "agent_identity.agent_id",
+    "effective_action",
+    "heartbeat_recommendation.recommended_mode",
+    "interaction_contract.mode",
+)
+
+
+def build_projected_codex_app_automation_id(
+    *,
+    goal_id: Any,
+    agent_id: Any,
+) -> str:
+    """Build a deterministic Codex App automation id when none is installed yet.
+
+    The fallback bridge needs a stable automation id to create the first
+    heartbeat automation for a goal/agent pair. The id is derived from the
+    same identity keys used by the scheduler so a later run can resolve it
+    back to the installed automation without guessing.
+    """
+
+    safe_goal_id = str(goal_id or "").strip()
+    safe_agent_id = str(agent_id or "").strip()
+    raw = (
+        f"loopx-{safe_goal_id}-{safe_agent_id}"
+        if safe_agent_id
+        else f"loopx-{safe_goal_id}"
+    )
+    projected = re.sub(r"[^A-Za-z0-9._:-]", "-", raw)
+    projected = re.sub(r"-+", "-", projected).strip("-")
+    return projected[:128] or "loopx-fallback"
+SCHEDULER_FRONTIER_IDENTITY_KEYS = (
+    "selected_todo.todo_id",
+    "selected_todo.action_kind",
+    "selected_todo.target_key",
+    "selected_todo.claimed_by",
+    "selected_todo.capability_binding_ref",
+)
+SCHEDULER_IDENTITY_KEYS = (
+    *SCHEDULER_BASE_IDENTITY_KEYS,
+    "recommended_action",
+)
+MONITOR_WAIT_IDENTITY_KEYS = SCHEDULER_BASE_IDENTITY_KEYS
+CODEX_APP_SSH_GOAL_RUNTIME_KEY = SchedulerRuntimeProfile.CODEX_APP_SSH_VISIBLE.value
+CODEX_NATIVE_GOAL_BLOCK_ACTION = "update_goal_blocked_keep_loopx_active"
+CODEX_NATIVE_GOAL_RESUME_TRIGGER = "explicit_codex_goal_resume"
+
+build_codex_app_scheduler_ack_event = scheduler_ack.build_codex_app_scheduler_ack_event
+build_scheduler_ack_plan = scheduler_ack.build_scheduler_ack_plan
+scheduler_backoff_packet = scheduler_ack.scheduler_backoff_packet
+
+
+def _stable_digest(value: Any, *, length: int) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=True,
+        sort_keys=True,
+        default=str,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()[:length]
+
+
+def _dict_or_empty(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _scheduler_identity_keys(
+    *,
+    cadence_class: str,
+    execution_context: SchedulerExecutionContextResolution,
+) -> tuple[str, ...]:
+    base_keys = (
+        MONITOR_WAIT_IDENTITY_KEYS
+        if cadence_class == "monitor_wait"
+        else SCHEDULER_IDENTITY_KEYS
+    )
+    context = execution_context.context if execution_context.ok else None
+    if context is None or context.scheduler_owner is not SchedulerOwner.GOAL_RUNTIME:
+        return base_keys
+    if cadence_class == "monitor_wait":
+        return (*base_keys, *SCHEDULER_FRONTIER_IDENTITY_KEYS)
+    return (
+        *base_keys[:-1],
+        *SCHEDULER_FRONTIER_IDENTITY_KEYS,
+        base_keys[-1],
+    )
+
+
+def _build_scheduler_stop_hint(
+    *,
+    execution_context: SchedulerExecutionContextResolution,
+    action: str,
+    cadence_class: str,
+    reason_code: str,
+    reason: str,
+    spend_policy: str,
+    resume_trigger: str,
+    ssh_goal_runtime_action: str,
+    unchanged_spend_policy: str,
+) -> dict[str, Any]:
+    return apply_scheduler_execution_context(
+        {
+            "schema_version": SCHEDULER_HINT_SCHEMA_VERSION,
+            "source": "quota.should-run",
+            "action": action,
+            "cadence_class": cadence_class,
+            "reason_code": reason_code,
+            "reason": reason,
+            "spend_policy": spend_policy,
+            "codex_app": {
+                "apply": "pause_or_delete_current_heartbeat_if_possible",
+                "host_tool": "automation_update",
+                "host_action": "pause_or_delete_current_heartbeat",
+                "host_action_required": True,
+                "attempt_limit": 1,
+                "verify_host_result": True,
+                "ack_required": False,
+                "resume_trigger": resume_trigger,
+                "no_spend_for_host_action": True,
+            },
+            "unchanged_poll": {
+                "local_scheduler": "stop",
+                "codex_cli_tui": "exit",
+                CODEX_APP_SSH_GOAL_RUNTIME_KEY: ssh_goal_runtime_action,
+                "claude_code_loop": "stop",
+                "final_quota_replan_check_enabled": False,
+                "spend_policy": unchanged_spend_policy,
+            },
+            "unchanged_identity_keys": list(
+                _scheduler_identity_keys(
+                    cadence_class=cadence_class,
+                    execution_context=execution_context,
+                )
+            ),
+        },
+        execution_context,
+    )
+
+
+def _scheduler_progression_interval_elapsed(
+    scheduler_state: Mapping[str, Any],
+    *,
+    current_time: datetime,
+) -> bool:
+    """Advance only after the applied host cadence has had one real interval."""
+
+    updated_at = parse_scheduler_timestamp(scheduler_state.get("updated_at"))
+    applied_interval = scheduler_rrule_interval_minutes(
+        scheduler_state.get("last_applied_rrule")
+    )
+    if updated_at is None or applied_interval is None:
+        # Legacy or partial state has no trustworthy settlement clock. Preserve
+        # the historical progression behavior instead of pinning it forever.
+        return True
+    return current_time >= updated_at + timedelta(minutes=applied_interval)
+
+
+def _user_gate_notification_cooldown(
+    *,
+    cadence_class: str,
+    host_failure_suppressed: bool,
+    current_interval_minutes: int,
+    effective_host_rrule: str,
+    recorded_host_failure: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    """Bound repeat gate notices when a failed host update leaves a tight poll."""
+
+    if cadence_class != "human_gate" or not host_failure_suppressed:
+        return None
+    failed_at = parse_scheduler_timestamp((recorded_host_failure or {}).get("failed_at"))
+    host_interval = scheduler_rrule_interval_minutes(effective_host_rrule)
+    target_interval = max(1, int(current_interval_minutes))
+    if failed_at is None or host_interval is None or host_interval >= target_interval:
+        return None
+    current_time = now_utc()
+    elapsed_seconds = max(0.0, (current_time - failed_at).total_seconds())
+    cooldown_seconds = target_interval * 60
+    window_seconds = host_interval * 60
+    cycle_index = int(elapsed_seconds // cooldown_seconds)
+    cycle_position = elapsed_seconds - cycle_index * cooldown_seconds
+    notification_due = cycle_index >= 1 and cycle_position < window_seconds
+    next_reminder_at = failed_at + timedelta(
+        seconds=(cycle_index + 1) * cooldown_seconds
+    )
+    return {
+        "schema_version": USER_GATE_NOTIFICATION_COOLDOWN_SCHEMA_VERSION,
+        "active": True,
+        "notification_due": notification_due,
+        "notification_suppressed": not notification_due,
+        "policy": "failed_host_update_bounded_reminder_window",
+        "cooldown_minutes": target_interval,
+        "reminder_window_minutes": host_interval,
+        "failed_at": utc_isoformat(failed_at),
+        "next_reminder_at": utc_isoformat(next_reminder_at),
+        "reason": (
+            "the user gate is still pending, but the failed host cadence update "
+            "left a tighter poll; suppress duplicate notices outside the bounded "
+            "human-gate reminder window"
+        ),
+    }
+
+
+def _monitor_rrule_applied_within_stale_tolerance(
+    *,
+    cadence_class: str,
+    last_applied_rrule: str,
+    current_rrule: str,
+) -> bool:
+    if cadence_class != "monitor_wait":
+        return False
+    applied_minutes = scheduler_rrule_interval_minutes(last_applied_rrule)
+    current_minutes = scheduler_rrule_interval_minutes(current_rrule)
+    if applied_minutes is None or current_minutes is None:
+        return False
+    if applied_minutes < current_minutes:
+        return False
+    return (
+        applied_minutes - current_minutes
+        <= scheduler_ack.SCHEDULER_ACK_STALE_HINT_TOLERANCE_MINUTES
+    )
+
+
+def build_codex_app_scheduler_ack_hint(
+    *,
+    goal_id: Any,
+    agent_id: Any,
+    applied_rrule: Any,
+    reset_token: Any,
+    identity_signature: Any,
+    available_capabilities: Any = None,
+    after: str = "automation_update_rrule_success",
+    host_match_observed: bool = False,
+    surface: str = CODEX_APP_SURFACE,
+    state_key: str = CODEX_APP_STATEFUL_BACKOFF_STATE_KEY,
+) -> dict[str, Any]:
+    safe_rrule = normalize_scheduler_rrule(applied_rrule)
+    safe_goal_id = str(goal_id or "").strip()
+    safe_agent_id = str(agent_id or "").strip()
+    safe_surface = str(surface or "").strip()
+    safe_state_key = str(state_key or "").strip()
+    safe_reset_token = str(reset_token or "").strip()
+    safe_identity_signature = str(identity_signature or "").strip()
+    safe_available_capabilities: list[str] = []
+    if isinstance(available_capabilities, (list, tuple, set)):
+        for capability in available_capabilities:
+            safe_capability = str(capability or "").strip()
+            if (
+                safe_capability
+                and safe_capability not in DEFAULT_ACK_CAPABILITIES
+                and safe_capability not in safe_available_capabilities
+            ):
+                safe_available_capabilities.append(safe_capability)
+    cli_args = [
+        "quota",
+        "scheduler-ack-current",
+        "--goal-id",
+        safe_goal_id,
+        "--agent-id",
+        safe_agent_id,
+        "-A",
+    ]
+    for capability in safe_available_capabilities:
+        cli_args.extend(["--available-capability", capability])
+    if safe_surface != CODEX_APP_SURFACE:
+        cli_args.extend(["--surface", safe_surface])
+    if safe_state_key != CODEX_APP_STATEFUL_BACKOFF_STATE_KEY:
+        cli_args.extend(["--state-key", safe_state_key])
+    cli_args.extend(["--applied-rrule", safe_rrule])
+    if host_match_observed:
+        cli_args.extend(
+            [
+                "--host-match-observed",
+                "--reset-token",
+                safe_reset_token,
+                "--identity-signature",
+                safe_identity_signature,
+            ]
+        )
+    cli_args.append("--execute")
+    args = {
+        "goal_id": safe_goal_id,
+        "agent_id": safe_agent_id,
+        "surface": safe_surface,
+        "state_key": safe_state_key,
+        "applied_rrule": safe_rrule,
+        "reset_token": safe_reset_token,
+        "identity_signature": safe_identity_signature,
+    }
+    if safe_available_capabilities:
+        args["available_capabilities"] = safe_available_capabilities
+    if host_match_observed:
+        args["host_match_observed"] = True
+    return {
+        "schema_version": CODEX_APP_SCHEDULER_ACK_HINT_SCHEMA_VERSION,
+        "after": str(after or "automation_update_rrule_success").strip(),
+        "command": "quota scheduler-ack-current",
+        "execute": True,
+        "cli_args": cli_args,
+        "args": args,
+        "uses_current_hint": True,
+        "no_spend": True,
+    }
+
+
+def build_codex_app_scheduler_failure_hint(
+    *,
+    goal_id: Any,
+    agent_id: Any,
+    failed_rrule: Any,
+    observed_host_rrule: Any = None,
+    available_capabilities: Any = None,
+) -> dict[str, Any]:
+    safe_goal_id = str(goal_id or "").strip()
+    safe_agent_id = str(agent_id or "").strip()
+    safe_rrule = normalize_scheduler_rrule(failed_rrule)
+    safe_observed_rrule = normalize_scheduler_rrule(observed_host_rrule)
+    safe_capabilities: list[str] = []
+    if isinstance(available_capabilities, (list, tuple, set)):
+        for capability in available_capabilities:
+            safe_capability = str(capability or "").strip()
+            if (
+                safe_capability
+                and safe_capability not in DEFAULT_ACK_CAPABILITIES
+                and safe_capability not in safe_capabilities
+            ):
+                safe_capabilities.append(safe_capability)
+    cli_args = [
+        "quota",
+        "scheduler-fail-current",
+        "--goal-id",
+        safe_goal_id,
+        "--agent-id",
+        safe_agent_id,
+        "-A",
+    ]
+    for capability in safe_capabilities:
+        cli_args.extend(["--available-capability", capability])
+    cli_args.extend(
+        [
+            "--failed-rrule",
+            safe_rrule,
+        ]
+    )
+    if safe_observed_rrule:
+        cli_args.extend(["--codex-app-current-rrule", safe_observed_rrule])
+    cli_args.append("--execute")
+    return {
+        "schema_version": CODEX_APP_SCHEDULER_FAILURE_HINT_SCHEMA_VERSION,
+        "cli_args": cli_args,
+    }
+
+
+def build_codex_app_scheduler_fallback_hint(
+    *,
+    goal_id: Any,
+    agent_id: Any,
+    automation_id: Any,
+    turn_instance_id: Any = "${LOOPX_TURN:?}",
+) -> dict[str, Any]:
+    """Project the bounded SQLite/TOML RRULE fallback for automation_update gaps.
+
+    The fallback is a standalone host bridge (``loopx-apply-rrule``) that backs
+    up ``codex-dev.db``, syncs the automation TOML and SQLite row, and runs the
+    bound scheduler ACK. It directly edits the Codex App automation store,
+    bypassing the app API, so it is projected only when the host tool is
+    unavailable or failed and ``apply_needed=true`` - never as the routine path.
+    When no automation is installed yet, a deterministic automation id is
+    projected so the fallback bridge can create the first heartbeat automation.
+    """
+
+    safe_goal_id = str(goal_id or "").strip()
+    safe_agent_id = str(agent_id or "").strip()
+    safe_automation_id = str(automation_id or "").strip()
+    safe_turn_instance_id = str(turn_instance_id or "").strip() or "${LOOPX_TURN:?}"
+    projected_automation_id = False
+    if not FALLBACK_AUTOMATION_ID_PATTERN.match(safe_automation_id):
+        safe_automation_id = build_projected_codex_app_automation_id(
+            goal_id=safe_goal_id,
+            agent_id=safe_agent_id,
+        )
+        projected_automation_id = True
+    cli_args = [
+        "loopx-apply-rrule",
+        "--goal-id",
+        safe_goal_id,
+        "--agent-id",
+        safe_agent_id,
+        "--automation-id",
+        safe_automation_id,
+        "--turn-instance-id",
+        safe_turn_instance_id,
+    ]
+    return {
+        "schema_version": CODEX_APP_SCHEDULER_FALLBACK_HINT_SCHEMA_VERSION,
+        "available": True,
+        "command": "loopx-apply-rrule",
+        "after": "automation_update_unavailable_or_failed",
+        "cli_args": cli_args,
+        "args": {
+            "goal_id": safe_goal_id,
+            "agent_id": safe_agent_id,
+            "automation_id": safe_automation_id,
+            "turn_instance_id": safe_turn_instance_id,
+        },
+        "no_spend": True,
+        "reason": (
+            "fallback only when automation_update is unavailable or failed and "
+            "apply_needed=true; loopx-apply-rrule directly updates the Codex App "
+            "SQLite automation store (codex-dev.db) and TOML, which bypasses the "
+            "app API - use only as a bounded fallback, never as the routine path; "
+            "run the bound ack_hint after it succeeds"
+            + (
+                "; automation_id_projected: no installed heartbeat automation "
+                "matched this goal/agent, so loopx-apply-rrule will create it "
+                "before applying the rrule"
+                if projected_automation_id
+                else ""
+            )
+        ),
+        **(
+            {
+                "automation_id_projected": True,
+                "action": "create_then_apply_rrule_via_fallback",
+            }
+            if projected_automation_id
+            else {}
+        ),
+    }
+
+
+@dataclass(frozen=True)
+class _SchedulerHintBuilder:
+    payload: dict[str, Any]
+    execution_context: SchedulerExecutionContextResolution
+    arbitration: SchedulerArbitration
+    spend_policy: Any
+    scheduler_ack_capabilities: Any
+    codex_app_scheduler_state: dict[str, Any] | None
+    codex_app_current_rrule: Any
+    codex_app_automation_id: Any
+    include_detail: bool
+
+    def _identity_value(self, path: str) -> Any:
+        current: Any = self.payload
+        for part in path.split("."):
+            if not isinstance(current, dict):
+                return None
+            current = current.get(part)
+        return current
+
+    def build(
+        self,
+        *,
+        action: str,
+        cadence_class: str,
+        reason: str,
+        codex_interval: int,
+        codex_max: int,
+        cli_limit: int | None,
+        claude_limit: int | None,
+        multiplier: int = 2,
+        cadence_progression_override: list[int] | None = None,
+        reset_profile_snapshot_override: dict[str, Any] | None = None,
+        cadence_context_detail: dict[str, Any] | None = None,
+        advance_same_identity: bool = True,
+    ) -> dict[str, Any]:
+        local_cadence_progression = cadence_progression_override or [
+            min(codex_interval * (multiplier**step), codex_max) for step in range(3)
+        ]
+        codex_host_max = min(max(1, codex_max), CODEX_APP_MAX_INTERVAL_MINUTES)
+        codex_cadence_progression: list[int] = []
+        for interval in local_cadence_progression:
+            bounded_interval = min(max(1, int(interval)), codex_host_max)
+            if (
+                not codex_cadence_progression
+                or codex_cadence_progression[-1] != bounded_interval
+            ):
+                codex_cadence_progression.append(bounded_interval)
+        codex_initial_interval = codex_cadence_progression[0]
+        local_initial_interval = local_cadence_progression[0]
+        final_replan_check = {
+            "enabled": cli_limit is not None or claude_limit is not None,
+            "trigger": "before_unchanged_poll_after_limit",
+            "action": "rerun_quota_should_run_once",
+            "if_changed": "follow_new_scheduler_hint",
+            "if_run_now": "execute_new_quota_contract",
+            "if_unchanged": "apply_after_limit_without_spend",
+            "spend_policy": "no quota spend for final replan check or loop stop",
+        }
+        identity_keys = list(
+            _scheduler_identity_keys(
+                cadence_class=cadence_class,
+                execution_context=self.execution_context,
+            )
+        )
+        identity_snapshot = {key: self._identity_value(key) for key in identity_keys}
+        codex_rrule = rrule_for_minutes(codex_initial_interval)
+        profile_snapshot = {
+            "cadence_class": cadence_class,
+            "codex_app_initial_interval_minutes": codex_initial_interval,
+            "codex_app_initial_rrule": codex_rrule,
+            "codex_app_max_interval_minutes": codex_host_max,
+            "codex_app_progression_minutes": codex_cadence_progression,
+            "unchanged_poll_backoff_multiplier": multiplier,
+            "local_scheduler_unchanged_poll_limit": cli_limit,
+            "claude_code_loop_unchanged_poll_limit": claude_limit,
+        }
+        reset_profile_snapshot = reset_profile_snapshot_override or profile_snapshot
+        reset_token = _stable_digest(
+            {
+                "action": action,
+                "identity_snapshot": identity_snapshot,
+                "profile_snapshot": reset_profile_snapshot,
+            },
+            length=16,
+        )
+        identity_signature = _stable_digest(identity_snapshot, length=12)
+        profile_signature = _stable_digest(profile_snapshot, length=12)
+        reset_profile_signature = _stable_digest(reset_profile_snapshot, length=12)
+        reset_policy_detail = {
+            "schema_version": SCHEDULER_RESET_POLICY_SCHEMA_VERSION,
+            "source": "quota.should-run",
+            "reset_to": "profile_initial_interval",
+            "profile_action": action,
+            "reset_token": reset_token,
+            "host_state_key": "scheduler_hint.reset_policy.reset_token",
+            "codex_app_initial_interval_minutes": codex_initial_interval,
+            "codex_app_initial_rrule": codex_rrule,
+            "local_scheduler_initial_interval_minutes": local_initial_interval,
+            "clear_unchanged_poll_state": True,
+            "identity_key_count": len(identity_keys),
+            "identity_signature": identity_signature,
+            "profile_signature": profile_signature,
+            "reset_profile_signature": reset_profile_signature,
+            "reset_condition_summary": "token_changed|user_feedback|new_or_reassigned_todo|gate_or_material_transition|active_work_projected",
+            "after_reset": "apply_initial_interval_before_backoff",
+            "codex_app_tool": "automation_update",
+            "codex_app_apply": "call_automation_update_to_restore_initial_rrule_on_token_change",
+            "no_spend_for_reset": True,
+        }
+        reset_policy = {
+            "reset_token": reset_token,
+            "host_state_key": "scheduler_hint.reset_policy.reset_token",
+            "codex_app_initial_interval_minutes": codex_initial_interval,
+            "codex_app_initial_rrule": codex_rrule,
+            "identity_signature": identity_signature,
+        }
+        local_scheduler = {
+            "recommended_interval_minutes": local_initial_interval,
+            "max_interval_minutes": codex_max,
+            "unchanged_poll_backoff_multiplier": multiplier,
+            "example_progression_minutes": local_cadence_progression,
+            "unchanged_poll_limit": cli_limit,
+            "after_limit": "stop_tick_loop" if cli_limit is not None else "continue",
+            "final_quota_replan_check": final_replan_check,
+            "no_spend_for_cadence_change": True,
+        }
+        codex_goal_loop = {
+            "unchanged_poll_limit": cli_limit,
+            "after_limit": (
+                CODEX_NATIVE_GOAL_BLOCK_ACTION
+                if cli_limit is not None
+                else "continue"
+            ),
+            "final_quota_replan_check": final_replan_check,
+            "loopx_goal_state": "remains_active",
+            "resume_trigger": CODEX_NATIVE_GOAL_RESUME_TRIGGER,
+            "no_spend_for_block": True,
+        }
+        codex_cli_tui = {
+            **codex_goal_loop,
+            "no_spend_for_exit": True,
+        }
+        codex_app_ssh_goal = dict(codex_goal_loop)
+        claude_code_loop = {
+            "unchanged_poll_limit": claude_limit,
+            "after_limit": "stop_loop" if claude_limit is not None else "continue",
+            "final_quota_replan_check": final_replan_check,
+            "no_spend_for_stop": True,
+        }
+        scheduler_state = _dict_or_empty(self.codex_app_scheduler_state)
+        scheduler_now = now_utc()
+        all_host_update_failures = retained_scheduler_host_update_failures(
+            normalize_scheduler_host_update_failures(
+                scheduler_state.get("host_update_failures"),
+                legacy_failure=scheduler_state.get("host_update_failure"),
+            ),
+            reference_time=scheduler_now,
+        )
+        cadence_decision = decide_scheduler_cadence_transition(
+            codex_cadence_progression,
+            scheduler_state=scheduler_state,
+            reset_token=reset_token,
+            identity_signature=identity_signature,
+            advance_same_identity=advance_same_identity,
+            applied_interval_elapsed=_scheduler_progression_interval_elapsed(
+                scheduler_state,
+                current_time=scheduler_now,
+            ),
+            has_host_update_failures=bool(all_host_update_failures),
+        )
+        current_index = cadence_decision.current_index
+        state_status = cadence_decision.state_status
+        current_interval = codex_cadence_progression[current_index]
+        current_rrule = rrule_for_minutes(current_interval)
+        last_applied_rrule = str(
+            scheduler_state.get("last_applied_rrule") or ""
+        ).strip()
+        observed_host_rrule = normalize_scheduler_rrule(self.codex_app_current_rrule)
+        effective_host_rrule = observed_host_rrule or last_applied_rrule
+        host_update_failures = retained_scheduler_host_update_failures(
+            all_host_update_failures,
+            reference_time=scheduler_now,
+            observed_host_rrule=effective_host_rrule,
+        )
+        recorded_host_failure = next(
+            (
+                failure
+                for failure in reversed(host_update_failures)
+                if normalize_scheduler_rrule(failure.get("target_rrule"))
+                == current_rrule
+            ),
+            host_update_failures[-1] if host_update_failures else None,
+        )
+        current_rrule_already_applied = effective_host_rrule == current_rrule
+        if (
+            not current_rrule_already_applied
+            and not observed_host_rrule
+            and state_status == "same_identity"
+        ):
+            current_rrule_already_applied = (
+                _monitor_rrule_applied_within_stale_tolerance(
+                    cadence_class=cadence_class,
+                    last_applied_rrule=effective_host_rrule,
+                    current_rrule=current_rrule,
+                )
+            )
+        host_decision = decide_scheduler_host_transition(
+            state_status=state_status,
+            observed_host_rrule=observed_host_rrule,
+            effective_host_rrule=effective_host_rrule,
+            current_rrule=current_rrule,
+            current_rrule_already_applied=current_rrule_already_applied,
+            scheduler_state_acknowledges_current_rrule=(
+                state_status == "same_identity"
+                and normalize_scheduler_rrule(last_applied_rrule) == current_rrule
+            ),
+            all_host_update_failures=all_host_update_failures,
+            recorded_host_failure=recorded_host_failure,
+        )
+        apply_needed = host_decision.apply_needed
+        ack_needed = host_decision.ack_needed
+        host_match_ack_needed = host_decision.host_match_ack_needed
+        host_failure_suppressed = host_decision.host_failure_suppressed
+        if host_failure_suppressed:
+            state_status = "host_update_failure_suppressed"
+        stateful_backoff_detail = {
+            "progression_minutes": codex_cadence_progression,
+            "current_interval_minutes": current_interval,
+            "host_max_interval_minutes": codex_host_max,
+            "coarser_wait_fallback": "local_scheduler_only",
+            "host_update_failure": "cache_recent_failed_target_and_observed_host_pairs_then_suppress_each_exact_repeat_until_host_changes_ack_or_expiry",
+            "ack_required_after_apply": apply_needed,
+            "ack_required_from_host_match": host_match_ack_needed,
+            "persist": "reset_token|identity_signature|progression_index|last_applied_rrule|host_update_failures|host_update_failure_compat",
+            "same_identity_action": (
+                "advance_index_after_applied_interval_elapsed"
+                if advance_same_identity
+                else "keep_initial_interval_while_active_work"
+            ),
+            "reset_action": "clear_progression_index_apply_initial_rrule",
+            "automation_update_scope": "rrule_only_preserve_body_name_status",
+        }
+        codex_app = {
+            "recommended_interval_minutes": current_interval,
+            "max_interval_minutes": codex_host_max,
+            "unchanged_poll_backoff_multiplier": multiplier,
+            "example_progression_minutes": codex_cadence_progression,
+            "apply": (
+                "update_automation_cadence_if_possible"
+                if apply_needed
+                else (
+                    "none_recorded_host_failure"
+                    if host_failure_suppressed
+                    else "none_already_applied"
+                )
+            ),
+            "host_tool": "automation_update",
+            "host_action": (
+                "update_current_heartbeat_rrule"
+                if apply_needed
+                else (
+                    "none_recorded_host_failure"
+                    if host_failure_suppressed
+                    else "ack_observed_rrule_without_update"
+                    if host_match_ack_needed
+                    else "none"
+                )
+            ),
+            "host_action_contract": (
+                "automation_update_rrule_then_quota_scheduler_ack"
+                if apply_needed
+                else (
+                    "skip_automation_update_for_recorded_host_failure"
+                    if host_failure_suppressed
+                    else "quota_scheduler_ack_from_matching_host_observation"
+                    if host_match_ack_needed
+                    else "skip_automation_update_when_apply_needed_false"
+                )
+            ),
+            "rrule_source": (
+                "scheduler_hint.codex_app.recommended_rrule" if apply_needed else None
+            ),
+            "stateful_backoff": {
+                "schema_version": CODEX_APP_STATEFUL_BACKOFF_SCHEMA_VERSION,
+                "state_key": CODEX_APP_STATEFUL_BACKOFF_STATE_KEY,
+                "identity_signature": identity_signature,
+                "reset_token": reset_token,
+                "progression_index": current_index,
+                "current_rrule": current_rrule,
+                "apply_needed": apply_needed,
+                "ack_needed": ack_needed,
+                "state_status": state_status,
+            },
+            "no_spend_for_cadence_change": True,
+        }
+        stateful_backoff = codex_app["stateful_backoff"]
+        if host_update_failures:
+            stateful_backoff["host_update_failures"] = [
+                dict(failure) for failure in host_update_failures
+            ]
+        if recorded_host_failure:
+            stateful_backoff["host_update_failure"] = dict(recorded_host_failure)
+        if observed_host_rrule:
+            stateful_backoff["host_observation"] = {
+                "source": "quota_should_run_host_observation",
+                "current_rrule": observed_host_rrule,
+                "status": (
+                    "matches_recommended"
+                    if current_rrule_already_applied
+                    else "drift_detected"
+                ),
+            }
+        goal_id = self.payload.get("goal_id")
+        agent_id = self._identity_value("agent_identity.agent_id")
+        if apply_needed:
+            codex_app["recommended_rrule"] = current_rrule
+            if goal_id and agent_id:
+                codex_app["failure_hint"] = build_codex_app_scheduler_failure_hint(
+                    goal_id=goal_id,
+                    agent_id=agent_id,
+                    failed_rrule=current_rrule,
+                    observed_host_rrule=effective_host_rrule,
+                    available_capabilities=self.scheduler_ack_capabilities,
+                )
+                codex_app["fallback_hint"] = build_codex_app_scheduler_fallback_hint(
+                    goal_id=goal_id,
+                    agent_id=agent_id,
+                    automation_id=self.codex_app_automation_id,
+                )
+        if ack_needed and goal_id and agent_id:
+            codex_app["ack_hint"] = build_codex_app_scheduler_ack_hint(
+                goal_id=goal_id,
+                agent_id=agent_id,
+                applied_rrule=current_rrule,
+                reset_token=reset_token,
+                identity_signature=identity_signature,
+                available_capabilities=self.scheduler_ack_capabilities,
+                after=(
+                    "automation_update_rrule_success"
+                    if apply_needed
+                    else "matching_host_rrule_observed"
+                ),
+                # Bind the host proof to the originating identity.
+                host_match_observed=True,
+            )
+        unchanged_poll_limits = {
+            "local_scheduler": cli_limit,
+            "codex_cli_tui": cli_limit,
+            "claude_code_loop": claude_limit,
+        }
+        unchanged_poll_after_limits = {
+            "local_scheduler": local_scheduler["after_limit"],
+            "codex_cli_tui": codex_cli_tui["after_limit"],
+            "claude_code_loop": claude_code_loop["after_limit"],
+        }
+        detail_contains = [
+            "local_scheduler",
+            "codex_cli_tui",
+            "claude_code_loop",
+            "final_quota_replan_check",
+            "reset_policy_detail",
+            "stateful_backoff_detail",
+        ]
+        if cli_limit is not None:
+            unchanged_poll_limits[CODEX_APP_SSH_GOAL_RUNTIME_KEY] = cli_limit
+            unchanged_poll_after_limits[CODEX_APP_SSH_GOAL_RUNTIME_KEY] = (
+                codex_app_ssh_goal["after_limit"]
+            )
+            detail_contains.insert(2, CODEX_APP_SSH_GOAL_RUNTIME_KEY)
+        scheduler_hint = {
+            "schema_version": SCHEDULER_HINT_SCHEMA_VERSION,
+            "source": "quota.should-run",
+            "action": action,
+            "cadence_class": cadence_class,
+            "reason_code": self.arbitration.reason_code,
+            "reason": reason,
+            "spend_policy": self.spend_policy,
+            "codex_app": codex_app,
+            "unchanged_poll": {
+                "limits": unchanged_poll_limits,
+                "after_limits": unchanged_poll_after_limits,
+                "final_quota_replan_check_enabled": final_replan_check["enabled"],
+                "final_quota_replan_check_action": (
+                    final_replan_check["action"]
+                    if final_replan_check["enabled"]
+                    else None
+                ),
+                "spend_policy": final_replan_check["spend_policy"],
+            },
+            "unchanged_identity_keys": identity_keys,
+            "reset_policy": reset_policy,
+            "detail_ref": {
+                "schema_version": SCHEDULER_HINT_DETAIL_SCHEMA_VERSION,
+                "omitted_by_default": True,
+                "execution_required": False,
+                "request": "loopx quota should-run --include-detail scheduler",
+                "hot_path_runtime_fields": [
+                    "codex_app",
+                    "unchanged_poll",
+                    "reset_policy",
+                ],
+                "contains": detail_contains,
+            },
+        }
+        notification_cooldown = _user_gate_notification_cooldown(
+            cadence_class=cadence_class,
+            host_failure_suppressed=host_failure_suppressed,
+            current_interval_minutes=current_interval,
+            effective_host_rrule=effective_host_rrule,
+            recorded_host_failure=recorded_host_failure,
+        )
+        if notification_cooldown:
+            scheduler_hint["user_gate_notification_cooldown"] = notification_cooldown
+        frontier_recheck = build_frontier_recheck_plan(
+            self.payload,
+            current_time=now_utc(),
+        )
+        if self.include_detail:
+            scheduler_hint["cold_path_detail"] = {
+                "schema_version": SCHEDULER_HINT_DETAIL_SCHEMA_VERSION,
+                "source": "quota.should-run",
+                "local_scheduler": local_scheduler,
+                "codex_cli_tui": codex_cli_tui,
+                CODEX_APP_SSH_GOAL_RUNTIME_KEY: codex_app_ssh_goal,
+                "claude_code_loop": claude_code_loop,
+                "final_quota_replan_check": final_replan_check,
+                "reset_policy_detail": reset_policy_detail,
+                "stateful_backoff_detail": stateful_backoff_detail,
+            }
+            if cadence_context_detail:
+                scheduler_hint["cold_path_detail"]["cadence_context"] = (
+                    cadence_context_detail
+                )
+            if frontier_recheck:
+                scheduler_hint["cold_path_detail"]["frontier_recheck"] = (
+                    frontier_recheck
+                )
+        return apply_scheduler_execution_context(
+            scheduler_hint,
+            self.execution_context,
+            frontier_recheck_after_seconds=(
+                frontier_recheck.get("frontier_recheck_after_seconds")
+                if frontier_recheck
+                else None
+            ),
+        )
+
+
+def build_scheduler_hint(
+    payload: dict[str, Any],
+    *,
+    user_action_required: bool = False,
+    agent_scope_frontier_actions: Collection[str] = (),
+    include_detail: bool = False,
+    codex_app_scheduler_state: dict[str, Any] | None = None,
+    available_capabilities: Any = None,
+    codex_app_current_rrule: Any = None,
+    codex_app_automation_id: Any = None,
+    scheduler_execution_context: (
+        Mapping[str, Any] | SchedulerExecutionContextResolution | None
+    ) = None,
+) -> dict[str, Any]:
+    """Project host-runtime cadence/backoff policy from a quota decision.
+
+    This helper is intentionally pure: callers provide the few quota-local
+    classification facts it needs, and it returns the public scheduler contract
+    without reading files, mutating state, or depending on the full quota module.
+    """
+
+    execution_context = resolve_scheduler_execution_context(scheduler_execution_context)
+    if not execution_context.ok:
+        return {
+            "schema_version": SCHEDULER_HINT_SCHEMA_VERSION,
+            "source": "quota.should-run",
+            "action": "repair_scheduler_execution_context",
+            "cadence_class": "control_plane_repair",
+            "reason_code": "invalid_scheduler_execution_context",
+            "reason": (
+                "scheduler ownership is missing or contradictory; repair the "
+                "typed execution context before applying cadence"
+            ),
+            "spend_policy": "no quota spend for scheduler context repair",
+            "execution_context": execution_context.projection(),
+            "execution_phase": {
+                "schema_version": "scheduler_execution_phase_v0",
+                "disposition": "contract_error",
+                "completed": False,
+                "apply_needed": False,
+                "ack_needed": False,
+                "acknowledged": False,
+            },
+            "codex_app": {
+                "applicability": "blocked_invalid_context",
+                "apply": "none",
+                "host_action": "none",
+                "ack_required": False,
+            },
+            "unchanged_poll": {
+                "local_scheduler": "stop_until_context_repaired",
+                "codex_cli_tui": "stop_until_context_repaired",
+                CODEX_APP_SSH_GOAL_RUNTIME_KEY: "stop_until_context_repaired",
+                "claude_code_loop": "stop_until_context_repaired",
+                "final_quota_replan_check_enabled": False,
+                "spend_policy": "no quota spend for scheduler context repair",
+            },
+            "consistency_error": {
+                "source": "scheduler_execution_context",
+                "errors": list(execution_context.errors),
+            },
+        }
+
+    heartbeat_recommendation = _dict_or_empty(payload.get("heartbeat_recommendation"))
+    if heartbeat_recommendation.get("recommended_mode") == "quota_paused":
+        return apply_scheduler_execution_context(
+            {
+                "schema_version": SCHEDULER_HINT_SCHEMA_VERSION,
+                "source": "quota.should-run",
+                "action": "stop_until_explicit_resume",
+                "cadence_class": "quota_paused",
+                "reason_code": "quota_paused",
+                "reason": (
+                    "Goal-level compute quota is paused; recurring host automation "
+                    "must stop until quota.compute is explicitly raised above 0"
+                ),
+                "spend_policy": "no quota spend for paused automation shutdown",
+                "codex_app": {
+                    "apply": "pause_or_delete_current_heartbeat_if_possible",
+                    "host_tool": "automation_update",
+                    "host_action": "pause_or_delete_current_heartbeat",
+                    "host_action_required": True,
+                    "attempt_limit": 1,
+                    "verify_host_result": True,
+                    "ack_required": False,
+                    "resume_trigger": "explicit quota resume with quota.compute > 0",
+                    "no_spend_for_host_action": True,
+                },
+                "unchanged_poll": {
+                    "local_scheduler": "stop",
+                    "codex_cli_tui": "exit",
+                    CODEX_APP_SSH_GOAL_RUNTIME_KEY: "complete_host_goal",
+                    "claude_code_loop": "stop",
+                    "final_quota_replan_check_enabled": False,
+                    "spend_policy": "no quota spend while the Goal is paused",
+                },
+                "unchanged_identity_keys": list(
+                    _scheduler_identity_keys(
+                        cadence_class="quota_paused",
+                        execution_context=execution_context,
+                    )
+                ),
+            },
+            execution_context,
+        )
+
+    execution_obligation = _dict_or_empty(payload.get("execution_obligation"))
+    automation_liveness = _dict_or_empty(payload.get("automation_liveness"))
+    spend_policy = (
+        automation_liveness.get("spend_policy")
+        or execution_obligation.get("spend_policy")
+        or heartbeat_recommendation.get("spend_policy")
+    )
+    capability_gate = _dict_or_empty(payload.get("capability_gate"))
+    scheduler_ack_capabilities = (
+        available_capabilities
+        if available_capabilities is not None
+        else capability_gate.get("available")
+        if isinstance(capability_gate.get("available"), list)
+        else []
+    )
+    agent_scope_action_set = {str(value) for value in agent_scope_frontier_actions}
+    arbitration = build_scheduler_arbitration(
+        payload,
+        agent_scope_frontier_actions=agent_scope_action_set,
+    )
+
+    if arbitration.disposition == SchedulerDisposition.TERMINAL_STOP:
+        return _build_scheduler_stop_hint(
+            execution_context=execution_context,
+            action="stop_until_explicit_resume",
+            cadence_class="terminal_no_followup",
+            reason_code=arbitration.reason_code,
+            reason=(
+                "validated closure evidence derives no-follow-up and confirms no "
+                "remaining frontier; recurring polling must stop until resume"
+            ),
+            spend_policy="no quota spend for terminal automation shutdown",
+            resume_trigger="explicit goal resume or newly projected work",
+            ssh_goal_runtime_action="complete_host_goal",
+            unchanged_spend_policy="no quota spend for terminal loop stop",
+        )
+
+    if arbitration.disposition == SchedulerDisposition.PEER_COORDINATION_STOP:
+        cadence_class = "peer_coordination_blocked"
+        return _build_scheduler_stop_hint(
+            execution_context=execution_context,
+            action="return_to_owner_until_material_change",
+            cadence_class=cadence_class,
+            reason_code=arbitration.reason_code,
+            reason=(
+                "explicit peer coordination has no executable peer lane or local "
+                "fallback; recurring polling must stop until its inputs change"
+            ),
+            spend_policy=(
+                "no quota spend while explicit peer coordination is blocked"
+            ),
+            resume_trigger=(
+                "peer activation capability, peer runtime readiness, coordinator "
+                "configuration, or newly projected local work"
+            ),
+            ssh_goal_runtime_action="return_to_owner",
+            unchanged_spend_policy=(
+                "no quota spend for blocked coordination stop"
+            ),
+        )
+
+    builder = _SchedulerHintBuilder(
+        payload=payload,
+        execution_context=execution_context,
+        arbitration=arbitration,
+        spend_policy=spend_policy,
+        scheduler_ack_capabilities=scheduler_ack_capabilities,
+        codex_app_scheduler_state=codex_app_scheduler_state,
+        codex_app_current_rrule=codex_app_current_rrule,
+        codex_app_automation_id=codex_app_automation_id,
+        include_detail=include_detail,
+    )
+    if arbitration.disposition == SchedulerDisposition.AGENT_MONITOR_ONLY_WAIT:
+        return builder.build(
+            action="backoff_agent_monitor_only",
+            cadence_class="agent_monitor_only",
+            reason=(
+                "agent monitor-only mode blocks advancement while a quiet poll keeps "
+                "due monitors and verified direct replies responsive"
+            ),
+            codex_interval=15,
+            codex_max=60,
+            cli_limit=3,
+            claude_limit=3,
+        )
+
+    if arbitration.disposition == SchedulerDisposition.CONSISTENCY_REPAIR:
+        result = builder.build(
+            action="repair_interaction_contract_projection",
+            cadence_class="control_plane_repair",
+            reason=(
+                "scheduler inputs disagree with the final interaction contract; "
+                "repair the projection before applying delivery or wait cadence"
+            ),
+            codex_interval=3,
+            codex_max=10,
+            cli_limit=None,
+            claude_limit=None,
+            advance_same_identity=False,
+        )
+        result["consistency_error"] = arbitration.consistency_error()
+        return result
+
+    if arbitration.disposition == SchedulerDisposition.HUMAN_GATE:
+        return builder.build(
+            action="backoff_waiting_for_user",
+            cadence_class="human_gate",
+            reason=(
+                "user/controller action is the next unlock; surface the concrete "
+                "gate once, then stop repeating the same quiet poll"
+            ),
+            codex_interval=30,
+            codex_max=120,
+            cli_limit=3,
+            claude_limit=3,
+        )
+
+    if arbitration.disposition == SchedulerDisposition.ACTIVE_WORK:
+        interaction_contract = payload.get("interaction_contract")
+        agent_channel = (
+            interaction_contract.get("agent_channel")
+            if isinstance(interaction_contract, Mapping)
+            else None
+        )
+        capability_bridge_wait = (
+            arbitration.mode == "capability_bridge_repair"
+            and isinstance(agent_channel, Mapping)
+            and agent_channel.get("delivery_allowed") is False
+        )
+        return builder.build(
+            action="run_now",
+            cadence_class="active_work",
+            reason=(
+                "the interaction contract requires an agent attempt; keep the active "
+                "scheduler cadence until the turn validates or blocks"
+            ),
+            codex_interval=3,
+            codex_max=10,
+            cli_limit=None,
+            claude_limit=None,
+            advance_same_identity=capability_bridge_wait,
+        )
+
+    if arbitration.disposition == SchedulerDisposition.UNCHANGED_WAIT:
+        return builder.build(
+            action="backoff_until_fresh_evidence",
+            cadence_class="unchanged_noop",
+            reason=(
+                "the current mapped or post-handoff source is unchanged; do not "
+                "keep a tight loop while waiting for fresh evidence or a concrete handoff"
+            ),
+            codex_interval=60,
+            codex_max=240,
+            cli_limit=3,
+            claude_limit=3,
+        )
+
+    if arbitration.disposition == SchedulerDisposition.AGENT_SCOPE_WAIT:
+        return builder.build(
+            action="backoff_until_reassigned",
+            cadence_class="agent_scope_wait",
+            reason=(
+                "this registered agent has no in-scope advancement candidate; "
+                "agent-to-agent handoffs may change quickly, so stay closer to "
+                "the prior scheduler cadence while waiting for handoff owner "
+                "progress, reassignment, or a current-agent todo"
+            ),
+            codex_interval=10,
+            codex_max=60,
+            cli_limit=3,
+            claude_limit=3,
+            cadence_progression_override=[10, 20, 30, 60],
+        )
+
+    if arbitration.disposition == SchedulerDisposition.MONITOR_WAIT:
+        monitor_plan = build_monitor_wait_cadence_plan(
+            payload,
+            current_time=now_utc(),
+        )
+        monitor_progression = (
+            monitor_plan.get("progression_minutes")
+            if isinstance(monitor_plan, dict)
+            else None
+        )
+        monitor_initial_interval = (
+            monitor_progression[0]
+            if isinstance(monitor_progression, list) and monitor_progression
+            else MONITOR_WAIT_HOST_FLOOR_MINUTES
+        )
+        monitor_reset_profile = (
+            {
+                "cadence_class": "monitor_wait",
+                "codex_app_initial_interval_minutes": monitor_initial_interval,
+                "codex_app_initial_rrule": rrule_for_minutes(monitor_initial_interval),
+                "codex_app_max_interval_minutes": 60,
+                "unchanged_poll_backoff_multiplier": 2,
+                "local_scheduler_unchanged_poll_limit": 3,
+                "claude_code_loop_unchanged_poll_limit": 3,
+                **monitor_plan["reset_profile"],
+            }
+            if isinstance(monitor_plan, dict)
+            and isinstance(monitor_plan.get("reset_profile"), dict)
+            else None
+        )
+        return builder.build(
+            action="backoff_until_material_transition",
+            cadence_class="monitor_wait",
+            reason=(
+                "monitor-only quiet polls should remain alive but use a slower "
+                "cadence until material evidence, a blocker, or replan obligation appears"
+            ),
+            codex_interval=monitor_initial_interval,
+            codex_max=60,
+            cli_limit=3,
+            claude_limit=3,
+            cadence_progression_override=(
+                monitor_progression or MONITOR_WAIT_PROGRESSION_MINUTES
+            ),
+            reset_profile_snapshot_override=monitor_reset_profile,
+            cadence_context_detail=monitor_plan,
+        )
+
+    if arbitration.disposition == SchedulerDisposition.QUIET_WAIT:
+        return builder.build(
+            action="backoff_until_state_change",
+            cadence_class="quiet_wait",
+            reason=(
+                "quota blocks delivery and no immediate user/monitor-specific path "
+                "is projected; poll at a slower cadence until the status changes"
+            ),
+            codex_interval=30,
+            codex_max=120,
+            cli_limit=3,
+            claude_limit=3,
+        )
+
+    raise AssertionError(f"unhandled scheduler disposition: {arbitration.disposition}")