ctrlrelay 0.20.2__tar.gz → 0.21.0__tar.gz

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

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-11-05
+
+### Added
+
+- A run going in circles is stopped early with a clear reason, instead of
+  running until the session timeout (#224). The agent is stopped when its
+  live transcript shows the same command 5 times in a row with the same
+  result each time (polling a job whose output moves on is not a loop,
+  though 5 identical polls in a row still are), or
+  the same error from the same command 5 times in a row. Between CI fix
+  rounds each failed job's log is sorted on its own, as flaky infrastructure (the failed jobs are re-run once, without
+  the agent), out of budget (not retried), or a code failure (sent to the
+  agent, as before); the same tests failing in 3 CI rounds in a row stops the
+  run. A stopped run is recorded as failed with `sessions.stuck_reason`, the
+  issue comment and chat say it was stuck and why, and the status page counts
+  these runs. See "Stuck runs" in the operations guide.
+
+- A dev run's question is now asked on its GitHub issue as well as in chat,
+  and the first answer from either one wins. An answer on the issue is a
+  comment that starts with `/answer`, since the relay and every working
+  session comment as the operator's account; it counts only from an account
+  with write access to the repository, and only if it is newer than the
+  question and carries no relay marker; other comments
+  are logged and ignored. The chat is told when the issue answered it, and a
+  chat answer is copied to the issue. A reply that loses is told it was not
+  applied, and never resumes the session a second time. On a public
+  repository the issue gets a short notice instead of the question unless
+  `repos[].question_on_issue` says `full`. An expired question is retired
+  in both channels and the issue says so. While the question waits, the
+  issue's claim is marked held, so another machine does not take the issue
+  if this one stops; it goes back to working when the run resumes.
+
+### Fixed
+
+- A push GitHub refuses because the branch changes a file under
+  `.github/workflows/` and the relay's token has no `workflow` scope is no
+  longer retried. It cost one full agent run per poll, up to three, for a
+  push that could never pass. Chat now says the branch changes a workflow
+  file, names it, and says why no retry can pass. For any other rejected
+  push, the chat line shows the remote's reason rather than the first 200
+  characters of the error, which ended before the reason (#325).
+
+- The status page bound to a LAN address now also answers on
+  `127.0.0.1`, and it no longer keeps running, silently, on an address the
+  machine has lost. It checks every 30 seconds; when `web.host` is gone it
+  logs `web.address_gone`, says so in `web.error.log` and exits 1 so the
+  service manager restarts it (#322).
+
 ## [0.20.2] - 2026-11-04
 
 ### Fixed
@@ -2359,7 +2407,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.20.2...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.21.0...HEAD
+[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
 [0.20.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.19.1...v0.20.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.20.2
+Version: 0.21.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.20.2 → ctrlrelay-0.21.0}/config/orchestrator.yaml.example

@@ -271,3 +271,7 @@ repos: []
   #   # Fix rounds for a PR whose CI is red or whose branch conflicts,
   #   # before the run fails. Defaults to 3; 0 means none.
   #   max_fix_attempts: 3
+  #   # A dev run's question is asked on its issue as well as in chat.
+  #   # auto: full text on a private repo, a short notice on a public one.
+  #   # full / notice force one or the other.
+  #   question_on_issue: auto

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

@@ -207,7 +207,7 @@ agent:
 |---|---|---|---|
 | `type` | string | `"claude"` | Default backend for every repo: `"claude"` or `"opencode"`. See [agent backends](#agent-backends). |
 | `binary` | string | `"claude"` | Path to the `claude` executable. The bare name `"claude"` is auto-resolved at startup using `shutil.which("claude")`, then `~/.local/bin/claude`, `/usr/local/bin/claude`, `/opt/homebrew/bin/claude`. Set an absolute path to skip lookup (useful under launchd/systemd where PATH is minimal). |
-| `default_timeout_seconds` | int | `1800` | Per-session timeout passed to `asyncio.wait_for`. Sessions that exceed this are killed and reported as failed. |
+| `default_timeout_seconds` | int | `1800` | Per-session timeout passed to `asyncio.wait_for`. Sessions that exceed this are killed and reported as failed. A session going in circles is stopped before this; see [stuck runs](operations.md#stuck-runs). |
 | `output_format` | string | `"json"` | Not used. The relay always runs `claude -p --output-format stream-json --verbose`, because only that output carries the subscription usage it reads (see [usage](#usage)). Kept so existing configs still load. |
 
 ctrlrelay always invokes claude with `--dangerously-skip-permissions` so the
@@ -534,7 +534,7 @@ web:
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `host` | string | `"127.0.0.1"` | Address to listen on, exactly. Loopback by default so a fresh install is never reachable from other machines. Set it to this machine's LAN address to open the page from the home network. `0.0.0.0` listens on every interface and is warned about at startup. |
+| `host` | string | `"127.0.0.1"` | Address to listen on, exactly. Loopback by default so a fresh install is never reachable from other machines. Set it to this machine's LAN address to open the page from the home network. `0.0.0.0` listens on every interface and is warned about at startup. A LAN address also gets a second listener on `127.0.0.1`, and the server exits (for the service manager to restart it) if that address stops being this machine's. |
 | `port` | int (1-65535) | `8787` | Port to listen on. |
 | `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. |
@@ -665,6 +665,7 @@ repos:
 | `code_review` | object | no | (defaults) | Review run over an agent branch before its PR is handed over. See [code_review](#code_review). |
 | `steps` | object | no | (all unset) | How strict each dev pipeline work step is. See [steps](#repossteps). |
 | `max_fix_attempts` | integer ≥ 0 | no | `3` | Fix rounds the dev pipeline asks for when a PR's CI is red or its branch conflicts, before the run fails. `0` means none. See [steps](#repossteps). |
+| `question_on_issue` | `auto` \| `full` \| `notice` | no | `auto` | What a dev run's question looks like on its GitHub issue. The question is asked there as well as in chat, and the first answer from either wins; on the issue only a comment that starts with `/answer`, from an account with write access, counts. `auto` posts the full question on a private repository and a short "a question is waiting for the operator in chat" notice on a public one (or one whose visibility could not be read); a chat answer is copied to the issue under the same rule. `full` and `notice` force one or the other. |
 | `deploy` | object | no | `null` | Reserved for deploy policy. Currently surfaced in `ctrlrelay config repos` but otherwise inert. |
 
 ### repos[].automation

{ctrlrelay-0.20.2 → ctrlrelay-0.21.0}/docs/operations.md

@@ -346,7 +346,8 @@ control plane. Every field is defined in `src/ctrlrelay/web/numbers.py`.
 | `success_rate` | `done / (done + failed + blocked)`, 0 to 1; `null` when none has finished. |
 | `time_to_pr_s`, `time_to_merge_s` | `{median, n}`: seconds from the run's start to its first `pr_opened` (or `merged`) event, over the `n` runs that have one. Events stamped after now are not read. `null` when events cannot be read, or when a run in the window started before the oldest event still kept: its PR event may have been deleted. The daemon deletes events older than `web.history_days` (7 by default), so with the default the 30-day times are `null`. **To get them, set `web.history_days` to 30**; they appear once the events kept reach back past every run in the window (up to 30 days after the change, since deleted events do not come back). |
 | `came_back` | Distinct issues dispatched again in the window after an earlier run on the same issue had ended `done`. The window's `came_back_issues` lists them (`repo`, `issue_number`, `url`; at most 50). An issue reopened on GitHub and not picked up again is not counted: ctrlrelay does not record reopening. |
-| `cost_per_run`, `stuck` | Always `null` for now: cost per run is not recorded yet (#223), and no run records that it was stuck (#224). The window's `unavailable` says this, and why any other field is `null`. |
+| `cost_per_run` | Always `null` for now: cost per run is not recorded yet (#223). The window's `unavailable` says this, and why any other field is `null`. |
+| `stuck` | Runs the relay stopped as stuck (#224), also counted in `failed`. `null` only on a database the daemon has not migrated yet. |
 
 `numbers` is `null`, with a line in `errors`, when the sessions cannot be read.
 
@@ -400,6 +401,23 @@ The first line in `web.log` is a `web.started` event naming the address it
 bound. If `web.host` is `0.0.0.0` it also logs a warning: that listens on
 every interface, which is rarely what you want.
 
+With `web.host` set to a LAN address the page also answers on
+`127.0.0.1:8787`, so a browser or health check on the machine itself is not
+refused, and `web.log` has a second `web.started` line for it. The LAN side
+still listens on `web.host` and nothing else. If that loopback port is taken
+by something else, `web.loopback_unavailable` is logged and the LAN page
+starts anyway.
+
+Every 30 seconds the server checks that `web.host` is still one of this
+machine's addresses. If it is not (a new DHCP lease, a router reboot,
+another network), it logs `web.address_gone` to `web.log`, prints why to
+`web.error.log` and exits 1. systemd (or launchd's `KeepAlive`) restarts it;
+on the old address that start fails with `Cannot listen on ...: Cannot
+assign requested address` in `web.error.log`, again every few seconds, until
+the address comes back or you set `web.host` to the new one. A check that
+cannot be made (a `web.host` name that does not resolve) is logged once as
+`web.address_unchecked` and the page keeps running.
+
 The page answers only to names it knows: `localhost`, `127.0.0.1`, `[::1]`,
 `web.host`, and this machine's own hostname (plus `.local`). A request whose
 `Host` header carries any other name gets `421 misdirected request`, and the
@@ -605,6 +623,43 @@ unit files above set `ExitTimeOut=180` (launchd) and
 and leaves stale `git worktree` admin state behind. If you're upgrading
 from an older plist/unit that didn't set these, add them and reload.
 
+## Stuck runs
+
+A run that goes in circles is stopped early instead of running until
+`agent.default_timeout_seconds`.
+
+- **While the agent works**, ctrlrelay reads its live transcript every 30
+  seconds. If the agent runs the same command with the same input 5 times in
+  a row and gets the same result back each time, or gets the same error
+  back from the same command 5 times in a row with no success of that
+  command in between (edits in between do not count), the agent is stopped.
+  A command polled while its output moves on is waiting, not a loop; a poll
+  that gets the identical output back 5 times in a row is still treated as
+  one. Only the `claude` backend writes a transcript ctrlrelay knows how to
+  read; other backends are not watched.
+- **Between CI fix rounds**, each failed job's log is sorted on its own into
+  one of three kinds. The round is *out of budget* if any job is,
+  *infrastructure* only if every job is, and a *code failure* otherwise; a
+  job whose log could not be fetched counts as a code failure, and a check
+  that is not an Actions job, or one past the first 3 jobs, is not sorted
+  at all:
+  - *flaky infrastructure* (the runner was lost, the network failed, a
+    registry answered 502/503, and no failing test is named): the failed
+    GitHub Actions jobs are re-run once, without asking the agent. If they
+    fail on infrastructure again, the run stops. A fix round in between
+    resets this, so a new flake later gets its own re-run.
+  - *out of budget* (the job hit its maximum execution time or a spending
+    limit): the run stops at once. A re-run would spend the same budget.
+  - *code failure* (anything else, including every log that names failing
+    tests): sent to the agent as a fix round, as before. If the same tests
+    fail in 3 CI rounds in a row (the first failure and two fixes that changed
+    nothing), the run stops instead of spending the next round.
+
+A stopped run is recorded as `failed` with a `stuck_reason` in the
+`sessions` table, its summary starts with `Stuck:`, the issue comment gives
+the reason, and chat gets `🔁 Stuck on #<n>, stopped: <reason>`. The status
+page's numbers count these runs in `stuck`.
+
 ## When to restart
 
 | You changed... | Restart... |

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

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

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

@@ -15,6 +15,11 @@ from ctrlrelay import __version__
 from ctrlrelay.core.config import ConfigError, load_config, resolve_config_path
 from ctrlrelay.core.events import EventKind, emit_event
 from ctrlrelay.core.github import GitHubCLI, GitHubError
+from ctrlrelay.core.issue_questions import (
+    note_chat_answer_on_issue,
+    note_expiry_on_issue,
+    watch_issue_answers,
+)
 from ctrlrelay.core.job_claims import JobClaimer
 from ctrlrelay.core.obs import get_logger, log_event
 from ctrlrelay.core.pr_verifier import PRVerifier
@@ -621,6 +626,12 @@ async def announce_issue_outcome(
         line = f"⏸️ Blocked on #{issue_number}: {result.question}"
         await transport.send(line)
         sent.append(line)
+    elif getattr(result, "stuck_reason", None):
+        # Its own line (#224): a stuck run cost time and quota going in
+        # circles, which is a different thing to look at from a crash.
+        line = f"🔁 Stuck on #{issue_number}, stopped: {result.stuck_reason}"
+        await transport.send(line)
+        sent.append(line)
     else:
         line = f"❌ Failed on #{issue_number}: {failure_text(result)}"
         await transport.send(line)
@@ -1192,9 +1203,17 @@ PUBLISH_ATTEMPTS = 3
 
 def publish_failure_message(
     repo: str, issue_number: int, error: str, *, attempts: int, retrying: bool,
+    rejection: str | None = None,
 ) -> str:
-    """The chat line for a run whose branch the relay could not publish."""
-    why = (error.strip().splitlines() or ["no error recorded"])[0][:200]
+    """The chat line for a run whose branch the relay could not publish.
+
+    When the remote rejected the push, its reason is the line shown: the
+    full error leads with the URL, sha and ref, and its first 200
+    characters ended before the reason did (#325)."""
+    if rejection and rejection.strip():
+        why = rejection.strip()[:300]
+    else:
+        why = (error.strip().splitlines() or ["no error recorded"])[0][:200]
     if retrying:
         return (
             f"\u23f3 #{issue_number} in {repo}: the agent finished but the "
@@ -1253,6 +1272,13 @@ async def settle_publish_failure(
             _logger, "publish.refused_not_retried", repo=repo,
             issue_number=issue_number, error=(result.error or "")[:200],
         )
+        refusal = outputs.get("publish_refusal")
+        if isinstance(refusal, str) and refusal:
+            return (
+                f"\u26d4 #{issue_number} in {repo}: the agent finished, but "
+                f"the branch cannot be published, so the relay is not "
+                f"retrying: {refusal}."
+            )
         return (
             f"\u26d4 #{issue_number} in {repo}: the relay refused to push "
             f"the branch, so it is not retrying. {result.error or ''}".strip()
@@ -1286,9 +1312,11 @@ async def settle_publish_failure(
                 error=f"{type(e).__name__}: {str(e)[:200]}",
             )
             notice_failed = True
+    rejection = outputs.get("push_rejection")
     message = publish_failure_message(
         repo, issue_number, result.error or "",
         attempts=attempts, retrying=retrying,
+        rejection=rejection if isinstance(rejection, str) else None,
     )
     if notice_failed:
         # The issue's last word is still the retraction promising a
@@ -2514,6 +2542,7 @@ def run_dev(
             code_review=repo_config.code_review,
             max_fix_attempts=repo_config.max_fix_attempts,
             steps=repo_config.steps,
+            question_on_issue=repo_config.question_on_issue,
         )
 
     try:
@@ -3268,6 +3297,7 @@ def poller_start(
                         max_fix_attempts=repo_config.max_fix_attempts,
                         steps=repo_config.steps,
                         claims=claims,
+                        question_on_issue=repo_config.question_on_issue,
                     )
 
                 # Lost the race check to another machine (#245): not a
@@ -3673,6 +3703,32 @@ def poller_start(
                     f"[dim]question_expiry: retired "
                     f"{row['session_id']} ({row['expired_reason']})[/dim]"
                 )
+                # Expired in every channel at once (#328): the row stops
+                # being routable in chat and watched on the issue; the
+                # issue is told.
+                await note_expiry_on_issue(github, row)
+
+        async def _notify_chat_once(text: str) -> None:
+            """Send one chat message on a short-lived bridge connection:
+            the note that a question was answered on GitHub (#328)."""
+            settings = _bridge_socket_settings(config)
+            if settings is None:
+                return
+            from ctrlrelay.transports import SocketTransport
+            sock, ask_timeout = settings
+            if not sock.exists():
+                return
+            note_transport = SocketTransport(
+                sock, ask_timeout_seconds=ask_timeout,
+            )
+            await note_transport.connect()
+            try:
+                await note_transport.send(text)
+            finally:
+                try:
+                    await note_transport.close()
+                except Exception:
+                    pass
 
         async def _run_pending_resume_sweeper() -> None:
             """Drain pending_resumes rows that an operator answered via
@@ -3686,6 +3742,12 @@ def poller_start(
             resumed and fans out a Telegram notification with the result
             so the operator knows whether the resume landed.
             """
+            # Questions asked on their GitHub issue as well (#328): read
+            # each one's issue for an answer, so a row answered there is
+            # resumed in this same tick.
+            await watch_issue_answers(
+                github, state_db, notify=_notify_chat_once,
+            )
             try:
                 pending = state_db.list_pending_resumes_to_execute()
             except Exception as e:
@@ -3749,6 +3811,17 @@ def poller_start(
                     pipeline_name = row["pipeline"]
                     answer = row["answer"] or ""
 
+                    # A chat answer to a question also asked on the issue
+                    # is copied there before the resume (#328), once.
+                    sweep_cfg = repo_cfg_by_name.get(repo)
+                    await note_chat_answer_on_issue(
+                        github, state_db, row,
+                        mode=(
+                            sweep_cfg.question_on_issue
+                            if sweep_cfg is not None else "auto"
+                        ),
+                    )
+
                     if sweeper_transport:
                         try:
                             await sweeper_transport.send(
@@ -3822,6 +3895,7 @@ def poller_start(
                                 max_fix_attempts=repo_cfg.max_fix_attempts,
                                 code_review=repo_cfg.code_review,
                                 steps=repo_cfg.steps,
+                                question_on_issue=repo_cfg.question_on_issue,
                             )
                         elif pipeline_name == "task":
                             result = await resume_task_from_pending(
@@ -4512,7 +4586,13 @@ def web_start(
     pid_file.write_text(str(os.getpid()))
     try:
         from ctrlrelay.core.github import GitHubCLI
-        from ctrlrelay.web.server import WaitingRefresher, make_server
+        from ctrlrelay.web.server import (
+            AddressWatch,
+            Listeners,
+            WaitingRefresher,
+            make_loopback_twin,
+            make_server,
+        )
         from ctrlrelay.web.status import make_sessions_reader
         from ctrlrelay.web.waiting import WaitingTracker
 
@@ -4533,10 +4613,19 @@ def web_start(
             ) if fleet_cfg.peers else None
             httpd = make_server(config, waiting=tracker, peers=peers)
         except OSError as e:
-            console.print(
-                f"[red]Cannot listen on {config.web.host}:{config.web.port}:[/red] {e}"
+            # stderr, so a restart loop on an address this machine no longer
+            # has (#322) lands in web.error.log, not only beside web.started.
+            Console(stderr=True).print(
+                f"[red]Cannot listen on {config.web.host}:{config.web.port}:[/red] {e}",
+                soft_wrap=True,
             )
             raise typer.Exit(1)
+        # Answers on 127.0.0.1 too when web.host is one LAN address (#322).
+        twin = make_loopback_twin(config, waiting=tracker, peers=peers)
+        listeners = Listeners(
+            httpd, twin,
+            watch=AddressWatch(config.web.host, on_gone=lambda: None),
+        )
         from ctrlrelay.core.github_budget import LOW, OUT, BudgetStore
 
         budget_store = BudgetStore.beside(config.paths.state_db)
@@ -4561,12 +4650,21 @@ def web_start(
         if peers is not None:
             peers.start()
         try:
-            httpd.serve_forever()
+            address_gone = listeners.serve_forever()
         finally:
             if peers is not None:
                 peers.stop()
             refresher.stop()
-            httpd.server_close()
+            listeners.close()
+        if address_gone:
+            # Exit non-zero so the service manager restarts it (#322).
+            Console(stderr=True).print(
+                f"[red]{config.web.host} is no longer an address of this "
+                "machine; stopped the status page.[/red] Set web.host to the "
+                "new address, or it restarts and fails until the old one is back.",
+                soft_wrap=True,
+            )
+            raise typer.Exit(1)
     finally:
         pid_file.unlink(missing_ok=True)
 

{ctrlrelay-0.20.2 → ctrlrelay-0.21.0}/src/ctrlrelay/core/claims.py

@@ -606,6 +606,21 @@ class ClaimKeeper:
         task.add_done_callback(_forget)
         return False
 
+    async def resume_working(self) -> bool:
+        """Back to ``working`` after a ``hold`` for a question that has
+        now been answered in process (#328): cancel any background hold
+        retry, write ``working`` and start refreshing again. A claim taken
+        over stays the taker's. Returns whether ``working`` was written;
+        refreshing restarts either way, and its next tick writes it."""
+        if self.taken_over_by is not None:
+            return False
+        pending = _BACKGROUND_HOLDS.pop(self.claim_id, None)
+        if pending is not None:
+            pending.cancel()
+        written = await self._write(WORKING)
+        self.start()
+        return written
+
     async def _hold_later(self) -> None:
         deadline = self._confirmed_at + self.settings.stale_after_seconds
         while True:

{ctrlrelay-0.20.2 → ctrlrelay-0.21.0}/src/ctrlrelay/core/config.py

@@ -624,6 +624,14 @@ class RepoConfig(BaseModel):
     # default is the pipeline's own (DEFAULT_MAX_FIX_ATTEMPTS in
     # pipelines/dev.py; a test keeps the two equal). 0 means no fix round.
     max_fix_attempts: int = Field(default=3, ge=0)
+    # What a dev run's question looks like on its GitHub issue (#328).
+    # The question is always asked there as well as in chat. ``auto``:
+    # the full text on a private repository and a short "a question is
+    # waiting in chat" notice on a public one (or one whose visibility
+    # could not be read); ``full`` and ``notice`` force one or the other.
+    # A question can name machines, other repositories and plans, which
+    # is why a public repository does not get it by default.
+    question_on_issue: Literal["auto", "full", "notice"] = "auto"
 
     @model_validator(mode="after")
     def _review_settings_agree(self) -> RepoConfig:

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

@@ -12,6 +12,7 @@ from __future__ import annotations
 import asyncio
 import json
 import os
+import re
 import shutil
 import tempfile
 import time
@@ -35,6 +36,7 @@ from ctrlrelay.core.agent_env import (
 from ctrlrelay.core.binaries import resolve_binary
 from ctrlrelay.core.checkpoint import CheckpointState, CheckpointStatus, read_checkpoint
 from ctrlrelay.core.obs import get_logger, hash_text, log_event
+from ctrlrelay.core.stuck import StuckPolicy, watch_transcript
 from ctrlrelay.core.usage import (
     UsageStore,
     parse_agent_session_id,
@@ -136,6 +138,9 @@ class SessionResult:
     # The relay killed the agent at its time limit (#311). Set only by the
     # relay's own timeout path, never parsed from anything the agent wrote.
     timed_out: bool = False
+    # The relay stopped the agent because its transcript showed it going in
+    # circles (#224), and why. Set only by the relay's own watch.
+    stuck_reason: str | None = None
 
     @property
     def success(self) -> bool:
@@ -188,11 +193,69 @@ class CliAgentAdapter:
     # name the backend without every subclass remembering to.
     agent_type: ClassVar[str] = "unknown"
 
+    # How the live transcript is watched for a run going in circles (#224).
+    # A plain class attribute, not a dataclass field: every adapter gets
+    # the watch by construction, and a test sets it on the instance.
+    # ``None`` turns the watch off.
+    stuck_policy: StuckPolicy | None = StuckPolicy()
+
     @property
     def agent_binary(self) -> str:
         """The executable this adapter runs. Subclasses override."""
         raise NotImplementedError
 
+    def _transcript_dirs(
+        self, working_dir: Path, env: dict[str, str]
+    ) -> list[Path]:
+        """Where this CLI writes the live transcript of a run in
+        ``working_dir``. Empty by default: a backend whose transcript is
+        not known is not watched, rather than watched somewhere wrong."""
+        return []
+
+    async def _communicate_watched(
+        self,
+        proc: Any,
+        *,
+        folders: list[Path],
+        since: float,
+        ident: dict[str, Any],
+        stuck: list[str],
+    ) -> tuple[bytes, bytes]:
+        """``proc.communicate()``, while the transcript is watched (#224).
+
+        When the watch sees a loop it records the reason in ``stuck`` and
+        kills the child, which ends ``communicate()`` the normal way. The
+        watch is cancelled however this returns, the time limit included.
+        """
+        if not folders or self.stuck_policy is None:
+            return await proc.communicate()
+        policy = self.stuck_policy
+
+        async def _watch() -> None:
+            reason = await watch_transcript(
+                folders, since=since, policy=policy, ident=ident,
+            )
+            stuck.append(reason)
+            _logger.warning(
+                "dispatcher.session.stuck",
+                extra={**ident, "reason": reason},
+            )
+            try:
+                if proc.returncode is None:
+                    proc.kill()
+            except ProcessLookupError:
+                pass
+
+        watcher = asyncio.create_task(_watch())
+        try:
+            return await proc.communicate()
+        finally:
+            watcher.cancel()
+            try:
+                await watcher
+            except BaseException:
+                pass
+
     def _parse_agent_session_id(self, stdout_text: str) -> str | None:
         """The agent's own session id, for a later resume.
 
@@ -288,6 +351,10 @@ class CliAgentAdapter:
             prompt_len=len(prompt),
         )
         started = time.monotonic()
+        # Transcript rows are stamped in wall-clock time. A second of slack
+        # for the clock the CLI reads being a hair behind this one.
+        wall_started = time.time() - 1.0
+        stuck: list[str] = []
 
         try:
             proc = await asyncio.create_subprocess_exec(
@@ -328,7 +395,14 @@ class CliAgentAdapter:
 
         try:
             stdout, stderr = await asyncio.wait_for(
-                proc.communicate(), timeout=timeout
+                self._communicate_watched(
+                    proc,
+                    folders=self._transcript_dirs(working_dir, env),
+                    since=wall_started,
+                    ident=ident,
+                    stuck=stuck,
+                ),
+                timeout=timeout,
             )
         except asyncio.TimeoutError as e:
             proc.kill()
@@ -482,6 +556,15 @@ class CliAgentAdapter:
         agent_session_id = self._parse_agent_session_id(stdout_text)
         self._record_usage(stdout_text, ident)
 
+        # A checkpoint the agent wrote wins: it finished, or asked, before
+        # the kill landed, so it was not stuck at the end.
+        stuck_reason = stuck[0] if stuck and state is None else None
+        if stuck_reason is not None:
+            # In stderr too, so a lane that reads only stderr still says why.
+            stderr_text = (
+                f"Session stopped: stuck: {stuck_reason}\n{stderr_text}"
+            )
+
         log_event(
             _logger,
             "dispatcher.session.finished",
@@ -510,6 +593,7 @@ class CliAgentAdapter:
             stdout=stdout_text,
             stderr=stderr_text,
             agent_session_id=agent_session_id,
+            stuck_reason=stuck_reason,
         )
 
 
@@ -560,6 +644,21 @@ class ClaudeDispatcher(CliAgentAdapter):
     def _parse_agent_session_id(self, stdout_text: str) -> str | None:
         return _extract_agent_session_id(stdout_text)
 
+    def _transcript_dirs(
+        self, working_dir: Path, env: dict[str, str]
+    ) -> list[Path]:
+        """``<config dir>/projects/<working dir, "/", "." and "_" as "-">``,
+        the folder :mod:`ctrlrelay.web.transcript` reads too. Both the path
+        as given and its resolved form, since which one the CLI sees
+        depends on how the worktree path was spelled."""
+        base = Path(env.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+        out: list[Path] = []
+        for spelled in (str(working_dir), str(working_dir.resolve())):
+            folder = base / "projects" / re.sub(r"[/._]", "-", spelled)
+            if folder not in out:
+                out.append(folder)
+        return out
+
     def __post_init__(self) -> None:
         # Only auto-resolve the bare default. Absolute paths, relative paths
         # (resolved vs. working_dir by the child), and custom bare names pass

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

@@ -148,6 +148,7 @@ def emit_outcome(
         kind = _OUTCOME_KINDS[f["status"]]
         exit_code = f.get("exit_code")
         question = f.get("question")
+        stuck_reason = f.get("stuck_reason")
         fields = {
             "repo": f.get("repo"),
             "issue_number": f.get("issue_number"),
@@ -167,6 +168,9 @@ def emit_outcome(
                 ),
             },
         }
+        # Only on a run the relay stopped as stuck (#224).
+        if isinstance(stuck_reason, str) and stuck_reason:
+            fields["detail"]["stuck"] = stuck_reason[:QUESTION_DETAIL_CHARS]
     except Exception as e:  # noqa: BLE001 - best-effort by design
         _log_failure("<outcome>", e)
         return