alissa-tools-github-devloop 0.3.0__tar.gz → 0.4.0__tar.gz

{alissa_tools_github_devloop-0.3.0/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.3.0
+Version: 0.4.0
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.3.0 → alissa_tools_github_devloop-0.4.0}/src/main/alissa/tools/github/devloop/__main__.py

@@ -115,6 +115,30 @@ def build_parser() -> argparse.ArgumentParser:
         "even if the config enables it",
     )
 
+    over.add_argument(
+        "--maintain-label",
+        metavar="LABEL",
+        help="PR label an operator applies to request a maintenance session "
+        "(merge main into the branch / freshen it); the session removes the "
+        "label on completion",
+    )
+    maintain = over.add_mutually_exclusive_group()
+    maintain.add_argument(
+        "--maintain",
+        dest="maintain_enabled",
+        action="store_true",
+        default=None,
+        help="poll open PRs carrying the maintenance label and spawn "
+        "maintenance sessions (the default)",
+    )
+    maintain.add_argument(
+        "--no-maintain",
+        dest="maintain_enabled",
+        action="store_false",
+        help="never search for the maintenance label or spawn maintenance "
+        "sessions, even if the config enables it",
+    )
+
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
         "--dry-run",
@@ -149,6 +173,8 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "on_missing_origin_task": args.on_missing_origin_task,
         "on_missing_hub": args.on_missing_hub,
         "fix_rounds_enabled": args.fix_rounds_enabled,
+        "maintain_label": args.maintain_label,
+        "maintain_enabled": args.maintain_enabled,
         "dry_run": args.dry_run,
     }
 
@@ -180,9 +206,10 @@ def log_effective_config(config: Config, login: str) -> None:
     log.info("reviewers: %s", ", ".join(config.reviewers) or "none")
     log.info(
         "poll every %ss; dry_run=%s; attempt_cap=%s; stale after %s min; "
-        "fix_rounds=%s",
+        "fix_rounds=%s; maintain=%s (label %r)",
         config.poll_interval, config.dry_run, config.attempt_cap,
         config.stale_minutes, config.fix_rounds_enabled,
+        config.maintain_enabled, config.maintain_label,
     )
     log.debug("hub_template: %s", config.hub_template)
     log.debug("agent_profile: %s", config.agent_profile)

{alissa_tools_github_devloop-0.3.0 → alissa_tools_github_devloop-0.4.0}/src/main/alissa/tools/github/devloop/config.py

@@ -59,6 +59,8 @@ CONFIG_KEYS = (
     "on_missing_origin_task",
     "on_missing_hub",
     "fix_rounds_enabled",
+    "maintain_label",
+    "maintain_enabled",
     "dry_run",
 )
 
@@ -128,7 +130,7 @@ class Config:
     # resolved location, never this field.
     state_path: Path | None = None
 
-    attempt_cap: int = 2
+    attempt_cap: int = 10
     stale_minutes: int = 120
 
     on_missing_origin_task: str = ON_MISSING_WARN
@@ -140,6 +142,15 @@ class Config:
     # still honors dry_run. Turning it off reverts to issues-only polling.
     fix_rounds_enabled: bool = True
 
+    # The maintenance edge (the third polled edge): an operator labels an
+    # open PR `maintain_label` to request an ad-hoc maintenance session
+    # (merge conflicts on approved-but-unmerged branches, freshening stale
+    # branches — the re-trigger the other two edges deliberately don't
+    # cover). Default ON like fix_rounds_enabled, and every side effect
+    # still honors dry_run.
+    maintain_label: str = "alissa:maintain"
+    maintain_enabled: bool = True
+
     dry_run: bool = False
 
     # Derived at build time: `repos` casefolded for matching. GitHub names are
@@ -282,6 +293,10 @@ class Config:
             fix_rounds_enabled=bool(
                 raw.get("fix_rounds_enabled", cls.fix_rounds_enabled)
             ),
+            maintain_label=raw.get("maintain_label", cls.maintain_label),
+            maintain_enabled=bool(
+                raw.get("maintain_enabled", cls.maintain_enabled)
+            ),
             dry_run=bool(raw.get("dry_run", cls.dry_run)),
         )
 

{alissa_tools_github_devloop-0.3.0 → alissa_tools_github_devloop-0.4.0}/src/main/alissa/tools/github/devloop/ghclient.py

@@ -6,11 +6,13 @@ through `gh api` against the REST v3 endpoints instead.
 
 from __future__ import annotations
 
+import calendar
 import json
 import logging
 import os
 import re
 import tempfile
+import time
 from dataclasses import dataclass
 
 from . import proc
@@ -43,6 +45,19 @@ TIMELINE_MAX_PAGES = 5
 SUBMITTED_STATES = {"APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"}
 
 
+def parse_github_timestamp(ts: "str | None") -> "int | None":
+    """A GitHub API timestamp (`2026-07-23T02:13:56Z`) as unix seconds, or
+    None when absent/unparseable. GitHub emits UTC `Z` timestamps
+    everywhere; anything else conservatively reads as "unknown" -- callers
+    treat an unknown boundary as "do not filter", never as an error."""
+    if not ts:
+        return None
+    try:
+        return calendar.timegm(time.strptime(ts, "%Y-%m-%dT%H:%M:%SZ"))
+    except ValueError:
+        return None
+
+
 def parse_task_ref(body: str) -> int | None:
     """Origin Alissa task number from an issue body, or None if absent.
 
@@ -383,6 +398,129 @@ class GitHub:
             out.append((parts[-2], parts[-1], number))
         return out
 
+    def search_maintain_prs(
+        self, label: str, repos: tuple[str, ...] = ()
+    ) -> list[tuple[str, str, int]]:
+        """Open PRs carrying the maintenance label across the watched repos,
+        as `(owner, repo, number)` hits -- the candidate set of the
+        operator-triggered maintenance edge.
+
+        The label IS the trigger and the visible in-flight state: an operator
+        applies it to request a maintenance session, and the session removes
+        it on completion -- so this search re-sees in-flight work every poll
+        (the ledger, not the label, dedupes) and the query deliberately has
+        no `author:@me` or `draft:false` qualifier: the operator labeled a
+        specific PR, and evaluate_maintain()'s re-fetch guards (author,
+        head-ref shape, closed-between-search-and-fetch) do the filtering.
+        The label is quoted because it contains a colon (`alissa:maintain`).
+
+        Fails closed on an empty/degenerate allowlist exactly like the two
+        sibling searches: an unscoped label query would run against ALL of
+        GitHub, and the caller spawns code-writing sessions against whatever
+        comes back.
+        """
+        repos = tuple(r.strip() for r in repos if r and r.strip())
+        if not repos:
+            log.warning(
+                "search_maintain_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:open 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_maintain_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 close or lose the label.",
+                self.SEARCH_PER_PAGE,
+            )
+
+        out: list[tuple[str, str, int]] = []
+        for item in items:
+            # repository_url looks like https://api.github.com/repos/<owner>/<repo>
+            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 maintain_labeled_at(
+        self, owner: str, repo: str, number: int, label: str
+    ) -> "str | None":
+        """When the maintenance label was MOST RECENTLY applied to this PR
+        (ISO timestamp), or None when no labeled event is visible -- the
+        epoch boundary of the current maintenance request.
+
+        Completion is a label removal the daemon never observes (a completed
+        PR drops out of the label search), so the maintain ledger cannot be
+        reset on completion -- instead the caller re-bases its attempt budget
+        on rows spawned AFTER the newest `labeled` event: an operator
+        re-labeling a PR weeks after a completed cycle starts a fresh budget,
+        while a dead session (label never removed, same labeling) keeps
+        accumulating attempts toward the cap.
+
+        Source: the issue-events feed (PRs are issues to this endpoint),
+        walked in the same bounded page loop as the timeline probe --
+        ascending chronological order, so the NEWEST matching event is the
+        last one seen; the walk stops at the first short page and hard-caps
+        at TIMELINE_MAX_PAGES pages. A labeled event past the ceiling is
+        invisible: the probe then reports an OLDER labeling (or none), which
+        under-filters -- attempts from an older request stay in the budget,
+        the same direction as the no-event fallback (lifetime accounting)
+        and never a fresh budget that should not exist. Malformed events
+        are skipped, never fatal.
+        """
+        newest: "str | None" = None
+        for page in range(1, TIMELINE_MAX_PAGES + 1):
+            events = (
+                self._api(
+                    "-X",
+                    "GET",
+                    f"repos/{owner}/{repo}/issues/{number}/events",
+                    "-f",
+                    f"per_page={TIMELINE_PAGE_SIZE}",
+                    "-f",
+                    f"page={page}",
+                )
+                or []
+            )
+            if not isinstance(events, list):
+                break
+            for event in events:
+                if not isinstance(event, dict) or event.get("event") != "labeled":
+                    continue
+                name = (event.get("label") or {}).get("name")
+                if name != label:
+                    continue
+                created = event.get("created_at")
+                if created:
+                    newest = created  # ascending order: the last one wins
+            if len(events) < TIMELINE_PAGE_SIZE:
+                break  # short page: the feed is exhausted
+        return newest
+
     def pull_request(self, owner: str, repo: str, number: int) -> PullRequest:
         """The evaluate_pr() re-fetch: draft state, head, author, and the
         pending review requests -- the consistency guard over search

{alissa_tools_github_devloop-0.3.0 → alissa_tools_github_devloop-0.4.0}/src/main/alissa/tools/github/devloop/loop.py

@@ -57,6 +57,34 @@ CHANGES_REQUESTED); COMMENTED-mode reviews defer to the CR6 verdict envelope
 via an injectable reader, and with no readable verdict the edge stays closed
 -- a fix session is never spawned on an ambiguous verdict.
 
+The pass's THIRD edge is the MAINTENANCE edge (maintain_enabled): open PRs
+an operator labeled `maintain_label` (default `alissa:maintain`) get a
+maintenance session -- merge conflicts on approved-but-unmerged branches,
+freshening stale branches: the ad-hoc re-trigger the other two edges
+deliberately don't cover. The label is BOTH the trigger and the visible
+in-flight state, and its lifecycle is remove-on-completion by design: the
+daemon never removes it -- the maintenance session does, as its terminal
+act, after push -> re-request (the push stales any approve, so the
+re-request re-arms the reviewer daemon). While the label stays, the
+maintain_spawns ledger dedupes a fresh spawn, ages a stale one into attempt
+k+1 (a dead session's label never clears itself, so the retry is what the
+lifecycle buys), and caps attempts PER REQUEST -- at cap the daemon posts
+ONE operator comment per request (the `maintain-cap` kind, epoch-folded)
+and stops until the operator acts. "Per request" is load-bearing: the edge
+exists to be RE-triggered, completion is a label removal the daemon never
+observes (a completed PR drops out of the search), and ledger rows are
+never deleted -- so the budget is re-based on the newest `labeled` event
+(maintain_labeled_at, fetched lazily on the stale path only): attempts
+spawned before the current labeling belong to a prior, completed request
+and neither age into a false "presumed dead" retry warning nor count
+toward a false cap-out. Attempt NUMBERING stays lifetime-monotonic
+(maintain_max_attempt) even as the budget resets: session names fold the
+attempt number in, and a fresh budget reusing attempt 1 could collide with
+a prior epoch's zombie session. With no readable labeled event the budget
+conservatively stays lifetime-wide (the pre-epoch behavior). The re-fetch
+guards mirror the fix edge's: closed/merged between search and fetch, a
+foreign author, and a foreign-shaped head ref all skip.
+
 Finally, every pass runs the SESSION REAPER: finished `develop-*`/`fix-*`
 worker sessions otherwise idle in tmux forever (observed live on the reviewer
 daemon, 2026-07-22 -- and dev workers are worse, because they block through
@@ -99,6 +127,7 @@ from .ghclient import (
     PullRequest,
     RateLimited,
     Review,
+    parse_github_timestamp,
     parse_task_ref,
 )
 from .proc import CommandError
@@ -182,6 +211,35 @@ FIX_DIRECTIVE = (
     "create further ali-* sessions — this loop is depth-1."
 )
 
+MAINTAIN_DIRECTIVE = (
+    "You are an IMPLEMENTER on maintenance duty, not a reviewer. An operator "
+    "labeled PR {pr_url} `{label}` (maintenance attempt {attempt} of {cap}): "
+    "bring the branch current with main — resolve any merge conflict and "
+    "freshen it. "
+    "Golden path: your cwd is the repo's worktree hub ROOT and the PR's head "
+    "branch `{head_ref}` already exists — re-attach its worktree with `git "
+    "worktree add {head_ref} {head_ref}` if it is missing, and work ONLY on "
+    "that branch (never a new branch, never a clone, never main). "
+    "FIRST the idempotent no-op check: if the branch is already conflict-free "
+    "AND current vs origin/main, remove the `{label}` label from the PR "
+    "(`gh pr edit {number} --remove-label \"{label}\"`) and exit — push "
+    "nothing, re-request nobody; this no-op path is what makes retries safe. "
+    "Otherwise merge origin/main INTO the branch (`git merge origin/main`) — "
+    "NEVER rebase, never force-push: review threads keep their anchors only "
+    "while history is append-only — resolving any conflicts so BOTH sides' "
+    "intent is preserved, then run the repo's four scripts (unit tests, "
+    "coverage, style, types) and get ALL of them green before publishing. "
+    "The terminal sequence's ORDER is load-bearing: push the merge commit, "
+    "THEN re-request review from {reviewers} — the push stales any approve, "
+    "so the re-request is what re-arms the review daemon — THEN remove the "
+    "`{label}` label from the PR LAST: the label removal is the convergence "
+    "signal, and nothing may follow it except your last act: run "
+    "`alissa tmux kill {session}` to end this session and free the machine "
+    "(best-effort — a crashed session never reaches it). NEVER merge the PR, "
+    "never push to main, and do NOT create further ali-* sessions — this "
+    "loop is depth-1."
+)
+
 ESCALATION_COMMENT = (
     "**Dev loop cap-out** — {attempts} developer attempt(s) were spawned on "
     "this issue without it converging (attempt cap: {cap}). The daemon will "
@@ -223,6 +281,16 @@ FIX_STALLED_COMMENT = (
     "close the PR to park the work."
 )
 
+MAINTAIN_CAP_COMMENT = (
+    "**Maintain loop cap-out** — {attempts} maintenance attempt(s) were "
+    "spawned on this PR without any of them completing (attempt cap: {cap}; "
+    "completion = the `{label}` label removed, the session's terminal act). "
+    "The daemon will not spawn another while the label stays. This needs an "
+    "operator decision: finish the maintenance by hand (merge main into the "
+    "branch, push, re-request review) and remove the `{label}` label, raise "
+    "`attempt_cap` to re-enter the loop, or remove the label to park the PR."
+)
+
 ASSIGNMENT_REJECTED_COMMENT = (
     "**Dev loop cannot start** — the daemon tried to self-assign this issue "
     "as its in-flight marker, but GitHub silently dropped the assignment: "
@@ -245,6 +313,11 @@ ESCALATION_STALLED = "stalled"
 ESCALATION_FIX_CAP = "fix-cap"
 ESCALATION_FIX_STALLED = "fix-stalled"
 
+# The maintenance edge's cap-out kind prefix. The `maintain-` prefix keeps
+# rows from ever colliding with the issue edge's `cap` when an issue and a
+# PR share a number; the epoch suffix is maintain_cap_kind's job below.
+ESCALATION_MAINTAIN_CAP = "maintain-cap"
+
 # CR6 verdict words, spelled exactly as reviewloop's alissa.py spells them --
 # the envelope tie-breaker (see DevWatcher.envelope_verdict) must return
 # these strings, so the two daemons read one vocabulary.
@@ -252,6 +325,21 @@ VERDICT_APPROVE = "approve"
 VERDICT_REQUEST_CHANGES = "request_changes"
 
 
+def maintain_cap_kind(labeled_ts: "int | None") -> str:
+    """The ledger kind that dedupes ONE maintenance request's cap-out page.
+
+    Folded per request like fix_cap_kind is per round: request k capping
+    out must not silence request k+1's page -- a re-label re-opens the edge
+    with a fresh budget, and its cap-out is a fresh operator ask going
+    unanswered. The epoch boundary IS the newest `labeled` event's
+    timestamp, so it folds into the kind (`maintain-cap:e<ts>`). With no
+    readable labeled event (labeled_ts None) the kind stays bare -- the
+    budget is lifetime-wide there, so one lifetime page matches it."""
+    if labeled_ts is None:
+        return ESCALATION_MAINTAIN_CAP
+    return f"{ESCALATION_MAINTAIN_CAP}:e{labeled_ts}"
+
+
 def fix_cap_kind(round_: int) -> str:
     """The ledger kind that dedupes ONE round's fix cap-out operator page.
 
@@ -366,6 +454,22 @@ def fix_session_name(pr: PullRequest, round_: int, attempt: int) -> str:
     return f"fix-{owner}-{repo}-pr{pr.number}-r{round_}-a{attempt}"
 
 
+def maintain_session_name(pr: PullRequest, attempt: int) -> str:
+    """A tmux-safe maintenance-session name:
+    `maintain-<owner>-<repo>-pr<n>-a<attempt>`.
+
+    Deterministic like its two siblings (no nonce): the attempt number comes
+    from the maintain ledger's row count, so every spawn gets a fresh name.
+    No round segment -- the edge has no rounds. The owner is folded in for
+    the same reason as the other edges (the P3 session-name lesson):
+    maintain counts are keyed per `owner/repo`, so two owners' PR #16 can
+    both sit at attempt 1, and a repo-only name would collide.
+    """
+    owner = re.sub(r"[^A-Za-z0-9-]", "-", pr.owner).strip("-").lower()
+    repo = re.sub(r"[^A-Za-z0-9-]", "-", pr.repo).strip("-").lower()
+    return f"maintain-{owner}-{repo}-pr{pr.number}-a{attempt}"
+
+
 def no_envelope_verdict(owner: str, repo: str, number: int) -> "str | None":
     """The default (stub) envelope tie-breaker: no verdict is ever readable.
 
@@ -990,31 +1094,39 @@ class DevWatcher:
             return VERDICT_REQUEST_CHANGES
         return self.envelope_verdict(pr.owner, pr.repo, pr.number)
 
+    def _foreign_head_skip(self, pr: PullRequest, attempt: int) -> "Decision | None":
+        """The head-ref shape guard, shared by every PR-side spawn (fix and
+        maintain): head_ref is interpolated into the directive as both a
+        worktree path and a shell token (`git worktree add {head_ref}
+        {head_ref}`), and a PR's head branch is not strictly self-authored
+        (anyone with push access can move it). This daemon only ever creates
+        flat `TASK-<n>-<DESC>` branches, so a ref outside that shape --
+        slashes that nest the worktree path, whitespace or shell
+        metacharacters that reach an agent prompt -- is not this daemon's
+        work anyway: skip conservatively rather than sanitize. Returns the
+        SKIPPED Decision, or None when the ref is safe to interpolate."""
+        if re.fullmatch(r"[A-Za-z0-9._-]+", pr.head_ref):
+            return None
+        log.warning(
+            "%s head ref %r does not match the daemon's own branch shape "
+            "— not spawning a worker session on a foreign-shaped branch",
+            pr.pr_slug,
+            pr.head_ref,
+        )
+        return Decision(
+            Action.SKIPPED,
+            f"head ref {pr.head_ref!r} does not match the daemon's own "
+            f"branch shape ([A-Za-z0-9._-]+) — foreign-shaped branch, "
+            f"not this daemon's work",
+            attempt,
+        )
+
     def _spawn_fix(
         self, pr: PullRequest, round_: int, attempt: int, review: Review
     ) -> Decision:
-        # head_ref is interpolated into FIX_DIRECTIVE as both a worktree
-        # path and a shell token (`git worktree add {head_ref} {head_ref}`),
-        # and a PR's head branch is not strictly self-authored (anyone with
-        # push access can move it). This daemon only ever creates flat
-        # `TASK-<n>-<DESC>` branches, so a ref outside that shape -- slashes
-        # that nest the worktree path, whitespace or shell metacharacters
-        # that reach an agent prompt -- is not this daemon's work anyway:
-        # skip conservatively rather than sanitize.
-        if not re.fullmatch(r"[A-Za-z0-9._-]+", pr.head_ref):
-            log.warning(
-                "%s head ref %r does not match the daemon's own branch shape "
-                "— not spawning a fix session on a foreign-shaped branch",
-                pr.pr_slug,
-                pr.head_ref,
-            )
-            return Decision(
-                Action.SKIPPED,
-                f"head ref {pr.head_ref!r} does not match the daemon's own "
-                f"branch shape ([A-Za-z0-9._-]+) — foreign-shaped branch, "
-                f"not this daemon's work",
-                attempt,
-            )
+        skipped = self._foreign_head_skip(pr, attempt)
+        if skipped is not None:
+            return skipped
 
         hub, problem = self._ensure_hub(pr.owner, pr.repo)
         if problem is not None:
@@ -1062,11 +1174,211 @@ class DevWatcher:
             attempt,
         )
 
+    # -- the maintenance edge (operator-labeled PRs) ------------------------
+
+    def evaluate_maintain(self, owner: str, repo: str, number: int) -> Decision:
+        """Is a maintenance session owed on this labeled PR? The label IS the
+        ask -- an operator applied it -- so unlike the fix edge there is no
+        verdict or court arithmetic here, only the re-fetch guards and the
+        ledger. The label's lifecycle is remove-on-completion: the daemon
+        NEVER removes it (the maintenance session does, as its terminal
+        act), so the label doubles as the visible in-flight state -- the
+        ledger dedupes a fresh spawn, a stale ledger row under a
+        still-present label means the session died and attempt k+1 is owed,
+        and the attempt cap pages the operator once PER REQUEST and stops.
+
+        The attempt budget is per maintenance REQUEST, not per PR lifetime:
+        completion (the session's label removal) is invisible to the daemon
+        and rows are never deleted, so on the stale path the budget is
+        re-based on the newest `labeled` event -- attempts spawned before
+        the current labeling belong to a prior, completed request, and must
+        neither trigger the false "presumed dead" warning nor eat the new
+        request's budget (the edge exists to be re-triggered). The probe is
+        lazy: no prior rows, or a fresh in-flight spawn (always the current
+        request's), never pays for the events fetch."""
+        pr = self.github.pull_request(owner, repo, number)
+
+        # Closed/merged between search and fetch: nothing left to maintain.
+        if pr.state != "open":
+            return Decision(Action.SKIPPED, "PR closed between search and fetch")
+
+        # Mirror of the fix edge's author guard: a maintenance session
+        # merges main into the head branch and pushes it, and a foreign PR
+        # must never grow a session pushing to its branch -- whoever labeled
+        # it, the daemon only maintains its own work.
+        if pr.author != self.github.login:
+            return Decision(
+                Action.SKIPPED,
+                f"PR author is {pr.author!r}, not the developer identity — "
+                f"not this daemon's to maintain",
+            )
+
+        attempts = self.state.maintain_attempt_count(pr.full_name, number)
+        age = self.state.maintain_spawn_age(pr.full_name, number)
+
+        if age is not None and age < self.config.stale_minutes * 60:
+            return Decision(
+                Action.IN_FLIGHT,
+                f"maintenance attempt {attempts} enqueued {int(age)}s ago "
+                f"(the label stays until the session completes)",
+                attempts,
+            )
+
+        # Stale path with history: re-base the budget on the current
+        # request. An unreadable boundary (no visible labeled event, or an
+        # unparseable timestamp) conservatively leaves the lifetime budget
+        # in place -- under-filtering can only page the operator early,
+        # never spawn past a real request's cap.
+        labeled_ts: "int | None" = None
+        if attempts:
+            labeled_ts = parse_github_timestamp(
+                self.github.maintain_labeled_at(
+                    owner, repo, number, self.config.maintain_label
+                )
+            )
+            if labeled_ts is not None:
+                attempts = self.state.maintain_attempt_count(
+                    pr.full_name, number, since=labeled_ts
+                )
+                age = self.state.maintain_spawn_age(
+                    pr.full_name, number, since=labeled_ts
+                )
+
+        # This request's budget ran dry while the label is still present:
+        # page the operator ON the PR once (the epoch-folded maintain-cap
+        # kind, so a later request's cap-out pages again) and stop. No
+        # deferral tier above this, unlike the other edges: the label is an
+        # explicit operator ask, and its removal -- by the session on
+        # completion, or by the operator to park the PR -- is the only
+        # convergence signal this edge has.
+        if attempts >= self.config.attempt_cap:
+            kind = maintain_cap_kind(labeled_ts)
+            if self.state.escalated(pr.full_name, number, kind):
+                return Decision(Action.CAPPED, "already escalated", attempts)
+            self._escalate_maintain_cap(pr, attempts, kind)
+            return Decision(
+                Action.ESCALATED,
+                f"{attempts} maintenance attempts this request, cap "
+                f"{self.config.attempt_cap} — the label is still present; "
+                f"operator paged on the PR",
+                attempts,
+            )
+
+        if age is not None:
+            log.warning(
+                "%s maintenance attempt %d has been in flight %.0f min and "
+                "the %r label is still present — re-enqueuing (maintenance "
+                "session presumed dead; a live one removes the label as its "
+                "terminal act)",
+                pr.pr_slug,
+                attempts,
+                age / 60,
+                self.config.maintain_label,
+            )
+
+        # Numbering is lifetime-monotonic even when the budget reset: the
+        # attempt number is folded into the deterministic session name, and
+        # a fresh request reusing attempt 1 could collide with a prior
+        # epoch's still-idling session.
+        return self._spawn_maintain(
+            pr, self.state.maintain_max_attempt(pr.full_name, number) + 1
+        )
+
+    def _spawn_maintain(self, pr: PullRequest, attempt: int) -> Decision:
+        skipped = self._foreign_head_skip(pr, attempt)
+        if skipped is not None:
+            return skipped
+
+        hub, problem = self._ensure_hub(pr.owner, pr.repo)
+        if problem is not None:
+            return Decision(Action.SKIPPED, problem, attempt)
+
+        # The resolved reviewers, re-requested after the push (which stales
+        # any approve). With none resolved the session falls back to the
+        # PR's own review history -- always recoverable from the PR itself.
+        reviewers = ", ".join(self.config.reviewers) or (
+            "the PR's existing reviewers (none resolved in config — "
+            "re-request whoever reviewed it)"
+        )
+        name = maintain_session_name(pr, attempt)
+        directive = MAINTAIN_DIRECTIVE.format(
+            pr_url=pr.url,
+            number=pr.number,
+            label=self.config.maintain_label,
+            attempt=attempt,
+            cap=self.config.attempt_cap,
+            head_ref=pr.head_ref,
+            reviewers=reviewers,
+            session=name,
+        )
+
+        # No self-assignment (authorship is the marker, like the fix edge)
+        # and NO label removal: remove-on-completion is the design decision.
+        # The label stays as the visible in-flight state; the ledger row
+        # below is what dedupes the next poll.
+        self.alissa.enqueue_developer(
+            session=name,
+            directive=directive,
+            cwd=hub,
+            agent=self.config.agent_profile,
+            dry_run=self.config.dry_run,
+        )
+
+        if not self.config.dry_run:
+            self.state.record_maintain_spawn(
+                repo_slug=pr.full_name,
+                number=pr.number,
+                attempt=attempt,
+                session=name,
+            )
+
+        return Decision(
+            Action.SPAWNED,
+            f"maintenance session {name} (label {self.config.maintain_label!r} "
+            f"stays until the session removes it)",
+            attempt,
+        )
+
+    def _escalate_maintain_cap(
+        self, pr: PullRequest, attempts: int, kind: str
+    ) -> None:
+        """Operator page for one maintenance request's cap-out, posted ON
+        the PR (the fix edge's _escalate_fix_cap shape): log, comment
+        (dry-run gated), and record the epoch-folded dedupe row (`kind` is
+        maintain_cap_kind's output) even if the comment fails -- a
+        terminal-state page, same trade as cap/assignment/fix-cap."""
+        body = MAINTAIN_CAP_COMMENT.format(
+            attempts=attempts,
+            cap=self.config.attempt_cap,
+            label=self.config.maintain_label,
+        )
+        log.error(
+            "MAINTAIN CAP-OUT %s after %d maintenance attempt(s) with the %r "
+            "label still present — escalating to operator on the PR",
+            pr.pr_slug,
+            attempts,
+            self.config.maintain_label,
+        )
+
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", pr.pr_slug, body)
+            return
+
+        try:
+            self.github.comment(pr.owner, pr.repo, pr.number, body)
+        except CommandError as exc:
+            log.error(
+                "could not post the maintain cap-out comment on %s: %s",
+                pr.pr_slug,
+                exc,
+            )
+        self.state.record_escalation(pr.full_name, pr.number, kind)
+
     def _ensure_hub(self, owner: str, repo: str) -> tuple[Path, str | None]:
         """Resolve a spawn's cwd (the hub ROOT), hub-ifying the repo first if
-        configured. Shared by both edges (issue spawns and fix spawns), so it
-        takes the bare owner/repo. Returns (hub, problem); `problem` is
-        non-None when the spawn cannot run."""
+        configured. Shared by all three edges (issue, fix, and maintenance
+        spawns), so it takes the bare owner/repo. Returns (hub, problem);
+        `problem` is non-None when the spawn cannot run."""
         full_name = f"{owner}/{repo}"
         hub = self.config.hub_for(owner, repo)
         if hub.is_dir():
@@ -1280,16 +1592,21 @@ class DevWatcher:
     def poll_once(self) -> list[tuple[str, Decision]]:
         """One pass: the reaper sweep FIRST (unconditional and
         search-independent — a broken or empty search must never starve
-        it), then both edges: labeled issues (the primary trigger), then —
-        behind the fix_rounds_enabled gate — the review-response edge over
-        open PRs authored by the token. One Decision list covers both
-        edges; the slug shape tells them apart in the logs (`owner/repo#7`
-        vs `owner/repo#pr16`). The pass ends with one INFO summary line so
+        it), then the three edges in order: labeled issues (the primary
+        trigger), then — behind the fix_rounds_enabled gate — the
+        review-response edge over open PRs authored by the token, then —
+        behind the maintain_enabled gate — the maintenance edge over PRs
+        the operator labeled. One Decision list covers all edges (the INFO
+        summary counts them together); the slug shape tells issues from PRs
+        in the logs (`owner/repo#7` vs `owner/repo#pr16`), and the decision
+        reason names the edge. The pass ends with one INFO summary line so
         unattended logs stay legible without -v."""
         reaped = self.reap_finished()
         results = self._poll_issues()
         if self.config.fix_rounds_enabled:
             results.extend(self._poll_prs())
+        if self.config.maintain_enabled:
+            results.extend(self._poll_maintain())
 
         counts = Counter(decision.action for _, decision in results)
         log.info(
@@ -1388,6 +1705,42 @@ class DevWatcher:
             results.append((slug, decision))
         return results
 
+    def _poll_maintain(self) -> list[tuple[str, Decision]]:
+        found = self.github.search_maintain_prs(
+            self.config.maintain_label, self.config.repos
+        )
+        # "candidates" like the other edges: every labeled PR comes back
+        # each poll -- the label is the in-flight state by design (the
+        # ledger, not the label, dedupes), so in-flight work is re-seen
+        # until its session removes the label.
+        log.info(
+            "%d candidate PR(s) labeled %r (in-flight maintenance included "
+            "by design — the session removes the label on completion)",
+            len(found),
+            self.config.maintain_label,
+        )
+
+        results: list[tuple[str, Decision]] = []
+        for owner, repo, number in found:
+            slug = f"{owner}/{repo}#pr{number}"
+            # Defense in depth, same as the other edges: the search is
+            # already repo-scoped, but nothing outside the allowlist is
+            # evaluated.
+            if not self.config.watches(f"{owner}/{repo}"):
+                continue
+            try:
+                decision = self.evaluate_maintain(owner, repo, number)
+            except RateLimited:
+                raise
+            except CommandError as exc:
+                log.error("%s: %s", slug, exc)
+                decision = Decision(Action.SKIPPED, str(exc))
+
+            level = logging.INFO if decision.action != Action.SKIPPED else logging.DEBUG
+            log.log(level, "%s → %s (%s)", slug, decision.action.value, decision.reason)
+            results.append((slug, decision))
+        return results
+
     def run_forever(self) -> None:
         # preflight() is the caller's responsibility -- the CLI runs it once
         # for every mode, so calling it here too would double every check.

{alissa_tools_github_devloop-0.3.0 → alissa_tools_github_devloop-0.4.0}/src/main/alissa/tools/github/devloop/state.py

@@ -16,6 +16,23 @@ leaves every existing ledger untouched. Fix-round cap-outs reuse the
 prefixed (`fix-cap:r<k>`, see loop.fix_cap_kind) so an issue and a PR sharing
 a number can never collide on a row.
 
+The maintenance edge keeps its own additive table too, `maintain_spawns`,
+keyed (repo_slug, number, attempt): `number` is the PULL REQUEST number and
+`attempt` retries a presumed-dead maintenance session while the operator's
+label stays on the PR. No `round` column -- the edge has no review rounds:
+the label is the whole trigger, applied and RE-applied by the operator, and
+completion is the SESSION removing it -- a GitHub-side event this ledger
+never observes, so rows are never deleted. Instead the count/age readers
+take a `since` floor: the loop passes the newest `labeled` event's
+timestamp, so each re-label starts a fresh attempt budget while the
+lifetime rows stay put (maintain_max_attempt keeps session names monotonic
+across those epochs -- a fresh budget must never reuse an old attempt
+number, or the deterministic session name could collide with a zombie).
+Cap-outs reuse the `escalations` table under `maintain-cap` kinds
+(prefixed, so a PR can never collide with an issue-edge `cap` row when
+they share a number; the epoch timestamp folds into the kind so each
+request's cap-out pages the operator again -- see loop.maintain_cap_kind).
+
 Escalations are keyed per KIND ("cap", "assignment", "stalled", ...): each
 condition has its own operator remedy (raise attempt_cap; grant push access;
 check the developer session / close its PR), so each kind's comment must
@@ -62,6 +79,15 @@ CREATE TABLE IF NOT EXISTS fix_spawns (
     spawned_at INTEGER NOT NULL,
     PRIMARY KEY (repo_slug, number, round, attempt)
 );
+
+CREATE TABLE IF NOT EXISTS maintain_spawns (
+    repo_slug  TEXT    NOT NULL,
+    number     INTEGER NOT NULL,
+    attempt    INTEGER NOT NULL,
+    session    TEXT    NOT NULL,
+    spawned_at INTEGER NOT NULL,
+    PRIMARY KEY (repo_slug, number, attempt)
+);
 """
 
 
@@ -147,6 +173,64 @@ class State:
         ).fetchone()
         return None if row["ts"] is None else max(0.0, time.time() - row["ts"])
 
+    def record_maintain_spawn(
+        self, *, repo_slug: str, number: int, attempt: int, session: str
+    ) -> None:
+        """Record a maintenance-session spawn. `repo_slug` is `owner/repo`;
+        `number` is the PR number."""
+        self._db.execute(
+            "INSERT OR REPLACE INTO maintain_spawns "
+            "(repo_slug, number, attempt, session, spawned_at) "
+            "VALUES (?,?,?,?,?)",
+            (repo_slug, number, attempt, session, int(time.time())),
+        )
+        self._db.commit()
+
+    def maintain_attempt_count(
+        self, repo_slug: str, number: int, since: int = 0
+    ) -> int:
+        """Maintenance attempts for this PR spawned at or after `since` (unix
+        seconds). The default floor of 0 counts the PR's lifetime; the loop
+        passes the newest `labeled` event's timestamp so the budget covers
+        only the CURRENT maintenance request (completion never deletes
+        rows -- see the module docstring)."""
+        row = self._db.execute(
+            "SELECT COUNT(*) AS n FROM maintain_spawns "
+            "WHERE repo_slug=? AND number=? AND spawned_at>=?",
+            (repo_slug, number, since),
+        ).fetchone()
+        return int(row["n"])
+
+    def maintain_spawn_age(
+        self, repo_slug: str, number: int, since: int = 0
+    ) -> float | None:
+        """Seconds since the NEWEST maintenance spawn at or after `since` for
+        this PR, or None if none exists there. Newest, and clamped at 0.0,
+        for the same reasons as spawn_age: a retry resets the staleness
+        clock, and a wall-clock step backwards must read as "just spawned",
+        never as a negative age. With the epoch floor, spawns from a PRIOR
+        request read as None -- a fresh re-label must not inherit a
+        weeks-old "stale" age (and the presumed-dead warning behind it)."""
+        row = self._db.execute(
+            "SELECT MAX(spawned_at) AS ts FROM maintain_spawns "
+            "WHERE repo_slug=? AND number=? AND spawned_at>=?",
+            (repo_slug, number, since),
+        ).fetchone()
+        return None if row["ts"] is None else max(0.0, time.time() - row["ts"])
+
+    def maintain_max_attempt(self, repo_slug: str, number: int) -> int:
+        """The highest attempt number ever spawned for this PR (0 when
+        none) -- the LIFETIME horizon for numbering the next attempt.
+        Deliberately unfiltered: a fresh epoch resets the budget, not the
+        numbering, because the deterministic session name folds the attempt
+        number in and an old epoch's session can still be idling in tmux."""
+        row = self._db.execute(
+            "SELECT MAX(attempt) AS m FROM maintain_spawns "
+            "WHERE repo_slug=? AND number=?",
+            (repo_slug, number),
+        ).fetchone()
+        return int(row["m"] or 0)
+
     def spawn_for_session(self, session: str) -> "sqlite3.Row | None":
         """The spawn row behind a developer session name, or None when the
         name is not on THIS ledger. Session names are deterministic per

alissa_tools_github_devloop-0.4.0/src/main/alissa/tools/github/devloop/version

@@ -0,0 +1 @@
+0.4.0

{alissa_tools_github_devloop-0.3.0 → alissa_tools_github_devloop-0.4.0/src/main/alissa_tools_github_devloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.3.0
+Version: 0.4.0
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_devloop-0.3.0/src/main/alissa/tools/github/devloop/version

@@ -1 +0,0 @@
-0.3.0