ctrlrelay 0.19.1__tar.gz → 0.20.1__tar.gz

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/CHANGELOG.md

@@ -7,6 +7,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.1] - 2026-11-04
+
+### Fixed
+
+- The status page's server panel reads memory and uptime on macOS too. It
+  read those two from `/proc`, which macOS does not have, so on a Mac those
+  rows were empty and the page printed the read error. On macOS it now
+  uses `sysctl` and `vm_stat`. macOS has no `MemAvailable`, so "available"
+  there is free plus inactive pages: an estimate, and not the same
+  measurement as Linux's (#321).
+
+- A run waiting for the operator's answer is no longer lost when the poller
+  stops during the wait. The question is now saved, and the session marked
+  `blocked`, before the wait starts rather than after it ends (if that
+  write fails it is logged and the wait goes ahead as before). If the
+  poller stops, a later answer in chat reaches the saved question and
+  resumes the same agent session; when the poller starts again it drops the
+  repo lock such a run held, if the process that ran it is gone, so the
+  repo is not wedged until then. An answer that arrives during the wait
+  still resumes the run at once and closes the saved question; if a reply
+  already answered the saved question first, that first answer stands and
+  the run is resumed once, with it. A planning session's question resumes
+  the plan, not the code. The claim on the issue is not marked held while the
+  question waits, so after a stop it goes stale as before (#324).
+
+- An issue is read again from GitHub just before its run starts. A poll
+  returns a batch that is handled one issue at a time, so with one slot the
+  last issue could start an hour after the poll saw it, after its trigger
+  label was removed or the issue was closed. Now an issue that is closed,
+  has gained an `exclude_labels` label, or no longer meets any trigger is
+  skipped and left for the next poll to judge; so is one that cannot be read.
+  The run is routed on the labels read then, not the poll's. Who added a
+  trigger is not asked again: a trigger the operator removed and someone
+  else put back in that window still counts (#326).
+
+## [0.20.0] - 2026-11-04
+
+### Added
+
+- `repos[].steps.plan` (`off`, `on`, `required`; unset is `off`) runs a
+  planning session before the dev pipeline's code session. It changes no
+  files and writes a plan with numbered acceptance criteria, saved under
+  `<paths.contexts>/<owner>-<repo>/plans/issue-<n>.md` (outside the worktree),
+  posted on the issue as the criteria list, and added to the code session's
+  prompt. A vague issue gets one question instead of a pull request. A plan
+  without criteria is a failed plan: `on` reports it and codes without one,
+  `required` fails the run (#220).
+- On the status page, a peer machine's name links to that machine's own
+  page: in the machine strip, in "Who has what" and on a "Needs you" card.
+  The address is the `fleet.peers` entry from this machine's config, cut to
+  `<scheme>://<host>[:port]/`; nothing a peer answers changes it, and an
+  entry with userinfo or a non-http scheme gives plain text (#319).
+
+### Fixed
+
+- A run whose relay process died mid-run (the machine ran out of memory, or
+  the service was stopped) no longer stays `running` for ever. Sessions now
+  record the process running them (`owner_pid`, `owner_run`) and their claim
+  id. When the poller starts, it finds `running` sessions whose process is
+  gone, and in whose worktree no process is still working, and marks them
+  failed, dropping any repo lock they held. A dev or task issue goes back to
+  the next poll unless an open pull request was found for its branch. Where
+  the run had claimed the issue, the relay posts a comment that names the
+  worktree and releases the claim. The relay deletes nothing in the
+  worktree. It detaches the worktree's HEAD, when that can be done safely,
+  so the next run can check the issue's branch out. Rows written by an older
+  version name no process and are left alone (#312).
+- A dev run whose agent session hits its time limit no longer throws away
+  the agent's work. Before the worktree is removed, the files on disk are
+  committed on top of the commit it sits on, and that commit, or the
+  unpushed commits alone, are pushed to a new `wip/issue-<n>-<run id>`
+  branch. The run's own branch is not pushed, no pull request is opened, and
+  the local run branch is kept, since it can hold commits the worktree's
+  HEAD does not reach. The failure comment on the issue names the wip branch
+  and, when it is known, how long the run took. If the work cannot be saved,
+  the worktree is kept on disk and the comment names it. A run with nothing
+  new loses only its worktree. Files the worktree's `.gitignore` ignores are
+  not saved; files that cannot be read are not saved either, and then the
+  worktree is kept and the comment says so. The files are read by a git with
+  a private git dir, index, config and attributes override, so filters,
+  hooks and attributes named by the agent do not take effect (#311).
+
 ## [0.19.1] - 2026-11-03
 
 ### Fixed
@@ -2266,7 +2348,9 @@ 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.19.1...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.20.1...HEAD
+[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
 [0.19.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.17.1...v0.18.0

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.19.1
+Version: 0.20.1
 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.19.1 → ctrlrelay-0.20.1}/docs/configuration.md

@@ -865,7 +865,8 @@ repos:
 
 ### repos[].steps
 
-The dev pipeline does its work in a fixed order: **code** (the agent run and
+The dev pipeline does its work in a fixed order: **plan** (an optional
+planning session, off unless asked for), **code** (the agent run and
 any questions it asks), **publish** (the relay pushes the branch and opens the
 pull request), **verify** (wait for CI and mergeability, asking the agent to
 fix what fails, up to `max_fix_attempts` rounds) and **review** (the
@@ -893,6 +894,7 @@ repos:
 
 | Step | Accepts | Unset means |
 |---|---|---|
+| `plan` | `off`, `on`, `required` | `off`: no planning session. |
 | `code` | `required` | A failed or crashed agent run stops the run. Same as `required`. |
 | `publish` | `required` | A refused or failed push stops the run (the branch is kept). Same as `required`. |
 | `verify` | `off`, `required` | CI still red after the fix rounds stops the run. CI that is still pending when the wait times out hands the PR over. |
@@ -905,6 +907,28 @@ PR as ready while its CI is red, with no line in the announcement saying so.
 Unknown step names (a typo such as `verfy`) are refused as well. A bare `on`
 or `off` works unquoted.
 
+**`plan: on`** or **`plan: required`** runs one planning session in the
+run's worktree before the code session. It is told to read the issue and the
+repo and change no files, and returns a plan with four headings: `## Change`,
+`## Files`, `## Risks` and `## Acceptance criteria`, a numbered list of items
+that can each be checked by a command or by reading the diff. The relay then:
+
+- saves the plan to `<paths.contexts>/<owner>-<repo>/plans/issue-<n>.md`,
+  outside the worktree, so it is never committed;
+- posts the criteria list as one comment on the issue;
+- adds the plan to the code session's prompt under `## Plan`, telling the
+  agent the criteria are what "done" means.
+
+If the issue is too vague to plan, the planning session asks one question,
+through the same chat loop the code session uses. No code session runs and no
+PR is opened until it is answered; an answer that arrives after the run
+stopped resumes the planning session, then codes with the plan.
+
+A plan with no numbered acceptance criteria is a failed plan, as is a
+planning session that fails or crashes. With `on` the failure is posted on the
+issue and the code session runs without a plan; with `required` the run fails
+and no code session runs.
+
 **`verify: required`** also fails the run when the CI wait times out, before
 or after a fix round. (Checks that cannot be read at all fail the run in every
 mode that waits on CI, not only under `required`.)

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/pyproject.toml

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

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/src/ctrlrelay/cli.py

@@ -3801,7 +3801,8 @@ def poller_start(
                                 )
                                 try:
                                     state_db.mark_pending_resume_resumed(
-                                        session_id
+                                        session_id, answered_at=row["answered_at"],
+                                        answer=row["answer"],
                                     )
                                 except Exception:
                                     pass
@@ -3844,7 +3845,8 @@ def poller_start(
                             )
                             try:
                                 state_db.mark_pending_resume_resumed(
-                                    session_id
+                                    session_id, answered_at=row["answered_at"],
+                                    answer=row["answer"],
                                 )
                             except Exception:
                                 pass
@@ -3862,7 +3864,10 @@ def poller_start(
                         # same broken row. Operator can inspect via the
                         # sessions table.
                         try:
-                            state_db.mark_pending_resume_resumed(session_id)
+                            state_db.mark_pending_resume_resumed(
+                                session_id, answered_at=row["answered_at"],
+                                answer=row["answer"],
+                            )
                         except Exception:
                             pass
                         continue
@@ -3926,7 +3931,10 @@ def poller_start(
                         continue
 
                     try:
-                        state_db.mark_pending_resume_resumed(session_id)
+                        state_db.mark_pending_resume_resumed(
+                            session_id, answered_at=row["answered_at"],
+                            answer=row["answer"],
+                        )
                     except Exception:
                         pass
 
@@ -4203,6 +4211,34 @@ def poller_start(
                         skip_initial_persist=True,
                     )
 
+            # Runs whose process died with them (#312): settle them before
+            # the first poll, so the issues they held are taken again by
+            # that poll rather than skipped as already seen.
+            from ctrlrelay.core.orphans import reap_orphaned_sessions
+            reaped = await reap_orphaned_sessions(
+                state_db, poller=poller, github=github, worktree=worktree,
+            )
+            for r in reaped:
+                where = (
+                    f"#{r['issue_number']} in {r['repo']}"
+                    if r["issue_number"] is not None else r["repo"]
+                )
+                kept = (
+                    f" Its worktree is kept at {r['worktree_path']}."
+                    if r["worktree_path"]
+                    and Path(r["worktree_path"]).exists() else ""
+                )
+                console.print(
+                    f"[yellow]Run {r['session_id']} for {where} stopped "
+                    f"when the relay did; marked failed.{kept}[/yellow]"
+                )
+            # A run that stopped while waiting for an answer (#324) is
+            # `blocked` with its question saved, and is resumed when the
+            # answer comes; the repo lock it held would only wedge the
+            # repo until then.
+            from ctrlrelay.core.orphans import release_dead_blocked_locks
+            release_dead_blocked_locks(state_db)
+
             try:
                 await github_budget.refresh()
                 await run_poll_loop(

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/src/ctrlrelay/core/config.py

@@ -507,6 +507,9 @@ _REPO_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$")
 # reads this table as well, so a caller that bypasses the config cannot
 # get a mode accepted and ignored.
 DEV_STEP_MODES: dict[str, tuple[str, ...]] = {
+    # ``plan`` (#220) runs before ``code``. Unset is ``off``: a repo that
+    # does not ask for a plan runs exactly as it did before the step.
+    "plan": ("off", "on", "required"),
     "code": ("required",),
     "publish": ("required",),
     "verify": ("off", "required"),
@@ -514,6 +517,7 @@ DEV_STEP_MODES: dict[str, tuple[str, ...]] = {
 }
 
 _STEP_REFUSALS: dict[str, str] = {
+    "plan": "",
     "code": (
         "a dev run without the agent run has nothing to publish"
     ),
@@ -567,7 +571,7 @@ class DevStepsConfig(BaseModel):
     ``verify`` stops it when CI is still red after the fix rounds, but
     hands the pull request over when the CI wait times out; ``review``
     reports a review that did not post and hands the pull request over
-    anyway (``on``).
+    anyway (``on``); ``plan`` does not run (``off``).
 
     Unknown keys are refused, so a typo such as ``verfy: required``
     cannot load as "unset".
@@ -575,12 +579,15 @@ class DevStepsConfig(BaseModel):
 
     model_config = {"extra": "forbid"}
 
+    plan: str | None = None
     code: str | None = None
     publish: str | None = None
     verify: str | None = None
     review: str | None = None
 
-    @field_validator("code", "publish", "verify", "review", mode="before")
+    @field_validator(
+        "plan", "code", "publish", "verify", "review", mode="before"
+    )
     @classmethod
     def _known_mode(cls, v: Any, info: Any) -> str | None:
         return check_dev_step_mode(info.field_name, v)

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/src/ctrlrelay/core/dispatcher.py

@@ -133,6 +133,9 @@ class SessionResult:
     stdout: str = ""
     stderr: str = ""
     agent_session_id: str | None = None
+    # 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
 
     @property
     def success(self) -> bool:
@@ -352,6 +355,7 @@ class CliAgentAdapter:
                 exit_code=-1,
                 state=None,
                 stderr="Session timed out",
+                timed_out=True,
             )
         except asyncio.CancelledError as e:
             # Scheduler/shutdown cancel: kill the child BEFORE re-raising

{ctrlrelay-0.19.1 → ctrlrelay-0.20.1}/src/ctrlrelay/core/github.py

@@ -561,6 +561,19 @@ class GitHubCLI:
         )
         return json.loads(output)
 
+    async def get_issue_gate(self, repo: str, issue_number: int) -> dict[str, Any]:
+        """Return ``{"state", "labels", "assignees"}`` for one issue, read
+        live over REST: the fields that decide whether the relay may still
+        start it (#326). ``labels`` and ``assignees`` are lists of names.
+        """
+        output = await self._run_gh(
+            "api", f"repos/{repo}/issues/{issue_number}",
+            "--jq",
+            "{state: .state, labels: [.labels[].name], "
+            "assignees: [.assignees[].login]}",
+        )
+        return json.loads(output)
+
     async def create_pr(
         self,
         repo: str,