ctrlrelay 0.22.0__tar.gz → 0.23.0__tar.gz

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

@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-11-05
+
+### Added
+
+- `repos[].automation.operator_prs` (`ask` or `ignore`; unset is `ask`) lets
+  the secops sweep leave the operator's own open PRs alone on a repo. By
+  default every such PR that touches more than `.github/dependabot.yml` is a
+  question, which can be asked again on later sweeps while the PR stays
+  open. With `ignore` those PRs get no question and are not named in the
+  summary; a PR that touches only `.github/dependabot.yml` is handled as
+  before (merged if it passes the author, diff and CI checks, a question if
+  not), and Dependabot PRs and alerts are unchanged. Unset renders the same
+  prompt as before (#335).
+
+- The status page shows config drift between machines. Each machine's
+  `/api/status` carries a fingerprint of its config: the repo names, and a
+  hash per field of each repo's `automation` and `steps` and of
+  `schedules`; never a value. Each peer's card names what differs from this
+  machine, such as repos only here or only there, or a field that differs
+  on some repos, within one peer read. A peer on a different version shows
+  as unknown, not as drift. An intended difference, such as a routing label in
+  `exclude_labels`, is left out with `fleet.expected_drift` (#307).
+
+- Reopened issues are recorded. When the relay sees an issue's PR merge
+  (and closes the issue), it notes the finish in the state database. If
+  that issue later turns up open in the poller's search, the poller reads
+  its GitHub events and, when there is a `reopened` event after the
+  finish, records the reopen once and puts a `reopened` event in the
+  feed. Ordinary polls make no extra GitHub call. The status page and
+  `/api/status` count reopens per window and per repo (`reopened`, with
+  `reopened_issues`), whether or not the relay picks the issue up again;
+  `null` until the daemon has added the new table (#230).
+- A weekly chat summary. Once a week each node sends one message with its
+  last-7-day numbers: runs started, done, failed, blocked and stuck, the
+  success rate, time to PR, time to merge and reopens. A number it cannot
+  read says `unknown`, never 0. Set with `schedules.weekly_summary`
+  (`enabled`, `day`, `hour`; Monday 09:00 in the configured timezone by
+  default). The last delivery is kept in the state database, so a restart
+  does not send it twice, and a failed send is logged and tried again five
+  minutes later without affecting the poller (#230).
+
+- `ctrlrelay self-update [--version X]` updates a node in one command, only
+  once it is idle. It reads the release from PyPI's JSON, downloads the
+  wheel and checks its sha256 (installing by path, because a node's index
+  has lagged a release by more than ten minutes), then holds new work with
+  a file beside the state database that the poller obeys the way it obeys
+  the usage pause. It waits, bounded, until the poller acknowledges that
+  nothing is in flight and no session is running, so a poll cannot start a
+  run between the check and the restart. Then `uv tool install --force`,
+  a restart of this node's systemd user units or LaunchAgents, and a check
+  that `/api/status` reports the new version and that a new poller process
+  reports it in its heartbeat and stays up (the heartbeat now carries the
+  poller's pid, version and start time). If a step after the install
+  fails, or the command is interrupted after the install began, the old
+  version is installed and restarted again; chat is told either way and
+  the command exits non-zero. The hold is removed on every
+  exit, and ignored once its process is gone or it expires (#306).
+- The status page marks a peer whose version differs from this machine's:
+  its card is red and says which version each runs (#306).
+
+- The poller does not start an issue whose GitHub "blocked by" issues are
+  still open (#310). Before claiming an issue it reads its blockers from
+  GitHub's issue dependencies, including blockers in other repositories.
+  An issue with an open blocker is not claimed, is logged as
+  `poll.issue.blocked`, is listed on the status page under Skipped as
+  "blocked by #A", and is said in chat once; every later poll asks again,
+  so it starts on the first poll after its last blocker closes. Blockers
+  that cannot be read (an API error, a rate limit, a 404 on a GitHub
+  without the dependencies API) hold the issue the same way
+  (`poll.issue.blockers_unknown`) and are never read as "no blockers"; the
+  chat is told only after 3 failed polls in a row. A held issue stays out
+  of `seen_issues` and is recorded in `blocked` in `poller_state.json`, so
+  a restart neither loses it nor repeats the chat line, and a failed
+  self-assignment check while it waits retries it next poll rather than
+  dropping it. Free text such as "Starts after: #A" is not read; use the link.
+
 ## [0.22.0] - 2026-11-05
 
 ### Added
@@ -2449,7 +2525,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.22.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.22.0...v0.23.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.22.0
+Version: 0.23.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.22.0 → ctrlrelay-0.23.0}/docs/cli.md

@@ -383,6 +383,20 @@ Opens the SQLite state DB at `paths.state_db` and prints:
 
 If the DB doesn't exist yet, prints a hint to run a pipeline first.
 
+## `ctrlrelay self-update`
+
+```bash
+ctrlrelay self-update [--version X] [--wait-minutes N] [--no-ack] [-c PATH]
+```
+
+Installs a version already on PyPI on this node once it is idle: holds new
+work, waits (up to `--wait-minutes`, default 60) for the run in flight,
+installs the wheel after checking its sha256 against PyPI's JSON, restarts
+this node's units and checks `/api/status` reports the new version. On any
+failure the old version stays or is put back, chat is told, and it exits
+non-zero. `--no-ack` is for updating from a poller too old to acknowledge
+the hold. See [Operations: Updating a node](operations.md#updating-a-node).
+
 ## `ctrlrelay version`
 
 ```bash

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

@@ -623,6 +623,8 @@ fleet:
   timeout_seconds: 5
   silent_after_seconds: 300
   account_label: "max-2"
+  expected_drift:
+    - "automation.exclude_labels"
 ```
 
 | Key | Type | Default | Description |
@@ -632,6 +634,36 @@ fleet:
 | `timeout_seconds` | number (0-60] | `5` | The longest wait for any one network step of a read; a whole read gets twice this before the peer is reported as `timeout`. |
 | `silent_after_seconds` | int (>= 60) | `300` | A machine whose daemon heartbeat is older than this is shown as **silent**: its web server answers, but the daemon's heartbeat is missing or old, so its poller cannot be confirmed to be working. |
 | `account_label` | string | unset | A name for this machine's agent subscription, shown on its card, such as `max-2`. Never an email address (refused). |
+| `expected_drift` | list of strings | `[]` | Config differences with the peers that are intended, so the page does not report them. Each entry is a repo (`owner/name`: left out of the comparison entirely), a section (`automation`, `steps`, `schedules`) or one field of one (`automation.exclude_labels`, `steps.review`, `schedules.secops_cron`). Anything else is refused at load. See [Config drift](#config-drift). |
+
+### Config drift
+
+Each machine's status page publishes a fingerprint of its config in
+`node.config_fingerprint`. Each time the page or `/api/status` is built, it
+compares the latest fingerprint read from each peer with its own, so a change
+on a peer shows within one peer read. A difference shows on that peer's card, for example
+`config: 2 repos only here: org/a, org/b` or
+`config: automation.exclude_labels differs on 3 repos: …`, and marks the card.
+Identical configs show nothing.
+
+What is compared: the list of repos; for each repo in both, every field of
+`automation` and of `steps`; and every field of `schedules`. Only repo
+names and hashes are sent, never a value. The fingerprint is the config the
+server was started with, so an edit shows once the daemon is restarted.
+
+A peer on a version that sends no fingerprint, or one in another format,
+shows `config drift unknown`, not as drift. So does a peer on a different
+ctrlrelay version than this machine, even one that sends a fingerprint: two
+versions can hash the same config differently (a changed default, say), so
+the two are compared once both run the same version. A field only one side
+has is not compared.
+
+`expected_drift` is read on each machine for its own page only. A routing
+label that only some machines carry in `exclude_labels` is listed as
+`automation.exclude_labels` on every machine whose page should not report
+it. Leaving out a field leaves it out on every repo: a different change to
+that field is not reported either, which is the cost of comparing hashes
+rather than values.
 
 ## repos
 
@@ -681,6 +713,7 @@ and ask the operator), or `never` (skip).
 | `codeql_dismiss` | `ask` | CodeQL alert dismissal. |
 | `secret_alerts` | `never` | Secret-scan alerts. |
 | `deploy_after_merge` | `auto` | Whether to deploy after a merged PR. |
+| `operator_prs` | `ask` | `ask` or `ignore`. What the secops sweep does with your own open PRs that touch more than `.github/dependabot.yml`. See [operator_prs](#reposautomationoperator_prs) below. |
 | `accept_foreign_assignments` | `false` | When `true`, the poller also picks up issues assigned to you by someone else. Default (`false`) runs the dev pipeline only on issues you self-assigned. |
 | `exclude_labels` | `["manual", "operator", "instruction"]` | Issue labels that tell the poller "this isn't for the agent". See [exclude_labels](#reposautomationexclude_labels) below. |
 | `include_labels` | `[]` | Issue labels that opt an issue **into** the dev pipeline regardless of who is (or isn't) assigned. See [include_labels](#reposautomationinclude_labels) below. |
@@ -690,6 +723,31 @@ and ask the operator), or `never` (skip).
 The current secops and dev pipelines read these settings to bias their prompts
 to the agent — they're not enforced by hard-coded checks.
 
+### repos[].automation.operator_prs
+
+The secops sweep looks at the open PRs you authored on each repo. One that
+touches only `.github/dependabot.yml` is a "turn on Dependabot" change: it is
+merged if it passes an author check, a diff check (additions only) and a CI
+check, and is a question if it fails any of them.
+Any other PR of yours is a question by default (`ask`), and while the PR
+stays open that question can be asked again on later sweeps.
+
+On a repo where you keep your own PRs open for a while (blog posts, drafts),
+set `ignore`:
+
+```yaml
+repos:
+  - name: you/your-blog
+    automation:
+      operator_prs: ignore
+```
+
+With `ignore`, those PRs are left alone: no question, and they are not named
+in the sweep's summary. A PR that touches only `.github/dependabot.yml` is
+still handled as above, and Dependabot PRs and alerts are handled as before.
+Unset is `ask`, and the sweep then runs exactly as it did before the setting
+existed.
+
 ### repos[].automation.exclude_labels
 
 Some issues you assign to the operator user aren't code work — they're operator
@@ -1024,12 +1082,39 @@ won't silently disable the job at runtime.
 schedules:
   secops_cron: "0 6 * * *"          # daily 06:00 sweep across repos
   personalization_cron: "*/15 * * * *"  # optional auto-pull
+  weekly_summary:                   # one chat message a week (#230)
+    enabled: true
+    day: mon
+    hour: 9
 ```
 
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `secops_cron` | string | no | `"0 6 * * *"` | When to run the secops sweep (`ctrlrelay secops run` equivalent) across all configured repos. Set to e.g. `"0 6 * * 1"` for weekly Mondays. |
 | `personalization_cron` | string | no | unset | When to auto-pull the personalization repo on this machine. Only effective when [`personalization`](#personalization) is also set. Skip-on-dirty: never rebases under uncommitted operator edits. Adoption is never performed by auto-pull — that stays an init-time concern. |
+| `weekly_summary.enabled` | bool | no | `true` | Send this node's last-7-day numbers to the chat once a week. `false` turns it off. Nothing is sent when no chat [`transport`](#transport) is configured. |
+| `weekly_summary.day` | string | no | `"mon"` | The weekday to send it: `mon` to `sun` (full English names work too). |
+| `weekly_summary.hour` | int | no | `9` | The hour to send it, 0-23, in the top-level `timezone`. |
+
+### schedules.weekly_summary
+
+Once a week, each node sends one chat message with its own numbers for
+the last 7 days, the same ones its status page shows: runs started, done,
+failed, blocked and stuck, the success rate, the median time to PR and to
+merge, and how many issues the relay finished were reopened. A number the
+node cannot read is written `unknown`, with the reason, never 0.
+
+The daemon checks every five minutes. It sends at the first check after
+`day` at `hour`:00 that finds nothing delivered since then, so a node that
+was off at that time sends when it comes back, and a send that fails (the
+bridge restarting, the chat unreachable) is logged as
+`summary.weekly.send_failed` and tried again five minutes later. The time
+of the last delivery is kept in the state database, so restarting the
+poller does not send the week a second time. Two cases can still give an
+extra message: a poller stopped after the message went out but before
+that time was written, and changing `day` or `hour` to a time that has
+already passed this week. The first check on a new or upgraded node only
+notes the time, so its first summary goes at the next `day` and `hour`.
 
 ## personalization
 

{ctrlrelay-0.22.0 → ctrlrelay-0.23.0}/docs/operations.md

@@ -295,7 +295,7 @@ Fields added in #232 (all in `/api/status`):
 |---|---|
 | `url` | On every `running`, `needs_you`, `waiting.items`, `skipped` and `feed` item (and on `/api/events` events): a link to the GitHub issue, or for a feed event that names a PR by number, the PR. Built only as `https://github.com/<owner>/<repo>/issues/<n>` or `/pull/<n>`, from a repo matching `owner/name` and an integer; `null` otherwise (a secops run with no issue, a restart). A `pr_url` an agent reported is never used. |
 | `refs` | On every `needs_you` item (#241): one `{"number", "url"}` per distinct `#N` in the question, in order, at most 20, with `url` built the same way as `url` above from the item's repo and N. A `#N` right after a letter, digit, `_`, `/` or `&` is not counted. The page turns each listed `#N` in the question into a link, so a secops question's PRs are clickable. `[]` when there are none. |
-| `skipped` | Every open issue assigned to you that the poller will **not** pick up and is not running, from the same search as the waiting line (no extra GitHub calls): `repo`, `issue_number`, `title`, `url`, `updated`/`updated_ts` and `reason`, one of `repo not in config`, `excluded label <label>`, `already handled once (won't retry)`, `missing required label <label>` (several joined with "or": any one admits it), `assigned by someone else`. `null` until GitHub has answered once; `waiting.status` and `waiting.last_good_ts` say how current it is. The page shows it collapsed, with a count. |
+| `skipped` | Every open issue assigned to you that the poller will **not** pick up and is not running, from the same search as the waiting line (no extra GitHub calls): `repo`, `issue_number`, `title`, `url`, `updated`/`updated_ts` and `reason`, one of `repo not in config`, `excluded label <label>`, `already handled once (won't retry)`, `missing required label <label>` (several joined with "or": any one admits it), `assigned by someone else`, `blocked by <#N, owner/repo#N>` or `could not read its blockers; asked again every poll` (#310, see [Issues blocked by other issues](#issues-blocked-by-other-issues); these two are listed for a label-triggered issue too). `null` until GitHub has answered once; `waiting.status` and `waiting.last_good_ts` say how current it is. The page shows it collapsed, with a count. |
 | `server` | This machine's health, read on each request: `load_1m`, `load_5m`, `load_15m`, `cpu_count`, `memory` (`total_bytes`, `available_bytes`, `available_pct`, `low`), `disks` (one each for `home` and `worktrees`: `name`, `path`, `total_bytes`, `free_bytes`, `free_pct`, `low`), `uptime_s`, and `unavailable` (why any number is `null`; memory and uptime are `null` off Linux). `low` is true below 10% free and the page marks it. The whole section is `null`, with a line in `errors`, only if reading it failed outright. |
 
 Added in #247:
@@ -333,6 +333,13 @@ Added in #249:
 | `node.open_questions` | How many questions are waiting for an answer. |
 | `fleet` | `{peers: [...]}` with one item per `fleet.peers` URL: `url`, `name`, `reachable`, `checked_at`, `error`, `state`, `node` (that peer's `node` block), `last_known` (its last block while it does not answer) and `needs_you`. `null` when no peers are configured. |
 
+Added in #307:
+
+| Field | What |
+|---|---|
+| `node.config_fingerprint` | `{v, repos_hash, profiles, repos, schedules}`, `v` is `2`. `profiles` maps a profile hash to `{automation, steps}`, each a map of field name to a hash of its value; `repos` maps each repo name to its profile hash, so repos with the same configuration share one profile; `repos_hash` is the hash of the sorted, lowercased repo names; `schedules` maps each `schedules` field to a hash. Hashes and repo names only, never a value. `null` if it could not be built. A peer's fingerprint is unknown unless every hash is 16 lowercase hex characters, `repos_hash` is the hash of its own repo names, each profile key is the hash of that profile, and each repo names a profile it carries. A field's hash cannot be checked against its value, which is never sent. |
+| `fleet.peers[].drift` | `{status, reason, only_here, only_there, fields, lines}`. `status` is `same`, `differs` or `unknown` (with `reason`: not read yet, not reachable, the peer sends no fingerprint in this format, or the comparison failed); `fields` maps a field path such as `automation.exclude_labels` to the repos it differs on; `lines` is what the page shows. Leaves out `fleet.expected_drift`. The peer's own fingerprint is not repeated in `fleet.peers[].node`. |
+
 Added in #230: `numbers` is how this machine's runs went, for the last 7 and
 the last 30 days (`numbers.windows`, each with `days`, `since`/`since_ts`,
 `until`/`until_ts`). The page shows it in the **Numbers** box, with a table
@@ -345,16 +352,23 @@ control plane. Every field is defined in `src/ctrlrelay/web/numbers.py`.
 | `done`, `failed`, `blocked`, `running`, `other` | How many of those runs have that status now. `running` includes a run left behind by a daemon that stopped mid-run. The five add up to `started`. |
 | `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. |
+| `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). |
+| `reopened` | Issues the relay finished (it saw their PR merge and closed them) that were reopened on GitHub in the window, dated by GitHub's `reopened` event. Counted whether or not the relay picks the issue up again; one per finish. The window's `reopened_issues` lists them. The poller notices a reopen only for an issue its search returns (open and assigned to the operator, or wearing a trigger label), with no extra GitHub call unless a finished issue shows up open. Finishes are recorded in the state database from this version on, plus those still in the kept `merged` events when the table is created. `null` on a database the daemon has not migrated yet. A `reopened` event goes to the feed when one is recorded. |
 | `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.
 
+Each machine also sends these 7-day numbers to the chat once a week; see
+[configuration: schedules.weekly_summary]({{ '/configuration/' | relative_url }}#schedulesweekly_summary).
+
 **The page with peers.** A **Machines** strip shows one card per machine,
 this one first: state, slots, 5-hour and 7-day usage, heartbeat age. A card is
 red when the machine is paused, silent, unknown, not reachable, or not read
-yet. A peer that does not
+yet. A peer that answers with a different version from this machine's is red
+too, with `version X, this machine runs Y` on its card, so a node a release
+missed shows up; a peer whose version is unknown is not marked. A peer that
+does not
 answer is shown as **not reachable from here**, with the reason (`timeout`,
 `refused`, `name not found`, `bad host header`, an HTTP status) and its last
 known numbers greyed out, never as idle. **Who has what** lists every claimed
@@ -623,6 +637,44 @@ 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.
 
+## Issues blocked by other issues
+
+When work has an order (B changes the same files as A, so B waits for A),
+say so on GitHub with an issue dependency: on B, **Relationships → Mark as
+blocked by → A**. The blocker may be in another repository. Before the
+poller claims an issue it reads that issue's blockers
+(`GET /repos/{owner}/{repo}/issues/{n}/dependencies/blocked_by`), and:
+
+- **None is open:** the run starts as usual.
+- **One or more is open:** the issue is not claimed and not started. The
+  log has `poll.issue.blocked` with `blocked_by` (the open ones, `#N` in
+  the same repository, `owner/repo#N` in another), the status page lists
+  it under **Skipped** as `blocked by …`, and the chat is told once per
+  issue, not every poll. Every later poll asks again, so it starts on the
+  first poll after the last blocker closes, with nothing to do by hand.
+- **The blockers could not be read** (an API error, the GitHub API budget
+  used up, a 404 from a GitHub Enterprise Server without the dependencies
+  API): treated like an open blocker, never as "no blockers". The log has
+  `poll.issue.blockers_unknown` with the error on every failed poll, and
+  the next poll tries again. A single failure is usually a blip, so the
+  status page keeps showing the blockers last read and the chat is not
+  told; after 3 failed polls in a row the page says `could not read its
+  blockers` and the chat is told once per issue. If the blockers can then
+  be read and are the same as before, nothing more is said.
+
+Only the dependency link counts. A line such as "Starts after: #A" in the
+issue body is not read, so add the link as well.
+
+A held issue is kept out of `seen_issues` (that is what brings it back)
+and recorded in `blocked` in the same `poller_state.json`, so a restart
+neither loses it nor repeats the chat line. Its self-assignment is
+checked again every poll (it may have been unassigned and assigned again
+by someone else), but a check that fails leaves a held issue for the next
+poll instead of marking it handled for good.
+Each poll costs a held issue one extra REST call (`core` budget) for its
+blockers, plus the re-read every issue gets just before it starts. A blocked issue that is closed or loses its trigger is dropped
+from `blocked` when the poller next sees it.
+
 ## Stuck runs
 
 A run that goes in circles is stopped early instead of running until
@@ -673,6 +725,73 @@ page's numbers count these runs in `stuck`.
 | Bot token env var | bridge **and** poller |
 
 After a `ctrlrelay` package upgrade (`uv pip install -e .`), restart both.
+For a node installed with `uv tool`, `ctrlrelay self-update` does the
+install and the restarts for you; see below.
+
+## Updating a node
+
+```bash
+ctrlrelay self-update                    # the latest version on PyPI
+ctrlrelay self-update --version 0.23.0   # a given version
+```
+
+It only installs a version already published on PyPI; publishing stays a
+human decision. In order:
+
+1. Reads `https://pypi.org/pypi/ctrlrelay/<version>/json` and checks that
+   this node's status page answers on `127.0.0.1:<web.port>`; without it the
+   update could not be checked, so it refuses. It also refuses when there is
+   no poller or web unit installed, or ctrlrelay is not a `uv tool` install.
+   Nothing has changed yet.
+2. Downloads the wheel into `wheels/` beside the state database and checks
+   its sha256 against that JSON. A mismatch deletes the file and installs
+   nothing. The wheel is installed by path rather than by name because a
+   node's package index has served a stale list for more than ten minutes
+   after a release. The file is kept, since uv's receipt records the path.
+3. Holds new work: it writes `intake-hold.json` beside the state database.
+   While it is there the poller leaves new issues for the next poll and
+   skips the scheduled sweep and resumed questions, the same way the usage
+   pause does; runs already going finish. The poller answers in
+   `intake-hold.ack.json` with whether anything is still in flight. The
+   command waits, up to `--wait-minutes` (default 60), until the poller says
+   nothing is in flight and the state database has no `running` session.
+   Checking the database alone is not enough: an issue can pass the poller's
+   checks a few seconds before its session row is written, and a restart in
+   that gap cancels it.
+4. `uv tool install --force <wheel>`, then restarts every installed unit:
+   `systemctl --user restart ctrlrelay-{bridge,poller,web}.service` on
+   Linux, `launchctl kickstart -k gui/<uid>/<label>` for each
+   `*.ctrlrelay-{bridge,poller,web}.plist` in `~/Library/LaunchAgents` on
+   macOS (the label is the file's name, whatever `--label-prefix` it was
+   installed with).
+5. Waits up to two minutes for `/api/status` to report the new version,
+   and up to two and a half for a new poller process to report it in its
+   heartbeat (`heartbeat.json` now carries the poller's `pid`, `version`
+   and `started_at`) and still be the one reporting at least one heartbeat
+   interval (30 s) after it started. The status page's version
+   is the web server's own, and a restart command succeeds even when the
+   unit then crash-loops, so neither alone shows the poller is up.
+
+If any step after the install fails, or the command is interrupted
+(Ctrl-C, SIGTERM) once the install has begun, the old version is installed
+and restarted the same way, and checked; a poller from before this command
+writes no version in its heartbeat, so for the old version a fresh
+heartbeat from a new process is enough. Chat (when a transport is configured)
+gets one line either way: the update, or the step that failed and whether
+the old version is running again. The command exits non-zero on any
+failure. The hold is removed on every way out, including Ctrl-C and
+SIGTERM; one left by a process that was killed outright is ignored once
+that process is gone or the hold's expiry (the wait plus 30 minutes) has
+passed.
+
+A poller from before this command does not know the hold and never
+acknowledges it, so the command stops after a minute without changing
+anything. For that one update, `--no-ack` goes on the state database alone,
+with the gap described in step 3. A poller that is not running (its
+heartbeat is older than `fleet.silent_after_seconds`) is not waited on.
+
+A scheduled security sweep whose time comes while the hold is in place is
+skipped until its next time, not delayed.
 
 After merging a PR that the dev pipeline opened, no manual restart is required —
 the PR is referenced from the open branch in your bare repo, so cleanup is
@@ -846,6 +965,13 @@ number only — no assignee and no labels — so the number has to leave
 `seen_issues` (and the relay has to be restarted, since the running
 poller holds the set in memory and rewrites the file from it).
 
+An issue held back by an open GitHub blocker (see [Issues blocked by
+other issues](#issues-blocked-by-other-issues)) is never in `seen_issues`
+while it waits; it is listed in `blocked[<repo>]` as `{"open": [...],
+"failures": n}`: the open blockers as last read (`null` if never read)
+and how many lookups have failed in a row since. Nothing needs deleting: it starts on
+its own once the blockers close.
+
 ### A repo whose history was replaced
 
 If the local copy's default branch can no longer fast-forward to GitHub's

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

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