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

alissa/tools/github/devloop/loop.py

@@ -21,6 +21,61 @@ 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.
+
+The same pass then runs the REVIEW-RESPONSE edge (fix_rounds_enabled): open
+PRs authored by the token identity whose newest substantive review verdict is
+request_changes, with no pending re-request and no push since that review --
+the ball is demonstrably in the author's court and no session is answering.
+Like the issue edge, the state is derived from GitHub fresh each pass (no
+local PR list, no diffing); the fix_spawns ledger only dedupes one fix
+session per (PR, round), ages it for retry, and caps attempts per round.
+Fix-retry staleness follows the issue edge's two-signal doctrine: the timer
+alone cannot tell a dead fix session from a live one still in its triage
+phase (FIX_DIRECTIVE's load-bearing order puts every CR8 reply BEFORE the
+first push), so the retry is deferred while the author's own review activity
+postdates the review being answered -- the zero-body records those inline
+replies create are the live session's footprint, read from the reviews list
+already in hand. That deferral has the same floor as the issue edge's, and
+needs it more: review records are immutable, so unlike a linked PR (which
+closes) the author-activity signal NEVER clears -- a session that died
+right after its triage replies latches the deferral forever, with the
+retry and the cap-out (below the deferral) both unreachable. Past
+STALLED_DEFER_MULTIPLE stale windows the loop posts one "fix stalled"
+operator comment per deferral episode (per round AND attempt, so a later
+episode pings again) and keeps deferring -- it never respawns over author
+activity. A fix cap-out pages the operator ON the PR: in the capped
+state there is provably no pending re-request, so the reviewer daemon
+(whose only entry point is a review-requested:@me search) cannot see the PR
+-- this edge is the last automation standing and must not stop silently. The
+fix session's terminal act is the re-request, which clears the edge
+server-side and re-arms the reviewer daemon -- and a LIVE dev session
+blocking in alissa-pr-review holds the edge closed the same way, because its
+own re-request is pending for exactly as long as it blocks. Verdicts mirror
+reviewloop's semantics (the two daemons must never disagree): the GitHub
+review state is authoritative where it can speak (APPROVED /
+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.
+
+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
+entire review loops). Both directives tell the session to kill itself as its
+last act, but that self-kill is UNRELIABLE by assumption -- a session that
+crashes, stalls, or is superseded never reaches its last act -- so the sweep
+is the guarantee, not the fast path. The sweep is deliberately
+SEARCH-INDEPENDENT, the reviewer daemon's structural lesson baked in: its
+`_reap_finished` keyed off the poll's search results and starved -- it became
+unreachable the moment the trigger state cleared, which is exactly when
+sessions finish. Here the sweep runs unconditionally at the top of poll_once,
+BEFORE the searches, off the tmux list and the local ledgers alone: it lists
+`develop-*`/`fix-*` sessions via `alissa tmux ls`, cross-references each
+against the spawn/fix ledgers and GitHub state (issue closed / PR closed or
+merged / attempt or round superseded), and kills the idle finished ones via
+`alissa tmux kill <name>` -- one session at a time, never the server. Busy
+sessions and fresh in-flight ones (ledger row younger than stale_minutes) are
+spared, dry-run only logs, and kills are best-effort: a CLI without
+`tmux kill` degrades to a once-per-process warning.
 """
 
 from __future__ import annotations
@@ -28,13 +83,24 @@ from __future__ import annotations
 import logging
 import re
 import time
+from collections import Counter
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
+from typing import Callable
 
 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 .ghclient import (
+    SUBMITTED_STATES,
+    AssignmentRejected,
+    GitHub,
+    Issue,
+    PullRequest,
+    RateLimited,
+    Review,
+    parse_task_ref,
+)
 from .proc import CommandError
 from .state import State
 
@@ -64,18 +130,56 @@ DEV_DIRECTIVE = (
     "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). "
+    "worktree with `git worktree add TASK-<n>-<DESC>`, where <n> is YOUR "
+    "IMPLEMENTATION task's number (the downstream task YOU created, NOT the "
+    "origin task's — first-run lesson: a worker branch named after the "
+    "origin collides with every sibling of that origin), 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."
+    "body contains `Closes #{number}` and BOTH task refs — the origin task "
+    "AND your implementation task: the PR body is the canonical cross-actor "
+    "record, and each actor's tasks live in its own partition — 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. Once your task is "
+    "pending_validation and the handoff is complete, your last act: run "
+    "`alissa tmux kill {session}` to end this session and free the machine "
+    "(best-effort — the daemon's reaper sweep collects stragglers)."
+)
+
+FIX_DIRECTIVE = (
+    "You are an IMPLEMENTER in a fix round, not a reviewer. PR {pr_url} "
+    "received a `request_changes` review (round {round}; this is fix attempt "
+    "{attempt} of {cap}) and no developer session is answering it — you are "
+    "the fresh triage-and-fix session. The PR body carries BOTH task refs "
+    "(origin + implementation): locate YOUR implementation task from it and "
+    "keep its status honest — in_progress while you work, pending_validation "
+    "at handoff. If a ref is missing from the PR body, restoring both is part "
+    "of your job: the PR body is the canonical cross-actor record. "
+    "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 verify the triage of every prior review finding per CR8: exactly "
+    "one reasoned `[triage:*]` reply on each finding's thread — post any that "
+    "are missing. Then fix the pursued findings on the same branch and VERIFY "
+    "locally (run the repo's test/style/type scripts). The ORDER is "
+    "load-bearing: triage replies FIRST, then push the fixes, then re-request "
+    "review from {reviewer} (`gh pr edit {number} --add-reviewer {reviewer}`) "
+    "— the review daemon re-enters on head movement, so pushing before the "
+    "triage lands orphans your replies, and the RE-REQUEST IS YOUR TERMINAL "
+    "STEP: it clears this fix edge server-side and re-arms the reviewer "
+    "daemon, so set your task pending_validation before it and do nothing "
+    "after it except your last act: run `alissa tmux kill {session}` to end "
+    "this session and free the machine (best-effort — the daemon's reaper "
+    "sweep collects stragglers). NEVER merge, never push to main, and do NOT "
+    "create further ali-* sessions — this loop is depth-1."
 )
 
 ESCALATION_COMMENT = (
@@ -96,6 +200,29 @@ STALLED_COMMENT = (
     "attempt while the PR is open."
 )
 
+FIX_CAP_COMMENT = (
+    "**Fix loop cap-out** — {attempts} fix attempt(s) were spawned on review "
+    "round {round} of this PR without any of them completing the round "
+    "(attempt cap: {cap}). The daemon will not spawn another for this round, "
+    "and no other automation can reach the PR in this state: with no pending "
+    "re-request the reviewer daemon's `review-requested:@me` search cannot "
+    "see it. This needs an operator decision: finish the round by hand "
+    "(CR8 triage replies, fixes, re-request review), raise `attempt_cap` to "
+    "re-enter the loop, or close the PR to park the work."
+)
+
+FIX_STALLED_COMMENT = (
+    "**Fix loop stalled?** — fix attempt {attempts} on review round {round} "
+    "has been in flight {minutes} min. The author's own triage replies "
+    "postdate the review being answered, so the daemon keeps deferring the "
+    "retry — but review records never expire, so a fix session that died "
+    "AFTER posting its replies looks alive forever: is that session alive? "
+    "The daemon will keep deferring (it never respawns over author "
+    "activity). Operator options: check (and if dead, kill) the fix "
+    "session and finish the round by hand (fixes, re-request review), or "
+    "close the PR to park the work."
+)
+
 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: "
@@ -115,6 +242,50 @@ ASSIGNMENT_REJECTED_COMMENT = (
 ESCALATION_CAP = "cap"
 ESCALATION_ASSIGNMENT = "assignment"
 ESCALATION_STALLED = "stalled"
+ESCALATION_FIX_CAP = "fix-cap"
+ESCALATION_FIX_STALLED = "fix-stalled"
+
+# 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.
+VERDICT_APPROVE = "approve"
+VERDICT_REQUEST_CHANGES = "request_changes"
+
+
+def fix_cap_kind(round_: int) -> str:
+    """The ledger kind that dedupes ONE round's fix cap-out operator page.
+
+    Folded per round like stalled_kind: round k capping out must not silence
+    round k+1's budget (a fresh review round re-opens the edge with fresh
+    attempts), and the `fix-cap` prefix keeps PR rows from ever colliding
+    with issue-edge kinds when an issue and a PR share a number. The row
+    dedupes FIX_CAP_COMMENT to once per round — commenting, not just
+    recording, because the capped state has provably NO pending re-request
+    (the guard above the cap check returns first otherwise), and reviewloop's
+    only entry point is a `review-requested:@me` search: the two conditions
+    are mutually exclusive by construction, so at cap-out the PR is invisible
+    to the reviewer daemon and this comment is the operator's only signal.
+    """
+    return f"{ESCALATION_FIX_CAP}:r{round_}"
+
+
+def fix_stalled_kind(round_: int, attempt: int) -> str:
+    """The ledger kind for ONE fix-deferral episode's stalled ping.
+
+    stalled_kind's episode reasoning, transposed: the author-activity
+    deferral can latch on every attempt of every round (any fix session can
+    die after its triage replies), and episode (k, j)'s ping must not
+    silence a later one -- a fresh round re-arms the edge with fresh
+    attempts, and a later attempt of the same round can stall behind its
+    own replies after attempt 1 stalled behind its. So the round AND the
+    attempt both fold into the key (`fix-stalled:r<k>a<j>`); the `fix-`
+    prefix keeps PR rows from ever colliding with issue-edge stalled rows
+    when an issue and a PR share a number. Delivery contract as
+    stalled_kind's: the row lands only AFTER the comment posts, so a
+    transient failure retries next poll and the ping lands exactly once per
+    episode.
+    """
+    return f"{ESCALATION_FIX_STALLED}:r{round_}a{attempt}"
 
 
 def stalled_kind(attempt: int) -> str:
@@ -125,10 +296,12 @@ def stalled_kind(attempt: int) -> str:
     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.
+    schema change): one ping per (issue, attempt). Delivery contract: unlike
+    cap/assignment (terminal-state pages, recorded despite a failed comment
+    so the spawn stop is never retried every poll), a stalled row is
+    recorded only AFTER the comment posts -- the ping is the operator's ONLY
+    signal for this episode, so a transient failure retries next poll and
+    the ping lands exactly once.
     """
     return f"{ESCALATION_STALLED}:a{attempt}"
 
@@ -177,6 +350,51 @@ def session_name(issue: Issue, attempt: int) -> str:
     return f"develop-{owner}-{repo}-i{issue.number}-a{attempt}"
 
 
+def fix_session_name(pr: PullRequest, round_: int, attempt: int) -> str:
+    """A tmux-safe fix-session name:
+    `fix-<owner>-<repo>-pr<n>-r<round>-a<attempt>`.
+
+    Deterministic like session_name (no nonce): the attempt number comes from
+    the fix ledger's per-round row count, so every spawn gets a fresh name.
+    The owner is folded in for the same reason as the issue edge (the P3
+    session-name lesson): fix counts are keyed per `owner/repo`, so two
+    owners' PR #16 can both sit at round 1 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"fix-{owner}-{repo}-pr{pr.number}-r{round_}-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.
+
+    COMMENTED-mode reviews cannot express a verdict in GitHub state; the
+    verdict of record then lives in the CR6 envelope on the Alissa review
+    task (reviewloop's `Alissa.latest_verdict` reads it). This stub is
+    permanent BY POLICY, not a scope deferral: the reader is blocked on
+    cross-actor task visibility -- the three daemon identities deliberately
+    do not share Alissa actors (least-privilege plus review independence,
+    operator decision 2026-07-22), so the developer identity cannot read
+    the reviewer's review task at all (GET returns 404, downstream POST
+    403 NOT_OWNER). TODO(blocked on cross-actor observer grants -- a
+    Studio-side platform ask): when that grant lands, this seam takes a
+    real envelope reader -- semantics per reviewloop's
+    alissa.tools.github.reviewloop.alissa.Alissa.latest_verdict (the CR2
+    review task by title `Review PR <owner>/<repo>#<n>`, newest CR6
+    `Review verdict: ... — <word>` evidence envelope), so COMMENTED-mode
+    reviewers close this edge exactly like they close reviewloop's. Until
+    then a COMMENTED-only history conservatively reads as NO verdict (the
+    edge never spawns on an ambiguous verdict) -- which also means a
+    substantive COMMENTED follow-up landing after a CHANGES_REQUESTED
+    demotes that round to no-verdict and closes the edge: accepted as the
+    conservative side of the same policy (never spawn on a guess); the
+    round stays operator-recoverable (the reviewer re-requests or an
+    operator drives it), and the observer-grant reader above is the fix.
+    """
+    return None
+
+
 class DevWatcher:
     def __init__(
         self,
@@ -184,11 +402,19 @@ class DevWatcher:
         github: GitHub | None = None,
         alissa: Alissa | None = None,
         state: State | None = None,
+        envelope_verdict: "Callable[[str, str, int], str | None] | 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)
+        # The COMMENTED-mode verdict tie-breaker (see no_envelope_verdict):
+        # injectable so the future Alissa-envelope reader is one constructor
+        # argument, not a rewrite of the verdict logic.
+        self.envelope_verdict = envelope_verdict or no_envelope_verdict
+        # The reaper's warn-once latch for a CLI without `tmux kill` (kills
+        # are best-effort; the condition is per-process, not per-session).
+        self._kill_warned = False
 
     # -- per-issue decision ------------------------------------------------
 
@@ -308,7 +534,7 @@ class DevWatcher:
     # -- actions -----------------------------------------------------------
 
     def _spawn(self, issue: Issue, attempt: int, task_number: int | None) -> Decision:
-        hub, problem = self._ensure_hub(issue)
+        hub, problem = self._ensure_hub(issue.owner, issue.repo)
         if problem is not None:
             return Decision(Action.SKIPPED, problem, attempt)
 
@@ -322,6 +548,7 @@ class DevWatcher:
             "none resolved — follow the alissa-pr-review skill's reviewer "
             "resolution"
         )
+        name = session_name(issue, attempt)
         directive = DEV_DIRECTIVE.format(
             issue_url=issue.url,
             number=issue.number,
@@ -329,8 +556,8 @@ class DevWatcher:
             cap=self.config.attempt_cap,
             task_instruction=task_instruction,
             reviewers=reviewers,
+            session=name,
         )
-        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
@@ -405,7 +632,11 @@ class DevWatcher:
         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).
+        stalled_kind(attempts), so a later attempt stalling pings again),
+        and the row is recorded only AFTER the comment posts: this ping is
+        the operator's only signal for the episode, so a transient comment
+        failure must retry next poll -- exactly once delivered, unlike the
+        cap/assignment pages (terminal states, recorded despite failure).
         The decision stays IN_FLIGHT either way -- this comments, it never
         respawns."""
         body = STALLED_COMMENT.format(
@@ -428,10 +659,12 @@ class DevWatcher:
             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",
+                "could not post the stalled-deferral comment on %s: %s — "
+                "not recording the episode; the ping retries next poll",
                 issue.issue_slug,
                 exc,
             )
+            return
         self.state.record_escalation(
             issue.full_name, issue.number, stalled_kind(attempts)
         )
@@ -458,18 +691,391 @@ class DevWatcher:
             )
         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)
+    # -- the review-response edge (fix rounds) -----------------------------
+
+    def evaluate_pr(self, owner: str, repo: str, number: int) -> Decision:
+        """Is a fix session owed on this PR? The edge is TRUE only when ALL
+        hold: the PR is open, non-draft, authored by the token identity; a
+        substantive review by the reviewer set exists; its newest verdict
+        reads request_changes; NO re-request is pending (the ball would be in
+        a reviewer's court -- and a live dev session blocking in
+        alissa-pr-review holds its own re-request pending, which is what
+        keeps this edge from double-spawning over it); and NO push landed
+        after that review (a push means an implementer is already answering
+        it). Everything is derived fresh from GitHub -- the ledger only
+        dedupes, ages, and caps the spawn itself."""
+        pr = self.github.pull_request(owner, repo, number)
+
+        # Closed/merged between search and fetch: nothing left to fix.
+        if pr.state != "open":
+            return Decision(Action.SKIPPED, "PR closed between search and fetch")
+
+        # The search carries draft:false, but a PR can flip back to draft
+        # between search and fetch -- and a draft is out of review by
+        # definition (same belt-and-braces as reviewloop's CR1 re-check).
+        if pr.draft:
+            return Decision(Action.SKIPPED, "PR is a draft — not in review")
+
+        # Defense in depth: the search is author:@me already, but a foreign
+        # PR must never grow a fix session pushing to its branch.
+        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 fix",
+            )
+
+        # A pending re-request means a review round is in flight server-side:
+        # either a live session already re-requested (its terminal step) or
+        # the reviewer daemon is being awaited. Either way the ball is NOT in
+        # the author's court. This is also the tier-1 interplay guard: a dev
+        # session blocking in alissa-pr-review keeps its re-request pending
+        # for as long as it blocks, so the edge stays closed under it.
+        if pr.requested_reviewers:
+            return Decision(
+                Action.SKIPPED,
+                f"review re-request pending "
+                f"({', '.join(pr.requested_reviewers)}) — the ball is in the "
+                f"reviewer's court",
+            )
+
+        # One reviews() fetch serves both the round arithmetic (the filtered
+        # reviewer-set view) and the liveness probe below (the raw records,
+        # author's own included) — the probe must cost no extra API call.
+        records = self.github.reviews(pr.owner, pr.repo, pr.number)
+        reviews = self._reviewer_reviews(pr, records)
+        if not reviews:
+            return Decision(
+                Action.SKIPPED,
+                "no substantive review by the reviewer set yet — nothing to "
+                "respond to",
+            )
+
+        # A push newer than the newest review means SOMEONE is already
+        # answering it (a live session mid-fix-round, or a human). Checked
+        # the way reviewloop binds verdicts to heads: the review's commit_id
+        # is the head it reviewed, so commit_id != head_sha means the head
+        # moved after the review. A falsy commit_id (older records lack one)
+        # cannot be checked and falls through, same as reviewloop.
+        newest = reviews[-1]
+        if newest.commit_id and newest.commit_id != pr.head_sha:
+            return Decision(
+                Action.SKIPPED,
+                f"head {pr.head_sha[:8]} is newer than the reviewed commit "
+                f"{newest.commit_id[:8]} — an implementer is already active",
+            )
+
+        verdict = self._verdict(pr, newest)
+        if verdict == VERDICT_APPROVE:
+            return Decision(
+                Action.SKIPPED, "verdict is approve — the merge is the operator's"
+            )
+        if verdict != VERDICT_REQUEST_CHANGES:
+            # COMMENTED/DISMISSED with no readable envelope: ambiguous, and a
+            # fix session is never spawned on an ambiguous verdict.
+            return Decision(
+                Action.SKIPPED,
+                f"newest review state {newest.state} carries no readable "
+                f"verdict (no envelope) — conservative no-op",
+            )
+
+        # One completed round per substantive review (reviewloop's round
+        # arithmetic): the count IS the round this fix session answers.
+        round_ = len(reviews)
+        attempts = self.state.fix_attempt_count(pr.full_name, number, round_)
+        age = self.state.fix_spawn_age(pr.full_name, number, round_)
+
+        if age is not None and age < self.config.stale_minutes * 60:
+            return Decision(
+                Action.IN_FLIGHT,
+                f"fix attempt {attempts} for round {round_} enqueued "
+                f"{int(age)}s ago",
+                attempts,
+            )
+
+        # Fix-retry staleness needs TWO signals, the issue edge's doctrine
+        # verbatim (see the linked-PR probe in evaluate()): the ledger timer
+        # says the newest fix spawn is old, but elapsed time alone cannot
+        # tell a dead fix session from a live one still in its triage phase
+        # -- FIX_DIRECTIVE's load-bearing order puts every CR8 reply BEFORE
+        # the first push, so for that whole phase the head has not moved and
+        # the timer is the only thing speaking. A respawn over a live session
+        # lands on the SAME branch in the SAME worktree, and CR8 replies are
+        # not idempotent (duplicate triage bounces the next round). The
+        # second signal is already in hand: each inline triage reply creates
+        # a zero-body review record authored by the PR author, so author
+        # activity newer than the review being answered means a session is
+        # demonstrably triaging -- defer the retry (and the cap-out behind
+        # it), exactly as the issue edge defers behind a linked open PR. No
+        # author activity + stale falls through to the respawn below.
+        # The deferral is floored, not unbounded, and needs the floor MORE
+        # than the issue edge does: a linked PR closes when the work dies,
+        # but review records are immutable -- once the session is gone its
+        # triage replies latch this deferral forever, with the respawn AND
+        # the cap-out below both unreachable. Past STALLED_DEFER_MULTIPLE
+        # stale windows the loop posts one "fix stalled" operator comment
+        # per deferral episode (fix_stalled_kind: per round AND attempt)
+        # and keeps deferring -- it never respawns over author activity.
+        if age is not None:
+            author_activity = any(
+                r.author == pr.author and r.submitted_at > newest.submitted_at
+                for r in records
+            )
+            if author_activity:
+                stalled_after = STALLED_DEFER_MULTIPLE * self.config.stale_minutes * 60
+                if age >= stalled_after and not self.state.escalated(
+                    pr.full_name, number, fix_stalled_kind(round_, attempts)
+                ):
+                    self._escalate_fix_stalled(pr, round_, attempts, age)
+                return Decision(
+                    Action.IN_FLIGHT,
+                    f"fix attempt {attempts} for round {round_} is stale "
+                    f"({int(age / 60)} min) but the author's own review "
+                    f"activity postdates the review being answered — a live "
+                    f"session is already triaging (its CR8 replies are the "
+                    f"footprint); not respawning",
+                    attempts,
+                )
+
+        # The per-round budget ran dry: stop and page the operator ON the
+        # PR. This edge cannot defer to the reviewer daemon here -- its only
+        # entry point is a `review-requested:@me` search, and this branch is
+        # reachable only with NO pending re-request (the guard above returns
+        # first otherwise), so at cap-out the PR is invisible to reviewloop
+        # and FIX_CAP_COMMENT is the operator's only signal. Deduped by the
+        # fix-cap:r<k> row: once per round.
+        if attempts >= self.config.attempt_cap:
+            kind = fix_cap_kind(round_)
+            if self.state.escalated(pr.full_name, number, kind):
+                return Decision(
+                    Action.CAPPED, f"round {round_} already capped", attempts
+                )
+            self._escalate_fix_cap(pr, round_, attempts)
+            return Decision(
+                Action.ESCALATED,
+                f"{attempts} fix attempts on round {round_}, cap "
+                f"{self.config.attempt_cap} — operator paged on the PR (no "
+                f"pending re-request, so the reviewer daemon cannot see it)",
+                attempts,
+            )
+
+        if age is not None:
+            log.warning(
+                "%s fix attempt %d (round %d) has been in flight %.0f min "
+                "with no re-request — re-enqueuing as attempt %d (fix "
+                "session presumed dead)",
+                pr.pr_slug,
+                attempts,
+                round_,
+                age / 60,
+                attempts + 1,
+            )
+
+        return self._spawn_fix(pr, round_, attempts + 1, newest)
+
+    def _reviewer_reviews(
+        self, pr: PullRequest, records: list[Review]
+    ) -> list[Review]:
+        """Substantive submitted reviews by the reviewer set, oldest first --
+        one per completed round, exactly reviewloop's `my_reviews` rule
+        (SUBMITTED_STATES, empty bodies dropped as inline-comment artifacts,
+        sorted by submitted_at) so the two daemons count the same rounds.
+        `records` is the raw fetched list -- fetched ONCE by evaluate_pr,
+        which also feeds the unfiltered records to the liveness probe.
+
+        Reviewloop filters to ITS OWN login; the mirror image here is the
+        configured reviewers (casefolded -- the set is operator-typed, and
+        GitHub logins are case-insensitive). With no reviewers resolved the
+        filter falls back to any non-author reviewer: the reviewer set is
+        unknown, and a substantive non-author review is still a round. The
+        author's own records never count on either side.
+        """
+        allowed = {r.casefold() for r in self.config.reviewers}
+        mine = [
+            r
+            for r in records
+            if r.author
+            and r.author != pr.author
+            and r.state in SUBMITTED_STATES
+            and r.is_substantive
+            and (not allowed or r.author.casefold() in allowed)
+        ]
+        return sorted(mine, key=lambda r: r.submitted_at)
+
+    def _escalate_fix_cap(self, pr: PullRequest, round_: int, attempts: int) -> None:
+        """Operator page for a fix cap-out, posted ON the PR (the issue
+        edge's _escalate shape): log, comment (dry-run gated), and record
+        the fix-cap:r<k> dedupe row even if the comment fails -- at most one
+        lost page per round, the same trade every other escalation makes."""
+        body = FIX_CAP_COMMENT.format(
+            attempts=attempts, round=round_, cap=self.config.attempt_cap
+        )
+        log.error(
+            "FIX CAP-OUT %s round %d after %d fix attempt(s) — escalating to "
+            "operator on the PR (no pending re-request, so the reviewer "
+            "daemon cannot see it)",
+            pr.pr_slug,
+            round_,
+            attempts,
+        )
+
+        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 fix cap-out comment on %s: %s",
+                pr.pr_slug,
+                exc,
+            )
+        self.state.record_escalation(pr.full_name, pr.number, fix_cap_kind(round_))
+
+    def _escalate_fix_stalled(
+        self, pr: PullRequest, round_: int, attempts: int, age: float
+    ) -> None:
+        """Operator ping when the author-activity deferral itself runs long
+        (_escalate_stalled's shape): the author's own triage replies are the
+        only thing holding the retry (and the cap-out) back, and because
+        review records are immutable that signal never clears on its own --
+        a human must check whether the session behind the replies is still
+        alive. Posted once per deferral EPISODE (the ledger row is keyed
+        fix_stalled_kind(round_, attempts), so a later episode pings
+        again); the row is recorded only AFTER the comment posts, the same
+        exactly-once delivery contract as _escalate_stalled -- a transient
+        failure retries next poll. The decision stays IN_FLIGHT either way
+        -- this comments, it never respawns."""
+        body = FIX_STALLED_COMMENT.format(
+            attempts=attempts, round=round_, minutes=int(age / 60)
+        )
+        log.warning(
+            "FIX STALLED %s fix attempt %d (round %d) has been deferred "
+            "%.0f min behind the author's own triage replies — escalating "
+            "to operator (once per episode)",
+            pr.pr_slug,
+            attempts,
+            round_,
+            age / 60,
+        )
+
+        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 fix stalled-deferral comment on %s: %s — "
+                "not recording the episode; the ping retries next poll",
+                pr.pr_slug,
+                exc,
+            )
+            return
+        self.state.record_escalation(
+            pr.full_name, pr.number, fix_stalled_kind(round_, attempts)
+        )
+
+    def _verdict(self, pr: PullRequest, newest: Review) -> "str | None":
+        """The newest review's verdict, mirroring reviewloop's precedence:
+        the GitHub review state is authoritative where it can speak, and
+        COMMENTED-mode reviews (plus DISMISSED records, which erased their
+        state) defer to the CR6 envelope tie-breaker. None means no readable
+        verdict."""
+        if newest.state == "APPROVED":
+            return VERDICT_APPROVE
+        if newest.state == "CHANGES_REQUESTED":
+            return VERDICT_REQUEST_CHANGES
+        return self.envelope_verdict(pr.owner, pr.repo, pr.number)
+
+    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,
+            )
+
+        hub, problem = self._ensure_hub(pr.owner, pr.repo)
+        if problem is not None:
+            return Decision(Action.SKIPPED, problem, attempt)
+
+        name = fix_session_name(pr, round_, attempt)
+        directive = FIX_DIRECTIVE.format(
+            pr_url=pr.url,
+            number=pr.number,
+            round=round_,
+            attempt=attempt,
+            cap=self.config.attempt_cap,
+            head_ref=pr.head_ref,
+            # Re-request the reviewer whose request_changes this round
+            # answers -- precise, and always resolvable (the review exists).
+            reviewer=review.author,
+            session=name,
+        )
+
+        # No self-assignment here: the PR's authorship IS the server-side
+        # marker (the token already owns it), and the in-flight signal is the
+        # fix ledger row plus, once the session re-requests, the pending
+        # re-request that closes the edge.
+        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_fix_spawn(
+                repo_slug=pr.full_name,
+                number=pr.number,
+                round_=round_,
+                attempt=attempt,
+                session=name,
+            )
+
+        return Decision(
+            Action.SPAWNED,
+            f"fix session {name} → round {round_} ({review.author}: "
+            f"request_changes)",
+            attempt,
+        )
+
+    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."""
+        full_name = f"{owner}/{repo}"
+        hub = self.config.hub_for(owner, 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"`alissa code workspace add {full_name}`, or set "
                 f"on_missing_hub='add' (requires a repos allowlist)"
             )
 
@@ -477,8 +1083,8 @@ class DevWatcher:
         # 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.watches(full_name):
+            return hub, f"{full_name} is not in the repos allowlist"
 
         if not self.config.manifest_path.is_file():
             return hub, (
@@ -488,19 +1094,19 @@ class DevWatcher:
 
         try:
             self.alissa.add_repo_to_workspace(
-                issue.owner,
-                issue.repo,
+                owner,
+                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}"
+            return hub, f"could not hub-ify {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"`alissa code workspace add {full_name}` reported "
                 f"success but {hub} still does not exist — check hub_template "
                 f"against the manifest's `dir:` override"
             )
@@ -545,12 +1151,168 @@ class DevWatcher:
 
         return warnings
 
+    # -- the session reaper ------------------------------------------------
+
+    def reap_finished(self) -> int:
+        """The sweep: kill idle, finished `develop-*`/`fix-*` sessions.
+        Returns how many were killed (or would be, under dry-run).
+
+        Runs EVERY pass, from the tmux list and the local ledgers alone --
+        never from the polls' search results (the reviewer daemon's
+        `_reap_finished` starved exactly there: keyed off the search, it
+        became unreachable once the trigger state cleared, which is when
+        sessions finish). "Finished" needs a positive signal per session:
+        the issue closed, the PR closed/merged, or a newer attempt/round on
+        the ledger superseded it. Everything else is spared -- busy
+        sessions, fresh in-flight ones (row younger than stale_minutes, the
+        same grace the retry logic uses), sessions this ledger does not know
+        (another workspace's, or the documented enqueue-before-ledger crash
+        window), and sessions whose GitHub check fails this pass. Kills go
+        through `alissa tmux kill <name>` one session at a time (never the
+        server) and are best-effort; dry-run only logs."""
+        try:
+            sessions = self.alissa.list_sessions()
+        except CommandError as exc:
+            log.warning("reaper: could not list sessions (%s) — skipping "
+                        "this sweep", exc)
+            return 0
+
+        reaped = 0
+        for entry in sessions:
+            name = str(entry.get("name") or "")
+            if not name.startswith(("develop-", "fix-")):
+                continue
+            if entry.get("live") is False:
+                # A registered-but-gone session has no tmux session to kill;
+                # `alissa tmux cleanup` owns purging stale registrations.
+                continue
+            try:
+                verdict = self._session_finished(name)
+            except CommandError as exc:
+                log.warning(
+                    "reaper: could not cross-reference %s (%s) — spared "
+                    "this pass", name, exc,
+                )
+                continue
+            if verdict is None:
+                continue
+            if entry.get("status") != "idle":
+                log.debug(
+                    "reaper: %s is finished (%s) but not idle (%s) — spared",
+                    name, verdict, entry.get("status"),
+                )
+                continue
+            if self.config.dry_run:
+                log.info("[dry-run] would kill session %s (%s)", name, verdict)
+                reaped += 1
+                continue
+            try:
+                self.alissa.kill_session(name)
+            except CommandError as exc:
+                if not self._kill_warned:
+                    self._kill_warned = True
+                    log.warning(
+                        "reaper: could not kill %s (%s) — kills are "
+                        "best-effort (this CLI may lack `alissa tmux "
+                        "kill`); warning once, later failures log at DEBUG",
+                        name, exc,
+                    )
+                else:
+                    log.debug("reaper: could not kill %s (%s)", name, exc)
+                continue
+            log.info("reaper: killed finished session %s (%s)", name, verdict)
+            reaped += 1
+        return reaped
+
+    def _session_finished(self, name: str) -> "str | None":
+        """Why this worker session is finished, or None to spare it.
+
+        The cheap checks run first: the ledger lookup (no match -> spare:
+        not provably ours), the fresh-in-flight grace (no GitHub call for a
+        session younger than stale_minutes -- it may still be initializing,
+        and a finished one waits at most one stale window for the sweep),
+        and ledger supersession (a newer attempt/round exists, so this
+        session's episode is over whatever GitHub says). Only a stale,
+        non-superseded session costs a GitHub fetch, whose closed/merged
+        state is the terminal signal. CommandError propagates to the caller
+        (spare this pass); RateLimited propagates further out to
+        run_forever's backoff, like every other GitHub call in the pass."""
+        row = self.state.spawn_for_session(name)
+        if row is not None:
+            slug, number = row["repo_slug"], row["issue"]
+            if time.time() - row["spawned_at"] < self.config.stale_minutes * 60:
+                return None
+            newest = self.state.attempt_count(slug, number)
+            if row["attempt"] < newest:
+                return f"superseded by attempt {newest}"
+            owner, _, repo = slug.partition("/")
+            if self.github.issue(owner, repo, number).state != "open":
+                return "issue closed"
+            return None
+
+        row = self.state.fix_spawn_for_session(name)
+        if row is not None:
+            slug, number = row["repo_slug"], row["number"]
+            if time.time() - row["spawned_at"] < self.config.stale_minutes * 60:
+                return None
+            newest_round = self.state.max_fix_round(slug, number)
+            if row["round"] < newest_round:
+                return f"superseded by round {newest_round}"
+            newest = self.state.fix_attempt_count(slug, number, row["round"])
+            if row["attempt"] < newest:
+                return (
+                    f"superseded by attempt {newest} of round {row['round']}"
+                )
+            owner, _, repo = slug.partition("/")
+            if self.github.pull_request(owner, repo, number).state != "open":
+                return "PR closed/merged"
+            return None
+
+        log.debug(
+            "reaper: %s matches a worker name but is not on this ledger — "
+            "spared (another workspace's session, or the "
+            "enqueue-before-ledger crash window)", name,
+        )
+        return None
+
     # -- polling -----------------------------------------------------------
 
     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
+        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())
+
+        counts = Counter(decision.action for _, decision in results)
+        log.info(
+            "poll summary: %d candidate(s) — %d spawned, %d in-flight, "
+            "%d skipped, %d escalated, %d capped; %d session(s) reaped",
+            len(results),
+            counts[Action.SPAWNED],
+            counts[Action.IN_FLIGHT],
+            counts[Action.SKIPPED],
+            counts[Action.ESCALATED],
+            counts[Action.CAPPED],
+            reaped,
+        )
+        return results
+
+    def _poll_issues(self) -> list[tuple[str, Decision]]:
         found = self.github.search_issues(self.config.label, self.config.repos)
+        # "candidates", not "awaiting a developer": the search deliberately
+        # includes assigned issues (the daemon must re-see its own in-flight
+        # work), so the count covers work in every state, not a backlog.
         log.info(
-            "%d open issue(s) labeled %r awaiting a developer",
+            "%d candidate issue(s) labeled %r (assigned issues included by "
+            "design)",
             len(found),
             self.config.label,
         )
@@ -595,6 +1357,37 @@ class DevWatcher:
             results.append((slug, decision))
         return results
 
+    def _poll_prs(self) -> list[tuple[str, Decision]]:
+        found = self.github.search_prs(self.config.repos)
+        # "candidates" for the same reason as the issue edge: every open PR
+        # authored by the token comes back, whatever review state it is in.
+        log.info(
+            "%d candidate PR(s) authored by %s (PRs in every review state "
+            "included by design)",
+            len(found),
+            self.github.login,
+        )
+
+        results: list[tuple[str, Decision]] = []
+        for owner, repo, number in found:
+            slug = f"{owner}/{repo}#pr{number}"
+            # Defense in depth, same as the issue edge: 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_pr(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.