ctrlrelay 0.17.1__tar.gz → 0.18.0__tar.gz

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

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- 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 +568,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 +599,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 +1135,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 +1297,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 +2192,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.17.1...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.18.0...HEAD
+[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.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.17.1
+Version: 0.18.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.18.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

{ctrlrelay-0.17.1 → ctrlrelay-0.18.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,6 +655,7 @@ 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). |
 | `deploy` | object | no | `null` | Reserved for deploy policy. Currently surfaced in `ctrlrelay config repos` but otherwise inert. |

{ctrlrelay-0.17.1 → ctrlrelay-0.18.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

{ctrlrelay-0.17.1 → ctrlrelay-0.18.0}/docs/personalization.md

@@ -224,10 +224,14 @@ schedules:
 The poller registers an APScheduler job that runs `personalization pull`
 on this schedule. Two safety rails:
 
-- **Skip-on-dirty.** If the working tree has uncommitted changes, the
-  auto-pull skips with a `working tree dirty` summary. A daemon
-  rebasing under your unsaved edits is exactly the surprise we don't
-  want.
+- **Refuse-on-dirty, loudly.** If the working tree has uncommitted
+  changes, the auto-pull does not rebase (a daemon rebasing under your
+  unsaved edits is exactly the surprise we don't want) but it is **not**
+  a quiet success: the run fails, is logged at error level as
+  `auto-pull BLOCKED: working tree dirty (...)`, and names the dirty
+  entries. It still fetches, so the line carries `behind N`.
+  Every run reports `behind N`; a machine drifting is a number in the
+  log, not silence (#287: one machine sat 36 commits behind for weeks).
 - **No adoption.** Adoption is an init-time concern. The auto-pull
   re-wire phase runs with `adopt=False` so a background sync never
   silently moves files. New entries in `paths` that have no remote
@@ -293,9 +297,32 @@ unrelated, project-scoped feature.
 A write to `~/.claude/CLAUDE.md` is a write to
 `~/.ctrlrelay/personalization/global/CLAUDE.md`. After editing, run
 `ctrlrelay personalization push`. If you forget, the auto-pull's
-skip-on-dirty rail keeps things safe — the daemon won't rebase under
-your unsaved work — but your edit doesn't reach other machines until
-you push.
+refuse-on-dirty rail keeps things safe — the daemon won't rebase under
+your unsaved work and says so at error level — but your edit doesn't
+reach other machines until you push.
+
+### Files an app rewrites in place (`settings.json`)
+
+If a target such as `~/.claude/settings.json` is a symlink into the
+checkout, the app that owns it writes straight into a tracked file: any
+per-viewer preference it records (and a mere key reordering on rewrite)
+dirties the tree and blocks every later pull.
+
+**How to handle this is not decided yet** (#287). Two things are known
+not to work: committing the app-written keys (one machine's preference
+would reach every machine as if it were policy), and resetting the file
+on a loop (the app writes it again). One way out is for a machine whose
+live file carries keys the synced one lacks to keep a real file instead
+of the symlink. Until a decision lands, the `BLOCKED` line above is the
+signal that a machine is stuck this way.
+
+### Git identity
+
+`push` pre-flights the author identity before staging: it falls back to a
+repo-local `ctrlrelay <ctrlrelay@local>` when none is configured, then
+asks git (`git var GIT_AUTHOR_IDENT`) and refuses with
+`git identity unresolvable` if it still cannot commit, rather than
+leaving a dirty tree behind.
 
 ### Allowlist enforcement