ctrlrelay 0.17.1__tar.gz → 0.19.0__tar.gz

{ctrlrelay-0.17.1 → ctrlrelay-0.19.0}/CHANGELOG.md

@@ -7,6 +7,155 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-11-03
+
+### Added
+
+- `repos[].steps` sets each dev pipeline work step (`code`, `publish`,
+  `verify`, `review`) to `off`, `on` or `required`, and `repos[].max_fix_attempts`
+  caps the CI fix rounds. `required` stops the run on a failure, including a
+  reviewer that cannot run or CI that never finished; the PR stays open and the
+  run is announced as failed. Unset keys keep today's behaviour, and settings
+  the pipeline could not honour (`code: off`, `verify: on`, a review switch
+  that disagrees with `code_review.method`) are refused at load (#226).
+- `mode: merge` for a personalization path keeps the live file real and, on
+  pull, writes only the top-level JSON keys listed in the local `merge_keys`,
+  so `~/.claude/settings.json` can carry fleet policy while the keys the app
+  writes on its own stay on that machine and no longer dirty the checkout. The
+  synced file cannot widen the list; it must be a JSON object without
+  duplicate keys; links (at the file or any directory under `$HOME` on the
+  way), non-regular and foreign-owned files are refused; writes are atomic at
+  mode 0600 or stricter and are redone once if the app writes the file
+  meanwhile; push refuses while the checkout copy differs from HEAD (`migrate
+  --reset-copy` drops the change) and a configuration with no merge entry
+  pushes exactly as before; logs name keys, never values, and a change to
+  `hooks`, `env`, `permissions`, `apiKeyHelper` or
+  `skipDangerousModePermissionPrompt` logs a warning. `ctrlrelay
+  personalization migrate` converts the old symlink once, on request, and
+  resets the checkout copy to the fleet's version; pull and auto-pull refuse
+  the symlink instead (#287).
+
+### Fixed
+
+- A personalization pull on a machine still wired the old way (`~/.claude/settings.json`
+  a symlink into the checkout, with the app having written through it) failed
+  with "rebase hit conflicts" and never mentioned the fix. Pull and auto-pull
+  now add: run `ctrlrelay personalization migrate` (#287)
+
+### Security
+
+- The relay's own git touches of agent-written trees no longer reach past
+  the agent sandbox (#263).
+  - Every `git worktree add` the relay runs now reads no global or system
+    git config and runs no hooks or fsmonitor, whether or not the sandbox is
+    on. A committed or planted attributes file therefore cannot select a
+    filter driver the operator's config defines. For that checkout this
+    drops `lfs.*` and `filter.*` drivers, post-checkout hooks,
+    `safe.directory`, `core.autocrlf`/`core.eol`, `core.longpaths` and
+    `url.*.insteadOf` (not needed: the add does no fetch).
+  - A repository using git-lfs now gives the agent pointer files. None of
+    the repositories the relay currently works on uses LFS: 0 of 90 bare
+    clones have `filter=lfs` in HEAD's `.gitattributes`.
+  - The bare clone's own config is still read. The relay writes it, and the
+    sandbox keeps it read-only.
+  - The `CLAUDE.md` exclude line is written only to the worktree's git
+    directory found from the path the relay made (never from the
+    worktree's `.git` file): `<clone>.git/worktrees/<basename>[N]`, whose
+    back-pointer must name this worktree. It is opened without following
+    any link, a hard-linked file is refused, and every refusal is logged
+    and skipped rather than failing the resume.
+  - The reviewer's base branch and its commit come from GitHub rather than
+    the bare clone, are pinned in the review copy, and are named in the
+    review comment.
+
+## [0.18.0] - 2026-11-03
+
+### Added
+
+- A third agent backend: `agent.type: "opencode"` runs sessions through
+  `opencode run --format json --dangerously-skip-permissions` — the spelling
+  every opencode from 1.4 to 2.x accepts; its `--auto` alias exists only from
+  1.17.12 — which can target a self-hosted OpenAI-compatible endpoint
+  (ollama, llama.cpp, LM Studio, MLX) and so lets the dev pipeline run on a
+  local model instead of a hosted API. The endpoint, its credential and the
+  model list stay in opencode's own config; ctrlrelay names the model with
+  `agent.opencode.model` (`provider/model`) and the binary with
+  `agent.opencode.binary` — its own block, because `agent.binary` is claude's
+  and most configs set it to the literal `"claude"`.
+- `repos[].agent_type` opts a single repository into another backend, with
+  `agent.type` the default for every other one. Per repo rather than global on
+  purpose: ctrlrelay works unattended over issue and pull-request text from
+  many repositories and opens pull requests, so a weaker model behind the
+  whole daemon would produce bad pull requests at machine speed with nobody
+  watching. An unroutable session goes to the default backend, never to the
+  opt-in one, and repo names match case-insensitively. A value no adapter
+  answers to stops the daemon at startup naming the repository, the same way
+  an unknown `agent.type` already did (closes #286)
+- The status page and `/api/status` show how this node's runs went over
+  the last 7 and 30 days, overall and per repo: runs started, done,
+  failed, blocked and still running, success rate, median time to PR and
+  to merge, and issues dispatched again after a done run. Cost per run and
+  stuck runs are shown as not recorded yet (refs #230)
+
+### Changed
+
+- Internal, no behaviour change: the dev pipeline's work (code, publish,
+  verify, review) runs as a fixed, ordered list of steps inside a frame that
+  keeps the lock, claim, worktree, cleanup and claim reconciliation as they
+  were. Groundwork for per-repo step switches (refs #226)
+- The subprocess machinery every CLI-driven adapter shares — the timeout, the
+  kill on cancel, the replacing decode, the checkpoint read and #204's outcome
+  report on every exit path — moved from `ClaudeDispatcher` to a
+  `CliAgentAdapter` base both adapters inherit. A second copy of it is how the
+  next backend gets dispatch failures that nothing counts.
+- `ctrlrelay node check` skips its agent-login row, and says why, when no
+  repository routes to `claude` — the global `agent.type` is not `claude` and
+  no `repos[].agent_type` names it. That check is a `claude -p` call reading
+  the claude subscription, so on another backend it reported a failed login
+  against a CLI the deployment does not use; with even one repo still on
+  `claude` it runs, so an expired login shows up there and not as that repo's
+  next failed job.
+
+### Fixed
+
+- The code review no longer runs in the agent's worktree. It runs in a
+  fresh clone of the commit the relay pushed, in a new temporary
+  directory, removed afterwards. Before, a nested repository the agent
+  left in its worktree (a gitlink with its own `.git` and config) made a
+  plain `git status` or `git diff` there run a program the agent chose,
+  in the reviewer's process, outside the agent sandbox. The copy also
+  switches off filter and diff drivers from the operator's own git
+  config (for example git-lfs or a textconv), so a committed
+  `.gitattributes` cannot point agent files at them. If no clean copy can
+  be made, the PR is announced as not reviewed (`copy_failed`); it never
+  falls back to the worktree (#263)
+- Personalization auto-pull no longer reports success when it could not
+  sync. A dirty working tree now fails the run, logged at error level with
+  the dirty entries; every run reports `behind N` (a dirty tree still
+  fetches to measure it). `push` pre-flights the git identity and refuses
+  with `git identity unresolvable` instead of leaving a dirty tree.
+  `docs/personalization.md` describes the open question of app-rewritten
+  files such as `settings.json` (refs #287)
+
+### Known limits
+
+- The `opencode` backend writes no usage reading. A self-hosted model has no
+  subscription window, and recording "unknown" after every run would erase a
+  reading the claude backend holds and un-pause a machine that is at its limit.
+- `agent.sandbox: "bwrap"` is **refused**, not ignored, alongside an `opencode`
+  backend: that confinement binds `~/.claude/*` writable and copies
+  `~/.claude.json`, so it is written for one CLI. Running unconfined under a
+  config that says otherwise would be worse than a daemon that will not start.
+  Credential stripping (#219) applies to every backend either way.
+- Whether a given local model can drive the pipeline is a separate question
+  from whether the adapter is correct, and this change does not answer it.
+  Measured on an M1 Max on 2026-11-01: `qwen2.5-coder:32b-instruct-q4_K_M`
+  emitted **no tool calls at all** (0/3) while advertising `tools` in its
+  metadata, and `qwen3-coder:30b` emitted them (3/3). ctrlrelay's agents signal
+  DONE / BLOCKED / FAILED by running a shell command that writes the checkpoint
+  file, so a model that cannot call tools cannot finish a session. A declared
+  capability is not evidence; only a live call is.
+
 ## [0.17.1] - 2026-11-01
 
 ### Fixed
@@ -484,7 +633,7 @@ daemon with any of it.
   rewind even when every other ref applied. `ensure_bare_repo` read that
   exit code as failure and aborted the session.
 
-  Observed on `AInvirion/zzsites`, whose sweep died reporting
+  Observed on one of the swept repositories, whose sweep died reporting
   `WorktreeError: git failed: ... ! [rejected] ... (non-fast-forward)`
   in the same fetch that had just advanced `main`. Twelve bare repos
   were holding a `dependabot/*` ref at the time, each one primed to fail
@@ -515,8 +664,7 @@ daemon with any of it.
   `✅ Scheduled secops sweep done: N/M ok`, which fires once every repo
   has been swept. On the 2026-09-09 sweep that was hours after the reply
   and named no repo: four answers merged 20 Dependabot PRs across
-  `ai-miner`, `kenos-orchestrator`, `prompt-injection-benchmark` and
-  `aiproxyguard-promptest`, and not one outbound message went back to
+  four repositories, and not one outbound message went back to
   the operator. Answering looked indistinguishable from being ignored.
 
   The inline path now reports the same three outcomes the sweeper
@@ -1052,7 +1200,7 @@ during the dogfood validation:
 
 - **`setup` no longer lists the personalization repo under
   `repos:`.** When the operator's personalization repo lives under
-  one of the configured owners (e.g. `alice/dotclaude` while `alice`
+  one of the configured owners (e.g. `alice/agent-config` while `alice`
   is also an enumerated owner), it was being added to the dev
   pipeline's monitored set — the poller would have polled it for
   issues and worktree-cloned it. The repo is the cross-machine sync
@@ -1214,7 +1362,7 @@ personalization flow.
 ### Docs
 
 - **[Personalization sync](docs/personalization.md)** (#125). New
-  page (nav order 8) covering setup, the dotclaude repo layout, the
+  page (nav order 8) covering setup, the personalization repo layout, the
   init/status/push/pull lifecycle, `--no-adopt`, auto-pull cron,
   multi-machine bootstrap, and the gotchas (worktrees, edit-through-
   symlink semantics, allowlist enforcement, conflict handling, strict
@@ -2109,7 +2257,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.17.1...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.19.0...HEAD
+[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
 [0.17.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.17.0...v0.17.1
 [0.17.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.4...v0.17.0
 [0.16.4]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.3...v0.16.4

{ctrlrelay-0.17.1 → ctrlrelay-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.17.1
+Version: 0.19.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.17.1 → ctrlrelay-0.19.0}/config/orchestrator.yaml.example

@@ -21,16 +21,52 @@ paths:
   #   AInvirion: AINVIRION       # GitHub owner -> on-disk folder name
   #   SemClone: SEMCL.ONE
 
-# Headless coding agent. `type` selects the adapter (currently only
-# "claude" is implemented; other backends — codex, opencode, hermes,
-# kiro — are planned). Legacy `claude:` key is still accepted as an
-# alias for backwards compatibility but is deprecated.
+# Headless coding agent. `type` selects the adapter: "claude" and
+# "opencode" are implemented, and codex/hermes/kiro are still planned.
+# An unimplemented value stops the daemon at startup rather than falling
+# back to claude, so a typo here is loud. Legacy `claude:` key is still
+# accepted as an alias for backwards compatibility but is deprecated.
+#
+# `type` is the DEFAULT for every repo. A single repo can opt into
+# another backend with `repos[].agent_type` — see the repos block at the
+# bottom of this file. That is the intended shape: claude everywhere,
+# one low-stakes repo on a self-hosted model, rather than a global flip.
 agent:
   type: "claude"
+  # claude's own binary and nothing else's. The opencode block below has
+  # its own, because most configs set this to the literal "claude" and
+  # a second backend reading it would exec the wrong program.
   binary: "claude"
   default_timeout_seconds: 1800
   output_format: "json"
 
+  # Read only when a backend of type "opencode" is built, so this block
+  # is inert on a claude-only deployment and harmless to leave in place.
+  #
+  # `model` is "provider/model" as opencode spells it. Point a provider
+  # at a self-hosted OpenAI-compatible endpoint in opencode's own config
+  # (~/.config/opencode/opencode.json), e.g.
+  #
+  #   {"provider": {"local": {"npm": "@ai-sdk/openai-compatible",
+  #     "options": {"baseURL": "http://127.0.0.1:11434/v1"},
+  #     "models": {"qwen3-coder:30b": {}}}}}
+  #
+  # and name it here as "local/qwen3-coder:30b". The endpoint, its
+  # credential and the model list live there, not in ctrlrelay — leaving
+  # `model` unset lets opencode pick, which is usually what you want.
+  #
+  # One measured caveat before choosing a model: a model can advertise
+  # tool support and emit no tool calls at all. ctrlrelay's agents
+  # signal DONE / BLOCKED / FAILED by RUNNING A SHELL COMMAND that
+  # writes the checkpoint file, so a model that cannot call tools cannot
+  # finish a session however good its prose is. Test with a live call.
+  # opencode:
+  #   binary: "opencode"
+  #   model: "local/qwen3-coder:30b"
+  #   # Falls back to agent.default_timeout_seconds when unset. A local
+  #   # model is usually slower per token than a hosted one.
+  #   default_timeout_seconds: 3600
+
 # EXACTLY ONE transport is active, and it is the one named by `type`.
 # The other blocks below are inert: they may stay in the file, but nothing
 # reads them. Running Telegram and Mattermost at the same time is NOT
@@ -184,6 +220,16 @@ repos: []
   # - name: "owner/repo"
   #   # Optional when paths.repo_root is set; otherwise required.
   #   local_path: "~/Projects/repo"
+  #   # Which agent backend runs THIS repo. Omit for agent.type, which
+  #   # is where every repo is unless it says otherwise. A value no
+  #   # adapter answers to stops the daemon at startup naming this repo.
+  #   #
+  #   # Opt in per repo rather than globally. ctrlrelay works unattended
+  #   # over issue and pull-request text and opens pull requests, so a
+  #   # weaker model behind the whole daemon produces bad pull requests
+  #   # at machine speed with nobody watching. Put a low-stakes repo
+  #   # here; leave the ones that matter on claude.
+  #   agent_type: "opencode"
   #   automation:
   #     dependabot_patch: auto
   #     dependabot_minor: ask
@@ -208,3 +254,20 @@ repos: []
   #     # generated while blocked in this call, so a slow default here
   #     # just adds idle wall-clock time. Defaults to 600 (10 minutes).
   #     ci_wait_timeout_seconds: 600
+  #   # How strict each dev pipeline work step is for this repo. The
+  #   # order (code, publish, verify, review) is fixed. Each key is
+  #   # off, on or required; leave a key out for today's behaviour.
+  #   #   required: a failure stops the run, and nothing skips the step
+  #   #             (a reviewer that cannot run is not a pass, and CI
+  #   #             that never finished is not a pass)
+  #   #   on:       a failure is reported and the PR is handed over
+  #   #   off:      the step does not run
+  #   # code and publish accept only required. verify accepts off or
+  #   # required. review: off is the same as code_review.method: off;
+  #   # set both only if they agree.
+  #   steps:
+  #     verify: required
+  #     review: required
+  #   # 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

{ctrlrelay-0.17.1 → ctrlrelay-0.19.0}/docs/configuration.md

@@ -70,6 +70,124 @@ paths:
 | `repo_root` | path | no | Convention root for repo clones. When set, `repos[].local_path` may be omitted and is derived as `${repo_root}/${owner.lower()}/${repo}` (since v0.4.0). Without `repo_root`, every repo entry must declare its own `local_path` (legacy behaviour). |
 | `owner_aliases` | object | no | **Deprecated since v0.4.0.** Pre-0.4.0 this remapped the on-disk folder name (e.g. `SemClone` -> `SEMCL.ONE`). The path resolver now always uses `owner.lower()`, so aliases are no longer consulted. Parsing is retained so 0.3.x configs still load; a `DeprecationWarning` is emitted when a non-empty mapping is supplied. To silence: drop the `owner_aliases` block, rename your on-disk folder to match `owner.lower()`, or set a per-repo `local_path` override for any that genuinely deviate. |
 
+## agent backends
+
+`agent.type` picks the adapter ctrlrelay uses to talk to a coding-agent
+CLI. Two are implemented:
+
+| `agent.type` | CLI it runs | notes |
+|---|---|---|
+| `claude` (default) | `claude -p --output-format stream-json --verbose --dangerously-skip-permissions` | Reads the subscription usage; supports `sandbox: "bwrap"`. |
+| `opencode` | `opencode run --format json --dangerously-skip-permissions` | Can target a self-hosted OpenAI-compatible endpoint. No usage reading; no bwrap yet. |
+
+Anything else raises at startup with a message naming the type. That is
+deliberate: a typo must stop the daemon rather than silently fall back
+to claude.
+
+### Per-repo opt-in
+
+`agent.type` is the default for every repo. A single repo opts into
+another backend with `repos[].agent_type`:
+
+```yaml
+agent:
+  type: "claude"          # everything, unless a repo says otherwise
+  opencode:
+    model: "local/qwen3-coder:30b"
+
+repos:
+  - name: "your-org/important-service"      # claude
+  - name: "your-org/scratchpad"
+    agent_type: "opencode"                  # the local model
+```
+
+Per repo rather than globally, on purpose. ctrlrelay runs unattended
+over issue and pull-request text from many repositories and opens pull
+requests. A weaker model behind the whole daemon produces bad pull
+requests at machine speed with nobody watching, so the shape that is
+safe is claude everywhere plus an explicit opt-in for low-stakes work.
+
+Repo names are matched case-insensitively — GitHub treats `owner/repo`
+that way and the config, an issue payload and `gh` output do not
+reliably agree on the case.
+
+### agent.opencode
+
+```yaml
+agent:
+  type: "claude"
+  opencode:
+    binary: "opencode"
+    model: "local/qwen3-coder:30b"
+    default_timeout_seconds: 3600
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `binary` | string | `"opencode"` | The `opencode` executable. The bare name is resolved like every other tool (PATH, then `~/.local/bin`, `/usr/local/bin`, `/opt/homebrew/bin`), which matters under systemd where the unit's PATH is minimal. An absolute or relative path is used exactly as written. |
+| `model` | string | `null` | `provider/model` as opencode spells it, passed as `--model`. Unset leaves the choice to opencode's own config, which is usually right. |
+| `default_timeout_seconds` | int | `null` | Falls back to `agent.default_timeout_seconds`. A local model is usually slower per token than a hosted one. |
+
+This block is its own rather than a reuse of `agent.binary`: that field
+is claude's, most deployed configs set it to the literal `"claude"`, and
+a second backend reading it would exec `claude` with `opencode`'s
+arguments — a failure that looks like the model's fault.
+
+**The endpoint is configured in opencode, not here.** Point a provider
+at your self-hosted OpenAI-compatible server in
+`~/.config/opencode/opencode.json`:
+
+```json
+{
+  "provider": {
+    "local": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
+      "models": { "qwen3-coder:30b": {} }
+    }
+  }
+}
+```
+
+and name it here as `local/qwen3-coder:30b`. The credential, if the
+endpoint needs one, lives there too.
+
+### What `opencode` does not do yet
+
+- **No usage reading.** A self-hosted model has no subscription window.
+  The adapter writes nothing to `usage.json` — not even "unknown" —
+  because marking it unknown after every run would erase a reading the
+  claude backend legitimately holds and un-pause a machine that is
+  genuinely at its limit. On a deployment with no claude backend at all,
+  `usage` stays empty and the idle probe does not run.
+- **No `sandbox: "bwrap"`.** The confinement binds `~/.claude/*`
+  writable and copies `~/.claude.json`: it is written for one CLI.
+  Combining `agent.sandbox: "bwrap"` with an `opencode` backend is
+  **refused at startup** rather than silently run unconfined. Set
+  `agent.sandbox: "none"` to use it. Credential stripping (#219) applies
+  to every backend either way.
+- **`ctrlrelay node check` skips the agent-login row** when no
+  repository routes to `claude` — the global `agent.type` is not
+  `claude` and no `repos[].agent_type` names it — because that check is
+  a `claude` call reading the claude subscription. With a global
+  `opencode` and even one repo on `claude`, the row still runs. The check
+  never probes `opencode` itself: verify it by running its CLI once by
+  hand.
+
+### Picking a model for `opencode`
+
+One result worth knowing before you choose, measured on an M1 Max on
+2026-11-01: **a model can advertise tool support and emit no tool calls
+at all.** `qwen2.5-coder:32b-instruct-q4_K_M` scored 0/3 on tool calling
+while declaring `tools` in its metadata and shipping a tool-aware
+template; `qwen3-coder:30b` scored 3/3.
+
+That matters more here than it looks. ctrlrelay's agents signal `DONE`,
+`BLOCKED_NEEDS_INPUT` and `FAILED` by **running a shell command that
+writes the checkpoint file** — so a model that cannot call tools cannot
+finish a session at all, however good its prose is. Test with a live
+call; a declared capability is not evidence.
+
 ## claude
 
 Controls how ctrlrelay invokes the `claude` CLI.
@@ -413,7 +531,7 @@ web:
 |---|---|---|---|
 | `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. |
 | `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=`. |
+| `history_days` | int (>= 1) | `7` | Days of feed the page shows, and what `/api/events` returns without `?since=`. Events older than this are deleted, so the run numbers' time to PR and time to merge are shown only for a window whose runs all started after the oldest event kept. Set it to `30` to get the 30-day ones; they appear once 30 days of events have been kept. |
 | `refresh_seconds` | int (>= 1) | `5` | How often the page asks `/api/status` again. |
 | `github_check_seconds` | int (>= 15) | `300` | How often the waiting line asks GitHub (one search, plus one query per `include_labels` label). Every check spends from the GitHub account's budget, which machines on the account share. |
 | `stale_after_minutes` | int (>= 1) | `15` | A running card is marked "looks stuck" after this long with no new agent step, unless ctrlrelay itself has a CI wait or review open for it. |
@@ -537,8 +655,11 @@ repos:
 | `name` | string | **yes** | — | GitHub `owner/repo` slug. Used for `gh` calls and bare-repo / worktree naming. |
 | `local_path` | path | conditional | derived | Where the repo is checked out on disk for human use. Optional when `paths.repo_root` is set (then derived as `${repo_root}/${owner.lower()}/${repo}`, since v0.4.0); required otherwise. An explicit value always wins as override. ctrlrelay itself uses bare mirrors under `paths.bare_repos`. |
 | `dev_branch_template` | string | no | `"fix/issue-{n}"` | Branch-name template for dev-pipeline runs. `{n}` is replaced by the issue number. |
+| `agent_type` | string | no | `null` | Which agent backend runs this repo's sessions. `null` means `agent.type`. See [agent backends](#agent-backends). A value no adapter answers to stops the daemon at startup, naming this repo. |
 | `automation` | object | no | (defaults) | See [automation](#repos-automation). |
 | `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). |
 | `deploy` | object | no | `null` | Reserved for deploy policy. Currently surfaced in `ctrlrelay config repos` but otherwise inert. |
 
 ### repos[].automation
@@ -737,6 +858,109 @@ repos:
 - This does not change the overall session timeout (`agent.default_timeout_seconds`,
   default 1800s) — it only bounds the one `ci wait` call.
 
+### repos[].steps
+
+The dev pipeline does its work in a fixed order: **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
+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
+switchable steps (see [below](#task-and-secops-have-no-step-switches)), so
+`steps` never changes how a `task`-labelled issue or a secops sweep runs.
+
+```yaml
+repos:
+  - name: "your-org/your-repo"
+    steps:
+      verify: required
+      review: required
+    max_fix_attempts: 2
+```
+
+| Mode | Meaning |
+|---|---|
+| `off` | The step does not run. |
+| `on` | A failure is reported and the run continues: the PR is handed over. |
+| `required` | A failure stops the run, and no route skips the step. A step that cannot run has not passed. |
+| (unset) | What the pipeline did before these switches. See the table below. |
+
+| Step | Accepts | Unset means |
+|---|---|---|
+| `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. |
+| `review` | `off`, `on`, `required` | `on`: a review that did not post is announced as `NO REVIEW ON THIS PR` and the PR is handed over. |
+
+`code` and `publish` cannot be `off` or `on`: a dev run without them has
+nothing to hand over, so the config refuses those values at load instead of
+accepting and ignoring them. `verify: on` is refused too: it would announce a
+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.
+
+**`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`.)
+**`verify: off`** skips the CI wait and the fix rounds; the review still runs.
+The PR is announced as ready without anyone having looked at its CI — the
+same thing `verify: on` is refused for, chosen deliberately here by turning
+verify off. The status page has no CI events for the run; `pr_opened` is
+still recorded, once, when the PR is published.
+
+**`review: required`** passes only when the review's findings were posted on
+the PR. A reviewer that cannot start, one that ran without reading the diff, a
+comment that failed to post, a copy of the commit that could not be made, and
+an exception inside the review are all failures. It is about the review
+having happened, not about what it found. **`review: off`** is the same as
+`code_review.method: off`, and loads as that.
+
+Two settings for one reviewer must agree, or the config refuses to load:
+
+- `code_review.method: off` with `steps.review: on` or `required`;
+- `steps.review: off` with an explicit `code_review.method: cli`;
+- `steps.review: required` with `code_review.comment_on_pr: false`, since the
+  findings would never reach the PR.
+
+`code_review.method: off` on its own keeps working as before.
+
+**What the operator sees when a required step stops a run after the PR
+exists.** The ordinary failure path, unchanged:
+
+- the PR stays open on GitHub, and the relay keeps watching it for a merge;
+- the session is marked `failed`; the worktree is removed and the pushed
+  branch kept;
+- the claim on the issue is retracted with a comment that names the PR and
+  the reason (for example `PR #42 not handed over: review is required for
+  your-org/your-repo and did not pass`);
+- 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
+these switches, and with `review` unset or `on` it still does not; with
+`review: required` it does.
+
+#### Task and secops have no step switches
+
+Each of their steps already behaves as `required` or as a best-effort side
+effect, and neither `off` nor `on` would mean something the relay can honour:
+
+- **Task, the agent run.** A task run without it has nothing to report.
+  Only `required` would make sense, and that is what it already does.
+- **Task, posting the report.** A DONE with no report, or a report the relay
+  cannot post, fails the run today. `off` would lose the report: chat gets
+  only the one-line summary. `on` would announce `✅ Task done` and keep the
+  claim on an issue with no report, which looks the same as a crash.
+- **Secops, the sweep.** One agent session reads the alerts and pull requests
+  and merges what the policy allows. The merges happen inside that session,
+  not in a relay step, so a switch could not hold them back. The switch for
+  them already exists: `automation.dependabot_patch`, `dependabot_minor` and
+  `dependabot_major` (`auto`, `ask` or `never`).
+- **Secops, reading earlier answers.** If the 30-day decision history cannot
+  be read, the sweep runs without it. `off` would drop the operator's answers
+  and let the policy merge a pull request they said to leave open.
+
 ## schedules
 
 In-process cron jobs run by the poller daemon. All expressions are
@@ -774,6 +998,10 @@ personalization:
       target: "~/.claude/CLAUDE.md"
     - source: "global/skills/"
       target: "~/.claude/skills/"
+    - source: "global/settings.json"
+      target: "~/.claude/settings.json"
+      mode: merge
+      merge_keys: [model, outputStyle, hooks]
     - source: "claude-memory/${PROJECT}/"
       target: "~/.claude/projects/${PROJECT_ENCODED}/memory/"
       project_scoped: true
@@ -802,6 +1030,8 @@ agree.
 | `source` | string | **yes** | Path inside the personalization repo. Trailing slash means directory. |
 | `target` | string | **yes** | On-disk path the symlink will be created at. Supports `${HOME}` and (when `project_scoped`) `${PROJECT}`, `${PROJECT_ENCODED}`, `${PROJECT_LOCAL}`, `${PROJECT_PARENT}`. |
 | `project_scoped` | bool | no (default `false`) | When `true`, the entry expands once per repo in `repos:`, with the `${PROJECT_*}` placeholders resolved against that repo's `local_path`. |
+| `mode` | string | no (default `"symlink"`) | `symlink` links the target into the checkout. `merge` keeps the target a real file and, on pull, writes into it only the top-level JSON keys in `merge_keys`; for files an app also rewrites, such as `~/.claude/settings.json`. A single file only, not `project_scoped`. See [Files an app rewrites in place]({{ '/personalization/' | relative_url }}). |
+| `merge_keys` | list of strings | with `mode: merge` | The top-level keys the fleet owns in that file. Local config only: the synced file cannot add to it. Required and non-empty for `merge`; not allowed for `symlink`. |
 
 The `${PROJECT}` slug uses **`<owner>--<repo>`** with a double
 hyphen so `a-b/c` and `a/b-c` produce different slugs. `${PROJECT_ENCODED}`

{ctrlrelay-0.17.1 → ctrlrelay-0.19.0}/docs/operations.md

@@ -331,6 +331,23 @@ 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 #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
+per repo under it. Numbers across machines are not here; they belong to the
+control plane. Every field is defined in `src/ctrlrelay/web/numbers.py`.
+
+| Field (in `overall` and in each `by_repo` item) | What |
+|---|---|
+| `started` | Runs (rows in the sessions table) started in the window, both ends included. A blocked run resumed after an answer is still one run. |
+| `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. |
+| `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`. |
+
+`numbers` is `null`, with a line in `errors`, when the sessions cannot be read.
+
 **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