agentic-devtools 0.2.577__py3-none-any.whl → 0.2.579__py3-none-any.whl

agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-admission/SKILL.md

@@ -18,17 +18,22 @@ smallest safe admission set needed to restore that target.
 ## Entry gate
 
 Before reading queue state, reserving admission budget, or dispatching any implementation handoff,
-verify an explicit handoff from the separately approved mutation-capable extension. The handoff must
-identify this admission role, authorize `drain` or `maintain` mode, and include a verified
-supervisor run and checkpoint context. If any authorization, mode, or handoff field is missing,
-contradictory, or unverified, return `blocked` without setup; the report-only `audit` baseline never
-authorizes this entrypoint.
+verify an explicit handoff from the separately approved mutation-capable extension. The local
+supervision host rooted at `6b1d128d-eef2-4f23-9576-81b56da1c314` may enter without a lease only
+after its trusted, unedited control-issue comment passes the pure host-handoff verifier. All other
+callers retain the existing singleton-lease route; a copied root-session ID or payload never grants
+that exception. Do not call the verifier in GitHub Actions, where the comment writer is
+`github-actions[bot]` under the bookkeeping credential. If the applicable handoff or lease is
+missing, contradictory, or unverified, return `blocked` without setup; the report-only `audit`
+baseline never authorizes this entrypoint.
 
 ## Procedure
 
 1. Validate the entry handoff and return `blocked` before setup when it does not authorize `drain` or
    `maintain` mode.
-2. Recount eligible open PRs and read the global budget counters under the orchestrator lease.
+2. Recount eligible open PRs and read global budget counters. A lease is required for callers outside
+   the verified local-host exception; preserve the existing reservation and capacity rechecks for
+   every route.
 3. Revalidate carried-over candidate records with the current run's evidence and dedup marker
    before ranking them; a prior-run origin alone is not a reason to block or discard a candidate.
    Rank confirmed issues by security, authorization, data-loss, and correctness impact; then user

agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-orchestration/SKILL.md

@@ -19,10 +19,15 @@ verdicts, provider receipts, budget usage, terminal reason, and a durable checkp
 
 ## Procedure
 
-1. Require a host-provided singleton supervision lease and capture its unique ID. Stop admitting
-   work after 50 minutes and release the lease at 55 minutes. If the host cannot acquire or release
-   the lease, return a blocked result before admitting work; this skill and the control CLI do not
-   implement lease mutations.
+1. For the local supervision host rooted at
+   `6b1d128d-eef2-4f23-9576-81b56da1c314`, accept the lease-free route only after verifying its
+   unedited control-issue handoff against the authenticated local GitHub CLI login. Resolve that
+   login with `_run_gh(["api", "user"])`, using `DEFAULT_CLASSIC_REPO_WORKFLOW_PAT` when configured
+   and otherwise the ambient `gh` credential; pass only that verified    login to the verifier. A copied root-session ID or payload does not grant the exception. Do not
+   call the verifier in GitHub Actions, where the writer is `github-actions[bot]` using the
+   bookkeeping credential. Every other caller must acquire the existing singleton supervision
+   lease. Stop admitting work after 50 minutes; release an acquired lease by 55 minutes. If a
+   required lease cannot be acquired or released, return a blocked result before further work.
 2. Delegate shared live workflow and queue evidence collection to the
    `ai-pr-loop-workflow-monitor` skill. Use its result and shared workflow-monitor record for current
    workflow runs, managed-PR ordering, and the expected next run; then reconstruct issue, task, PR,
@@ -50,9 +55,9 @@ verdicts, provider receipts, budget usage, terminal reason, and a durable checkp
 6. If a required operation has no route above (including implementation-PR labeling), record a
    blocked result naming the missing mutation capability. Do not substitute a direct provider write
    or claim the operation succeeded.
-7. After lease acquisition, always release the lease on success, blocked, and error paths. Publish
-   the checkpoint through the control leaf only after all required issue-creation tasks have
-   completed and their created issues have been verified, then return before the lease deadline.
+7. If a lease was acquired, release it on success, blocked, and error paths. Publish the checkpoint
+   through the control leaf only after all required issue-creation tasks have completed and their
+   created issues have been verified, then return before the lease deadline when one applies.
 
 ## Safety boundaries
 

agentic_devtools/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.577'
-__version_tuple__ = version_tuple = (0, 2, 577)
+__version__ = version = '0.2.579'
+__version_tuple__ = version_tuple = (0, 2, 579)
 
 __commit_id__ = commit_id = None

agentic_devtools/cli/ci/approver_preflight.py

@@ -0,0 +1,145 @@
+"""Read-only approver evidence; repository role is not a token permission grant."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+from agentic_devtools.cli.ci.credential_roles import AGDT_PR_APPROVER_PAT
+from agentic_devtools.cli.ci.github_api_error import GitHubApiError
+from agentic_devtools.cli.ci.retry import _provider_rate_limit_error_from_retryable
+from agentic_devtools.cli.shared.retry import ProviderRateLimitError, RetryableError
+
+Capability = Literal["identity", "repository_visibility", "repository_role", "review_eligibility"]
+
+
+class EvidenceStatus(Enum):
+    """Whether a read-only capability has been established."""
+
+    VERIFIED = "verified"
+    MISSING = "missing"
+    DENIED = "denied"
+    UNAVAILABLE = "unavailable"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class CapabilityEvidence:
+    """Safe evidence; values are validated login or fixed repository-role names."""
+
+    status: EvidenceStatus = EvidenceStatus.UNKNOWN
+    value: str | None = None
+    http_status: int | None = None
+
+
+@dataclass(frozen=True)
+class ApproverPreflightResult:
+    """Independent evidence, with no inferred fine-grained review-write grant."""
+
+    identity: CapabilityEvidence = field(default_factory=CapabilityEvidence)
+    repository_visibility: CapabilityEvidence = field(default_factory=CapabilityEvidence)
+    repository_role: CapabilityEvidence = field(default_factory=CapabilityEvidence)
+    review_eligibility: CapabilityEvidence = field(default_factory=CapabilityEvidence)
+
+    @property
+    def authenticated_login(self) -> str | None:
+        """Return only an authenticated identity, irrespective of review eligibility."""
+        return self.identity.value if self.identity.status is EvidenceStatus.VERIFIED else None
+
+    @property
+    def blocking_capability(self) -> Capability | None:
+        """Return the first missing, denied, unavailable, or unknown requirement."""
+        if not self.identity.value:
+            return "identity"
+        capabilities: tuple[Capability, ...] = (
+            "identity",
+            "repository_visibility",
+            "repository_role",
+            "review_eligibility",
+        )
+        return next(
+            (name for name in capabilities if getattr(self, name).status is not EvidenceStatus.VERIFIED),
+            None,
+        )
+
+
+def _read_evidence(
+    request: Callable[..., str],
+    endpoint: str,
+    token: str,
+) -> tuple[dict[str, Any], CapabilityEvidence]:
+    """Read once, converting capability failures but preserving real cooldowns."""
+    try:
+        response = request(
+            endpoint,
+            method="GET",
+            token=token,
+            credential_identity=AGDT_PR_APPROVER_PAT,
+            read_pool=False,
+        )
+        data = json.loads(response)
+        if not isinstance(data, dict):
+            return {}, CapabilityEvidence()
+        return data, CapabilityEvidence(EvidenceStatus.VERIFIED, http_status=200)
+    except RetryableError as exc:
+        if exc.is_rate_limit:
+            raise _provider_rate_limit_error_from_retryable(exc) from exc
+        raise
+    except ProviderRateLimitError:
+        raise
+    except GitHubApiError as exc:
+        status = EvidenceStatus.DENIED if exc.http_status in {401, 403} else EvidenceStatus.UNAVAILABLE
+        return {}, CapabilityEvidence(status, http_status=exc.http_status)
+    except Exception:
+        # No raw response/exception text is a safe diagnostic at this boundary.
+        return {}, CapabilityEvidence()
+
+
+def _repository_role(data: dict[str, Any]) -> CapabilityEvidence:
+    """Read repository permissions without mistaking role for PAT write grants."""
+    permissions = data.get("permissions")
+    if not isinstance(permissions, dict):
+        return CapabilityEvidence()
+    for permission, role in (
+        ("admin", "admin"),
+        ("maintain", "maintain"),
+        ("push", "write"),
+        ("triage", "triage"),
+        ("pull", "read"),
+    ):
+        if permissions.get(permission) is True:
+            status = EvidenceStatus.VERIFIED if role in {"admin", "maintain", "write"} else EvidenceStatus.DENIED
+            return CapabilityEvidence(status, role, 200)
+    if all(permissions.get(key) is False for key in ("admin", "maintain", "push", "triage", "pull")):
+        return CapabilityEvidence(EvidenceStatus.DENIED, http_status=200)
+    return CapabilityEvidence()
+
+
+def collect_approver_preflight(
+    request: Callable[..., str],
+    base_repo_full_name: str,
+    token: str,
+) -> ApproverPreflightResult:
+    """Collect GET-only evidence for the actual base repository, without retries."""
+    if not token.strip():
+        return ApproverPreflightResult(identity=CapabilityEvidence(EvidenceStatus.MISSING))
+    data, identity = _read_evidence(request, "/user", token)
+    if identity.status is EvidenceStatus.VERIFIED:
+        login = data.get("login")
+        identity = (
+            CapabilityEvidence(EvidenceStatus.VERIFIED, login, 200)
+            if isinstance(login, str) and re.fullmatch(r"[A-Za-z0-9_-]+(?:\[bot\])?", login)
+            else CapabilityEvidence()
+        )
+    if identity.status is not EvidenceStatus.VERIFIED:
+        return ApproverPreflightResult(identity=identity)
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9-]*/(?!\.\.?$)[A-Za-z0-9_.-]+", base_repo_full_name):
+        return ApproverPreflightResult(identity=identity)
+    repository, visibility = _read_evidence(request, f"/repos/{base_repo_full_name}", token)
+    role = _repository_role(repository) if visibility.status is EvidenceStatus.VERIFIED else CapabilityEvidence()
+    # No authoritative read-only source for effective review eligibility is established.
+    return ApproverPreflightResult(identity, visibility, role)

agentic_devtools/cli/ci/github_api_error.py

@@ -0,0 +1,20 @@
+"""Safe, non-retryable GitHub API failures."""
+
+from __future__ import annotations
+
+import re
+
+
+def parse_bare_http_status(stderr: str) -> int | None:
+    """Accept a leading CLI HTTP error code, never incidental URL/identifier digits."""
+    match = re.match(r"([45]\d{2})\b", stderr)
+    return int(match.group(1)) if match else None
+
+
+class GitHubApiError(RuntimeError):
+    """An API rejection with parsed status, never raw response or credential data."""
+
+    def __init__(self, http_status: int | None = None) -> None:
+        self.http_status = http_status
+        status = f"HTTP {http_status}" if http_status is not None else "status unavailable"
+        super().__init__(f"GitHub API error: {status}")

agentic_devtools/cli/ci/github_provider.py

@@ -26,6 +26,7 @@ from urllib.parse import quote
 from agentic_devtools.ai_providers.agent_tasks_payload import AGENT_TASKS_ENDPOINT_TEMPLATE
 from agentic_devtools.cli.ci import critique_adjudicator
 from agentic_devtools.cli.ci.agent_assignment import AgentAssignmentResult, assign_issue_to_agent
+from agentic_devtools.cli.ci.approver_preflight import ApproverPreflightResult, collect_approver_preflight
 from agentic_devtools.cli.ci.comment_format import (
     AI_PR_LOOP_COMMENT_LABEL,
     format_ai_pr_loop_comment,
@@ -45,6 +46,7 @@ from agentic_devtools.cli.ci.credential_roles import (
 from agentic_devtools.cli.ci.critique_provider import CritiqueProviderDispatch
 from agentic_devtools.cli.ci.exceptions import MalformedEventError
 from agentic_devtools.cli.ci.finalization_state import FinalizedReviewKey, PRCommentFinalizationStateStore
+from agentic_devtools.cli.ci.github_api_error import GitHubApiError, parse_bare_http_status
 from agentic_devtools.cli.ci.job_logs import UNKNOWN_STEP_SENTINEL
 from agentic_devtools.cli.ci.models import (
     COPILOT_COMMENT_LOGINS,
@@ -2455,9 +2457,7 @@ def _gh_api(
                 credential_identity=identity,
                 is_rate_limit=False,
             )
-        raise RuntimeError(
-            f"GitHub API error: {_sanitize_gh_error(stderr) if stderr else f'exit code {result.returncode}'}"
-        )
+        raise GitHubApiError(status if status is not None else parse_bare_http_status(stderr))
 
     return response_body
 
@@ -2905,6 +2905,7 @@ class GitHubActionsProvider(CIPlatformProvider):
         self._workflow_id_cache: dict[str, str | None] = {}
         self._cloud_writer_run_cache: dict[tuple[int, str, str, tuple[str, ...]], CloudWriterRunInventory] = {}
         self._approver_login_cache: str | None = None
+        self._approver_preflight_cache: dict[str, ApproverPreflightResult] = {}
         self._codeql_configured_cache: dict[tuple[str, str], bool] = {}
         self._pr_token_login_cache: str | None = None
         self._bookkeeping_token_login_cache: str | None = None
@@ -4230,24 +4231,24 @@ class GitHubActionsProvider(CIPlatformProvider):
             )
             return False
 
-        try:
-            _gh_api(
-                self._repo_api(f"/pulls/{pr_number}/reviews"),
-                method="POST",
-                body={"commit_id": head_sha, "event": "APPROVE", "body": body},
-                token=approver_token,
+        _gh_api(
+            self._repo_api(f"/pulls/{pr_number}/reviews"),
+            method="POST",
+            body={"commit_id": head_sha, "event": "APPROVE", "body": body},
+            token=approver_token,
+        )
+        return True
+
+    def get_approver_preflight(self, base_repo_full_name: str) -> ApproverPreflightResult:
+        """Cache read-only evidence by actual base repository for this provider run."""
+        if base_repo_full_name not in self._approver_preflight_cache:
+            result = collect_approver_preflight(
+                _gh_api,
+                base_repo_full_name,
+                os.environ.get(AGDT_PR_APPROVER_PAT, "").strip(),
             )
-            return True
-        except RuntimeError as exc:
-            stderr = str(exc)
-            if "401" in stderr or "Bad credentials" in stderr.lower():
-                logger.warning(
-                    "AGDT_PR_APPROVER_PAT authentication failed (401). "
-                    "The token may be expired or invalid. "
-                    "Skipping PR approval. Rotate the secret and retry."
-                )
-                return False
-            raise
+            self._approver_preflight_cache[base_repo_full_name] = result
+        return self._approver_preflight_cache[base_repo_full_name]
 
     def get_approver_login(self) -> str:
         """Return the GitHub login for the approver PAT identity.

agentic_devtools/cli/ci/pipeline/actions/approval_entry.py

@@ -0,0 +1,44 @@
+"""Focused approval-entry guards, before identity idempotency or review mutation."""
+
+from __future__ import annotations
+
+from agentic_devtools.cli.ci.approver_preflight import ApproverPreflightResult
+from agentic_devtools.cli.ci.pipeline.models import ActionDecision, ActionResult
+from agentic_devtools.cli.ci.pipeline.snapshot_models import DerivedState, PRStateSnapshot
+
+
+def preflight_block(preflight: ApproverPreflightResult | None) -> ActionResult | None:
+    """Render only fixed capability/status evidence through the existing summary."""
+    if preflight is None:
+        return None
+    capability = preflight.blocking_capability
+    if capability is None:
+        return None
+    evidence = getattr(preflight, capability)
+    status = f"HTTP {evidence.http_status}" if evidence.http_status is not None else "HTTP status unavailable"
+    return ActionResult(
+        name="approve",
+        decision=ActionDecision.BLOCKED,
+        preconditions={"approver_preflight": False},
+        details=f"Approver preflight blocked: {capability} ({evidence.status.value}; {status})",
+        capability=capability,
+        http_status=evidence.http_status,
+    )
+
+
+def approval_entry_guard(snapshot: PRStateSnapshot, derived: DerivedState) -> ActionResult | None:
+    """Check capabilities before any identity-based decision or live-HEAD guard."""
+    blocked = preflight_block(snapshot.approver_preflight)
+    if blocked is not None:
+        return blocked
+    provider = derived.get("provider")
+    if provider is not None:
+        live_head_sha = provider.get_pr_metadata(snapshot.pr_number).head_sha
+        if live_head_sha != snapshot.head_sha:
+            return ActionResult(
+                "approve",
+                ActionDecision.SKIP,
+                {"live_head_matches_snapshot": False},
+                f"PR HEAD moved from {snapshot.head_sha} to {live_head_sha}",
+            )
+    return None

agentic_devtools/cli/ci/pipeline/actions/approve.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import logging
 
+from agentic_devtools.cli.ci.github_api_error import GitHubApiError
+from agentic_devtools.cli.ci.pipeline.actions.approval_entry import approval_entry_guard, preflight_block
 from agentic_devtools.cli.ci.pipeline.gate_verdict import (
     copilot_review_gate_passed,
     suppressed_deferral_recorded,
@@ -30,18 +32,13 @@ class ApproveAction:
     Idempotency: when ``snapshot.approver_login`` is known (``AGDT_PR_APPROVER_PAT``
     resolved via ``GET /user``), the evaluate step short-circuits when that exact
     identity has already approved the current HEAD (``has_approver_approval_on_head``).
-    When the approver login cannot be resolved, the idempotency guard is skipped and
-    ``execute()`` is reached on every run. If the approver token is absent,
-    ``CIPlatformProvider.approve_pr()`` intentionally skips approval, so no duplicate
-    reviews are created. Duplicate approvals are only possible when the approver token
-    is configured and approval still succeeds, but resolving the login via ``GET /user``
-    failed (for example due to a transient API error). Configure ``AGDT_PR_APPROVER_PAT``
-    so the precise guard can fire and prevent re-approval.
+    Providers supporting read-only preflight must establish every required capability
+    before identity idempotency or approval submission. Unknown effective review
+    eligibility blocks approval, even when identity and repository role are known.
+    Providers without optional preflight retain their legacy login-only behavior.
 
-    The idempotency guard is keyed off the *precise* approver identity rather than a
-    generic non-Copilot approval check to avoid skipping the loop's own required
-    approval when a human reviewer has approved but is not the loop's approver PAT,
-    which would leave branch protection unsatisfied.
+    Idempotency uses the precise approver identity, not incidental human approvals,
+    so an unrelated review cannot satisfy the loop's required approval.
     """
 
     @property
@@ -52,17 +49,11 @@ class ApproveAction:
         """Evaluate whether approval should be submitted."""
         preconditions: dict[str, bool] = {}
 
-        provider = derived.get("provider")
-        if provider is not None:
-            live_head_sha = provider.get_pr_metadata(snapshot.pr_number).head_sha
-            preconditions["live_head_matches_snapshot"] = live_head_sha == snapshot.head_sha
-            if not preconditions["live_head_matches_snapshot"]:
-                return ActionResult(
-                    self.name,
-                    ActionDecision.SKIP,
-                    preconditions,
-                    f"PR HEAD moved from {snapshot.head_sha} to {live_head_sha}",
-                )
+        entry_result = approval_entry_guard(snapshot, derived)
+        if entry_result is not None:
+            return entry_result
+        if derived.get("provider") is not None:
+            preconditions["live_head_matches_snapshot"] = True
 
         loop_controller = derived.get("loop_controller")
         loop_state = derived.get("loop_state")
@@ -112,8 +103,8 @@ class ApproveAction:
 
         # Precise idempotency guard: skip only when the approver-PAT identity
         # (resolved at snapshot-build time via GET /user) has already approved the
-        # current HEAD. Falls through when approver_login is "" (PAT not configured
-        # or resolution failed) so that execute() remains the idempotency boundary.
+        # current HEAD. Optional preflight has already blocked unknown capabilities.
+        # Legacy providers without preflight retain the login-only path.
         if derived.has_approver_approval_on_head:
             preconditions["no_approver_approval_on_head"] = False
             return ActionResult(
@@ -219,6 +210,9 @@ class ApproveAction:
         derived: DerivedState,
     ) -> ActionResult:
         """Submit PR approval."""
+        blocked = preflight_block(snapshot.approver_preflight)
+        if blocked is not None:
+            return blocked
         try:
             live_head_sha = provider.get_pr_metadata(snapshot.pr_number).head_sha
             if live_head_sha != snapshot.head_sha:
@@ -232,6 +226,15 @@ class ApproveAction:
                 snapshot.head_sha,
                 "Auto-approved by AI PR loop",
             )
+        except GitHubApiError as exc:
+            return ActionResult(
+                name=self.name,
+                decision=ActionDecision.FAILED,
+                error=str(exc),
+                details="Review submission failed",
+                capability="review_submission",
+                http_status=exc.http_status,
+            )
         except Exception as exc:
             if isinstance(exc, ProviderRateLimitError) and exc.is_rate_limit:
                 raise

agentic_devtools/cli/ci/pipeline/models.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import TYPE_CHECKING
 
+from agentic_devtools.cli.ci.approver_preflight import ApproverPreflightResult as ApproverPreflightResult
+
 if TYPE_CHECKING:
     from agentic_devtools.cli.ci.pipeline.snapshot_models import PRStateSnapshot
 
@@ -50,6 +52,8 @@ class ActionResult:
         allows_file_removal: True only when the action explicitly confirms that
             removing a baseline file is intentional.
         allowed_removed_files: Baseline files that may be removed by this action.
+        capability: Stable capability identifier for approver preflight/submission.
+        http_status: Parsed HTTP status when available; never raw response data.
 
     """
 
@@ -69,6 +73,8 @@ class ActionResult:
     definitive_no_mutation: bool = False
     allows_file_removal: bool = False
     allowed_removed_files: tuple[str, ...] = ()
+    capability: str | None = None
+    http_status: int | None = None
 
 
 @dataclass

agentic_devtools/cli/ci/pipeline/snapshot_builder.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 
 import logging
 from dataclasses import replace
+from typing import Protocol, runtime_checkable
 
 from agentic_devtools.cli.ci.actionable_checks import get_actionable_check_names
+from agentic_devtools.cli.ci.approver_preflight import ApproverPreflightResult
 from agentic_devtools.cli.ci.models import PRMetadata, ReviewCommentInfo, ReviewInfo
 from agentic_devtools.cli.ci.pipeline import critique_snapshot
 from agentic_devtools.cli.ci.pipeline.gate_verdict import (
@@ -30,10 +32,37 @@ from agentic_devtools.cli.ci.pipeline.snapshot_reviews import (
 from agentic_devtools.cli.ci.pipeline.snapshot_thread_count import count_unresolved_prior_threads
 from agentic_devtools.cli.ci.pipeline.snapshot_utils import _raise_if_rate_limit, _supports_diff_fingerprint
 from agentic_devtools.cli.ci.provider import CIPlatformProvider
+from agentic_devtools.cli.ci.retry import _provider_rate_limit_error_from_retryable
+from agentic_devtools.cli.shared.retry import ProviderRateLimitError, RetryableError
 
 logger = logging.getLogger(__name__)
 
 
+@runtime_checkable
+class ApproverPreflightProvider(Protocol):
+    """Optional read-only approver evidence, independent of CIPlatformProvider."""
+
+    def get_approver_preflight(self, base_repo_full_name: str) -> ApproverPreflightResult:
+        """Return evidence for the actual PR base repository."""
+
+
+def _get_approver_preflight(provider: CIPlatformProvider, base_repo_full_name: str) -> ApproverPreflightResult | None:
+    """Fail closed for supported providers, preserving the existing cooldown path."""
+    if not isinstance(provider, ApproverPreflightProvider):
+        return None
+    try:
+        result = provider.get_approver_preflight(base_repo_full_name)
+        return result if isinstance(result, ApproverPreflightResult) else ApproverPreflightResult()
+    except RetryableError as exc:
+        if exc.is_rate_limit:
+            raise _provider_rate_limit_error_from_retryable(exc) from exc
+        raise
+    except ProviderRateLimitError:
+        raise
+    except Exception:
+        return ApproverPreflightResult()
+
+
 def _get_head_author(provider: CIPlatformProvider, head_sha: str) -> str:
     """Resolve the head author login, failing open when the provider lookup fails."""
     try:
@@ -166,12 +195,13 @@ def _get_approval_state(
     pr_number: int,
     reviews: list[ReviewInfo],
     head_sha: str,
+    preflight: ApproverPreflightResult | None = None,
 ) -> tuple[bool, str, bool]:
     """Return approval status on HEAD and the best-effort approver identity."""
     effective_reviews = get_effective_head_reviews(reviews, head_sha)
     has_approval = any(review.state == "APPROVED" for review in effective_reviews)
     try:
-        raw_login = provider.get_approver_login()
+        raw_login = preflight.authenticated_login if preflight is not None else provider.get_approver_login()
         approver_login = raw_login if isinstance(raw_login, str) else ""
     except Exception as exc:
         _raise_if_rate_limit(exc)
@@ -275,6 +305,7 @@ def build_pr_state_snapshot(
     if actionable_check_names is None:
         actionable_check_names = get_actionable_check_names()
     pr_meta = provider.get_pr_metadata(pr_number)
+    preflight = _get_approver_preflight(provider, pr_meta.base_repo_full_name)
     head_author_login = _get_head_author(provider, pr_meta.head_sha)
     files, base_sha, diff_hash, diff_hash_supported, diff_hash_available = _collect_diff_state(
         provider, pr_number, pr_meta
@@ -303,6 +334,7 @@ def build_pr_state_snapshot(
         pr_number,
         reviews,
         pr_meta.head_sha,
+        preflight,
     )
     copilot_review, copilot_review_state, copilot_review_id, copilot_review_inline_count, comments = (
         _get_copilot_review(
@@ -326,7 +358,6 @@ def build_pr_state_snapshot(
         pr_meta.base_branch,
         promotion_failure,
     )
-    effective_verdict_review_id = copilot_gate_verdict.review_id if copilot_gate_verdict.review_id > 0 else None
     (
         unresolved_threads,
         repairable_threads,
@@ -336,7 +367,7 @@ def build_pr_state_snapshot(
         provider,
         pr_number,
         reviews,
-        effective_verdict_review_id,
+        copilot_gate_verdict.review_id if copilot_gate_verdict.review_id > 0 else None,
         verdict=copilot_gate_verdict,
     )
     head_changed_since_review = _head_changed_since_effective_gate_review(
@@ -413,6 +444,7 @@ def build_pr_state_snapshot(
             critique_fields = replace(critique_fields, critique_task_state_available=False)
 
     return PRStateSnapshot(
+        approver_preflight=preflight,
         pr_number=pr_number,
         pr_id=pr_meta.pr_id,
         head_sha=pr_meta.head_sha,

agentic_devtools/cli/ci/pipeline/snapshot_models.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any
 
+from agentic_devtools.cli.ci.approver_preflight import ApproverPreflightResult
 from agentic_devtools.cli.ci.models import CheckRunStatus, ReviewInfo
 from agentic_devtools.cli.ci.pipeline.critique_snapshot import CritiqueSnapshotFields
 from agentic_devtools.cli.ci.pipeline.gate_verdict import CopilotGateVerdict
@@ -78,6 +79,8 @@ class PRStateSnapshot(CritiqueSnapshotFields):
             ``GET /user`` with ``AGDT_PR_APPROVER_PAT``).  Empty string when the token
             is not configured or login resolution failed.  Used together with
             ``has_approver_approval_on_head`` for precise approve-action idempotency.
+        approver_preflight: Read-only capability evidence for the actual base repository.
+            ``None`` only for providers without the optional preflight capability.
         has_approver_approval_on_head: Whether the approver-PAT identity has already
             approved the current HEAD.  Computed from ``approver_login`` and the
             effective HEAD reviews — only ``True`` when ``approver_login`` is non-empty,
@@ -128,6 +131,7 @@ class PRStateSnapshot(CritiqueSnapshotFields):
     """
 
     pr_number: int = 0
+    approver_preflight: ApproverPreflightResult | None = field(default=None, kw_only=True)
     pr_id: int | None = field(default=None, kw_only=True)
     head_sha: str = ""
     base_branch: str = ""

agentic_devtools/cli/ci/supervision_host_handoff.py

@@ -0,0 +1,358 @@
+"""Pure validation of authorized local supervision-host admission handoffs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Collection, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from types import MappingProxyType
+
+from agentic_devtools._bundled_skills.skills.fingerprint import canonicalize_json
+from agentic_devtools.cli.ci.comment_format import normalize_ai_pr_loop_comment
+
+HOST_ROOT_SESSION_ID = "6b1d128d-eef2-4f23-9576-81b56da1c314"
+HOST_HANDOFF_MARKER = "<!-- ai-pr-loop-host-handoff:v1 -->"
+_MARKER_NAMESPACE = "ai-pr-loop-host-handoff"
+_AI_PR_LOOP_LABEL = "🤖 AI PR Loop ·"
+_FIELDS = frozenset(
+    {
+        "repository",
+        "target",
+        "admission_role",
+        "mode",
+        "supervisor_run_id",
+        "checkpoint",
+        "host_root_session",
+        "issued_at",
+        "expires_at",
+        "fingerprint",
+    }
+)
+_EXPECTED_FIELDS = frozenset({"repository", "role", "mode", "supervisor_run_id", "checkpoint"})
+_REPOSITORY_PATTERN = re.compile(r"[^/\s]+/[^/\s]+")
+_FINGERPRINT_PATTERN = re.compile(r"[0-9a-f]{64}")
+_UTC_TIMESTAMP_PATTERN = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.([0-9]+))?Z")
+_COMMENT_TIMESTAMP_PATTERN = re.compile(
+    r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})"
+)
+_MAX_LIFETIME_SECONDS = 55 * 60
+
+
+class HostHandoffRejectionReason(StrEnum):
+    """Distinct fail-closed outcomes for host handoff verification."""
+
+    NO_RECORD = "no_record"
+    UNTRUSTED_AUTHOR = "untrusted_author"
+    EDITED_COMMENT = "edited_comment"
+    MALFORMED_MARKER = "malformed_marker"
+    MALFORMED_COMMENT_NODE = "malformed_comment_node"
+    MALFORMED_JSON = "malformed_json"
+    DUPLICATE_JSON_KEY = "duplicate_json_key"
+    UNKNOWN_FIELD = "unknown_field"
+    MISSING_FIELD = "missing_field"
+    INVALID_FIELD_TYPE = "invalid_field_type"
+    NONCANONICAL_JSON = "noncanonical_json"
+    TARGET_MISMATCH = "target_mismatch"
+    REPOSITORY_MISMATCH = "repository_mismatch"
+    ROLE_MISMATCH = "role_mismatch"
+    MODE_MISMATCH = "mode_mismatch"
+    SUPERVISOR_RUN_MISMATCH = "supervisor_run_mismatch"
+    CHECKPOINT_MISMATCH = "checkpoint_mismatch"
+    WRONG_HOST_ROOT_SESSION = "wrong_host_root_session"
+    INVALID_TIMESTAMP = "invalid_timestamp"
+    FUTURE_ISSUED_AT = "future_issued_at"
+    STALE_RECORD = "stale_record"
+    LIFETIME_EXCEEDED = "lifetime_exceeded"
+    FINGERPRINT_MISMATCH = "fingerprint_mismatch"
+    MULTIPLE_MATCHING_RECORDS = "multiple_matching_records"
+
+
+_STRUCTURAL_ORDER = (
+    HostHandoffRejectionReason.MALFORMED_MARKER,
+    HostHandoffRejectionReason.MALFORMED_COMMENT_NODE,
+    HostHandoffRejectionReason.DUPLICATE_JSON_KEY,
+    HostHandoffRejectionReason.MALFORMED_JSON,
+    HostHandoffRejectionReason.UNKNOWN_FIELD,
+    HostHandoffRejectionReason.MISSING_FIELD,
+    HostHandoffRejectionReason.INVALID_FIELD_TYPE,
+    HostHandoffRejectionReason.NONCANONICAL_JSON,
+)
+_MISMATCH_ORDER = (
+    HostHandoffRejectionReason.REPOSITORY_MISMATCH,
+    HostHandoffRejectionReason.TARGET_MISMATCH,
+    HostHandoffRejectionReason.ROLE_MISMATCH,
+    HostHandoffRejectionReason.MODE_MISMATCH,
+    HostHandoffRejectionReason.SUPERVISOR_RUN_MISMATCH,
+    HostHandoffRejectionReason.CHECKPOINT_MISMATCH,
+)
+_VALIDATION_ORDER = (
+    HostHandoffRejectionReason.WRONG_HOST_ROOT_SESSION,
+    HostHandoffRejectionReason.EDITED_COMMENT,
+    HostHandoffRejectionReason.INVALID_TIMESTAMP,
+    HostHandoffRejectionReason.FUTURE_ISSUED_AT,
+    HostHandoffRejectionReason.STALE_RECORD,
+    HostHandoffRejectionReason.LIFETIME_EXCEEDED,
+    HostHandoffRejectionReason.FINGERPRINT_MISMATCH,
+)
+
+
+@dataclass(frozen=True)
+class VerifyHostHandoffResult:
+    """Accepted handoff payload or its deterministic rejection reason."""
+
+    accepted: bool
+    reason: HostHandoffRejectionReason | None
+    payload: Mapping[str, str] | None
+
+
+class _HostHandoffVerifier:
+    """Validate candidate records after the host boundary has been established."""
+
+    def __init__(self, expected: Mapping[str, str], trusted_authors: set[str], now: tuple[int, str]) -> None:
+        self.expected = expected
+        self.trusted_authors = trusted_authors
+        self.now = now
+        self.epoch = datetime(1970, 1, 1, tzinfo=UTC)
+
+    def _parse_timestamp(self, value: str) -> tuple[int, str] | None:
+        match = _UTC_TIMESTAMP_PATTERN.fullmatch(value)
+        if match is None:
+            return None
+        try:
+            whole_seconds = datetime.strptime(value[:19], "%Y-%m-%dT%H:%M:%S").replace(tzinfo=UTC)
+        except ValueError:
+            return None
+        delta = whole_seconds - self.epoch
+        return delta.days * 86400 + delta.seconds, (match.group(1) or "").rstrip("0")
+
+    @staticmethod
+    def _valid_comment_timestamp(value: str) -> bool:
+        if _COMMENT_TIMESTAMP_PATTERN.fullmatch(value) is None:
+            return False
+        try:
+            parsed = datetime.fromisoformat(value[:-1] + "+00:00" if value.endswith("Z") else value)
+        except ValueError:
+            return False
+        return parsed.tzinfo is not None and parsed.utcoffset() is not None
+
+    @staticmethod
+    def _unwrap_body(body: str) -> tuple[str, HostHandoffRejectionReason | None]:
+        normalized = normalize_ai_pr_loop_comment(body)
+        if normalized is None or normalized == body:
+            return "", HostHandoffRejectionReason.MALFORMED_MARKER
+        lines = normalized.split("\n")
+        if (
+            "\r" in normalized
+            or len(lines) != 2
+            or lines[0] != HOST_HANDOFF_MARKER
+            or not body.endswith(f"\n\n{_AI_PR_LOOP_LABEL}")
+        ):
+            return "", HostHandoffRejectionReason.MALFORMED_MARKER
+        return lines[1], None
+
+    def _validate_payload(self, json_text: str, payload: dict[str, object]) -> HostHandoffRejectionReason | None:
+        if set(payload) - _FIELDS:
+            return HostHandoffRejectionReason.UNKNOWN_FIELD
+        if _FIELDS - set(payload):
+            return HostHandoffRejectionReason.MISSING_FIELD
+        fingerprint = payload["fingerprint"]
+        if (
+            any(type(value) is not str for value in payload.values())
+            or not isinstance(fingerprint, str)
+            or _FINGERPRINT_PATTERN.fullmatch(fingerprint) is None
+        ):
+            return HostHandoffRejectionReason.INVALID_FIELD_TYPE
+        try:
+            canonical_text = canonicalize_json(payload).decode("utf-8")
+        except TypeError, ValueError:
+            return HostHandoffRejectionReason.NONCANONICAL_JSON
+        return None if json_text == canonical_text else HostHandoffRejectionReason.NONCANONICAL_JSON
+
+    def _parse_payload(
+        self,
+        json_text: str,
+    ) -> tuple[dict[str, str], HostHandoffRejectionReason | None]:
+        duplicate_keys: list[str] = []
+
+        def unique_members(pairs: list[tuple[str, object]]) -> dict[str, object]:
+            result: dict[str, object] = {}
+            for key, value in pairs:
+                if key in result:
+                    duplicate_keys.append(key)
+                result[key] = value
+            return result
+
+        try:
+            parsed: object = json.loads(json_text, object_pairs_hook=unique_members)
+        except json.JSONDecodeError:
+            return {}, (
+                HostHandoffRejectionReason.DUPLICATE_JSON_KEY
+                if duplicate_keys
+                else HostHandoffRejectionReason.MALFORMED_JSON
+            )
+        if duplicate_keys:
+            return {}, HostHandoffRejectionReason.DUPLICATE_JSON_KEY
+        if not isinstance(parsed, dict):
+            return {}, HostHandoffRejectionReason.MALFORMED_JSON
+        reason = self._validate_payload(json_text, parsed)
+        if reason is not None:
+            return {}, reason
+        return {key: value for key, value in parsed.items() if isinstance(value, str)}, None
+
+    def _parse_candidate(
+        self,
+        node: Mapping[str, object],
+        body: str,
+    ) -> tuple[dict[str, str], bool, HostHandoffRejectionReason | None]:
+        json_text, reason = self._unwrap_body(body)
+        if reason is not None:
+            return {}, False, reason
+        last_edited_at = node.get("lastEditedAt")
+        if "lastEditedAt" not in node or (
+            last_edited_at is not None
+            and (not isinstance(last_edited_at, str) or not self._valid_comment_timestamp(last_edited_at))
+        ):
+            return {}, False, HostHandoffRejectionReason.MALFORMED_COMMENT_NODE
+        payload, reason = self._parse_payload(json_text)
+        if reason is not None:
+            return {}, False, reason
+        return payload, last_edited_at is not None, None
+
+    def _context_mismatch(self, payload: Mapping[str, str]) -> HostHandoffRejectionReason | None:
+        if (
+            _REPOSITORY_PATTERN.fullmatch(payload["repository"]) is None
+            or payload["repository"] != self.expected["repository"]
+        ):
+            return HostHandoffRejectionReason.REPOSITORY_MISMATCH
+        if payload["target"] != "admission":
+            return HostHandoffRejectionReason.TARGET_MISMATCH
+        if payload["admission_role"] != "admission" or payload["admission_role"] != self.expected["role"]:
+            return HostHandoffRejectionReason.ROLE_MISMATCH
+        if payload["mode"] not in {"drain", "maintain"} or payload["mode"] != self.expected["mode"]:
+            return HostHandoffRejectionReason.MODE_MISMATCH
+        if payload["supervisor_run_id"] != self.expected["supervisor_run_id"]:
+            return HostHandoffRejectionReason.SUPERVISOR_RUN_MISMATCH
+        if payload["checkpoint"] != self.expected["checkpoint"]:
+            return HostHandoffRejectionReason.CHECKPOINT_MISMATCH
+        return None
+
+    def _validate_candidate(
+        self,
+        payload: Mapping[str, str],
+        edited: bool,
+    ) -> list[HostHandoffRejectionReason]:
+        failures: list[HostHandoffRejectionReason] = []
+        if payload["host_root_session"] != HOST_ROOT_SESSION_ID:
+            failures.append(HostHandoffRejectionReason.WRONG_HOST_ROOT_SESSION)
+        if edited:
+            failures.append(HostHandoffRejectionReason.EDITED_COMMENT)
+        issued_at = self._parse_timestamp(payload["issued_at"])
+        expires_at = self._parse_timestamp(payload["expires_at"])
+        if issued_at is None or expires_at is None:
+            failures.append(HostHandoffRejectionReason.INVALID_TIMESTAMP)
+        else:
+            if issued_at > self.now:
+                failures.append(HostHandoffRejectionReason.FUTURE_ISSUED_AT)
+            if expires_at <= self.now:
+                failures.append(HostHandoffRejectionReason.STALE_RECORD)
+            if expires_at > (issued_at[0] + _MAX_LIFETIME_SECONDS, issued_at[1]):
+                failures.append(HostHandoffRejectionReason.LIFETIME_EXCEEDED)
+        unsigned_payload = dict(payload)
+        fingerprint = unsigned_payload.pop("fingerprint")
+        expected_fingerprint = hashlib.sha256(canonicalize_json(unsigned_payload)).hexdigest()
+        if fingerprint != expected_fingerprint:
+            failures.append(HostHandoffRejectionReason.FINGERPRINT_MISMATCH)
+        return failures
+
+    def _collect_candidates(
+        self,
+        comments: Sequence[object],
+    ) -> tuple[list[tuple[dict[str, str], bool]], list[HostHandoffRejectionReason], bool]:
+        candidates: list[tuple[dict[str, str], bool]] = []
+        structural_failures: list[HostHandoffRejectionReason] = []
+        untrusted_candidate = False
+        for raw_node in comments:
+            node = raw_node if isinstance(raw_node, Mapping) else {}
+            body = node.get("body")
+            if not isinstance(body, str) or _MARKER_NAMESPACE not in body:
+                continue
+            author = node.get("author")
+            login = author.get("login") if isinstance(author, Mapping) else None
+            if not isinstance(login, str) or not login.strip() or login.casefold() not in self.trusted_authors:
+                untrusted_candidate = True
+                continue
+            candidate, edited, reason = self._parse_candidate(node, body)
+            if reason is not None:
+                structural_failures.append(reason)
+            else:
+                candidates.append((candidate, edited))
+        return candidates, structural_failures, untrusted_candidate
+
+    def verify(self, comments: Sequence[object]) -> VerifyHostHandoffResult:
+        candidates, structural_failures, untrusted_candidate = self._collect_candidates(comments)
+        if structural_failures:
+            return VerifyHostHandoffResult(False, min(structural_failures, key=_STRUCTURAL_ORDER.index), None)
+        if not candidates:
+            reason = (
+                HostHandoffRejectionReason.UNTRUSTED_AUTHOR
+                if untrusted_candidate
+                else HostHandoffRejectionReason.NO_RECORD
+            )
+            return VerifyHostHandoffResult(False, reason, None)
+
+        matching: list[tuple[dict[str, str], bool]] = []
+        mismatches: list[HostHandoffRejectionReason] = []
+        for payload, edited in candidates:
+            mismatch = self._context_mismatch(payload)
+            if mismatch is None:
+                matching.append((payload, edited))
+            else:
+                mismatches.append(mismatch)
+        if not matching:
+            return VerifyHostHandoffResult(False, min(mismatches, key=_MISMATCH_ORDER.index), None)
+
+        validation_failures = [
+            reason for payload, edited in matching for reason in self._validate_candidate(payload, edited)
+        ]
+        if validation_failures:
+            return VerifyHostHandoffResult(False, min(validation_failures, key=_VALIDATION_ORDER.index), None)
+        if len(matching) != 1:
+            return VerifyHostHandoffResult(False, HostHandoffRejectionReason.MULTIPLE_MATCHING_RECORDS, None)
+        return VerifyHostHandoffResult(True, None, MappingProxyType(dict(matching[0][0])))
+
+
+def verify_host_handoff(
+    comments: Sequence[object],
+    *,
+    trusted_logins: Collection[str],
+    expected: Mapping[str, str],
+    now: datetime,
+) -> VerifyHostHandoffResult:
+    """Verify one canonical, unedited control-issue handoff from a trusted local host.
+
+    The caller must stop before invoking this verifier in GitHub Actions, where
+    control comments are written by the separate bookkeeping-token identity.
+    """
+    if not isinstance(now, datetime) or now.tzinfo is None or now.utcoffset() != timedelta(0):
+        raise ValueError("now must be a timezone-aware UTC datetime")
+    if (
+        not isinstance(expected, Mapping)
+        or set(expected) != _EXPECTED_FIELDS
+        or any(type(value) is not str for value in expected.values())
+    ):
+        raise ValueError("expected must contain exactly the five string handoff context fields")
+    if isinstance(trusted_logins, (str, bytes)) or not isinstance(trusted_logins, Collection):
+        raise ValueError("trusted_logins must be a collection of login strings")
+
+    trusted_authors = {login.casefold() for login in trusted_logins if isinstance(login, str) and login.strip()}
+    now_delta = now.astimezone(UTC) - datetime(1970, 1, 1, tzinfo=UTC)
+    now_exact = (
+        now_delta.days * 86400 + now_delta.seconds,
+        f"{now_delta.microseconds:06d}".rstrip("0"),
+    )
+    verifier = _HostHandoffVerifier(expected, trusted_authors, now_exact)
+    return verifier.verify(comments)

{agentic_devtools-0.2.577.dist-info → agentic_devtools-0.2.579.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-devtools
-Version: 0.2.577
+Version: 0.2.579
 Summary: Agentic devtools integrate Jira, DevOps & more
 Author: ayaiayorg
 License-Expression: MIT

{agentic_devtools-0.2.577.dist-info → agentic_devtools-0.2.579.dist-info}/RECORD

@@ -1,5 +1,5 @@
 agentic_devtools/__init__.py,sha256=J_Zw_vWKghk-cLmqI83hXQmSiS8zMhGIHM5WPLDkZuo,242
-agentic_devtools/_version.py,sha256=TIWdW15l89P8z-XtWYdluJmDXV7ryxUz-CBFY28AsZc,524
+agentic_devtools/_version.py,sha256=ttyJ4aa-Qss_defAUjpwHl__bX0HFcUvkugxDu8chT4,524
 agentic_devtools/agdt_gitignore.py,sha256=vVVqTjBZ_ijn6U3Lnh_JGrARLschYVN-fFal9jDk0Ak,2694
 agentic_devtools/background_tasks.py,sha256=sFgmqOnCdCjclABJ8V__yDwBXDyi45b1Z-MVv3G2zB8,17664
 agentic_devtools/config.py,sha256=DEVxTVZhsQbVQwO9qdB_1h19aBpjMzF6xJY_ePYLGLs,15629
@@ -229,6 +229,7 @@ agentic_devtools/cli/ci/actionable_checks.py,sha256=PICEBWfuD16UgPm5mgRgC55WuE3a
 agentic_devtools/cli/ci/ado_provider.py,sha256=6FpNOEF7zeeKdYwIgN56v7F7xpUZUYQLHpBiRrDbrSw,18115
 agentic_devtools/cli/ci/agent_assignment.py,sha256=xALWk47PMo2uW44kgMm6K7EXfQN5NCv3zyyzWScIAfE,46026
 agentic_devtools/cli/ci/agent_task_inventory.py,sha256=9ATECoO20I-_fVUrjYC0kLmSt_aHw3VpXG26AlLlkVU,3228
+agentic_devtools/cli/ci/approver_preflight.py,sha256=uM_LF0qrf_nMyGJT8CUvdqh0comD_AAsS9Sw_9HqBTA,5865
 agentic_devtools/cli/ci/commands.py,sha256=REVb_t8Ei4F37JmAn57FafIwzBa_u7PNhKkJHvchx5o,27282
 agentic_devtools/cli/ci/comment_format.py,sha256=-jbcUa1AtArU95gnGyhQ1asm704j1zYAf1m1bz7WhS8,1415
 agentic_devtools/cli/ci/conflict_repair_dispatch.py,sha256=nqdRa8DWOPx4DjLVvojUlsG9LmfFiZPtNt9eWxi_NJg,6715
@@ -244,7 +245,8 @@ agentic_devtools/cli/ci/dispatcher_throttle.py,sha256=6vOfb-UQ2uR8AM-l9yjSpgCowB
 agentic_devtools/cli/ci/due_probe_wakeup.py,sha256=4Tie-_cSFlYlkb6o3kJUZt9RaIiROBd5Crm5QAqSxfY,13494
 agentic_devtools/cli/ci/exceptions.py,sha256=zpKWOgnBbHHQgAQRvdRW4VFnE_qdgqgmo8r1H-x47l4,1086
 agentic_devtools/cli/ci/finalization_state.py,sha256=jQm_cH0J09LCZfEUdZK2XQNZFhF7KhyilKcGZ4g8Wzc,8978
-agentic_devtools/cli/ci/github_provider.py,sha256=pHOcZs_JVgCwTjTrHh-tUghNnfRYgmsEVD5I_zzj61Y,501276
+agentic_devtools/cli/ci/github_api_error.py,sha256=o_z8VsI706kzmLyzta-flkIvRyosrqpd3-RBqadL32I,712
+agentic_devtools/cli/ci/github_provider.py,sha256=UYCsLabfyuHaqXkG7pB_q0_kpjZt_d3dU3PcaLhku18,501602
 agentic_devtools/cli/ci/guards.py,sha256=MQbtBWTpwWgNlWPJ1VJL4oZA8XciKs4J1jsN28BQBfQ,59920
 agentic_devtools/cli/ci/job_logs.py,sha256=YUiW487uO0usSwWD-mpWrs6q7IedQuYyhhBJIc0EAfk,12772
 agentic_devtools/cli/ci/logging_config.py,sha256=1Ak6hPfqa6BhxhQ96FmpoqqeYk-aJLEdz0ekpb_gEdU,2328
@@ -276,6 +278,7 @@ agentic_devtools/cli/ci/scheduler_command.py,sha256=B8aRt5MycRcMfgEnH3aJ1xiY_EYH
 agentic_devtools/cli/ci/speckit_trigger.py,sha256=g1FEiWZR89RaN7pDol-HfujbHXArT-hZxb-8eaPOH5Q,909
 agentic_devtools/cli/ci/supervision_control.py,sha256=N8PJFnQ-nbgzXTsIRzuNh4sXCgZYjK4uAaKgslYHrFs,10878
 agentic_devtools/cli/ci/supervision_control_command.py,sha256=f0nBl0faEjMNbp3GqTKn3me4sBx9w4egjVR10-FkxJ4,88689
+agentic_devtools/cli/ci/supervision_host_handoff.py,sha256=uBGXWG62tIIFEuKKT-JTokmi14bCLx6xYxYN1v6vQzM,15546
 agentic_devtools/cli/ci/supervisor.py,sha256=CKFvmMI1zT67wZmqLXsFhjWtVRIyy-QVoP0EqskPlIg,29789
 agentic_devtools/cli/ci/supervisor_command.py,sha256=DWgIJtsABGFjbVrgoATq1GvDh0dSk5a9FC5tnwnXGMg,10674
 agentic_devtools/cli/ci/suppressed_reaper.py,sha256=hitRKUr3BhxB5fCJvEDvxMU0_9c6dxxbDWodZHqdX8w,22859
@@ -307,15 +310,15 @@ agentic_devtools/cli/ci/pipeline/diff_validation.py,sha256=LRf-FB2sIap6kLCcqZIw3
 agentic_devtools/cli/ci/pipeline/exceptions.py,sha256=4UXy2weeQZex_lp4sILNxlYfGjetxbR-tjms2ReT4iw,451
 agentic_devtools/cli/ci/pipeline/exclusion.py,sha256=mrOG5G1-m3U-GM4YgtMTuzmoj02TXB6GbNxemRoLtV4,931
 agentic_devtools/cli/ci/pipeline/gate_verdict.py,sha256=-vbp24Kr172wXpB5T-y9lm-7JxiYurixEu3-nuZohgY,44352
-agentic_devtools/cli/ci/pipeline/models.py,sha256=Q6b6Z_ItHQZvTefAOB_jPn5N2c5LNEnkgnV8Gp0oWm0,3724
+agentic_devtools/cli/ci/pipeline/models.py,sha256=s-ofx-Y_7lzdLF0KnSkuNUDA0Q0C4vwfy4F8NqMKwFY,4065
 agentic_devtools/cli/ci/pipeline/repair_attempts.py,sha256=K9JgsxIW0CjxfV6PMmZRKd6w7qsTYClZvzwFSu7shsA,11054
 agentic_devtools/cli/ci/pipeline/runner.py,sha256=SevvR__WUxZiEr4jXM8OVwYo2YrAIYFHpYXVFgpr_GM,76840
 agentic_devtools/cli/ci/pipeline/runner_diff_fingerprint.py,sha256=EpasXQX_wUpK3m3jRPTNJCbDU0yDAQQlsg1CynvuKXg,2055
 agentic_devtools/cli/ci/pipeline/runner_diff_parser.py,sha256=T3ofZoUxKGZaGSyx5dF9yc3ddwRh7tKXWRA7lDaT59Y,17369
 agentic_devtools/cli/ci/pipeline/session_detector.py,sha256=wVY3RRnsxWJ8duGN4_C2qcIRBWaNRMC8cpf5Ciz6SwM,63864
-agentic_devtools/cli/ci/pipeline/snapshot_builder.py,sha256=UCkA4iyknro6C1kYGgK_kY2XJc1ujb9m1yF3Ss60eqY,18599
+agentic_devtools/cli/ci/pipeline/snapshot_builder.py,sha256=WxMSAsfK1h1StwkWAOVHgaorvBpKyjeCAcD1ekGHt8g,20116
 agentic_devtools/cli/ci/pipeline/snapshot_ci.py,sha256=nvtqRVSEnjWUSCXLEUVa9-JBmMXV08cOLEczogorNTc,4531
-agentic_devtools/cli/ci/pipeline/snapshot_models.py,sha256=ZqY8R53xkB1S3ItlgrLRv-sbbaICKWOnP_Zp5eeoevE,12006
+agentic_devtools/cli/ci/pipeline/snapshot_models.py,sha256=NP02aqTG8L1N3v0Wa8DSeaiYGcNHwXaJQBqpwnxCY7E,12349
 agentic_devtools/cli/ci/pipeline/snapshot_review_comments.py,sha256=GuPKNBJ1g8-nrEcL7QRbMx-lUKwqrBfJlzb2q0z5UeA,7172
 agentic_devtools/cli/ci/pipeline/snapshot_reviews.py,sha256=wQtzxgw3-0s4m_5flqYYXTu45jLhTRaCkmdclSlPu-c,2837
 agentic_devtools/cli/ci/pipeline/snapshot_thread_count.py,sha256=QpNI383E3wJyb3jBOkcgvhpxY7cgn9yjyi1DZTlAZBA,7633
@@ -326,7 +329,8 @@ agentic_devtools/cli/ci/pipeline/summary.py,sha256=2xkuMPePCR2DUhnRaEbTVyje92aQl
 agentic_devtools/cli/ci/pipeline/title_utils.py,sha256=eDkE79WMJdiQ157VEs4NmG0M5FUKtazfDyHXNhMWNfo,708
 agentic_devtools/cli/ci/pipeline/actions/__init__.py,sha256=sqt2dc9zoLEz5U3GVEBMwbPlFtKnayWmx_E5by_oyrM,1844
 agentic_devtools/cli/ci/pipeline/actions/apply_suggestions.py,sha256=CIPMgfFSEEQfUnE9bv3tK7mKpVtgVbmcasuqcp4n8xY,24147
-agentic_devtools/cli/ci/pipeline/actions/approve.py,sha256=D3oI0g42bOXcEMmTQrR3k99fFqYcxo6AZIu9gLO7Nt8,12304
+agentic_devtools/cli/ci/pipeline/actions/approval_entry.py,sha256=G6nR120RmuOL2lf8Hi8EczER-r94lGWyzXnbCeA-YJY,1911
+agentic_devtools/cli/ci/pipeline/actions/approve.py,sha256=6eKIQyr4rDPoR_sRVzBWfudhAYQV5zsBdQkK74Lsu10,12229
 agentic_devtools/cli/ci/pipeline/actions/critique_adjudication.py,sha256=y3nsIySF26c9UGqDXL1JrnS_pK2JFuG_aVNrDxEId_w,7301
 agentic_devtools/cli/ci/pipeline/actions/critique_dispatch.py,sha256=-dp2FHQHNufmonHwypdRYBN4dAomeCUawZrXrz7_414,15843
 agentic_devtools/cli/ci/pipeline/actions/critique_task_binding.py,sha256=nnZNg14VLuYWh7z4NxMyHX5-VSUQ_0w-cK7sm0ObAek,12658
@@ -1267,11 +1271,11 @@ agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision/SKILL.md,sha256=F
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision/exception-merge-policy.md,sha256=kJrT8MpcMg72uODT13-MTVVMBZwwMuhIO-GQjOJozhU,1597
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision/extension-guidance.md,sha256=gfAGX4KtQiz7dS_d0iQ6sBOc6Xrg_pmSIt9AJVOFr6A,4550
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision/scratch-schema.md,sha256=yj6p6j38-6Vb611PVlNOL__r38d2fLgSvDUhJ_IvpfY,20295
-agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-admission/SKILL.md,sha256=BNMe12a1r3jgQi15slk81BcLxvjUXujCP6CTO7j7sKw,3059
+agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-admission/SKILL.md,sha256=mtax-Xl82zcuZjcLbHqFpd16_xVkEjt0NY3oNXH-fws,3473
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-control/SKILL.md,sha256=kAlJwdILhjTKAEnz9OwbxHJs1kjVt6NDb8z9huPRJFE,4289
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-issue-curator/SKILL.md,sha256=oRPxiiB0pW5_2G1ysr_WlSfTCZnHstzEagfwwuRhvpc,3577
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-maintainer/SKILL.md,sha256=uxg0AEx2udSk-4UVczguqFI33xBJ3Qe6NH3bQyUTyGQ,2459
-agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-orchestration/SKILL.md,sha256=_5TnjaPv6F_lWBEGjvq_jZ6Q3QLrPHzHN0nGXCK-uEY,4522
+agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-orchestration/SKILL.md,sha256=VyEzfnEPCfgT_DDNYnhZPLww3nrRHdZEjOCx584RmmM,5080
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-sso/SKILL.md,sha256=jeRJSReyMy96G-fQK3Nti8gMVzNHYXe8pAnesbNSDMQ,2813
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-steward/SKILL.md,sha256=aMOoBP_KDUOGUM6JdtLAEcZCwfsXkNg2T4f4RlHVFFY,3556
 agentic_devtools/_bundled_skills/skills/ai-pr-loop-supervision-worker/SKILL.md,sha256=Sp85L0jMzD2Xlr6gTo5iB-HynBoMx7KLDjgO_-gUBhY,9358
@@ -1289,8 +1293,8 @@ agentic_devtools/_bundled_skills/skills/speckit-plan/SKILL.md,sha256=qYLpzgLCIZ6
 agentic_devtools/_bundled_skills/skills/speckit-specify/SKILL.md,sha256=HbHRbdphMqbtNw6fL6NcYCj6sSFmUyk2S4U0bZ9p_l4,13681
 agentic_devtools/_bundled_skills/skills/write-github-commit-message/SKILL.md,sha256=Ep1lR8NDN117Iytj172VZgqazFiLpJ56Z7RXgaTnxR8,2626
 agentic_devtools/_bundled_skills/skills/write-github-commit-message/commit-types.md,sha256=bTy_t68ZD6R87rFIzq9wybTu8Wudoahb7nB9IWC4bFo,1839
-agentic_devtools-0.2.577.dist-info/METADATA,sha256=UDLYuI2Tr9N_i5CYmG3b1TL9uHo8cntMfnpr8BWPO1E,35393
-agentic_devtools-0.2.577.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-agentic_devtools-0.2.577.dist-info/entry_points.txt,sha256=kL35_Y5OHI6XpPneeBTcX82ORjjfx2VIK6XfmKHgNm4,13630
-agentic_devtools-0.2.577.dist-info/licenses/LICENSE,sha256=yBEDdICksxhBYLWoERKp9MTqwGnUF6Ryj9BTLwXTc6k,1082
-agentic_devtools-0.2.577.dist-info/RECORD,,
+agentic_devtools-0.2.579.dist-info/METADATA,sha256=69TNmXx21RVJB_e4Wyc5ZXAg-E0hZzAq0xDI8RKbyvI,35393
+agentic_devtools-0.2.579.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentic_devtools-0.2.579.dist-info/entry_points.txt,sha256=kL35_Y5OHI6XpPneeBTcX82ORjjfx2VIK6XfmKHgNm4,13630
+agentic_devtools-0.2.579.dist-info/licenses/LICENSE,sha256=yBEDdICksxhBYLWoERKp9MTqwGnUF6Ryj9BTLwXTc6k,1082
+agentic_devtools-0.2.579.dist-info/RECORD,,