Keep Gitea threads watched across restarts and interruptions

- Record a comment cursor per thread (board.last_comment, the field that
  already existed unused; pr.last_comment), advanced durably when a
  comment is taken up. CommentPoller.resume_after() skips comments at or
  below it, so re-attaching needs no request and cannot replay.
- Boot re-attaches the plan watch at an open gate and the review watch in
  PR_OPEN from their cursors, catching up on comments posted while the
  agent was down (#59). Data saved without a cursor skips what is there,
  so an old approval cannot approve the current revision.
- A restart in PR_OPEN resumes with a notice instead of the restart
  question (#58). A stored restart question for PR_OPEN returns to it on
  either reply instead of re-planning the milestone.
- A stopped or failed review response gets its own pending kind; the
  reply returns to PR_OPEN and resumes the watch from the cursor, so
  comments that arrived meanwhile are delivered. It used to return to
  milestone sign-off, where starting the milestone would open a second PR.
- Comments ignored because of the state leave the cursor alone, so they
  are delivered once the agent is back where they apply.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

nisse-dev/src/nisse_dev/control.py

@@ -277,12 +277,33 @@ class Orchestrator:
                 "restarted while waiting on you: "
                 + pending.get("prompt", "my last question still stands")
             )
+        elif state.state == PR_OPEN:
+            # Waiting on review is a committed state like a gate (A3 step
+            # 8): resume, and watch the PR again from its cursor.
+            pr = self._data.get("pr") or {}
+            self._watch_pr(pr)
+            self._transport.send_message(
+                f"restarted with PR #{pr.get('number')} open; still watching it "
+                "for review comments"
+            )
         elif state.state == IDLE or (
             state.state in (AWAIT_ARCH_SIGNOFF, AWAIT_MILESTONE_SIGNOFF) and gate
         ):
             # A gate is a safe place to have been interrupted: nothing was in
-            # flight, the plan and revision are durable. Announce and resume.
+            # flight, the plan and revision are durable. Announce and resume,
+            # watching the plan issue again from its cursor.
             if gate:
+                board_state = self._data.get("board")
+                if board_state and board_state.get("comment_id"):
+                    self._watch(
+                        "plan",
+                        board_state["issue"],
+                        self.handle_plan_comment,
+                        # No cursor means data from before cursors were
+                        # kept: skip what is there, as a fresh watch does,
+                        # so an old approval cannot approve this revision.
+                        after=board_state.get("last_comment") or None,
+                    )
                 self._transport.send_message(
                     f"restarted while awaiting sign-off on {gate['name']} "
                     f"rev-{gate['rev']}; the gate is still open"
@@ -671,8 +692,12 @@ class Orchestrator:
             return
         board_state["comment_id"] = post.comment_id
         # Approvals can arrive on the issue as well as over transport (A4),
-        # so watch it for as long as the gate stands.
-        self._watch("plan", board_state["issue"], self.handle_plan_comment)
+        # so watch it for as long as the gate stands. A new revision skips
+        # what came before it: an early "approve" must not approve it.
+        board_state["last_comment"] = self._watch(
+            "plan", board_state["issue"], self.handle_plan_comment
+        )
+        self._save(f"{gate_name} rev-{rev} posted to Gitea")
 
     def handle_plan_comment(self, comment: Any) -> None:
         """A comment on the project issue may satisfy an open plan gate (A4).
@@ -689,14 +714,17 @@ class Orchestrator:
         )
 
     def _handle_plan_comment_now(self, comment: Any) -> None:
+        board_state = self._data.get("board")
         if comment.author not in self._gitea_operators:
+            self._take_comment(board_state, comment)  # never actionable
             return
         state = self._store.get_state()
         if state is None or state.state not in (
             AWAIT_ARCH_SIGNOFF,
             AWAIT_MILESTONE_SIGNOFF,
         ):
-            return
+            return  # not taken: a watch attached later still sees it
+        self._take_comment(board_state, comment)
         self._store.append_event(
             UserMessage(text=comment.body, source=f"gitea:comment:{comment.id}")
         )
@@ -720,6 +748,7 @@ class Orchestrator:
 
     def _handle_review_comment_now(self, comment: Any) -> None:
         if comment.author not in self._gitea_operators:
+            self._take_comment(self._data.get("pr"), comment)  # never actionable
             self._store.oplog.emit(
                 "gitea.comment_ignored",
                 cause=f"author {comment.author!r} not an operator",
@@ -728,12 +757,15 @@ class Orchestrator:
             return
         state = self._store.get_state()
         if state is None or state.state != PR_OPEN:
+            # Not taken: back in PR_OPEN, the watch resumes from the cursor
+            # and delivers it again.
             self._store.oplog.emit(
                 "gitea.comment_ignored",
                 cause=f"not in PR_OPEN (state={state.state if state else None})",
                 comment_id=comment.id,
             )
             return
+        self._take_comment(self._data.get("pr"), comment)
         if self._executor is None or self._publisher is None:
             return
 
@@ -750,11 +782,8 @@ class Orchestrator:
             self._halt_for_stop(
                 what=f"the response to review comment {comment.id}",
                 note=outcome.note,
-                next_step=(
-                    f"The milestone {milestone} plan is still approved; say "
-                    f"'start milestone {milestone}' to run it again."
-                ),
-                pending={"kind": "milestone_stopped", "milestone": milestone},
+                next_step="Your reply returns to the open PR.",
+                pending={"kind": "review_stopped", "milestone": milestone},
             )
             return
         if outcome.status != "completed":
@@ -762,9 +791,10 @@ class Orchestrator:
                 cause=f"review response {outcome.status}",
                 prompt=(
                     f"could not address the review comment ({outcome.status}): "
-                    f"{outcome.note}"
+                    f"{outcome.note}. Reply to return to the open PR; comment "
+                    "again there to retry."
                 ),
-                pending={"kind": "milestone_stopped", "milestone": milestone},
+                pending={"kind": "review_stopped", "milestone": milestone},
             )
             return
         try:
@@ -824,19 +854,41 @@ class Orchestrator:
                 pending={"kind": "milestone_stopped", "milestone": milestone},
             )
             return
+        self._unwatch("plan")  # the gate is behind us; the PR is the thread now
         self._data["pr"] = {
             "number": result.pull_request.number,
             "url": result.pull_request.url,
             "milestone": milestone,
+            "last_comment": self._watch(
+                "review", result.pull_request.number, self.handle_review_comment
+            ),
         }
-        self._unwatch("plan")  # the gate is behind us; the PR is the thread now
-        self._watch("review", result.pull_request.number, self.handle_review_comment)
         self._transition(PR_OPEN, cause=f"milestone {milestone} published")
         self._transport.send_message(
             f"{result.note} — review it, then say 'next milestone' or "
             "'project complete'"
         )
 
+    def _return_to_pr_open(self, cause: str) -> None:
+        self._transition(PR_OPEN, cause=cause)
+        pr = self._data.get("pr") or {}
+        self._watch_pr(pr)
+        self._transport.send_message(
+            f"PR #{pr.get('number')} is open and watched for review comments; "
+            "say 'next milestone' or 'project complete'"
+        )
+
+    def _watch_pr(self, pr: dict[str, Any]) -> None:
+        """Watch the open PR from its recorded cursor, catching up on what
+        arrived while it was not watched."""
+        if pr.get("number"):
+            self._watch(
+                "review",
+                int(pr["number"]),
+                self.handle_review_comment,
+                after=pr.get("last_comment"),
+            )
+
     def _handle_pr_open(self, text: str) -> None:
         if text == "next milestone":
             self._unwatch("review")
@@ -861,17 +913,42 @@ class Orchestrator:
                 "'project complete'"
             )
 
-    def _watch(self, kind: str, index: int, handler: Any) -> None:
+    def _watch(
+        self, kind: str, index: int, handler: Any, *, after: int | None = None
+    ) -> int:
         """Start watching one Gitea thread, replacing any previous watch of
-        the same kind. Priming first, so attaching does not replay comments
-        already addressed."""
+        the same kind, and return the comment cursor to record.
+
+        A fresh watch (after=None) skips everything already there, so it
+        does not replay comments already addressed. Watching again from a
+        recorded cursor delivers what came in while nothing was watching."""
         if self._poller_factory is None:
-            return
+            return after or 0
         self._unwatch(kind)
         poller = self._poller_factory(handler)
-        poller.prime(index)
+        if after is None:
+            cursor = poller.prime(index)
+        else:
+            poller.resume_after(after)
+            cursor = after
         poller.start(index)
         self._pollers[kind] = poller
+        return cursor
+
+    def _save(self, cause: str) -> None:
+        """Make changes to the task's data durable without a state change."""
+        state = self._store.get_state()
+        self._transition(state.state if state else IDLE, cause=cause)
+
+    def _take_comment(self, record: dict[str, Any] | None, comment: Any) -> None:
+        """Advance a thread's cursor past a comment being acted on, durably,
+        before acting: a comment is handled at most once, even across a
+        crash mid-way."""
+        if record is not None:
+            record["last_comment"] = max(
+                int(record.get("last_comment") or 0), comment.id
+            )
+            self._save(f"gitea comment {comment.id} taken")
 
     def _unwatch(self, kind: str) -> None:
         poller = self._pollers.pop(kind, None)
@@ -910,6 +987,8 @@ class Orchestrator:
                 back = PLANNING_ARCH if gate_name == "arch" else MILESTONE_PLANNING
                 self._transition(back, cause="operator answered; resuming planning")
                 self._run_planning_turn(gate_name, answer=text)
+            case "review_stopped":
+                self._return_to_pr_open("operator answered; back to the open PR")
             case "boot":
                 self._resume_after_restart(pending, text)
             case "milestone_stopped":
@@ -939,6 +1018,12 @@ class Orchestrator:
         milestone = int(self._data.get("milestone", 1))
         gate = self._data.get("gate") or {}
         interrupted = pending.get("interrupted")
+        if interrupted == PR_OPEN:
+            # Recorded before a restart in PR_OPEN resumed quietly. Its PR is
+            # still open, so either reply goes back to it; re-planning the
+            # milestone would open a second PR.
+            self._return_to_pr_open(f"operator: {choice} after restart")
+            return
         if choice == "continue" and interrupted == EXECUTING and gate.get("approved"):
             self._transition(
                 AWAIT_MILESTONE_SIGNOFF, cause="operator: continue after restart"

nisse-dev/src/nisse_dev/poller.py

@@ -42,29 +42,43 @@ class CommentPoller:
         self._initial_backoff_s = initial_backoff_s
         self._max_backoff_s = max_backoff_s
         self._seen: set[int] = set()
+        # Comments at or below this ID were handled before this poller
+        # existed (a restart, or a watch attached again); Gitea's comment IDs
+        # only grow, so one number says it all.
+        self._after = 0
         self._stop = threading.Event()
         self._thread: threading.Thread | None = None
 
-    def prime(self, index: int) -> None:
-        """Mark existing comments as seen without delivering them.
+    def prime(self, index: int) -> int:
+        """Mark existing comments as seen without delivering them, and
+        return the highest ID marked (0 if none).
 
         A poller that starts by replaying the whole thread would re-act to
         feedback already addressed — including its own earlier replies.
         """
+        highest = 0
         try:
             for comment in self._client.list_comments(self._repo, index):
                 self._seen.add(comment.id)
+                highest = max(highest, comment.id)
         except GiteaError:
             # Nothing seen means the first successful poll delivers the
             # backlog once. Better than refusing to start.
             pass
+        return max(highest, self._after)
+
+    def resume_after(self, comment_id: int) -> None:
+        """Deliver only comments newer than comment_id: the ones posted
+        while nothing was watching are caught up, the handled ones are not
+        replayed. Needs no request, so an outage cannot cause a replay."""
+        self._after = comment_id
 
     def poll_once(self, index: int) -> list[Comment]:
         """One pass; returns what was newly delivered. Separated from the
         loop so behaviour is testable without threads or sleeps."""
         delivered: list[Comment] = []
         for comment in self._client.list_comments(self._repo, index):
-            if comment.id in self._seen:
+            if comment.id in self._seen or comment.id <= self._after:
                 continue
             self._seen.add(comment.id)
             if comment.author in self._ignore: