ctrlrelay 0.18.0__tar.gz → 0.19.0__tar.gz

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

@@ -7,6 +7,67 @@ 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
@@ -38,6 +99,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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
@@ -2192,7 +2257,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.18.0...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

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

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

@@ -254,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.18.0 → ctrlrelay-0.19.0}/docs/configuration.md

@@ -658,6 +658,8 @@ repos:
 | `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
@@ -856,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
@@ -893,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
@@ -921,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.18.0 → ctrlrelay-0.19.0}/docs/personalization.md

@@ -301,20 +301,152 @@ 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`)
+### Files an app rewrites in place (`settings.json`): `mode: merge`
 
 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.
+dirties the tree and blocks every later pull. Committing those keys is
+wrong too, because one machine's preference would reach every machine
+as if it were policy.
+
+So for such a file, declare the entry with `mode: merge` and list the
+top-level keys the fleet owns:
+
+```yaml
+personalization:
+  paths:
+    - source: "global/settings.json"
+      target: "~/.claude/settings.json"
+      mode: merge
+      merge_keys: [model, outputStyle, hooks, teammateMode,
+                   remoteControlAtStartup, skipDangerousModePermissionPrompt,
+                   idleCompaction]
+```
+
+The live file is then a **real file on this machine**, never a symlink.
+On `init`, `pull` and the daemon's auto-pull, ctrlrelay writes into it
+only the listed keys that the synced file carries, and reports what it
+did on the same line as the pull: `settings: wrote model, outputStyle`,
+or `settings: in-sync`. Everything else in the live file, including
+whatever the app wrote on its own, is left as it is and never reaches
+the checkout.
+
+The rules, all enforced and tested:
+
+- **The key list is local.** `merge_keys` lives in `orchestrator.yaml`
+  on each machine, not in the synced repo, so a push to that repo cannot
+  widen what it controls. A key in the synced file that is not listed
+  is not written. (Keep `orchestrator.yaml` itself out of the synced
+  repo, or this guarantee is gone.)
+- **An owned key missing upstream is left alone**, not deleted: absent
+  is not the same as "remove it". To change a value fleet-wide, set it.
+- **Bad input is refused.** The synced file must parse as a JSON object
+  with no duplicate keys, at any depth, and so must the live file (an
+  empty live file counts as `{}`). Nesting too deep to parse is refused
+  the same way. Anything else leaves the live file untouched and logs an
+  error.
+- **Everything stays under `$HOME`.** The live file **and the
+  personalization checkout** must both be under your home directory; a
+  path outside it is refused with `is not under $HOME`. (The default
+  checkout, `~/.ctrlrelay/personalization`, is.)
+- **Links and odd files are refused.** Directories are opened one
+  component at a time without following links (`O_DIRECTORY |
+  O_NOFOLLOW`), starting at the resolved `$HOME`, so a home reached
+  through an alias (macOS `/var` -> `/private/var`) works. The read, the
+  temp file and the rename all go through that directory handle. So a symlink at the file **or at any directory under `$HOME`
+  on the way to it** is refused, and its target is never opened. A
+  symlinked `~/.claude` is therefore refused too. Both files must be
+  regular files owned by you, so a FIFO or someone else's file is
+  refused as well. The live path, with its directories resolved, must sit outside
+  the checkout.
+- **Writes are atomic.** Temp file in the same directory, fsync, rename
+  over the live path; mode `0600`, or the existing mode if it is
+  stricter.
+- **A concurrent app write is not lost silently.** Just before the
+  rename, the live file is checked to still be what was read (device,
+  inode, size, mtime). If the app wrote it in between, the merge is
+  redone once from the new content; if it changed again, the pull
+  refuses and the app's write stands. Known limit: a write landing in
+  the few instructions between that last check and the rename itself
+  can still be overwritten, as can one that changes neither size nor
+  mtime. No user-space check can close that window without the app
+  taking a lock.
+- **Values too deep to handle are refused**, whether the parser rejects
+  them or they parse but are too deep to compare or write back.
+- **What keeps app-written keys out of the repo, exactly.** The live
+  file is a real file **outside the checkout**, so nothing the app
+  writes to it is in the git working tree at all. That is the guarantee.
+- **Push refuses a changed checkout copy.** If a merge entry's checkout
+  copy differs from `HEAD` in any way (modified, staged, deleted,
+  renamed away, or present but untracked), `push` refuses before
+  staging anything and leaves the file alone:
+  `refusing to push: global/settings.json in the checkout differs from
+  HEAD. This file is fleet policy; to change it for every machine,
+  commit it yourself with git in the checkout; to drop the local change,
+  run ctrlrelay personalization migrate --reset-copy`.
+  After staging, push also unstages every merge-mode file and checks the
+  index (ignoring case where git does), refusing if one is still staged.
+  These push checks are a **backstop against accidental staging**.
+- **What this does not cover: deliberate local edits in the checkout.**
+  Anyone who can write the checkout can already publish anything from
+  it, so these are out of scope by design, not gaps to close:
+  - renaming the copy (`git mv global/settings.json ...` and committing);
+  - copying it elsewhere in a synced directory (`cp global/settings.json
+    global/other.json`), which pushes the copy as an ordinary file;
+  - hiding a change from git with `git update-index --assume-unchanged`
+    or `--skip-worktree` on the copy;
+  - committing to the checkout by hand (`git commit`), which `push` then
+    publishes like any other commit.
+- **Whatever is committed in the checkout goes to every machine.** To
+  change fleet settings, edit `global/settings.json` in the checkout and
+  `git commit` it yourself; `push` publishes that commit like any other,
+  and every machine applies it within its own `merge_keys`. ctrlrelay
+  does not inspect such a commit, so never commit a value that belongs
+  to one machine.
+- **Only HEAD's fleet values reach the live file.** A merge (on pull,
+  `init` or `migrate`) is refused while the checkout copy differs from
+  `HEAD`, and `migrate --reset-copy` resets the copy *before* merging,
+  so a local edit to a fleet key is never applied to the live file.
+  If git cannot answer whether the copy differs, push and merge refuse
+  (`could not check global/settings.json: ...`) rather than assume.
+- **Without merge entries nothing changes.** A configuration with no
+  `mode: merge` entry stages and commits on `push` exactly as before.
+- **Logs name keys, never values** (a value can be a secret under
+  `env`). A pull that changes `hooks`, `env`, `permissions`,
+  `apiKeyHelper` or `skipDangerousModePermissionPrompt` logs a
+  **warning** naming the key, so a surprise change is visible.
+
+A refusal makes the pull fail (`settings: REFUSED (...)`), so a machine
+that cannot apply fleet settings says so rather than looking synced.
+
+#### Moving off the old symlink: `personalization migrate`
+
+A machine wired before this has `~/.claude/settings.json` as a symlink
+into the checkout. `pull` and auto-pull **refuse** that link and say so;
+they never convert it themselves. Convert it once, explicitly:
+
+```bash
+ctrlrelay personalization migrate
+```
+
+This replaces the link with a real file holding the same content (so
+anything the app or you wrote through it stays on this machine). Once
+the new live file is confirmed to match, it resets the checkout copy to
+`HEAD`, the fleet's version, so the tree is clean and those local keys
+can never be pushed; the output names the keys it reset, never their
+values. Then it merges. A link that points anywhere other than this
+checkout's source is refused.
+
+`ctrlrelay personalization migrate --reset-copy` additionally drops any
+remaining local change to a merge entry's checkout copy (resetting it to
+`HEAD`; the output names the keys, never the values). It is the way out
+of a push refused because that copy changed. It refuses while the live
+path is still the old symlink, since the copy is then the live file.
+
+Anything outside ctrlrelay that recreates the symlink (a converge
+script, a dotfiles installer) must stop doing so for this file, or the
+next pull will refuse again.
 
 ### Git identity
 

{ctrlrelay-0.18.0 → ctrlrelay-0.19.0}/pyproject.toml

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

{ctrlrelay-0.18.0 → ctrlrelay-0.19.0}/src/ctrlrelay/cli.py

@@ -2512,6 +2512,8 @@ def run_dev(
             contexts_dir=config.paths.contexts,
             ci_wait_timeout_seconds=repo_config.automation.ci_wait_timeout_seconds,
             code_review=repo_config.code_review,
+            max_fix_attempts=repo_config.max_fix_attempts,
+            steps=repo_config.steps,
         )
 
     try:
@@ -3263,6 +3265,8 @@ def poller_start(
                         contexts_dir=config.paths.contexts,
                         ci_wait_timeout_seconds=repo_config.automation.ci_wait_timeout_seconds,
                         code_review=repo_config.code_review,
+                        max_fix_attempts=repo_config.max_fix_attempts,
+                        steps=repo_config.steps,
                         claims=claims,
                     )
 
@@ -3814,6 +3818,9 @@ def poller_start(
                                 state_db=state_db,
                                 transport=sweeper_transport,
                                 contexts_dir=config.paths.contexts,
+                                max_fix_attempts=repo_cfg.max_fix_attempts,
+                                code_review=repo_cfg.code_review,
+                                steps=repo_cfg.steps,
                             )
                         elif pipeline_name == "task":
                             result = await resume_task_from_pending(
@@ -4740,6 +4747,46 @@ def personalization_pull(
         raise typer.Exit(1)
 
 
+@personalization_app.command("migrate")
+def personalization_migrate(
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
+    reset_copy: bool = typer.Option(
+        False,
+        "--reset-copy",
+        help=(
+            "Also drop any local change to a merge entry's checkout copy, "
+            "resetting it to HEAD (the fleet's version). The way out of a "
+            "push refused because that copy changed."
+        ),
+    ),
+) -> None:
+    """Turn each `mode: merge` live path that is still the old symlink
+    into this checkout into a real file, keeping its current content.
+
+    One-time and explicit: `pull` and the daemon's auto-pull refuse a
+    symlinked merge target and never migrate it themselves.
+    """
+    from ctrlrelay.personalization.manager import PersonalizationError
+
+    mgr = _make_personalization_manager(config_path)
+    try:
+        outcomes = mgr.migrate(reset_copy=reset_copy)
+    except PersonalizationError as e:
+        console.print(f"[red]Migrate failed:[/red] {e}")
+        raise typer.Exit(1)
+    if not outcomes:
+        console.print("no `mode: merge` entries configured")
+    for o in outcomes:
+        console.print(o.describe(), markup=False)
+    if any(o.refused for o in outcomes):
+        raise typer.Exit(1)
+
+
 @app.command("setup")
 def setup(
     owner: list[str] = typer.Option(

{ctrlrelay-0.18.0 → ctrlrelay-0.19.0}/src/ctrlrelay/core/code_review.py

@@ -160,22 +160,36 @@ def _dedupe_trailing_echo(text: str) -> str:
 
 
 def format_review_comment(
-    outcome: CodeReviewOutcome, *, worktree_path: Path | None = None
+    outcome: CodeReviewOutcome,
+    *,
+    worktree_path: Path | None = None,
+    head_sha: str | None = None,
+    base_branch: str | None = None,
+    base_sha: str | None = None,
 ) -> str:
     """Render findings for a PR comment.
 
     Absolute worktree paths are stripped: they name a directory on the
     orchestrator's disk that means nothing to a reader and will not exist
     by the time anyone clicks.
+
+    When the commits are known they are named, so a reader can tell what
+    was diffed against what: the base is taken from GitHub, and a later
+    push or a moved base is visible as a mismatch.
     """
     body = _dedupe_trailing_echo(extract_verdict(outcome.output))
     if worktree_path is not None:
         body = body.replace(f"{worktree_path}/", "").replace(str(worktree_path), "")
+    scope = ""
+    if head_sha and base_branch and base_sha:
+        scope = (
+            f"Commit `{head_sha}` against `{base_branch}` at `{base_sha}`.\n\n"
+        )
     return (
         "## Automated code review\n\n"
         "_Unverified: this is automated output over the branch, not a "
         "confirmation that anything was reviewed. Weigh it as one "
-        "opinion._\n\n" + (body or "_No findings reported._")
+        "opinion._\n\n" + scope + (body or "_No findings reported._")
     )