ctrlrelay 0.21.0__tar.gz → 0.22.0__tar.gz

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-11-05
+
+### Added
+
+- The code review is tied to the commit it read. Each `review_finished`
+  event records that commit (`head_sha`) and whether the findings reached
+  the PR (`posted`), so the status page feed and `/api/status` show what a
+  verdict is about. After a review the relay reads the PR's head from
+  GitHub; if somebody pushed after the review, the PR gets a comment saying
+  it needs review again, a `review_stale` event is recorded, and the new
+  head is reviewed before the run reports done. With
+  `steps.review: required`, the PR is opened as a draft (a reused PR is put
+  back to draft when the run pushes to it) and marked ready only once the
+  latest review posted on its current head. The new head is fetched from
+  the PR's own ref, since the run's branch is checked out in its worktree.
+  A repository that does not allow drafts (a private one on GitHub's free
+  plan) gets a normal PR with a comment saying it has not been reviewed
+  yet. A reused PR that cannot be put back to draft gets the same comment.
+
+### Fixed
+
+- The status page no longer says "looks stuck" while the agent is inside
+  one long command, such as a 20-minute test run. A tool call writes
+  nothing to the transcript until it returns. So before calling a card
+  stuck, the page reads `ps` for a process under that run's own agent
+  (the dispatcher records its pid in `agents/<session>.pid` beside the
+  state database) that started at or after the agent's last step. If it
+  finds one, it shows "running `<program>`" instead, with the program's
+  name only. An idle agent is still stuck. Where the process
+  table cannot be read, the card stays stuck and says why (#309).
+
+- A run that correctly changes nothing is no longer recorded as a failed
+  publish. The agent can now finish with `"no_changes": True` and a one-line
+  `"no_changes_reason"`. When the relay's own check also finds no new
+  commits, it opens no pull request, ends the session `done`, says so on
+  the issue, and tells chat "finished, no change needed". A DONE with no
+  commits and no declaration still fails as a forgotten commit. A
+  declaration on a branch that has commits is ignored, and the commits are
+  published. So is a declaration from a run that has already pushed or has
+  an open PR, such as a fix round or a resumed session, since ending it
+  done would orphan that PR (#336).
+
 ## [0.21.0] - 2026-11-05
 
 ### Added
@@ -2407,7 +2449,8 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.21.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.20.2...v0.21.0
 [0.20.2]: https://github.com/AInvirion/ctrlrelay/compare/v0.20.1...v0.20.2
 [0.20.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.20.0...v0.20.1

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.21.0
+Version: 0.22.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/docs/configuration.md

@@ -539,7 +539,7 @@ web:
 | `history_days` | int (>= 1) | `7` | Days of feed the page shows, and what `/api/events` returns without `?since=`. Events older than this are deleted, so the run numbers' time to PR and time to merge are shown only for a window whose runs all started after the oldest event kept. Set it to `30` to get the 30-day ones; they appear once 30 days of events have been kept. |
 | `refresh_seconds` | int (>= 1) | `5` | How often the page asks `/api/status` again. |
 | `github_check_seconds` | int (>= 15) | `300` | How often the waiting line asks GitHub (one search, plus one query per `include_labels` label). Every check spends from the GitHub account's budget, which machines on the account share. |
-| `stale_after_minutes` | int (>= 1) | `15` | A running card is marked "looks stuck" after this long with no new agent step, unless ctrlrelay itself has a CI wait or review open for it. |
+| `stale_after_minutes` | int (>= 1) | `15` | A running card is marked "looks stuck" after this long with no new agent step, unless ctrlrelay itself has a CI wait or review open for it, or the agent is still inside a command it started at its last step (read from `ps`; the card then says "running `<program>`"). Where the process table cannot be read, the card stays "looks stuck" and says why. |
 | `allowed_hosts` | list of strings | `[]` | Extra names the page may be opened by. A request is served only when its `Host` header is `localhost`, `127.0.0.1`, `[::1]`, `host` (unless it is `0.0.0.0`/`::`), this machine's hostname, the hostname plus `.local`, or one of these, alone or followed by `:port`. Anything else, or no `Host`, gets `421`. Matching ignores case and a trailing dot. This stops a web page on another site from pointing its own name at this server (DNS rebinding) and reading it. |
 
 The page has no login and shows repository names, issue titles and the
@@ -946,6 +946,28 @@ an exception inside the review are all failures. It is about the review
 having happened, not about what it found. **`review: off`** is the same as
 `code_review.method: off`, and loads as that.
 
+A review is about one commit. With `review: required` the PR is opened as a
+**draft**, and a PR the run reuses is put back to draft when the run pushes to
+it, because its new commits have not been reviewed. The relay marks it ready
+for review only when the latest review posted on the PR's current head. If
+the PR stays a draft, nothing was handed over. Draft pull requests need a
+public repository or a paid GitHub plan; where GitHub refuses a draft, the
+publish step fails and says why.
+
+With the review `on`, unset or `required`, the relay reads the PR's head from
+GitHub after each review. If somebody pushed after the review, the verdict is
+stale: the PR gets a comment saying it needs review again, a `review_stale`
+event is recorded, and the new head is reviewed before the run reports done
+(at most three reviews in all; a head still moving after that is not a
+pass). With `required`, a head GitHub will not report is not a pass either.
+
+Each `review_finished` event names the commit it reviewed, so the status page
+feed and `/api/status` show what the verdict is about:
+`{"pr_number", "ok", "head_sha", "status", "posted"}`. `ok` means the reviewer
+read the diff; `posted` means its findings reached the PR, which is what
+`required` checks. `review_stale` carries `{"pr_number", "head_sha",
+"current_sha"}`.
+
 Two settings for one reviewer must agree, or the config refuses to load:
 
 - `code_review.method: off` with `steps.review: on` or `required`;

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.21.0"
+version = "0.22.0"
 description = "Local-first orchestrator for headless coding agents across multiple GitHub repos"
 readme = "README.md"
 requires-python = ">=3.12"

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/src/ctrlrelay/cli.py

@@ -566,6 +566,17 @@ async def announce_dev_success(
     the caller's tests assert on.
     """
     sent: list[str] = []
+    outputs = getattr(result, "outputs", None) or {}
+    if outputs.get("no_change") is True:
+        # No pull request by design (#336): nothing to warn about, and
+        # "PR ready" with an empty link would be false.
+        line = (
+            f"✅ {repo}: finished, no change needed: "
+            f"{outputs.get('no_change_reason') or 'no reason given'}"
+        )
+        await transport.send(line)
+        sent.append(line)
+        return sent
     warning = unreviewed_pr_warning(repo, result)
     if warning is not None:
         await transport.send(warning)

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/src/ctrlrelay/core/dispatcher.py

@@ -265,6 +265,34 @@ class CliAgentAdapter:
         """
         return None
 
+    def _record_agent_pid(self, session_id: str, pid: int | None) -> None:
+        """Note which process is this session's agent (#309), in
+        ``agents/<session_id>.pid`` beside the state database, so the status
+        page can tell an agent inside a long command from one that stopped.
+        Several runs share the poller's pid, so only the agent's own pid
+        says which command belongs to which run. Best-effort; files older
+        than a week are pruned here."""
+        store = getattr(self, "usage_store", None)
+        if store is None or not pid:
+            return
+        folder = Path(store.path).parent / "agents"
+        try:
+            folder.mkdir(parents=True, exist_ok=True)
+            cutoff = time.time() - 7 * 86400
+            for old in folder.glob("*.pid"):
+                try:
+                    if old.stat().st_mtime < cutoff:
+                        old.unlink()
+                except OSError:
+                    pass
+            safe = re.sub(r"[^A-Za-z0-9._-]", "_", session_id)
+            (folder / f"{safe}.pid").write_text(f"{int(pid)}\n")
+        except Exception as e:  # noqa: BLE001 - must never fail a run
+            log_event(
+                _logger, "dispatcher.agent_pid.write_failed",
+                session_id=session_id, error=str(e)[:200],
+            )
+
     def _record_usage(self, stdout_text: str, ident: dict) -> None:
         """Keep this run's usage reading, if the backend reports one.
 
@@ -393,6 +421,8 @@ class CliAgentAdapter:
             )
             raise
 
+        self._record_agent_pid(session_id, getattr(proc, "pid", None))
+
         try:
             stdout, stderr = await asyncio.wait_for(
                 self._communicate_watched(

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/src/ctrlrelay/core/events.py

@@ -42,6 +42,9 @@ class EventKind(StrEnum):
     CI_FINISHED = "ci_finished"
     REVIEW_STARTED = "review_started"
     REVIEW_FINISHED = "review_finished"
+    # A review's commit is no longer the PR's head: somebody pushed after
+    # it, and the PR needs review again (#222).
+    REVIEW_STALE = "review_stale"
     MESSAGE_SENT = "message_sent"
     QUESTION_POSTED = "question_posted"
     QUESTION_HELD = "question_held"

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/src/ctrlrelay/core/github.py

@@ -581,9 +581,14 @@ class GitHubCLI:
         body: str,
         head: str,
         base: str,
+        draft: bool = False,
     ) -> dict[str, Any]:
         """Create a pull request; return ``{"number", "url"}``.
 
+        ``draft`` opens it as a draft (#222): a repository whose review is
+        required gets a PR that reads "not ready" until a review passed
+        on its current head.
+
         ``gh pr create`` has no ``--json`` flag (it prints the new
         pull request's URL), so the number is read from that URL. The
         old version passed ``--json`` and could never have succeeded;
@@ -599,6 +604,7 @@ class GitHubCLI:
             "--body", body,
             "--head", head,
             "--base", base,
+            *(("--draft",) if draft else ()),
         )
         url = ""
         for line in output.splitlines():
@@ -612,6 +618,25 @@ class GitHubCLI:
             )
         return {"number": int(match.group(1)), "url": url}
 
+    async def get_pr_head(self, repo: str, pr_number: int) -> dict[str, Any]:
+        """``{"sha", "draft"}`` for a pull request: the commit GitHub has
+        as its head, and whether it is a draft (#222)."""
+        output = await self._run_gh(
+            "pr", "view", str(pr_number),
+            "--repo", repo,
+            "--json", "headRefOid,isDraft",
+        )
+        data = json.loads(output)
+        return {"sha": data.get("headRefOid"), "draft": data.get("isDraft")}
+
+    async def set_pr_draft(self, repo: str, pr_number: int, draft: bool) -> None:
+        """Mark a pull request as a draft, or as ready for review (#222)."""
+        await self._run_gh(
+            "pr", "ready", str(pr_number),
+            "--repo", repo,
+            *(("--undo",) if draft else ()),
+        )
+
     async def get_default_branch(self, repo: str) -> str:
         """The repository's default branch, as GitHub reports it.
 

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/src/ctrlrelay/core/publish.py

@@ -45,6 +45,14 @@ class PushRefusedError(Exception):
     """A push the relay will not make. The message names why."""
 
 
+class NothingToPushError(PushRefusedError):
+    """The run branch has no commit the default branch lacks (#336).
+
+    A refusal like any other, unless the agent declared that no change
+    was the right outcome: then the run finished, with nothing to push.
+    """
+
+
 def check_push_target(
     target: str,
     *,

{ctrlrelay-0.21.0 → ctrlrelay-0.22.0}/src/ctrlrelay/core/worktree.py

@@ -1626,7 +1626,9 @@ class WorktreeManager:
                     session_id=session_id,
                     branch=branch,
                 )
-                raise PushRefusedError(
+                from ctrlrelay.core.publish import NothingToPushError
+
+                raise NothingToPushError(
                     f"push refused: {branch!r} has no commits that "
                     f"{default_branch!r} does not already have; the agent "
                     f"must commit its work on {branch!r}"
@@ -1847,6 +1849,37 @@ class WorktreeManager:
 
         return bare_path
 
+    async def fetch_pr_head(self, repo: str, pr_number: int) -> str:
+        """Fetch a pull request's current head into the bare clone and
+        return its commit id (#222).
+
+        Into ``refs/ctrlrelay/review/pr-<n>``, never into the branch: a
+        run's branch is checked out in its worktree for the whole session,
+        and :meth:`ensure_bare_repo` leaves such branches out of its fetch
+        (#253), so a commit pushed by someone else never reached the clone
+        and the review copy of it failed.
+        """
+        if not isinstance(pr_number, int) or pr_number <= 0:
+            raise WorktreeError(f"not a pull request number: {pr_number!r}")
+        bare_path = self._get_bare_repo_path(repo)
+        ref = f"refs/ctrlrelay/review/pr-{pr_number}"
+        await self._run_git(
+            "fetch", "--no-tags", "origin",
+            f"+refs/pull/{pr_number}/head:{ref}",
+            cwd=bare_path,
+            timeout=_GIT_TRANSFER_TIMEOUT_SECONDS,
+        )
+        sha = (
+            await self._run_git(
+                "rev-parse", "--verify", "--quiet", "--end-of-options",
+                f"{ref}^{{commit}}",
+                cwd=bare_path,
+            )
+        ).strip()
+        if not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", sha):
+            raise WorktreeError(f"{ref} is not a commit: {sha[:80]!r}")
+        return sha
+
     async def _follow_origin_default(
         self, repo: str, bare_path: Path, default_branch: str,
     ) -> None: