loopx 0.4.8__py3-none-any.whl

loopx/control_plane/scheduler/ack.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..work_items.delivery_outcome import DeliveryOutcome
+from .state import (
+    CODEX_APP_STATEFUL_BACKOFF_STATE_KEY,
+    CODEX_APP_SURFACE,
+    build_scheduler_state,
+    normalize_scheduler_host_update_failures,
+    normalize_scheduler_rrule,
+    retained_scheduler_host_update_failures,
+    scheduler_rrule_interval_minutes,
+)
+
+
+SCHEDULER_ACK_STALE_HINT_TOLERANCE_MINUTES = 2
+
+
+def _accepts_stale_monitor_ack_rrule(
+    scheduler_hint: dict[str, Any],
+    stateful_backoff: dict[str, Any],
+    *,
+    applied_rrule: str,
+    expected_rrule: str,
+    reset_token: str | None,
+    identity_signature: str | None,
+) -> bool:
+    if str(scheduler_hint.get("cadence_class") or "") != "monitor_wait":
+        return False
+    safe_reset_token = str(reset_token or "").strip()
+    safe_identity_signature = str(identity_signature or "").strip()
+    if not safe_reset_token or not safe_identity_signature:
+        return False
+    if safe_reset_token != str(stateful_backoff.get("reset_token") or ""):
+        return False
+    if safe_identity_signature != str(stateful_backoff.get("identity_signature") or ""):
+        return False
+    applied_minutes = scheduler_rrule_interval_minutes(applied_rrule)
+    expected_minutes = scheduler_rrule_interval_minutes(expected_rrule)
+    if applied_minutes is None or expected_minutes is None:
+        return False
+    if applied_minutes < expected_minutes:
+        return False
+    return (
+        applied_minutes - expected_minutes <= SCHEDULER_ACK_STALE_HINT_TOLERANCE_MINUTES
+    )
+
+
+def _scheduler_ack_rrule_acceptance(
+    scheduler_hint: dict[str, Any],
+    codex_app: dict[str, Any],
+    stateful_backoff: dict[str, Any],
+    *,
+    applied_rrule: str,
+    reset_token: str | None,
+    identity_signature: str | None,
+) -> dict[str, Any]:
+    expected_rrule = normalize_scheduler_rrule(
+        codex_app.get("recommended_rrule") or stateful_backoff.get("current_rrule")
+    )
+    if not expected_rrule:
+        return {
+            "ok": False,
+            "reason": "quota scheduler-ack has no current recommended_rrule to acknowledge",
+            "expected_rrule": "",
+        }
+    if applied_rrule == expected_rrule:
+        return {
+            "ok": True,
+            "applied_rrule": applied_rrule,
+            "expected_rrule": expected_rrule,
+        }
+    if _accepts_stale_monitor_ack_rrule(
+        scheduler_hint,
+        stateful_backoff,
+        applied_rrule=applied_rrule,
+        expected_rrule=expected_rrule,
+        reset_token=reset_token,
+        identity_signature=identity_signature,
+    ):
+        return {
+            "ok": True,
+            "applied_rrule": applied_rrule,
+            "expected_rrule": expected_rrule,
+            "stale_hint_accepted": True,
+            "stale_hint_tolerance_minutes": SCHEDULER_ACK_STALE_HINT_TOLERANCE_MINUTES,
+        }
+    return {
+        "ok": False,
+        "reason": (
+            f"quota scheduler-ack applied_rrule {applied_rrule!r} "
+            f"does not match expected {expected_rrule!r}"
+        ),
+        "expected_rrule": expected_rrule,
+    }
+
+
+def scheduler_backoff_packet(
+    decision: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    scheduler_hint = (
+        decision.get("scheduler_hint")
+        if isinstance(decision.get("scheduler_hint"), dict)
+        else {}
+    )
+    codex_app = (
+        scheduler_hint.get("codex_app")
+        if isinstance(scheduler_hint.get("codex_app"), dict)
+        else {}
+    )
+    stateful_backoff = (
+        codex_app.get("stateful_backoff")
+        if isinstance(codex_app.get("stateful_backoff"), dict)
+        else {}
+    )
+    return scheduler_hint, codex_app, stateful_backoff
+
+
+def build_scheduler_ack_plan(
+    before: dict[str, Any],
+    *,
+    agent_id: str | None,
+    state_key: str = CODEX_APP_STATEFUL_BACKOFF_STATE_KEY,
+    applied_rrule: str | None = None,
+    reset_token: str | None = None,
+    identity_signature: str | None = None,
+) -> dict[str, Any]:
+    safe_agent_id = str(agent_id or "").strip()
+    scheduler_hint, codex_app, stateful_backoff = scheduler_backoff_packet(before)
+    if not safe_agent_id:
+        return {
+            "ok": False,
+            "reason": "`loopx quota scheduler-ack` requires --agent-id",
+        }
+    if not stateful_backoff:
+        return {
+            "ok": False,
+            "reason": "current quota decision has no Codex App stateful scheduler packet",
+        }
+    if str(stateful_backoff.get("state_key") or "") != state_key:
+        return {
+            "ok": False,
+            "reason": "--state-key does not match scheduler_hint.codex_app.stateful_backoff.state_key",
+        }
+    if reset_token and str(reset_token).strip() != str(
+        stateful_backoff.get("reset_token") or ""
+    ):
+        return {
+            "ok": False,
+            "reason": "--reset-token does not match the current scheduler hint",
+        }
+    if identity_signature and str(identity_signature).strip() != str(
+        stateful_backoff.get("identity_signature") or ""
+    ):
+        return {
+            "ok": False,
+            "reason": "--identity-signature does not match the current scheduler hint",
+        }
+    safe_applied_rrule = normalize_scheduler_rrule(applied_rrule)
+    apply_needed = stateful_backoff.get("apply_needed") is True
+    ack_needed = stateful_backoff.get("ack_needed") is True
+    if not apply_needed and not ack_needed:
+        return {
+            "ok": True,
+            "already_applied": True,
+            "applied_rrule": safe_applied_rrule,
+        }
+    if not safe_applied_rrule:
+        return {
+            "ok": False,
+            "reason": "`loopx quota scheduler-ack` requires --applied-rrule when an ack is needed",
+        }
+    acceptance = _scheduler_ack_rrule_acceptance(
+        scheduler_hint,
+        codex_app,
+        stateful_backoff,
+        applied_rrule=safe_applied_rrule,
+        reset_token=reset_token,
+        identity_signature=identity_signature,
+    )
+    if not acceptance.get("ok"):
+        return {
+            "ok": False,
+            "reason": str(
+                acceptance.get("reason") or "scheduler ack RRULE validation failed"
+            ),
+        }
+    result = {
+        "ok": True,
+        "already_applied": False,
+        "applied_rrule": acceptance["applied_rrule"],
+        "expected_rrule": acceptance["expected_rrule"],
+    }
+    if ack_needed and not apply_needed:
+        result["host_match_ack"] = True
+    if acceptance.get("stale_hint_accepted"):
+        result["stale_hint_accepted"] = True
+        result["stale_hint_tolerance_minutes"] = acceptance.get(
+            "stale_hint_tolerance_minutes"
+        )
+    return result
+
+
+def _int_number(value: Any, *, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def build_codex_app_scheduler_ack_event(
+    before: dict[str, Any],
+    *,
+    agent_id: str | None,
+    applied_rrule: str,
+    classification: str = "quota_scheduler_ack",
+    surface: str = CODEX_APP_SURFACE,
+    state_key: str = CODEX_APP_STATEFUL_BACKOFF_STATE_KEY,
+    reset_token: str | None = None,
+    identity_signature: str | None = None,
+    generated_at: str | None = None,
+    reason_summary: str | None = None,
+    compact_before: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    safe_agent_id = str(agent_id or "").strip()
+    if not safe_agent_id:
+        raise ValueError("quota scheduler-ack requires a scoped --agent-id")
+    scheduler_hint, codex_app, stateful_backoff = scheduler_backoff_packet(before)
+    if not stateful_backoff:
+        raise ValueError(
+            "quota scheduler-ack requires scheduler_hint.codex_app.stateful_backoff"
+        )
+    if str(stateful_backoff.get("state_key") or "") != state_key:
+        raise ValueError(
+            "quota scheduler-ack state_key does not match current quota scheduler hint"
+        )
+    if (
+        stateful_backoff.get("apply_needed") is not True
+        and stateful_backoff.get("ack_needed") is not True
+    ):
+        raise ValueError(
+            "quota scheduler-ack is not needed because the current RRULE is already applied"
+        )
+    safe_applied_rrule = normalize_scheduler_rrule(applied_rrule)
+    acceptance = _scheduler_ack_rrule_acceptance(
+        scheduler_hint,
+        codex_app,
+        stateful_backoff,
+        applied_rrule=safe_applied_rrule,
+        reset_token=reset_token,
+        identity_signature=identity_signature,
+    )
+    if not acceptance.get("ok"):
+        raise ValueError(
+            str(acceptance.get("reason") or "scheduler ack RRULE validation failed")
+        )
+    expected_rrule = acceptance["expected_rrule"]
+    acknowledged_rrule = acceptance["applied_rrule"]
+    codex_progression = (
+        codex_app.get("example_progression_minutes")
+        if isinstance(codex_app.get("example_progression_minutes"), list)
+        else []
+    )
+    progression_minutes = (
+        stateful_backoff.get("progression_minutes")
+        if isinstance(stateful_backoff.get("progression_minutes"), list)
+        else codex_progression
+    )
+    progression_index = max(
+        0, _int_number(stateful_backoff.get("progression_index"), default=0)
+    )
+    safe_generated_at = generated_at or ""
+    retained_host_update_failures = [
+        failure
+        for failure in retained_scheduler_host_update_failures(
+            normalize_scheduler_host_update_failures(
+                stateful_backoff.get("host_update_failures"),
+                legacy_failure=stateful_backoff.get("host_update_failure"),
+            ),
+            reference_time=safe_generated_at,
+            observed_host_rrule=acknowledged_rrule,
+        )
+        if normalize_scheduler_rrule(failure.get("target_rrule")) != acknowledged_rrule
+    ]
+    scheduler_state = build_scheduler_state(
+        goal_id=before.get("goal_id"),
+        agent_id=safe_agent_id,
+        surface=surface,
+        state_key=state_key,
+        reset_token=stateful_backoff.get("reset_token"),
+        identity_signature=stateful_backoff.get("identity_signature"),
+        progression_index=progression_index,
+        progression_minutes=progression_minutes,
+        last_applied_rrule=acknowledged_rrule,
+        updated_at=safe_generated_at,
+        source=classification,
+        host_update_failure=(
+            retained_host_update_failures[-1] if retained_host_update_failures else None
+        ),
+        host_update_failures=retained_host_update_failures or None,
+    )
+    reason = str(reason_summary or "").strip() or (
+        f"acknowledged Codex App scheduler RRULE {acknowledged_rrule}; no quota spend"
+    )
+    scheduler_ack_event = {
+        "event_type": classification,
+        "surface": surface,
+        "state_key": state_key,
+        "applied_rrule": acknowledged_rrule,
+        "before": compact_before if isinstance(compact_before, dict) else before,
+        "scheduler_state": scheduler_state,
+    }
+    if acceptance.get("stale_hint_accepted"):
+        scheduler_ack_event["expected_rrule"] = expected_rrule
+        scheduler_ack_event["stale_hint_accepted"] = True
+        scheduler_ack_event["stale_hint_tolerance_minutes"] = acceptance.get(
+            "stale_hint_tolerance_minutes"
+        )
+    return {
+        "generated_at": safe_generated_at,
+        "goal_id": before.get("goal_id"),
+        "classification": classification,
+        "agent_id": safe_agent_id,
+        "recommended_action": reason,
+        "health_check": "scheduler ack state updated; no quota spend",
+        "delivery_outcome": DeliveryOutcome.SURFACE_ONLY.value,
+        "scheduler_ack_event": scheduler_ack_event,
+    }

loopx/control_plane/scheduler/arbitration.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from ..work_items.interaction_contract import INTERACTION_CONTRACT_SCHEMA_VERSION
+
+
+SCHEDULER_ARBITRATION_SCHEMA_VERSION = "scheduler_arbitration_v0"
+
+
+class SchedulerDisposition(str, Enum):
+    TERMINAL_STOP = "terminal_stop"
+    PEER_COORDINATION_STOP = "peer_coordination_stop"
+    AGENT_MONITOR_ONLY_WAIT = "agent_monitor_only_wait"
+    ACTIVE_WORK = "active_work"
+    AGENT_SCOPE_WAIT = "agent_scope_wait"
+    CONSISTENCY_REPAIR = "consistency_repair"
+    HUMAN_GATE = "human_gate"
+    MONITOR_WAIT = "monitor_wait"
+    QUIET_WAIT = "quiet_wait"
+    UNCHANGED_WAIT = "unchanged_wait"
+
+
+@dataclass(frozen=True)
+class SchedulerArbitration:
+    disposition: SchedulerDisposition
+    reason_code: str
+    mode: str
+    errors: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def consistency_error(self) -> dict[str, Any] | None:
+        if self.ok:
+            return None
+        return {
+            "schema_version": SCHEDULER_ARBITRATION_SCHEMA_VERSION,
+            "reason_code": self.reason_code,
+            "mode": self.mode or None,
+            "errors": list(self.errors),
+            "repair_action": (
+                "rebuild interaction_contract from the current quota decision, "
+                "then rerun quota before applying scheduler cadence"
+            ),
+        }
+
+
+def _mapping(value: Any) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _required_bool(
+    source: Mapping[str, Any],
+    field: str,
+    *,
+    error_prefix: str,
+    errors: list[str],
+) -> bool:
+    value = source.get(field)
+    if type(value) is not bool:
+        errors.append(f"{error_prefix}.{field}_must_be_boolean")
+        return False
+    return value
+
+
+def _classify_disposition(
+    *,
+    mode: str,
+    user_required: bool,
+    must_attempt: bool,
+    quiet_noop_allowed: bool,
+    agent_scope_frontier_actions: Collection[str],
+) -> tuple[SchedulerDisposition, str]:
+    agent_scope_modes = {str(value) for value in agent_scope_frontier_actions}
+    if mode == "terminal_no_followup":
+        return SchedulerDisposition.TERMINAL_STOP, mode
+    if mode == "peer_coordination_blocked":
+        return SchedulerDisposition.PEER_COORDINATION_STOP, mode
+    if mode == "agent_monitor_only":
+        return SchedulerDisposition.AGENT_MONITOR_ONLY_WAIT, mode
+    if user_required and not must_attempt:
+        return SchedulerDisposition.HUMAN_GATE, "interaction_blocking_user_gate"
+    if mode == "monitor_quiet_skip":
+        return SchedulerDisposition.MONITOR_WAIT, "interaction_monitor_quiet_wait"
+    if mode == "successor_replan_required" and must_attempt:
+        return SchedulerDisposition.ACTIVE_WORK, "interaction_successor_replan_required"
+    if mode in agent_scope_modes:
+        return SchedulerDisposition.AGENT_SCOPE_WAIT, "interaction_agent_scope_wait"
+    if mode == "mapped_noop_if_unchanged":
+        return SchedulerDisposition.UNCHANGED_WAIT, "interaction_unchanged_wait"
+    if must_attempt:
+        return SchedulerDisposition.ACTIVE_WORK, "interaction_agent_attempt_required"
+    if quiet_noop_allowed:
+        return SchedulerDisposition.QUIET_WAIT, "interaction_quiet_noop_allowed"
+    return SchedulerDisposition.QUIET_WAIT, "interaction_delivery_not_allowed"
+
+
+def build_scheduler_arbitration(
+    payload: Mapping[str, Any],
+    *,
+    agent_scope_frontier_actions: Collection[str] = (),
+) -> SchedulerArbitration:
+    """Derive scheduler authority from the final interaction contract.
+
+    Lower-level quota fields never participate in branch selection. Structural
+    contradictions inside the final contract fail closed to projection repair.
+    """
+
+    errors: list[str] = []
+    contract = _mapping(payload.get("interaction_contract"))
+    schema_version = contract.get("schema_version")
+    if schema_version != INTERACTION_CONTRACT_SCHEMA_VERSION:
+        errors.append("interaction_contract.schema_version_mismatch")
+
+    mode_value = contract.get("mode")
+    mode = str(mode_value or "").strip()
+    if not mode:
+        errors.append("interaction_contract.mode_missing")
+
+    user_channel = _mapping(contract.get("user_channel"))
+    agent_channel = _mapping(contract.get("agent_channel"))
+    if not user_channel:
+        errors.append("interaction_contract.user_channel_missing")
+    if not agent_channel:
+        errors.append("interaction_contract.agent_channel_missing")
+
+    user_required = _required_bool(
+        user_channel,
+        "action_required",
+        error_prefix="interaction_contract.user_channel",
+        errors=errors,
+    )
+    must_attempt = _required_bool(
+        agent_channel,
+        "must_attempt",
+        error_prefix="interaction_contract.agent_channel",
+        errors=errors,
+    )
+    delivery_allowed = _required_bool(
+        agent_channel,
+        "delivery_allowed",
+        error_prefix="interaction_contract.agent_channel",
+        errors=errors,
+    )
+    quiet_noop_allowed = _required_bool(
+        agent_channel,
+        "quiet_noop_allowed",
+        error_prefix="interaction_contract.agent_channel",
+        errors=errors,
+    )
+
+    if delivery_allowed and not must_attempt:
+        errors.append("interaction_contract.delivery_without_attempt")
+    if quiet_noop_allowed and (must_attempt or delivery_allowed or user_required):
+        errors.append("interaction_contract.quiet_noop_conflicts_with_required_action")
+    if mode in {
+        "terminal_no_followup",
+        "peer_coordination_blocked",
+        "agent_monitor_only",
+    } and (
+        user_required or must_attempt or delivery_allowed or not quiet_noop_allowed
+    ):
+        errors.append("interaction_contract.terminal_conflicts_with_open_action")
+    disposition, reason_code = _classify_disposition(
+        mode=mode,
+        user_required=user_required,
+        must_attempt=must_attempt,
+        quiet_noop_allowed=quiet_noop_allowed,
+        agent_scope_frontier_actions=agent_scope_frontier_actions,
+    )
+
+    if errors:
+        return SchedulerArbitration(
+            disposition=SchedulerDisposition.CONSISTENCY_REPAIR,
+            reason_code="scheduler_interaction_contract_inconsistent",
+            mode=mode,
+            errors=tuple(dict.fromkeys(errors)),
+        )
+    return SchedulerArbitration(
+        disposition=disposition,
+        reason_code=reason_code,
+        mode=mode,
+    )

loopx/control_plane/scheduler/automation_liveness.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..agents.agent_scope_frontier import (
+    AgentScopeFrontierAction,
+    agent_scope_frontier_action as _agent_scope_frontier_action,
+)
+from ..goals.goal_frontier import AUTONOMOUS_REPLAN_REQUIRED_MODE
+
+
+AUTOMATION_LIVENESS_SCHEMA_VERSION = "automation_liveness_v0"
+
+
+def build_automation_liveness(payload: dict[str, Any]) -> dict[str, Any]:
+    heartbeat_recommendation = (
+        payload.get("heartbeat_recommendation")
+        if isinstance(payload.get("heartbeat_recommendation"), dict)
+        else {}
+    )
+    execution_obligation = (
+        payload.get("execution_obligation")
+        if isinstance(payload.get("execution_obligation"), dict)
+        else {}
+    )
+    effective_action = str(payload.get("effective_action") or "")
+    recommended_mode = str(heartbeat_recommendation.get("recommended_mode") or "")
+    must_attempt_work = bool(execution_obligation.get("must_attempt_work"))
+
+    base = {
+        "schema_version": AUTOMATION_LIVENESS_SCHEMA_VERSION,
+        "keep_active": True,
+        "pause_allowed": False,
+        "pause_policy": (
+            "pause/delete only after a bounded self-repair or replan path is itself "
+            "stuck for two more eligible turns"
+        ),
+    }
+    if recommended_mode == "quota_paused":
+        return {
+            **base,
+            "keep_active": False,
+            "pause_allowed": True,
+            "pause_policy": (
+                "pause or delete the recurring automation now; only an explicit "
+                "quota resume with quota.compute > 0 should recreate or resume it"
+            ),
+            "automation_action": "stop_quota_paused",
+            "reason": "Goal-level compute quota is paused",
+            "next_trigger": "explicit quota resume with quota.compute > 0",
+            "spend_policy": "no quota spend for paused automation shutdown",
+        }
+    if effective_action == "agent_monitor_only":
+        return {
+            **base,
+            "keep_active": True,
+            "pause_allowed": False,
+            "pause_policy": (
+                "keep a quiet monitor/reply poll; do not start advancement, "
+                "autonomous replan, repair, or fallback work until mode changes"
+            ),
+            "automation_action": "keep_active_monitor_only",
+            "reason": "agent monitor-only mode suppresses advancement work",
+            "next_trigger": (
+                "due monitor, material monitor transition, verified direct operator "
+                "reply, or explicit work-mode change"
+            ),
+            "spend_policy": "no quota spend without a validated material transition",
+        }
+    if effective_action == "terminal_no_followup":
+        return {
+            **base,
+            "keep_active": False,
+            "pause_allowed": True,
+            "pause_policy": (
+                "pause or delete the recurring automation now; only an explicit "
+                "goal resume or new projected work should recreate it"
+            ),
+            "automation_action": "stop_terminal_no_followup",
+            "reason": (
+                "validated closure evidence derives no-follow-up from complete todo "
+                "sources and an empty normalized frontier"
+            ),
+            "next_trigger": "explicit goal resume or newly projected work",
+            "spend_policy": "no quota spend for terminal automation shutdown",
+        }
+    if (
+        effective_action == "monitor_quiet_skip"
+        or recommended_mode == "monitor_quiet_until_material_transition"
+    ):
+        return {
+            **base,
+            "automation_action": "keep_active_quiet",
+            "reason": (
+                "monitor-only quiet skip is a liveness-preserving no-op, not a "
+                "self-stop signal"
+            ),
+            "next_trigger": (
+                "material monitor transition, regression, concrete blocker, or "
+                f"{AUTONOMOUS_REPLAN_REQUIRED_MODE}"
+            ),
+            "spend_policy": "no quota spend for unchanged monitor-only polls",
+        }
+    if effective_action == "automation_prompt_upgrade_required":
+        return {
+            **base,
+            "automation_action": "repair_automation_prompt_identity",
+            "reason": (
+                "the installed automation is stale or unscoped; keep the automation "
+                "active but block delivery until it reruns with a registered agent id"
+            ),
+            "spend_policy": "no quota spend for identity prompt upgrade preflight",
+        }
+    if effective_action == AgentScopeFrontierAction.SUCCESSOR_REPLAN_REQUIRED.value:
+        agent_scope_frontier = (
+            payload.get("agent_scope_frontier")
+            if isinstance(payload.get("agent_scope_frontier"), dict)
+            else {}
+        )
+        if agent_scope_frontier.get("monitor_blocked_resume_candidates"):
+            return {
+                **base,
+                "automation_action": "execute_bounded_work",
+                "reason": (
+                    "a current-agent advancement todo is gated by an open standing "
+                    "monitor; repair the gate model before another quiet no-op"
+                ),
+                "next_trigger": "standing monitor gate repair writeback or fresh quota guard",
+                "spend_policy": "spend once only after validated gate repair/todo writeback",
+            }
+        return {
+            **base,
+            "automation_action": "execute_bounded_work",
+            "reason": (
+                "a ready deferred successor is visible to this agent; run a bounded "
+                "successor replan or write a no-follow-up rationale before another quiet no-op"
+            ),
+            "next_trigger": "deferred successor replan writeback or fresh quota guard",
+            "spend_policy": "spend once only after validated successor replan/todo writeback",
+        }
+    if _agent_scope_frontier_action(effective_action) is not None:
+        return {
+            **base,
+            "automation_action": "keep_active_quiet",
+            "reason": (
+                "the current agent has no in-scope runnable candidate; this is a "
+                "liveness-preserving no-op until work is reassigned or projected"
+            ),
+            "next_trigger": (
+                "handoff owner progress, reassignment, or a current-agent/unclaimed "
+                "advancement todo"
+            ),
+            "spend_policy": "no quota spend for agent-scoped no-candidate checks",
+        }
+    if must_attempt_work or recommended_mode == AUTONOMOUS_REPLAN_REQUIRED_MODE:
+        return {
+            **base,
+            "automation_action": "execute_bounded_work",
+            "reason": (
+                "execution_obligation requires a bounded progress or replan segment "
+                "before another quiet no-op"
+            ),
+            "spend_policy": "spend once only after validation and durable writeback",
+        }
+    if recommended_mode == "mapped_noop_if_unchanged":
+        return {
+            **base,
+            "automation_action": "keep_active_noop_if_unchanged",
+            "reason": (
+                "unchanged mapped state should stay quiet and active until new evidence "
+                "or a concrete safe handoff appears"
+            ),
+            "spend_policy": "no quota spend for unchanged mapped no-op checks",
+        }
+    return {
+        **base,
+        "automation_action": "keep_active",
+        "reason": "heartbeat liveness should be preserved unless the repair path is stuck",
+        "spend_policy": (
+            "follow heartbeat_recommendation; spend only after validated delivery or "
+            "safe-bypass writeback"
+        ),
+    }