alissa-tools-github-devloop 0.8.26__py3-none-any.whl → 0.8.28__py3-none-any.whl

alissa/tools/github/devloop/__main__.py

@@ -194,6 +194,40 @@ def build_parser() -> argparse.ArgumentParser:
         "sessions, even if the config enables it",
     )
 
+    over.add_argument(
+        "--revert-label",
+        metavar="LABEL",
+        help="label an operator applies to a MERGED PR to request a revert "
+        "session (a `TASK-<n>-REVERT-PR<k>` branch reverting the merge "
+        "commit, opened as a ready PR); the session removes the label on "
+        "completion. Env ALISSA_REVERT_LABEL (non-blank) wins over this flag",
+    )
+    revert = over.add_mutually_exclusive_group()
+    revert.add_argument(
+        "--revert",
+        dest="revert_enabled",
+        action="store_true",
+        default=None,
+        help="poll merged PRs carrying the revert label and spawn revert "
+        "sessions (the default)",
+    )
+    revert.add_argument(
+        "--no-revert",
+        dest="revert_enabled",
+        action="store_false",
+        help="never search for the revert label or spawn revert sessions, "
+        "even if the config enables it",
+    )
+    over.add_argument(
+        "--revert-any-author",
+        dest="revert_any_author",
+        action="store_true",
+        default=None,
+        help="let the revert lever act on merged PRs by ANY author, not only "
+        "the daemon's own (default off: a foreign-authored PR is refused "
+        "with a comment and unlabelled)",
+    )
+
     resume = over.add_mutually_exclusive_group()
     resume.add_argument(
         "--resume",
@@ -431,6 +465,9 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "fix_rounds_enabled": args.fix_rounds_enabled,
         "maintain_label": args.maintain_label,
         "maintain_enabled": args.maintain_enabled,
+        "revert_label": args.revert_label,
+        "revert_enabled": args.revert_enabled,
+        "revert_any_author": args.revert_any_author,
         "resume_enabled": args.resume_enabled,
         "wedge_minutes": args.wedge_minutes,
         "rerequest_enabled": args.rerequest_enabled,
@@ -532,7 +569,7 @@ def log_effective_config(config: Config, login: str) -> None:
     log.info(
         "poll every %ss; dry_run=%s; attempt_cap=%s; stale after %s min; "
         "max_sessions=%s; reap_grace=%s min; fix_rounds=%s; maintain=%s "
-        "(label %r); resume=%s; "
+        "(label %r); revert=%s (label %r, any_author=%s); resume=%s; "
         "rerequest=%s (grace %s min); orphan_sweep=%s (grace %s min); "
         "activity_claims=%s; janitor=%s (grace %s min, every %s min, cache "
         "cap %s MiB, warn at %s%%)",
@@ -542,6 +579,7 @@ def log_effective_config(config: Config, login: str) -> None:
         config.reap_grace_seconds // 60,
         config.fix_rounds_enabled,
         config.maintain_enabled, config.maintain_label,
+        config.revert_enabled, config.revert_label, config.revert_any_author,
         config.resume_enabled,
         config.rerequest_enabled,
         config.rerequest_grace_seconds // 60,

alissa/tools/github/devloop/config.py

@@ -24,6 +24,8 @@ through to the config rather than fail the daemon's boot on a mode of `''`.
 `loop_events_enabled` rides the same shape of rail through
 `ALISSA_DEV_LOOP_EVENTS_ENABLED`, with the same blank-falls-through rule, and
 `fleet_vitals_enabled` through `ALISSA_DEV_FLEET_VITALS_ENABLED` likewise.
+`revert_label` rides `ALISSA_REVERT_LABEL` the same way (issue #131): a
+non-blank value wins over the CLI and the file, a blank one falls through.
 """
 
 from __future__ import annotations
@@ -108,6 +110,12 @@ ENV_LOOP_EVENTS = "ALISSA_DEV_LOOP_EVENTS_ENABLED"
 # non-blank-wins / blank-falls-through rule, same config error on a typo.
 ENV_FLEET_VITALS = "ALISSA_DEV_FLEET_VITALS_ENABLED"
 
+# The revert lever's label rail (issue #131): `revert_label` ridden the way
+# ALISSA_DEV_REPOS_SOURCE rides repos_source -- a NON-BLANK value wins over
+# the CLI and the file, a blank one falls through. Spelled as the issue names
+# it (no `_DEV_` infix), because that is the name the operator runbook gives.
+ENV_REVERT_LABEL = "ALISSA_REVERT_LABEL"
+
 # The prompt responder's master switch (issue #127): `on` answers, `observe`
 # classifies and narrates but sends nothing, `off` never captures a pane.
 PROMPT_ON = "on"
@@ -192,6 +200,9 @@ CONFIG_KEYS = (
     "fix_rounds_enabled",
     "maintain_label",
     "maintain_enabled",
+    "revert_label",
+    "revert_enabled",
+    "revert_any_author",
     "resume_enabled",
     "wedge_minutes",
     "prompt_responder",
@@ -487,6 +498,20 @@ class Config:
     maintain_label: str = "alissa:maintain"
     maintain_enabled: bool = True
 
+    # The revert lever (issue #131, the fourth polled edge): an operator
+    # labels a MERGED PR `revert_label` to request a session that reverts its
+    # merge commit on a fresh `TASK-<n>-REVERT-PR<k>` branch and opens the
+    # revert PR ready for review. One spawn per label application (the ledger
+    # keys on the labeled-at instant), no stale retry -- the operator's retry
+    # is unlabel + re-label. `revert_any_author` widens the lever past the
+    # loop's own PRs: off by default in `merge_author_logins`' spirit, because
+    # the daemon reverting a human's merge is a decision a human should make
+    # explicitly, in config, not by applying a label. Default ON like the
+    # maintenance edge, and every side effect still honors dry_run.
+    revert_label: str = "alissa:revert"
+    revert_enabled: bool = True
+    revert_any_author: bool = False
+
     # The third staleness signal (session liveness, read from the reaper's own
     # tmux listing) and the auto-resume it unlocks: a stale attempt whose
     # ledger session is provably gone is respawned with RESUME_DIRECTIVE /
@@ -961,6 +986,14 @@ class Config:
             env_map, ENV_FLEET_VITALS,
             bool(raw.get("fleet_vitals_enabled", cls.fleet_vitals_enabled)),
         )
+        # The revert label's rail (issue #131): repos_source's shape -- a
+        # non-blank ALISSA_REVERT_LABEL wins, blank falls through.
+        revert_label = str(raw.get("revert_label", cls.revert_label))
+        env_revert_label = env_map.get(ENV_REVERT_LABEL, "").strip()
+        if env_revert_label:
+            revert_label = env_revert_label
+        if not revert_label.strip():
+            raise ValueError("revert_label must not be blank")
 
         bow_owners = normalize_bow_owners(raw.get("bow_owners", cls.bow_owners))
 
@@ -1215,6 +1248,11 @@ class Config:
             maintain_enabled=bool(
                 raw.get("maintain_enabled", cls.maintain_enabled)
             ),
+            revert_label=revert_label,
+            revert_enabled=bool(raw.get("revert_enabled", cls.revert_enabled)),
+            revert_any_author=bool(
+                raw.get("revert_any_author", cls.revert_any_author)
+            ),
             resume_enabled=bool(
                 raw.get("resume_enabled", cls.resume_enabled)
             ),

alissa/tools/github/devloop/fleet_vitals.py

@@ -208,7 +208,7 @@ def build_snapshot(
     ledgers = sources.ledgers()
 
     repo_by_session: "dict[str, str]" = {}
-    for table in ("spawns", "fix_spawns", "maintain_spawns"):
+    for table in ("spawns", "fix_spawns", "maintain_spawns", "revert_spawns"):
         for row in ledgers[table]:
             session = row.get("session")
             if session and session not in repo_by_session:
@@ -243,6 +243,7 @@ def build_snapshot(
             int(latest.get("issue_candidates") or 0)
             + int(latest.get("pr_candidates") or 0)
             + int(latest.get("maintain_candidates") or 0)
+            + int(latest.get("revert_candidates") or 0)
         )
 
     drift = sources.drift()

alissa/tools/github/devloop/ghclient.py

@@ -14,6 +14,7 @@ import re
 import tempfile
 import time
 from dataclasses import dataclass
+from urllib.parse import quote
 
 from . import proc
 
@@ -38,6 +39,13 @@ TASK_REF_RE = re.compile(r"TASK-(\d+)")
 TIMELINE_PAGE_SIZE = 100
 TIMELINE_MAX_PAGES = 5
 
+# How far back `first_parent_contains` walks the mainline (in pages of
+# TIMELINE_PAGE_SIZE commits) before a merge commit reads as out of reach.
+# Three hundred first-parent commits is roughly three hundred merged PRs on a
+# squash/merge-button repository -- weeks to months of history on the busiest
+# repo this daemon watches; a revert older than that is a hand-run one.
+FIRST_PARENT_MAX_PAGES = 3
+
 # Review states that count as "a review was submitted". PENDING is a draft
 # review that was never submitted, so it closes nothing. Same set as
 # reviewloop's SUBMITTED_STATES -- the two daemons must count rounds
@@ -156,6 +164,29 @@ class PullRequest:
     # probe already pays. Defaulted like the fields above it: the other edges
     # and their fakes never ask.
     updated_at: "int | None" = None
+    # The merge record, read by the REVERT edge (issue #131) and nobody else:
+    # whether the PR was merged (a closed-unmerged PR has nothing to revert),
+    # the commit the merge produced -- a merge commit, a squash commit or the
+    # last rebased commit, whichever shape the repository's merge button took
+    # -- and who pressed it. Defaulted like the fields above: the spawn edges
+    # and their fakes never ask, and an OPEN PR carries none of them.
+    merged: bool = False
+    merge_commit_sha: str = ""
+    merged_by: str = ""
+    # How many commits the PR carried (`commits` on the pulls payload), read
+    # by the revert edge alone: it is what tells a REBASE merge from a squash
+    # once the merge sha turns out to have one parent. After a rebase merge
+    # `merge_commit_sha` is only the LAST rebased commit, so a session that
+    # reverted it alone would undo one commit of N under a PR claiming the
+    # whole undo (PR #132 review round 1); with the count in hand the
+    # directive can name the range. 0 when the payload carried no readable
+    # count -- UNKNOWN, which the directive spells as "count first", never
+    # as one.
+    commits: int = 0
+    # The labels CURRENTLY on the PR, for the revert edge's re-fetch guard:
+    # the label search is a snapshot, and an operator who removed the label
+    # between search and fetch has withdrawn the request.
+    labels: tuple[str, ...] = ()
 
     @property
     def full_name(self) -> str:
@@ -212,9 +243,37 @@ def _pull_request_from(
         closed_at=parse_github_timestamp(data.get("closed_at")),
         base_ref=base.get("ref") or "",
         updated_at=parse_github_timestamp(data.get("updated_at")),
+        merged=bool(data.get("merged")),
+        merge_commit_sha=data.get("merge_commit_sha") or "",
+        merged_by=(data.get("merged_by") or {}).get("login", ""),
+        commits=_int_or_zero(data.get("commits")),
+        labels=tuple(
+            (lb.get("name") or "") if isinstance(lb, dict) else str(lb)
+            for lb in (data.get("labels") or [])
+        ),
     )
 
 
+def _int_or_zero(value: object) -> int:
+    """A payload integer, or 0 for anything that is not one (missing, null,
+    a string GitHub never sends) -- the thin-payload reading of a count."""
+    try:
+        return max(0, int(value))  # type: ignore[call-overload]
+    except (TypeError, ValueError):
+        return 0
+
+
+@dataclass(frozen=True)
+class LabelApplication:
+    """One `labeled` event: when a label was applied and by whom. The revert
+    edge's request record -- `created_at` is the dedupe epoch (one spawn per
+    label application) and `actor` is named in the revert PR's body and on
+    the original PR, so the paper trail says whose request it was."""
+
+    created_at: str
+    actor: str
+
+
 @dataclass(frozen=True)
 class Review:
     author: str
@@ -662,7 +721,40 @@ class GitHub:
         and never a fresh budget that should not exist. Malformed events
         are skipped, never fatal.
         """
-        newest: "str | None" = None
+        event = self._newest_labeled_event(owner, repo, number, label)
+        return None if event is None else event.get("created_at") or None
+
+    def revert_labeled_at(
+        self, owner: str, repo: str, number: int, label: str
+    ) -> "LabelApplication | None":
+        """The MOST RECENT application of the revert label to this PR -- when
+        and by whom -- or None when no labeled event is visible.
+
+        The revert edge's request record (issue #131): the timestamp is the
+        dedupe key of the one spawn a label application buys (re-labelling
+        after an unlabel is a NEW request and spawns again), and the actor
+        is who asked, named in the revert PR body and on the original PR.
+        Same bounded events walk as `maintain_labeled_at`; an event past the
+        ceiling reads as an OLDER application or none, which under-spawns
+        (a request the daemon cannot date is not acted on twice), never
+        over-spawns. An actor-less event (a deleted account) reads as ''.
+        """
+        event = self._newest_labeled_event(owner, repo, number, label)
+        if event is None or not event.get("created_at"):
+            return None
+        return LabelApplication(
+            created_at=str(event["created_at"]),
+            actor=str((event.get("actor") or {}).get("login") or ""),
+        )
+
+    def _newest_labeled_event(
+        self, owner: str, repo: str, number: int, label: str
+    ) -> "dict | None":
+        """The newest `labeled` event naming `label` on this issue/PR, as the
+        raw event dict, or None -- the walk behind maintain_labeled_at and
+        revert_labeled_at (ascending feed, so the last match wins; stops at
+        the first short page; hard-capped at TIMELINE_MAX_PAGES)."""
+        newest: "dict | None" = None
         for page in range(1, TIMELINE_MAX_PAGES + 1):
             events = (
                 self._api(
@@ -681,16 +773,170 @@ class GitHub:
             for event in events:
                 if not isinstance(event, dict) or event.get("event") != "labeled":
                     continue
+                # casefold(): GitHub label names are case-insensitive (the
+                # `label:"…"` search matches `Alissa:Revert`), and the revert
+                # edge's dedupe key hangs off this match (PR #132 review).
                 name = (event.get("label") or {}).get("name")
-                if name != label:
+                if not isinstance(name, str) or name.casefold() != label.casefold():
                     continue
-                created = event.get("created_at")
-                if created:
-                    newest = created  # ascending order: the last one wins
+                if event.get("created_at"):
+                    newest = event  # ascending order: the last one wins
             if len(events) < TIMELINE_PAGE_SIZE:
                 break  # short page: the feed is exhausted
         return newest
 
+    def search_revert_prs(
+        self, label: str, repos: tuple[str, ...] = ()
+    ) -> list[tuple[str, str, int]]:
+        """MERGED PRs carrying the revert label across the watched repos, as
+        `(owner, repo, number)` hits -- the candidate set of the operator-
+        triggered revert edge (issue #131).
+
+        `is:merged`, not `is:open`: the lever is for work that already
+        landed, and labels stay on closed PRs, so the label is a perfectly
+        good trigger there. Like the maintenance search this re-sees
+        in-flight requests every poll (the ledger, keyed on the label
+        application, dedupes) and carries no author qualifier: whether the
+        PR is the loop's own work is `evaluate_revert()`'s guard, and a
+        foreign one is REFUSED with a comment rather than silently skipped,
+        because an operator asked. Fails closed on an empty allowlist like
+        its siblings.
+        """
+        repos = tuple(r.strip() for r in repos if r and r.strip())
+        if not repos:
+            log.warning(
+                "search_revert_prs: repo allowlist is empty -- nothing is "
+                "watched. An unscoped search would match all of GitHub, so "
+                "this fails closed; configure `repos` to watch something."
+            )
+            return []
+
+        query = f'is:pr is:merged label:"{label}"'
+        for full_name in repos:
+            query += f" repo:{full_name}"
+
+        payload = self._api(
+            "-X",
+            "GET",
+            "search/issues",
+            "-f",
+            f"q={query}",
+            "-f",
+            f"per_page={self.SEARCH_PER_PAGE}",
+        )
+        items = (payload or {}).get("items", [])
+        if len(items) == self.SEARCH_PER_PAGE:
+            log.warning(
+                "search_revert_prs: got exactly %d items -- results are "
+                "likely truncated. Pagination is deliberately not implemented "
+                "(same hard ceiling as search_issues); the window only "
+                "drains as PRs lose the label.",
+                self.SEARCH_PER_PAGE,
+            )
+
+        out: list[tuple[str, str, int]] = []
+        for item in items:
+            parts = item.get("repository_url", "").rstrip("/").split("/")
+            if len(parts) < 2:
+                log.warning("could not parse repo from %s", item.get("repository_url"))
+                continue
+            try:
+                number = int(item["number"])
+            except (KeyError, TypeError, ValueError):
+                log.warning("could not parse PR number from %r", item.get("number"))
+                continue
+            out.append((parts[-2], parts[-1], number))
+        return out
+
+    def remove_label(self, owner: str, repo: str, number: int, label: str) -> None:
+        """Remove `label` from an issue or PR.
+
+        The ONE label write the daemon performs (issue #131): the revert
+        edge's refusal path -- a request it will not act on is acknowledged
+        by taking the request label off, so the PR drops out of the search
+        instead of being re-refused every poll. Every other label lifecycle
+        (the trigger label, the maintenance label, the revert label on the
+        happy path) is removed by an operator or by the SESSION, never here.
+        A label that is already gone is not an error: GitHub answers 404 and
+        the desired state holds, so that one is swallowed at DEBUG.
+        """
+        try:
+            self._api(
+                "-X",
+                "DELETE",
+                f"repos/{owner}/{repo}/issues/{number}/labels/{quote(label, safe='')}",
+            )
+        except proc.CommandError as exc:
+            if "404" in exc.stderr or "Not Found" in exc.stderr:
+                log.debug(
+                    "%s/%s#%d: label %r was already absent", owner, repo, number, label
+                )
+                return
+            raise
+
+    def first_parent_contains(
+        self, owner: str, repo: str, branch: str, sha: str,
+        max_pages: int = FIRST_PARENT_MAX_PAGES,
+    ) -> bool:
+        """Is commit `sha` on `branch`'s FIRST-PARENT history, within the
+        newest `max_pages` × 100 ancestors?
+
+        The revert edge's other refusal (issue #131): `git revert -m 1` on a
+        merge commit that is not on the mainline's first-parent chain
+        reverts the wrong side of the merge, and a PR merged into a stacked
+        branch or a since-rewritten history is exactly that shape. The list
+        endpoint returns EVERY ancestor of `branch` newest-first with each
+        commit's parents, so the chain is followed locally -- the branch
+        head, its first parent, that one's first parent -- across as many
+        pages as it takes to meet `sha` or run out. Not found within the
+        window reads as NOT on the chain: a merge older than a few hundred
+        mainline commits is out of the lever's reach and is refused with a
+        message that says so, which is the conservative direction (nothing
+        is reverted). A commit whose first parent falls outside the fetched
+        window with pages still to fetch pulls the next page; a chain that
+        breaks otherwise (a truncated payload) reads as not found.
+        """
+        commits: "dict[str, list[str]]" = {}
+        head: "str | None" = None
+        cursor: "str | None" = None
+        for page in range(1, max_pages + 1):
+            payload = self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/commits",
+                "-f",
+                f"sha={branch}",
+                "-f",
+                f"per_page={TIMELINE_PAGE_SIZE}",
+                "-f",
+                f"page={page}",
+            ) or []
+            if not isinstance(payload, list) or not payload:
+                break
+            for entry in payload:
+                if not isinstance(entry, dict) or not entry.get("sha"):
+                    continue
+                parents = [
+                    str(p.get("sha") or "")
+                    for p in (entry.get("parents") or [])
+                    if isinstance(p, dict)
+                ]
+                commits[str(entry["sha"])] = parents
+                if head is None:
+                    head = str(entry["sha"])  # newest first: page 1's first row
+            cursor = head if cursor is None else cursor
+            # Walk the chain as far as the fetched window allows.
+            while cursor is not None and cursor in commits:
+                if cursor == sha:
+                    return True
+                parents = commits[cursor]
+                cursor = parents[0] if parents else None
+            if cursor is None:
+                return False  # the root commit: the chain is exhausted
+            if len(payload) < TIMELINE_PAGE_SIZE:
+                break  # short page: nothing older to fetch
+        return False
+
     def pull_request(self, owner: str, repo: str, number: int) -> PullRequest:
         """The evaluate_pr() re-fetch: draft state, head, author, body, and
         the pending review requests -- the consistency guard over search