ctrlrelay 0.22.0__tar.gz → 0.24.0__tar.gz

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

@@ -7,6 +7,148 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-11-05
+
+### Added
+
+- Each poll's new issues run in priority order, oldest first (#356). The
+  batch is sorted by the position of the issue's priority label in
+  `intake.priority_labels` (default `["P0", "P1", "P2", "P3"]`, compared
+  without case; an issue with several runs at its earliest; unlabeled
+  last), then by when the issue was opened, then by number. An issue whose
+  creation time cannot be read runs after the others with its label. `[]`
+  keeps the oldest-first order only. Each poll that found issues logs the
+  order once as `poll.batch.order`. The re-read before each dispatch and
+  the blocker hold are unchanged; the order is per machine and fixed for
+  the batch.
+
+- Cost per run in the numbers (#230). Each 7- and 30-day window's
+  `cost_per_run` (in `/api/status` and the status page's **Numbers** box)
+  now gives the median and total tokens per run that ended (`done` or
+  `failed`), counted as the run budget counts them (#223), and the median
+  and total `total_cost_usd` where the agent reported one. Runs with no
+  usage recorded (from before #223, or on a backend that is not measured)
+  are left out and counted in `runs_without_usage`, never read as 0; a
+  window with no measured run is `null` with the reason in `unavailable`.
+  The weekly chat summary gets a `tokens per run` line, `unknown` when not
+  measured.
+
+- A dev run's PR goes ready only with proof the change works (#221). The
+  agent names a proving test in its DONE checkpoint. The relay runs it on
+  the pushed commit (must pass) and on the base with only the branch's test
+  changes (must fail), in fresh copies, with a time limit, without the
+  GitHub token, and under bwrap with no network when the agent was
+  sandboxed. It also flags deleted, skipped or loosened tests and empty or
+  whitespace-only diffs. A result counts only with evidence the named test
+  ran (pytest's junit report, or the exit code and the test in the output
+  for other runners), and the PR's head must still be the proven commit when
+  it is marked ready. The outcome is `proven`, `failed` or `not proven`;
+  only `proven` (or a docs-only diff) lets the PR go ready. Otherwise the PR
+  stays a draft and the run fails with `PR #N held as a draft`. The PR gets
+  one comment, edited in place, with the test, the command and both results.
+  Off by default: set `repos[].automation.require_proof: true` for a repo
+  whose tests can run offline in a fresh copy. With it off, the agent is not
+  asked for a proof and nothing is posted.
+
+- Each machine's agent sandbox mode is shown (#305). `/api/status` carries
+  `node.sandbox` (`"none"` or `"bwrap"`; `null` for a peer on an older
+  version), each machine's card on the status page says `sandbox off` in the
+  warning colour when the agent runs unconfined, and the poller logs
+  `poller.sandbox_off` once at start with what to do about it.
+- A token budget for each run (#223). `agent.budget.soft_tokens` warns once
+  in chat and the log; `agent.budget.hard_tokens` stops the agent, records the
+  run as failed with the reason `budget: used N tokens, hard limit M`, and
+  says `💸 Over budget` in chat. `agent.budget.rules` sets other limits by
+  issue label, which covers `size:*`; the first match wins. Nothing is limited
+  until a limit is set. The count is input + cache writes + output tokens,
+  read live from the agent's transcript, and covers the whole issue session
+  across resumes and fix rounds. Cache reads are recorded but not counted.
+  A run stopped over budget or as stuck after it opened a PR puts the PR back
+  to draft (or posts a "Do not merge" comment when that fails), starts no
+  merge watcher for it, and names it in chat and the issue comment.
+- Each session records the tokens it used (`sessions.usage_tokens` and
+  `sessions.usage_detail`, with the cost the agent CLI reported). Running
+  cards on the status page and `/api/status` show `tokens_used`,
+  `cache_read_tokens`, `cost_usd`, `token_soft_limit` and `token_hard_limit`.
+  A reading that could not be parsed shows as unknown (`null`), never as 0,
+  and never stops a run on its own (#223).
+
+## [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 +2591,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.22.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.24.0...HEAD
+[0.24.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.23.0...v0.24.0
+[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.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.22.0
+Version: 0.24.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.24.0}/docs/architecture.md

@@ -140,6 +140,14 @@ to confirm the PR is mergeable and CI is green. If not, it builds a fix prompt
 fix"), resumes the same agent session with that prompt, and re-verifies. Up
 to `DEFAULT_MAX_FIX_ATTEMPTS` (3) attempts.
 
+Then the proof step
+([`src/ctrlrelay/core/proof.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/proof.py),
+#221) runs the test the agent named, in fresh copies of the pushed commit
+(must pass) and of the base with only the branch's test changes (must fail),
+and scans the diff for weakened tests, when the repo turns it on. Only a proven run's PR is marked
+ready; any other outcome leaves it a draft and fails the run. See
+[`automation.require_proof`](configuration.md#reposautomationrequire_proof).
+
 `PRWatcher` (in
 [`src/ctrlrelay/core/pr_watcher.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/pr_watcher.py))
 polls a PR for merge status; the post-merge handler in

{ctrlrelay-0.22.0 → ctrlrelay-0.24.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.24.0}/docs/configuration.md

@@ -40,6 +40,7 @@ repos:        [ ... ]
 | `transport` | object | **yes** | — | See [transport](#transport). |
 | `dashboard` | object | no | (defaults) | See [dashboard](#dashboard). |
 | `web` | object | no | (defaults) | The read-only status page. See [web](#web). |
+| `intake` | object | no | (defaults) | The order each poll's new issues run in. See [intake](#intake). |
 | `claims` | object | no | (defaults) | Claim timings for several machines on one account. See [claims](#claims). |
 | `repos` | list | no | `[]` | See [repos](#repos). |
 | `schedules` | object | no | (defaults) | See [schedules](#schedules). |
@@ -217,6 +218,41 @@ modes either need every shell command allow-listed or filter by command text,
 which a wrapper script walks past, so they are not used as a guard. The guard
 is the next section: the agent holds no GitHub credentials.
 
+### agent.budget
+
+A token budget for each run (#223). Both limits unset (the default): no limit,
+and nothing changes. Usage is measured and shown on the status page either
+way. See [run budgets](operations.md#run-budgets) for what is counted.
+
+```yaml
+agent:
+  budget:
+    soft_tokens: 2000000     # warn once in chat and the log
+    hard_tokens: 6000000     # stop the agent
+    rules:                   # first rule naming any of the issue's labels wins
+      - labels: ["size:S", "size:XS"]
+        soft_tokens: 500000
+        hard_tokens: 1500000
+      - labels: ["size:L", "size:XL"]
+        hard_tokens: 15000000   # soft_tokens left out: 2000000 from above
+      - labels: ["no-budget"]
+        soft_tokens: null       # null: no limit for these runs
+        hard_tokens: null
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `soft_tokens` | int or null | `null` | When a run's total first reaches it, chat gets one line and the log gets `budget.soft_limit`. Once per session. |
+| `hard_tokens` | int or null | `null` | When a run's total reaches it, the agent is stopped and the run is recorded as failed with the reason `budget: used N tokens, hard limit M`. Must be at least `soft_tokens`. |
+| `rules` | list | `[]` | Other limits by issue label. Each rule has `labels` (a non-empty list) and optionally `soft_tokens` and `hard_tokens`. Labels match without regard to case. A size is a label (`size:S`), so this covers sizes too. A limit a rule leaves out comes from the top level; one set to `null` is no limit. |
+
+The count is input tokens + cache writes + output tokens; cache reads are
+recorded but not counted. The budget is for the whole issue session, across
+resumes and CI fix rounds. Unknown keys and a hard limit below the soft one
+(after a rule inherits from the top level) are refused when the config loads.
+Only the `claude` backend is measured. Runs with no issue (secops) get the
+top-level limits for each spawn.
+
 ### What the agent can reach (#219)
 
 The dev and task agents run **without GitHub access**. ctrlrelay starts them
@@ -290,6 +326,14 @@ your user. With `sandbox: "none"` a deliberately hostile agent can read
 and use them by hand, and it can write anywhere your user can, including your
 dotfiles and ctrlrelay's install. On macOS the login keychain is reachable
 whatever the environment says. `sandbox: "bwrap"` closes this on Linux.
+macOS has no sandbox yet, so a macOS node should only take issues from
+repositories you trust.
+
+So that an unconfined node is never a surprise (#305), each machine's mode is
+in `/api/status` as `node.sandbox` (`"none"` or `"bwrap"`; `null` for a peer on
+an older version), its card on the status page says `sandbox off` in the
+warning colour when it is `"none"`, and the poller logs `poller.sandbox_off`
+once at start.
 
 **`sandbox: "bwrap"` (#236).** The dev and task agents run under bubblewrap
 in a read-only copy of the machine (the secops agent, which needs your GitHub
@@ -545,6 +589,29 @@ web:
 The page has no login and shows repository names, issue titles and the
 questions agents asked. **Never expose it to the internet.**
 
+## intake
+
+The order each poll's new issues run in (#356). A poll gathers one batch of
+new issues and works through it before the next poll; this sets the order of
+that batch.
+
+```yaml
+intake:
+  priority_labels: ["P0", "P1", "P2", "P3"]
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `priority_labels` | list of strings | `["P0", "P1", "P2", "P3"]` | Issues carrying an earlier label in this list run first; labels are compared without case, and an issue carrying several runs at its earliest. Issues carrying none of them run last. Within the same label, the oldest issue runs first (by when it was opened, then by number). An issue whose creation time cannot be read runs after the others with its label. `[]` keeps the oldest-first order only. Each label must be a non-empty string and listed once. |
+
+Each poll that found new issues logs the order it will run them in, as one
+`poll.batch.order` event (`order`: `owner/repo#N` in run order). The order is
+fixed when the poll ends: an urgent issue opened while a batch runs waits for
+the next poll. Each issue is still read again just before it starts, and an
+issue blocked by an open issue is still held until the blocker closes; those
+can skip an issue, never reorder the batch. The order applies to this machine
+only, not across machines.
+
 ## claims
 
 How machines that share one GitHub account keep off each other's issues.
@@ -623,6 +690,8 @@ fleet:
   timeout_seconds: 5
   silent_after_seconds: 300
   account_label: "max-2"
+  expected_drift:
+    - "automation.exclude_labels"
 ```
 
 | Key | Type | Default | Description |
@@ -632,6 +701,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,14 +780,42 @@ 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. |
 | `require_labels` | `[]` | Issue labels that gate the plain-assignment trigger: when set, assignment alone is no longer enough — the issue must also carry one of these labels. See [require_labels](#reposautomationrequire_labels) below. |
 | `ci_wait_timeout_seconds` | `600` | Unused since #219 (the agent no longer waits on CI; ctrlrelay does). Still accepted so existing configs load. See [ci_wait_timeout_seconds](#reposautomationci_wait_timeout_seconds) below. |
+| `require_proof` | `false` | A dev run's PR goes ready only when the relay itself proved the change: a test that fails on the base and passes on the branch, and no weakened tests. See [require_proof](#reposautomationrequire_proof) below. |
+
+The current secops and dev pipelines read the policy settings to bias their
+prompts to the agent — they're not enforced by hard-coded checks.
+`require_proof` is the exception: the relay enforces it.
+
+### 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
+```
 
-The current secops and dev pipelines read these settings to bias their prompts
-to the agent — they're not enforced by hard-coded checks.
+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
 
@@ -864,13 +991,120 @@ repos:
 - This does not change the overall session timeout (`agent.default_timeout_seconds`,
   default 1800s) — it only bounds the one `ci wait` call.
 
+### repos[].automation.require_proof
+
+Off by default (#221). Green CI says a change did not break what was already
+tested; it does not say the issue was fixed. With `require_proof` the relay
+checks real evidence before it hands a dev run's PR over as ready.
+
+The agent names its proof in its DONE checkpoint:
+
+```json
+"proof": {"command": ["uv", "run", "--offline", "pytest", "tests/test_x.py::test_y"],
+          "tests": ["tests/test_x.py::test_y"]}
+```
+
+After CI is green, the relay runs `command` twice, as an argument list with
+no shell, each time in a fresh copy of committed content (never the agent's
+worktree):
+
+- on the commit it pushed, where it must pass;
+- on the base commit (the merge base with the default branch) with only the
+  branch's changes to test files applied, where it must fail.
+
+Each run has a 10-minute limit and never gets the operator's GitHub token.
+When the agent ran under `agent.sandbox: bwrap`, the proof runs under the
+same kind of bwrap confinement, with no network and only the copy and the
+agent's cache dir writable. When the agent ran with `sandbox: none`, it
+already ran arbitrary code as this user, so the proof runs unconfined too.
+The copies have no untracked files, so the command must set up what it needs
+offline.
+
+A run counts only with evidence that the named tests ran. For a pytest
+command (`pytest`, `uv run pytest`, `python -m pytest`) the relay adds
+`--junitxml` and reads the report: on the branch each named test must have
+passed, on the base each must have failed or errored. pytest exiting 2 to 5
+(a collection error, a usage error, no tests collected, or `uv run` failing
+to start it), no report, or a named test missing from it is no evidence.
+One exception, on the base only: a collection error in the file of a named
+test (a new test file that imports code only the branch has) counts as
+failing before, recorded as "could not import on base". A collection error
+only in other files does not. For any other runner the command must exit 0 on the
+branch and 1 on the base, and each named test (the part after the last
+`::`) must appear in its output.
+
+There are three outcomes:
+
+| Outcome | When |
+|---|---|
+| `proven` | The named tests failed on the base and passed on the branch. |
+| `failed` | The named tests ran on the branch and did not pass; they ran on the base and passed, so they prove nothing; the diff has no real change (empty or whitespace only); or the diff weakens tests. |
+| `not proven` | No proof was named, the proof is malformed or names a test outside the test files, there is no evidence the named tests ran (a setup, dependency or network failure, a usage error, a collection error), the command could not start, it timed out, or the branch moved after the proof ran. |
+
+Only `proven` lets the PR go ready. Two exemptions, recorded as `not
+required`: a diff that only touches docs (`*.md`, `*.rst`, `*.adoc`,
+`docs/**`), and a repo with `require_proof: false`.
+
+**The test weakening scan** reads the diff's test files (`tests/`, `test_*.py`,
+`*_test.py`, `conftest.py`, `*.test.ts`, `*.spec.js`, `__tests__/` and the
+like) and the test runner's config. These are blockers:
+
+- a deleted test file, in any language;
+- a test file renamed to a name the runner does not collect, or moved out
+  of the tests;
+- a removed test function;
+- an added skip, xfail or `.only` marker: decorators, a module-level
+  `pytestmark`, `pytest.importorskip`, unittest skips, and JS `.skip`,
+  `xit`, `it.only`;
+- an added line in runner config that can deselect or skip: `addopts`,
+  `--deselect`, `-k`, `testpaths`, `norecursedirs`, `collect_ignore` (in
+  `pytest.ini`, `pyproject.toml`, `setup.cfg`, `tox.ini`, `conftest.py`),
+  and jest's `testPathIgnorePatterns`, `testMatch`, `testRegex`;
+- a bare `return` added as the first statement of an existing Python test;
+- an assert line removed from a diff hunk that adds no assert.
+
+An assert line removed from a hunk that also adds one is an edit. The scan
+cannot tell a corrected expectation from a loosened one, so it is shown as a
+warning on the PR and does not block. Lines are matched by text, so a test or
+an assert moved to another file is not a hit. Any blocker makes the run
+`failed`, unless the plan's acceptance criteria say the change is intended
+with an item `Test removal intended: <why>`. Python and JS/TS are read; a
+test file in another language makes the scan report `not checked`, never
+`clean`.
+
+If no test can show the change, the plan's acceptance criteria can say `No
+test possible: <why>`. The run is still `not proven` and the PR stays a
+draft for a person to decide; the PR comment says why.
+
+**What the PR shows.** One comment, edited in place on a later run: the
+outcome and why, the proving test, the command, the fail-before and
+pass-after results with a short redacted tail of each, and any scan hits.
+A run that is not proven fails like any required step after the PR exists
+(see [below](#reposteps)): the PR stays a draft, and chat gets `❌ Failed on
+#N: PR #M held as a draft: not proven …`. A PR GitHub would not open as a
+draft gets a comment telling readers not to merge it.
+
+With `require_proof` on, the PR is opened as a draft, as with
+`steps.review: required`. When both are on, the review step marks it ready
+after the proof passed and the review posted. Right before it is marked
+ready, the relay reads the PR's head from GitHub: if it is not the commit the
+proof ran on, or cannot be read, the run is `not proven` and the PR stays a
+draft.
+
+Turn it on only for a repo whose tests can run offline in a fresh copy of
+the commit. With it off (the default) the agent is not asked for a proof,
+the PR is opened as before, and no proof comment is posted.
+
 ### repos[].steps
 
 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
+fix what fails, up to `max_fix_attempts` rounds), **proof** (the relay runs
+the agent's proving test before and after; switched by
+[`automation.require_proof`](#reposautomationrequire_proof), not here) and
+**review** (the
 configured reviewer reads the pushed commit and posts its findings). The order
 is not configurable. `steps` says how strict each step is for this repo.
 Only the dev pipeline reads it. The task and secops pipelines have no
@@ -918,7 +1152,10 @@ that can each be checked by a command or by reading the diff. The relay then:
   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.
+  agent the criteria are what "done" means;
+- reads two items from the criteria for the proof step: `Test removal
+  intended: <why>` and `No test possible: <why>` (see
+  [require_proof](#reposautomationrequire_proof)).
 
 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
@@ -989,7 +1226,7 @@ exists.** The ordinary failure path, unchanged:
 - chat gets `❌ Failed on #N: …`, never `✅ PR ready`.
 
 A resumed session (an answer that arrived after the run stopped to ask) goes
-through the same publish and verify steps. It did not run the review before
+through the same publish, verify and proof steps. It did not run the review before
 these switches, and with `review` unset or `on` it still does not; with
 `review: required` it does.
 
@@ -1024,12 +1261,41 @@ 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, how many issues the relay finished were reopened, and the median
+tokens per run (with the cost, when the agent reported one) over the runs
+that ended with their usage recorded. 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