alissa-tools-github-devloop 0.8.22__tar.gz → 0.8.23__tar.gz

{alissa_tools_github_devloop-0.8.22/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.23}/PKG-INFO

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

{alissa_tools_github_devloop-0.8.22 → alissa_tools_github_devloop-0.8.23}/src/main/alissa/tools/github/devloop/loop.py

@@ -810,6 +810,24 @@ RESUME_DIRECTIVE = (
     "(best-effort — the daemon's reaper sweep collects stragglers)."
 )
 
+# The handover clause (issue #121), shared by FIX_DIRECTIVE and
+# FIX_RESUME_DIRECTIVE. When a later review round lands on the head a fix
+# session is still working (the 2026-09-15 studio#1243 shape: a phantom round
+# 2 on round 1's head, minutes after round 1), the daemon no longer spawns a
+# second session onto the same branch -- it posts FIX_HANDOVER_COMMENT on the
+# PR and moves the live session's ledger row to the new round. The triage
+# loop reads review THREADS, not the PR's issue comments, so the contract has
+# to say it: look for a newer round before the terminal re-request.
+_NEWER_ROUNDS = (
+    "Before you re-request review, check the PR for a NEWER review round: "
+    "if another `request_changes` round (or a daemon comment beginning "
+    "`Round N+1 arrived while the round-N fix session … is still working "
+    "on this head`) landed while you worked, the daemon has handed that "
+    "round to THIS session instead of spawning a second one on your branch "
+    "— triage and address its findings here as well, and re-request review "
+    "ONCE, after the newest round is answered. "
+)
+
 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 "
@@ -831,6 +849,7 @@ FIX_DIRECTIVE = (
     "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). "
+    + _NEWER_ROUNDS
     + _FIX_DELIVERY_NOTE
     + " "
     + _APPROVE_FOLLOWUP
@@ -887,6 +906,7 @@ FIX_RESUME_DIRECTIVE = (
     "the ORIGINAL acceptance criteria the issue set, and VERIFY locally (run "
     "the repo's test/style/type scripts). NEVER force-push: history stays "
     "append-only, or the review threads lose their anchors. "
+    + _NEWER_ROUNDS
     + _FIX_DELIVERY_NOTE
     + " "
     + _APPROVE_FOLLOWUP
@@ -1000,6 +1020,29 @@ FIX_STALLED_COMMENT = (
     "close the PR to park the work."
 )
 
+# The hidden marker that identifies a fix-round handover comment (issue #121)
+# -- a machine-findable anchor for the live session and for anyone auditing
+# the PR, distinct from ACTIVITY_MARKER so the two kinds of comment never
+# collide on one PR. Dedupe is NOT by marker but by the fix-handover:r<k>
+# ledger row (see fix_handover_kind): once per (PR, round).
+FIX_HANDOVER_MARKER = "<!-- alissa-devloop:fix-handover -->"
+
+# The steering comment the fix edge posts INSTEAD of spawning when a later
+# review round lands on the head a fix session is still working. The first
+# sentence is the issue's mandated text verbatim; the trailer says what the
+# daemon did and what happens if the session dies anyway.
+FIX_HANDOVER_COMMENT = (
+    FIX_HANDOVER_MARKER + "\n"
+    "Round {new_round} arrived while the round-{round} fix session "
+    "`{session}` is still working on this head — handing it over: address "
+    "the round-{new_round} findings in the same session and re-request "
+    "review once.\n\n"
+    "_devloop: no second fix session was spawned for round {new_round} (head "
+    "`{head}` is the one `{session}` is working). If that session dies "
+    "without re-requesting review, the stale path re-enqueues round "
+    "{new_round} as its next attempt._"
+)
+
 MAINTAIN_CAP_COMMENT = (
     "**Maintain loop cap-out** — {attempts} maintenance attempt(s) were "
     "spawned on this PR without any of them completing (attempt cap: {cap}; "
@@ -1190,6 +1233,11 @@ ESCALATION_ASSIGNMENT = "assignment"
 ESCALATION_STALLED = "stalled"
 ESCALATION_FIX_CAP = "fix-cap"
 ESCALATION_FIX_STALLED = "fix-stalled"
+# The round handover's once-per-(PR, round) row (issue #121, see
+# fix_handover_kind). A steering comment, not an operator page -- it lives in
+# the escalations table because that is the daemon's dedupe gate for
+# comments that must land exactly once and survive a degraded ledger.
+ESCALATION_FIX_HANDOVER = "fix-handover"
 
 # The pre-PR liveness deferral's own kind (see live_stalled_kind). Distinct
 # from ESCALATION_STALLED because the two stories are different and so are
@@ -1503,6 +1551,21 @@ def fix_stalled_kind(round_: int, attempt: int) -> str:
     return f"{ESCALATION_FIX_STALLED}:r{round_}a{attempt}"
 
 
+def fix_handover_kind(round_: int) -> str:
+    """The ledger kind that dedupes ONE round's handover comment (issue #121).
+
+    Keyed per round (`fix-handover:r<k>`): round k+1 handed to a live session
+    must not silence a round k+2 handed to the same session later, and the
+    `fix-` prefix keeps the row from colliding with issue-edge kinds when an
+    issue and a PR share a number. Delivery contract as fix_stalled_kind's:
+    the row lands only AFTER the comment posts, so a transient failure
+    retries next poll and the steering lands exactly once per round. The
+    ledger round bump rides BEHIND the comment for the same reason -- a
+    bumped row would close this edge's fresh-in-flight gate before the
+    comment ever landed."""
+    return f"{ESCALATION_FIX_HANDOVER}:r{round_}"
+
+
 def stalled_kind(attempt: int) -> str:
     """The ledger kind for the stalled ping of ONE deferral episode.
 
@@ -3947,15 +4010,35 @@ class DevWatcher:
         age = self.state.fix_spawn_age(pr.full_name, number, round_)
 
         if age is not None and age < self.config.stale_minutes * 60:
+            # The row's own session name, not one re-derived from the
+            # attempt: after a handover (below) the row answering round k+1
+            # still carries its `-r<k>-` name, and the console reads this.
             return Decision(
                 Action.IN_FLIGHT,
                 f"fix attempt {attempts} for round {round_} enqueued "
                 f"{int(age)}s ago",
                 attempts,
-                session=fix_session_name(pr, round_, attempts),
+                session=self.state.newest_fix_spawn_session(
+                    pr.full_name, number, round_
+                ) or fix_session_name(pr, round_, attempts),
                 round=round_,
             )
 
+        # A round nothing was spawned for yet -- but the PREVIOUS round's fix
+        # session may still be alive on this very head (issue #121, the
+        # studio#1243 shape: the reviewer daemon posted a phantom round 2 on
+        # round 1's head four minutes after round 1, and this edge spawned a
+        # second session onto the branch the first was mid-work on). A live
+        # session on an unchanged head gets the new round handed to it with
+        # one steering comment; the spawn below is for a head that moved or a
+        # session that is gone. Above the external-claim check because it
+        # spends nothing (ledger + the pass's roster) and a live local session
+        # is the strongest evidence this edge can hold.
+        if age is None:
+            handed = self._hand_over_round(pr, round_, reviews, roster)
+            if handed is not None:
+                return handed
+
         # The cross-instance claim check, the issue edge's placement
         # transposed: past the fresh-in-flight return, the local ledger no
         # longer vouches for this round, and a peer instance's fresh spawn
@@ -4038,7 +4121,8 @@ class DevWatcher:
                         f"session may be there, already triaging (its CR8 "
                         f"replies are the footprint); not respawning",
                         attempts,
-                        session=fix_session_name(pr, round_, attempts),
+                        session=row_session
+                        or fix_session_name(pr, round_, attempts),
                         round=round_,
                         defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
@@ -5554,6 +5638,215 @@ class DevWatcher:
             pr.full_name, pr.number, fix_stalled_kind(round_, attempts)
         )
 
+    def _hand_over_round(
+        self,
+        pr: PullRequest,
+        round_: int,
+        reviews: list[Review],
+        roster: "SessionLiveness | None",
+    ) -> "Decision | None":
+        """Round `round_` just landed and nothing was spawned for it. Is the
+        previous round's fix session still ALIVE on this head? Then the round
+        is ITS to answer (issue #121): post one steering comment, move the
+        session's ledger row to this round, and spawn nothing. None means
+        "no handover -- spawn as always".
+
+        The gates, cheapest first, and every one of them is a reason to keep
+        the legacy spawn:
+
+        * no roster, or a listing that failed -- INDETERMINATE, and the issue
+          keeps today's behaviour for it (a spawn); the fail-safe direction
+          is inverted here on purpose: the wedge and resume gates defer
+          because their remedy is a MUTATION on a possibly-live branch, while
+          this gate's remedy is a comment, so ambiguity must not turn a real
+          new round into silence;
+        * the ledger holds no earlier round for this PR, or its newest round
+          is not below this one (a review deleted outright, or a ledger
+          written by a newer daemon -- NOT a dismissal: SUBMITTED_STATES
+          keeps DISMISSED records, so dismissing never shrinks the count);
+        * the newest session of that earlier round is not ALIVE -- DEAD is
+          the ordinary "session finished, next round" flow, and it spawns;
+        * the head is not that session's (see _head_is_sessions) -- the
+          round is on work someone else pushed, and it spawns.
+
+        The comment lands BEFORE the ledger moves, and the move is skipped
+        when the comment fails: a moved row closes the fresh-in-flight gate
+        above, so a comment that failed once would never be retried. With the
+        fix-handover:r<k> row down, the retry re-enters here with the comment
+        already deduped and just moves the row -- the same retry covers a
+        move that found no row to move (logged as an error: the ledger is
+        then not what the daemon just said it was). Dry-run comments nothing
+        and moves nothing. Both decisions ride Action.IN_FLIGHT with
+        DEFER_IN_FLIGHT: a handover is a hold behind own work already on the
+        lane, and the console must be able to tell it from a spawn.
+
+        What the live session does with it: FIX_DIRECTIVE's _NEWER_ROUNDS
+        clause tells it to look for a newer round before its terminal
+        re-request. If it dies without one, the moved row is what the stale
+        path ages: `stale_minutes` after the handover, with the session gone,
+        the edge re-enqueues attempt k+1 of THIS round (never of the old
+        one), because the row now says this is the round in flight."""
+        if roster is None or not roster.listed:
+            return None
+        previous = self.state.max_fix_round(pr.full_name, pr.number)
+        if not previous or previous >= round_:
+            return None
+        row = self.state.newest_fix_spawn(pr.full_name, pr.number, previous)
+        if row is None:
+            return None
+        session = str(row["session"])
+        if roster.of(session) is not Liveness.ALIVE:
+            return None
+        if not self._head_is_sessions(pr, row, reviews):
+            log.info(
+                "%s round %d landed while the round-%d fix session %s is "
+                "still listed, but head %s is not that session's — spawning "
+                "as usual",
+                pr.pr_slug,
+                round_,
+                previous,
+                session,
+                pr.head_sha[:8],
+            )
+            return None
+
+        kind = fix_handover_kind(round_)
+        body = FIX_HANDOVER_COMMENT.format(
+            new_round=round_,
+            round=previous,
+            session=session,
+            head=pr.head_sha[:8],
+        )
+        if self.config.dry_run:
+            log.info(
+                "[dry-run] would hand round %d of %s to the live fix session "
+                "%s and comment:\n%s",
+                round_,
+                pr.pr_slug,
+                session,
+                body,
+            )
+        elif not self.state.escalated(pr.full_name, pr.number, kind):
+            log.warning(
+                "%s round %d arrived while the round-%d fix session %s is "
+                "ALIVE on the same head %s — handing the round to it (one "
+                "steering comment), NOT spawning a second session",
+                pr.pr_slug,
+                round_,
+                previous,
+                session,
+                pr.head_sha[:8],
+            )
+            try:
+                self.github.comment(pr.owner, pr.repo, pr.number, body)
+            except CommandError as exc:
+                log.error(
+                    "could not post the round-%d handover comment on %s: %s "
+                    "— not moving the ledger row; the handover retries next "
+                    "poll",
+                    round_,
+                    pr.pr_slug,
+                    exc,
+                )
+                return Decision(
+                    Action.IN_FLIGHT,
+                    f"round {round_} is the live round-{previous} fix "
+                    f"session {session}'s to answer, but the steering comment "
+                    f"could not be posted — retrying next poll",
+                    int(row["attempt"]),
+                    session=session,
+                    round=round_,
+                    defer_token=loop_events_mod.DEFER_IN_FLIGHT,
+                )
+            self.state.record_escalation(pr.full_name, pr.number, kind)
+
+        if not self.config.dry_run:
+            moved = self.state.hand_over_fix_spawn(
+                repo_slug=pr.full_name,
+                number=pr.number,
+                session=session,
+                round_=round_,
+                head_sha=pr.head_sha,
+            )
+            if not moved:
+                log.error(
+                    "%s round %d handover: no fix_spawns row carries session "
+                    "%s any more — the ledger was not moved (the row is "
+                    "still on round %d); retrying the move next poll",
+                    pr.pr_slug,
+                    round_,
+                    session,
+                    previous,
+                )
+                return Decision(
+                    Action.IN_FLIGHT,
+                    f"round {round_} is the live round-{previous} fix "
+                    f"session {session}'s to answer (steering comment "
+                    f"posted), but its ledger row could not be moved — "
+                    f"retrying next poll",
+                    int(row["attempt"]),
+                    session=session,
+                    round=round_,
+                    defer_token=loop_events_mod.DEFER_IN_FLIGHT,
+                )
+        # The moved row is attempt 1 of the new round (see
+        # State.hand_over_fix_spawn); dry-run moved nothing and reports the
+        # row as it stands.
+        return Decision(
+            Action.IN_FLIGHT,
+            f"round {round_} handed to the live round-{previous} fix session "
+            f"{session} on the same head {pr.head_sha[:8]} (steering comment "
+            f"posted once; no second session)",
+            int(row["attempt"]) if self.config.dry_run else 1,
+            session=session,
+            round=round_,
+            defer_token=loop_events_mod.DEFER_IN_FLIGHT,
+        )
+
+    def _head_is_sessions(
+        self, pr: PullRequest, row: "sqlite3.Row", reviews: list[Review]
+    ) -> bool:
+        """Is the PR's current head the one the row's session is working --
+        the head it was spawned against, or one it has pushed since?
+
+        Three tiers, cheapest first, and the first two cost nothing:
+
+        1. the ledger's spawn head (`head_sha`, recorded since issue #121;
+           '' on older rows, which skip this tier);
+        2. the PREVIOUS verdict's head: the round before this one was
+           reviewed on `commit_id`, and a head still equal to it has not
+           moved between the rounds -- the issue's "simply" test, and the
+           #1243 shape exactly (round 2 on round 1's head);
+        3. a head that POSTDATES the session's spawn: one branch, one live
+           session, so a commit made after the session started is that
+           session's own push (the directives commit and push within
+           seconds). One GET, on this rare path only, and any failure to
+           read the instant answers False -- the legacy spawn.
+
+        False means "the head moved" for the handover's purposes, which keeps
+        today's behaviour (issue #121 §4)."""
+        spawn_head = str(row["head_sha"] or "")
+        if spawn_head and pr.head_sha == spawn_head:
+            return True
+        if len(reviews) >= 2:
+            before = reviews[-2]
+            if before.commit_id and before.commit_id == pr.head_sha:
+                return True
+        try:
+            committed = self.github.commit_time(pr.owner, pr.repo, pr.head_sha)
+        except CommandError as exc:
+            log.warning(
+                "could not read the commit instant of %s head %s (%s) — "
+                "treating the head as moved",
+                pr.pr_slug,
+                pr.head_sha[:8],
+                exc,
+            )
+            return False
+        if committed is None:
+            return False
+        return committed >= int(row["spawned_at"])
+
     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
@@ -5787,6 +6080,9 @@ class DevWatcher:
                 round_=round_,
                 attempt=attempt,
                 session=name,
+                # The head this session takes the round against -- the
+                # handover check's first tier (issue #121).
+                head_sha=pr.head_sha,
             )
 
         resumed = (

{alissa_tools_github_devloop-0.8.22 → alissa_tools_github_devloop-0.8.23}/src/main/alissa/tools/github/devloop/state.py

@@ -8,7 +8,11 @@ can be retried, and to remember which escalations were already raised.
 The review-response edge keeps its own additive table, `fix_spawns`, keyed
 (repo_slug, number, round, attempt): `number` is the PULL REQUEST number (the
 edge has no issue), `round` is the substantive-review count the fix session
-answers, and `attempt` retries a presumed-dead fix session within one round.
+is CURRENTLY ANSWERING (the round it was spawned for, until a handover -- see
+`hand_over_fix_spawn` -- moves the row to a later round without spawning),
+`attempt` retries a presumed-dead fix session within one round, and
+`head_sha` is the PR head the row's session took that round against (the
+spawn head, refreshed on handover; '' on rows written before the column).
 A separate table rather than new columns on `spawns` because the two edges
 age and dedupe on different keys (issue vs PR+round), and an additive table
 leaves every existing ledger untouched. Fix-round cap-outs reuse the
@@ -135,6 +139,7 @@ CREATE TABLE IF NOT EXISTS fix_spawns (
     attempt    INTEGER NOT NULL,
     session    TEXT    NOT NULL,
     spawned_at INTEGER NOT NULL,
+    head_sha   TEXT    NOT NULL DEFAULT '',
     PRIMARY KEY (repo_slug, number, round, attempt)
 );
 
@@ -193,6 +198,10 @@ CREATE TABLE IF NOT EXISTS poll_snapshots (
 _COLUMN_MIGRATIONS = (
     ("poll_snapshots", "deferred", "INTEGER NOT NULL DEFAULT 0"),
     ("poll_snapshots", "foreign_reaped", "INTEGER NOT NULL DEFAULT 0"),
+    # The head a fix session took its round against (issue #121): rows
+    # written before the column read '' and the handover check falls back to
+    # the previous verdict's head for them.
+    ("fix_spawns", "head_sha", "TEXT NOT NULL DEFAULT ''"),
 )
 
 
@@ -558,18 +567,74 @@ class State:
         return row is not None
 
     def record_fix_spawn(
-        self, *, repo_slug: str, number: int, round_: int, attempt: int, session: str
+        self, *, repo_slug: str, number: int, round_: int, attempt: int, session: str,
+        head_sha: str = "",
     ) -> None:
         """Record a fix-session spawn for one review round. `repo_slug` is
-        `owner/repo`; `number` is the PR number."""
+        `owner/repo`; `number` is the PR number; `head_sha` is the PR head the
+        session was spawned against (the handover check's first tier -- see
+        loop.DevWatcher._hand_over_round)."""
         self._db.execute(
             "INSERT OR REPLACE INTO fix_spawns "
-            "(repo_slug, number, round, attempt, session, spawned_at) "
-            "VALUES (?,?,?,?,?,?)",
-            (repo_slug, number, round_, attempt, session, int(time.time())),
+            "(repo_slug, number, round, attempt, session, spawned_at, head_sha) "
+            "VALUES (?,?,?,?,?,?,?)",
+            (repo_slug, number, round_, attempt, session, int(time.time()),
+             head_sha or ""),
         )
         self._db.commit()
 
+    def newest_fix_spawn(
+        self, repo_slug: str, number: int, round_: int
+    ) -> "sqlite3.Row | None":
+        """The newest fix-spawn row of THIS PR round (session, attempt,
+        spawned_at, head_sha), or None when the round was never spawned --
+        newest_fix_spawn_session with the rest of the row, for the handover
+        check that needs the head and the spawn instant too."""
+        return self._db.execute(
+            "SELECT session, attempt, spawned_at, head_sha FROM fix_spawns "
+            "WHERE repo_slug=? AND number=? AND round=? "
+            "ORDER BY spawned_at DESC, attempt DESC LIMIT 1",
+            (repo_slug, number, round_),
+        ).fetchone()
+
+    def hand_over_fix_spawn(
+        self, *, repo_slug: str, number: int, session: str, round_: int,
+        head_sha: str,
+    ) -> bool:
+        """Move a live fix session's row to the round it is now answering
+        (issue #121): a later review round landed on the head that session is
+        still working, so the daemon handed the round to it instead of
+        spawning a second session. The row's `round` becomes `round_`, its
+        `head_sha` the head handed over, and `spawned_at` NOW -- the staleness
+        clock restarts at the handover, because the session took the new
+        round at that instant and the stale path must not fire on it one poll
+        later just because the session was already old.
+
+        ONE row moves, not a copy: the console's inbox then shows one session
+        answering one round, `max_fix_round` reads the handed-over round (so
+        the reaper never counts the session as superseded by the round it is
+        answering), and the round's attempt budget starts at this row -- so
+        the row is RENUMBERED to attempt 1 (PR #122 review round 1). The
+        attempt ledger's contract is that a round's attempts are contiguous
+        from 1 (`fix_attempt_count` is a COUNT, and `attempts + 1` must be a
+        free slot for the next spawn); a resumed session's row is attempt 2,
+        and moving it as attempt 2 would leave the new round with one row
+        that COUNTs as one attempt -- the stale respawn would then
+        `INSERT OR REPLACE` over it as attempt 2 every stale window, and the
+        attempt cap would never fire. The target key (repo_slug, number,
+        round_, 1) is free by construction: the caller only hands over a
+        round nothing was spawned for. Strict like record_fix_spawn: a row
+        the daemon believes it moved but did not would spawn over the live
+        session next poll. Returns False when no row carries `session` on
+        this PR."""
+        cursor = self._db.execute(
+            "UPDATE fix_spawns SET round=?, attempt=1, head_sha=?, spawned_at=? "
+            "WHERE repo_slug=? AND number=? AND session=?",
+            (round_, head_sha or "", int(time.time()), repo_slug, number, session),
+        )
+        self._db.commit()
+        return cursor.rowcount > 0
+
     def fix_attempt_count(self, repo_slug: str, number: int, round_: int) -> int:
         """Fix attempts already spawned for THIS round of this PR. Keyed per
         round on purpose: a new review round starts a fresh attempt budget."""

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

@@ -0,0 +1 @@
+0.8.23

{alissa_tools_github_devloop-0.8.22 → alissa_tools_github_devloop-0.8.23/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.8.22
+Version: 0.8.23
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.8.22