alissa-tools-github-devloop 0.1.0__py3-none-any.whl

alissa/tools/github/devloop/loop.py

@@ -0,0 +1,620 @@
+"""The watcher loop.
+
+One pass = poll GitHub for open issues carrying the trigger label, decide per
+issue whether a fresh developer session is owed, and enqueue it. The search
+deliberately returns assigned issues too: the daemon must re-see its own
+in-flight work to age it, retry a dead session, and escalate a cap-out.
+GitHub assignment is the server-side in-flight marker (the daemon
+self-assigns BEFORE spawning); assignment-based filtering happens in
+evaluate() via the issue() re-fetch -- a foreign assignee is skipped, a
+fresh self-spawn is in flight. (poll_once pre-skips issues whose search
+payload already shows a foreign assignee, sparing the re-fetch; the
+authoritative re-fetch guard covers everything the daemon might act on.)
+Staleness is a two-signal rule: a spawn is presumed dead only when it is
+older than stale_minutes AND the issue has no linked open PR -- elapsed
+time alone cannot tell a dead session from a live implement→PR→review
+cycle that outlasts the timer. The linked-PR deferral has a floor: once it
+outlasts STALLED_DEFER_MULTIPLE stale windows, a "stalled" operator comment
+is posted -- once per deferral episode (per attempt), so a later attempt
+dying behind its own open PR pings again -- while the loop keeps
+deferring: a session that died with its draft PR open must not be silent
+forever. The local
+ledger only counts attempts, ages the newest spawn so a dead session can
+be retried, and remembers which escalation kinds were already raised.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from .alissa import Alissa
+from .config import HUB_ADD, ON_MISSING_SKIP, ON_MISSING_WARN, Config
+from .ghclient import AssignmentRejected, GitHub, Issue, RateLimited, parse_task_ref
+from .proc import CommandError
+from .state import State
+
+log = logging.getLogger(__name__)
+
+# The origin-task instruction is split in two because the downstream rule is
+# the same either way -- only the starting point differs: a present ref is
+# authoritative; an absent one (spawn_anyway / warn_and_spawn) makes locating
+# or creating the origin the developer's first job.
+_TASK_WITH_ORIGIN = (
+    "The origin Alissa task is {task_ref} — before writing code, create your "
+    "implementation task DOWNSTREAM of it (create_downstream_task), and keep "
+    "its status honest: in_progress while you work, pending_validation at "
+    "handoff."
+)
+
+_TASK_WITHOUT_ORIGIN = (
+    "The issue carries NO origin Alissa task ref — locate the origin task "
+    "behind this issue, or create one, then create your implementation task "
+    "DOWNSTREAM of it before writing code, and keep its status honest: "
+    "in_progress while you work, pending_validation at handoff."
+)
+
+DEV_DIRECTIVE = (
+    "You are an IMPLEMENTER, not a reviewer. Implement GitHub issue "
+    "{issue_url} (attempt {attempt} of {cap}) — the issue is your "
+    "self-contained spec and its acceptance criteria are authoritative. "
+    "{task_instruction} "
+    "Golden path: your cwd is the repo's worktree hub ROOT — create a task "
+    "worktree with `git worktree add TASK-<n>-<DESC>` from there (one task = "
+    "one branch = one worktree; never clone, never work directly on main). "
+    "Implement to the issue's acceptance criteria and VERIFY locally (run the "
+    "repo's test/style/type scripts) before publishing. Open a DRAFT PR whose "
+    "body contains `Closes #{number}` and the task ref, and attach the PR URL "
+    "to the task as evidence. Then drive the review handoff with the "
+    "alissa-pr-review skill, requesting reviewer(s): {reviewers}. In every "
+    "review round the ORDER is load-bearing: post your CR8 triage replies "
+    "FIRST, then push the fixes and re-request review — the review daemon "
+    "re-enters on head movement, so pushing before the triage lands orphans "
+    "your replies. NEVER merge, 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 "
+    "not spawn another; this needs an operator decision: finish the work by "
+    "hand, raise `attempt_cap` to re-enter the loop, or remove the "
+    "`{label}` label to park the issue."
+)
+
+STALLED_COMMENT = (
+    "**Dev loop stalled?** — attempt {attempts} has been in flight "
+    "{minutes} min; PR {urls} is still open — is that session alive? The "
+    "daemon keeps deferring the retry while the PR stays open. Operator "
+    "options: check (and if dead, kill) the developer session and close the "
+    "PR to let the retry proceed, or finish the work by hand. Unassigning "
+    "the issue alone is not enough — the daemon's ledger keeps aging this "
+    "attempt while the PR is open."
+)
+
+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: "
+    "`{login}` most likely lacks push access on `{full_name}`. Grant the "
+    "account push access, or remove the repo from the daemon's allowlist; "
+    "until then no developer session will be spawned for this issue."
+)
+
+
+# Escalation-ledger kinds. Cap-out, assignment-rejection, and a stalled
+# linked-PR deferral have different operator remedies (raise attempt_cap vs
+# grant push access vs check the session / close the PR), so each kind
+# dedupes its operator comment independently -- one must never silence
+# another. Cap and assignment dedupe once-ever per issue: a cap-out is
+# terminal and a push-access failure is permanent. A stall is neither --
+# see stalled_kind() below.
+ESCALATION_CAP = "cap"
+ESCALATION_ASSIGNMENT = "assignment"
+ESCALATION_STALLED = "stalled"
+
+
+def stalled_kind(attempt: int) -> str:
+    """The ledger kind for the stalled ping of ONE deferral episode.
+
+    Unlike cap/assignment, a stall can recur: every attempt can die behind
+    its own open PR, and attempt k's ping must not silence attempt k+1's --
+    keyed on the bare kind, the TERMINAL attempt stalling would defer
+    silently forever, with the cap-out unreachable behind the deferral.
+    `kind` is free-form TEXT, so the attempt number folds into the key (no
+    schema change): one ping per (issue, attempt). A side benefit: the
+    record-even-if-the-comment-fails contract now costs at most one lost
+    ping per EPISODE, where a bare-kind row would have silenced the issue
+    permanently after a single transient comment failure.
+    """
+    return f"{ESCALATION_STALLED}:a{attempt}"
+
+
+# The floor under the linked-PR deferral: an open linked PR defers the stale
+# retry indefinitely -- correct for a live review loop, silent forever for a
+# session that died with its draft PR open (the deferral sits ABOVE the cap
+# check, so even ESCALATION_COMMENT is unreachable while the PR stays open).
+# Once the newest spawn's age reaches this multiple of stale_minutes, the
+# loop posts one "stalled" operator comment per deferral episode and keeps
+# deferring. 2 means the
+# deferral itself has lasted a full extra stale window beyond the point the
+# timer first fired -- long enough that a healthy review loop has usually
+# converged, early enough that a dead session surfaces the same day.
+STALLED_DEFER_MULTIPLE = 2
+
+
+class Action(str, Enum):
+    SPAWNED = "spawned"
+    IN_FLIGHT = "in-flight"
+    CAPPED = "capped"
+    ESCALATED = "escalated"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: Action
+    reason: str = ""
+    attempt: int | None = None
+
+
+def session_name(issue: Issue, attempt: int) -> str:
+    """A tmux-safe developer session name:
+    `develop-<owner>-<repo>-i<n>-a<attempt>`.
+
+    Deterministic on purpose (no nonce, unlike reviewloop): the attempt number
+    comes from the ledger's row count, so every spawn gets a fresh number and
+    the name cannot collide with a still-live session. The owner is folded in
+    because the attempt count is keyed per `owner/repo` -- two owners' ledgers
+    count independently, so `acme/widgets#7` and `other/widgets#7` can both
+    legitimately sit at attempt 1 and a repo-only name would collide.
+    """
+    owner = re.sub(r"[^A-Za-z0-9-]", "-", issue.owner).strip("-").lower()
+    repo = re.sub(r"[^A-Za-z0-9-]", "-", issue.repo).strip("-").lower()
+    return f"develop-{owner}-{repo}-i{issue.number}-a{attempt}"
+
+
+class DevWatcher:
+    def __init__(
+        self,
+        config: Config,
+        github: GitHub | None = None,
+        alissa: Alissa | None = None,
+        state: State | None = None,
+    ):
+        self.config = config
+        self.github = github or GitHub(config.developer_login)
+        self.alissa = alissa or Alissa()
+        self.state = state or State(config.state_db)
+
+    # -- per-issue decision ------------------------------------------------
+
+    def evaluate(self, owner: str, repo: str, number: int) -> Decision:
+        issue = self.github.issue(owner, repo, number)
+        login = self.github.login
+
+        # Closed between search and fetch: nothing left to implement.
+        if issue.state != "open":
+            return Decision(Action.SKIPPED, "issue closed between search and fetch")
+
+        # The re-fetch is the consistency guard: the search deliberately
+        # returns assigned issues (so the daemon re-sees its own in-flight
+        # work), and the fetched assignment is authoritative over any search
+        # staleness -- a foreign assignee means someone else owns the work.
+        others = tuple(a for a in issue.assignees if a and a != login)
+        if others:
+            return Decision(
+                Action.SKIPPED,
+                f"assigned to {', '.join(others)} — not this daemon's to work",
+            )
+
+        attempts = self.state.attempt_count(issue.full_name, number)
+        age = self.state.spawn_age(issue.full_name, number)
+
+        if age is not None and age < self.config.stale_minutes * 60:
+            return Decision(
+                Action.IN_FLIGHT,
+                f"attempt {attempts} enqueued {int(age)}s ago",
+                attempts,
+            )
+
+        if login in issue.assignees and age is None:
+            # Self-assigned but the ledger never spawned: assigned outside this
+            # daemon (by hand, or under another workspace's ledger). Not a
+            # fresh self-spawn, so not ours to double-book.
+            return Decision(
+                Action.SKIPPED,
+                f"assigned to {login} outside this daemon (no spawn on the "
+                f"ledger) — unassign the issue to let the loop take it",
+            )
+
+        # Staleness needs TWO signals, not one: the ledger timer says the
+        # newest spawn is old, but elapsed time alone cannot tell a dead
+        # session from a live one -- a healthy implement → draft-PR → review
+        # loop routinely outlasts stale_minutes. An open PR linked to the
+        # issue is external evidence the work is alive, so the retry (and any
+        # cap-out it would feed) is deferred until that PR closes. The probe
+        # runs ONLY on the stale path: the fresh-in-flight return above keeps
+        # its per-poll cost off the common case. The deferral is floored, not
+        # unbounded: past STALLED_DEFER_MULTIPLE stale windows it posts a
+        # "stalled" operator comment (a dead session's draft PR stays open
+        # forever, and this deferral sits above the cap check, so no other
+        # escalation can reach the issue) -- and then keeps deferring. The
+        # ping dedupes per deferral EPISODE (stalled_kind), not per issue:
+        # every attempt can stall behind its own PR, including the terminal
+        # one.
+        if age is not None:
+            linked = self.github.linked_open_prs(issue.owner, issue.repo, number)
+            if linked:
+                stalled_after = STALLED_DEFER_MULTIPLE * self.config.stale_minutes * 60
+                if age >= stalled_after and not self.state.escalated(
+                    issue.full_name, number, stalled_kind(attempts)
+                ):
+                    self._escalate_stalled(issue, attempts, age, linked)
+                return Decision(
+                    Action.IN_FLIGHT,
+                    f"attempt {attempts} is stale ({int(age / 60)} min) but an "
+                    f"open PR is linked ({', '.join(linked)}) — work is alive "
+                    f"(the review loop can outlast stale_minutes); not "
+                    f"respawning",
+                    attempts,
+                )
+
+        # Never spawn attempt cap+1. Escalate ONCE; `escalated()` dedupes, and
+        # raising attempt_cap re-enters the loop without clearing the ledger.
+        if attempts >= self.config.attempt_cap:
+            if self.state.escalated(issue.full_name, number, ESCALATION_CAP):
+                return Decision(Action.CAPPED, "already escalated", attempts)
+            self._escalate(issue, attempts)
+            return Decision(
+                Action.ESCALATED,
+                f"{attempts} attempts, cap {self.config.attempt_cap}",
+                attempts,
+            )
+
+        if age is not None:
+            log.warning(
+                "%s attempt %d has been in flight %.0f min with no completion "
+                "and no linked open PR — re-enqueuing as attempt %d (developer "
+                "session presumed dead)",
+                issue.issue_slug,
+                attempts,
+                age / 60,
+                attempts + 1,
+            )
+        attempt = attempts + 1
+
+        task_number = parse_task_ref(issue.body)
+        if task_number is None:
+            if self.config.on_missing_origin_task == ON_MISSING_SKIP:
+                return Decision(
+                    Action.SKIPPED,
+                    "no origin Alissa task ref on the issue body "
+                    "(on_missing_origin_task=skip)",
+                    attempt,
+                )
+            if self.config.on_missing_origin_task == ON_MISSING_WARN:
+                log.warning(
+                    "%s has no origin Alissa task ref — spawning anyway; the "
+                    "developer must locate or create the origin task first",
+                    issue.issue_slug,
+                )
+
+        return self._spawn(issue, attempt, task_number)
+
+    # -- actions -----------------------------------------------------------
+
+    def _spawn(self, issue: Issue, attempt: int, task_number: int | None) -> Decision:
+        hub, problem = self._ensure_hub(issue)
+        if problem is not None:
+            return Decision(Action.SKIPPED, problem, attempt)
+
+        task_ref = f"TASK-{task_number}" if task_number is not None else None
+        task_instruction = (
+            _TASK_WITH_ORIGIN.format(task_ref=task_ref)
+            if task_ref is not None
+            else _TASK_WITHOUT_ORIGIN
+        )
+        reviewers = ", ".join(self.config.reviewers) or (
+            "none resolved — follow the alissa-pr-review skill's reviewer "
+            "resolution"
+        )
+        directive = DEV_DIRECTIVE.format(
+            issue_url=issue.url,
+            number=issue.number,
+            attempt=attempt,
+            cap=self.config.attempt_cap,
+            task_instruction=task_instruction,
+            reviewers=reviewers,
+        )
+        name = session_name(issue, attempt)
+
+        # assign_self FIRST: the assignment is the server-side in-flight
+        # marker, so it must land before anything is enqueued -- a crash
+        # between the two leaves an assigned-but-sessionless issue (safe:
+        # evaluate() sees a self-assignment with no ledger spawn and skips;
+        # the operator unassigns to retry), never an unmarked session racing
+        # a second spawn.
+        if self.config.dry_run:
+            log.info(
+                "[dry-run] would assign %s to %s", self.github.login, issue.issue_slug
+            )
+        else:
+            try:
+                self.github.assign_self(issue.owner, issue.repo, issue.number)
+            except AssignmentRejected as exc:
+                return self._escalate_rejection(issue, exc)
+
+        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_spawn(
+                repo_slug=issue.full_name,
+                issue=issue.number,
+                attempt=attempt,
+                session=name,
+            )
+
+        return Decision(
+            Action.SPAWNED,
+            f"session {name} → {task_ref or 'no origin task'}",
+            attempt,
+        )
+
+    def _escalate_rejection(self, issue: Issue, exc: AssignmentRejected) -> Decision:
+        """Escalate-don't-retry: a silently dropped assignment is a permanent,
+        operator-fixable condition (push access), and without the in-flight
+        marker the daemon would respawn a developer against the issue every
+        cycle. No spawn record, no enqueue -- comment once and stop."""
+        log.error("%s: assignment rejected — %s", issue.issue_slug, exc)
+        if self.state.escalated(issue.full_name, issue.number, ESCALATION_ASSIGNMENT):
+            return Decision(Action.CAPPED, "assignment rejected; already escalated")
+
+        body = ASSIGNMENT_REJECTED_COMMENT.format(
+            login=self.github.login, full_name=issue.full_name
+        )
+        try:
+            self.github.comment(issue.owner, issue.repo, issue.number, body)
+        except CommandError as comment_exc:
+            log.error(
+                "could not post the assignment-rejected comment on %s: %s",
+                issue.issue_slug,
+                comment_exc,
+            )
+        self.state.record_escalation(
+            issue.full_name, issue.number, ESCALATION_ASSIGNMENT
+        )
+        return Decision(
+            Action.ESCALATED,
+            "assignment rejected — the account likely lacks push access",
+        )
+
+    def _escalate_stalled(
+        self, issue: Issue, attempts: int, age: float, linked: list[str]
+    ) -> None:
+        """Operator ping when the linked-PR deferral itself runs long: the PR
+        being open is the only thing holding the retry (and the cap-out)
+        back, so a human must check whether the session behind it is still
+        alive. Posted once per deferral EPISODE (the ledger row is keyed
+        stalled_kind(attempts), so a later attempt stalling pings again).
+        The decision stays IN_FLIGHT either way -- this comments, it never
+        respawns."""
+        body = STALLED_COMMENT.format(
+            attempts=attempts, minutes=int(age / 60), urls=", ".join(linked)
+        )
+        log.warning(
+            "STALLED %s attempt %d has been deferred %.0f min behind open "
+            "PR(s) %s — escalating to operator (once per attempt)",
+            issue.issue_slug,
+            attempts,
+            age / 60,
+            ", ".join(linked),
+        )
+
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", issue.issue_slug, body)
+            return
+
+        try:
+            self.github.comment(issue.owner, issue.repo, issue.number, body)
+        except CommandError as exc:
+            log.error(
+                "could not post the stalled-deferral comment on %s: %s",
+                issue.issue_slug,
+                exc,
+            )
+        self.state.record_escalation(
+            issue.full_name, issue.number, stalled_kind(attempts)
+        )
+
+    def _escalate(self, issue: Issue, attempts: int) -> None:
+        body = ESCALATION_COMMENT.format(
+            attempts=attempts, cap=self.config.attempt_cap, label=self.config.label
+        )
+        log.error(
+            "CAP-OUT %s after %d attempt(s) — escalating to operator",
+            issue.issue_slug,
+            attempts,
+        )
+
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", issue.issue_slug, body)
+            return
+
+        try:
+            self.github.comment(issue.owner, issue.repo, issue.number, body)
+        except CommandError as exc:
+            log.error(
+                "could not post escalation comment on %s: %s", issue.issue_slug, exc
+            )
+        self.state.record_escalation(issue.full_name, issue.number, ESCALATION_CAP)
+
+    def _ensure_hub(self, issue: Issue) -> tuple[Path, str | None]:
+        """Resolve the developer's cwd (the hub ROOT), hub-ifying the repo
+        first if configured. Returns (hub, problem); `problem` is non-None
+        when the spawn cannot run."""
+        hub = self.config.hub_for(issue.owner, issue.repo)
+        if hub.is_dir():
+            return hub, None
+
+        if self.config.on_missing_hub != HUB_ADD:
+            return hub, (
+                f"no worktree hub at {hub} — add the repo with "
+                f"`alissa code workspace add {issue.full_name}`, or set "
+                f"on_missing_hub='add' (requires a repos allowlist)"
+            )
+
+        # Guarded twice: config.build() rejects 'add' without an allowlist,
+        # and poll_once() only reaches here for watched repos. Belt and
+        # braces -- this path clones code onto the machine and opens it as an
+        # agent cwd.
+        if not self.config.watches(issue.full_name):
+            return hub, f"{issue.full_name} is not in the repos allowlist"
+
+        if not self.config.manifest_path.is_file():
+            return hub, (
+                f"{self.config.workspace_root} is not an Alissa Code Workspace "
+                f"(no alissa-workspace.yaml) — run `alissa code workspace init`"
+            )
+
+        try:
+            self.alissa.add_repo_to_workspace(
+                issue.owner,
+                issue.repo,
+                self.config.workspace_root,
+                dry_run=self.config.dry_run,
+            )
+        except CommandError as exc:
+            return hub, f"could not hub-ify {issue.full_name}: {exc}"
+
+        if self.config.dry_run:
+            return hub, None
+        if not hub.is_dir():
+            return hub, (
+                f"`alissa code workspace add {issue.full_name}` reported "
+                f"success but {hub} still does not exist — check hub_template "
+                f"against the manifest's `dir:` override"
+            )
+        return hub, None
+
+    # -- preflight ---------------------------------------------------------
+
+    def preflight(self) -> list[str]:
+        """Startup checks. Returns warnings; raises on anything fatal."""
+        warnings: list[str] = []
+
+        # Fatal: a mismatched identity would search one account's issues and
+        # assign / push branches as another, so the in-flight marker breaks.
+        # (The CLI logs the resolved identity via log_effective_config.)
+        login = self.github.verify_identity()
+
+        for reviewer in self.config.reviewers:
+            if reviewer == login:
+                warnings.append(
+                    f"reviewer {reviewer!r} is the developer identity — GitHub "
+                    f"refuses review requests from the PR author, so this "
+                    f"reviewer will never be requested"
+                )
+
+        if not self.config.workspace_root.is_dir():
+            warnings.append(
+                f"workspace_root {self.config.workspace_root} does not exist"
+            )
+        elif not self.config.manifest_path.is_file():
+            warnings.append(
+                f"{self.config.workspace_root} has no alissa-workspace.yaml — "
+                f"it is not an Alissa Code Workspace yet "
+                f"(`alissa code workspace init`)"
+            )
+
+        if not self.config.dry_run and not self.alissa.worker_running():
+            warnings.append(
+                "`alissa worker` does not appear to be running — queued "
+                "developer sessions will not spawn until it is "
+                "(`alissa worker start`)"
+            )
+
+        return warnings
+
+    # -- polling -----------------------------------------------------------
+
+    def poll_once(self) -> list[tuple[str, Decision]]:
+        found = self.github.search_issues(self.config.label, self.config.repos)
+        log.info(
+            "%d open issue(s) labeled %r awaiting a developer",
+            len(found),
+            self.config.label,
+        )
+
+        results = []
+        for owner, repo, number, assignees in found:
+            slug = f"{owner}/{repo}#{number}"
+            # Defense in depth: the search is already repo-scoped, but nothing
+            # outside the allowlist is ever evaluated.
+            if not self.config.watches(f"{owner}/{repo}"):
+                continue
+            # Cheap pre-filter on the search payload's own assignee data: a
+            # foreign login visible in the search item means the work is
+            # someone else's, so the issue() re-fetch is skipped (an issue
+            # parked on a human would otherwise cost one re-fetch per poll,
+            # forever). Search data can lag the live issue; the worst case is
+            # a mis-skip that self-heals on a later poll, which is why ONLY
+            # the foreign case short-circuits -- self-assigned, unassigned,
+            # and assignee-data-free items all still go through evaluate()'s
+            # authoritative re-fetch guard.
+            foreign = tuple(
+                a for a in (assignees or ()) if a and a != self.github.login
+            )
+            if foreign:
+                decision = Decision(
+                    Action.SKIPPED,
+                    f"search already shows assignee(s) "
+                    f"{', '.join(foreign)} — foreign-owned, skipped without "
+                    f"the issue() re-fetch",
+                )
+            else:
+                try:
+                    decision = self.evaluate(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.
+        backoff = self.config.poll_interval
+        while True:
+            # The sleep lives INSIDE the KeyboardInterrupt guard: with a 60s
+            # poll interval (up to 900s backing off) the loop spends nearly
+            # all its wall-clock sleeping, so a real Ctrl-C almost always
+            # lands there and must hit the same clean-exit path.
+            try:
+                try:
+                    self.poll_once()
+                    backoff = self.config.poll_interval
+                except RateLimited as exc:
+                    backoff = min(backoff * 2, 900)
+                    log.warning("rate limited (%s) — backing off %ds", exc, backoff)
+                except CommandError as exc:
+                    backoff = min(backoff * 2, 900)
+                    log.error("poll failed: %s — retrying in %ds", exc, backoff)
+                time.sleep(backoff)
+            except KeyboardInterrupt:
+                log.info("stopping")
+                return

alissa/tools/github/devloop/proc.py

@@ -0,0 +1,56 @@
+"""Subprocess helpers. Everything shells out to `gh` and `alissa` so both keep
+their own auth handling; we never touch tokens ourselves."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+from typing import Sequence
+
+log = logging.getLogger(__name__)
+
+
+class CommandError(RuntimeError):
+    def __init__(self, argv: Sequence[str], returncode: int, stderr: str):
+        self.argv = list(argv)
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"{argv[0]} exited {returncode}: {stderr.strip()[:400]}")
+
+
+def run(
+    argv: Sequence[str],
+    *,
+    timeout: int = 60,
+    check: bool = True,
+    cwd: "str | os.PathLike[str] | None" = None,
+) -> str:
+    """Run a command, return stdout. Never uses shell=True."""
+    log.debug("exec: %s", " ".join(argv))
+    try:
+        proc = subprocess.run(
+            list(argv),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=str(cwd) if cwd is not None else None,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise CommandError(argv, -1, f"timed out after {timeout}s") from exc
+
+    if check and proc.returncode != 0:
+        raise CommandError(argv, proc.returncode, proc.stderr)
+    return proc.stdout
+
+
+def run_json(argv: Sequence[str], *, timeout: int = 60):
+    """Run a command whose stdout is JSON."""
+    out = run(argv, timeout=timeout).strip()
+    if not out:
+        return None
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise CommandError(argv, 0, f"expected JSON, got: {out[:300]}") from exc