ctrlrelay 0.2.1__tar.gz → 0.4.0__tar.gz

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/.github/workflows/pages.yml

@@ -47,7 +47,7 @@ jobs:
             --destination ./_site
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: docs/_site
 

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/.gitignore

@@ -37,3 +37,17 @@ repos.manifest
 
 # Lock file — not committed per AInvirion Python-SDK convention.
 uv.lock
+
+# Operator-private notes (runbooks, personal cheatsheets).
+notes/
+
+# Rendered service unit files. `ctrlrelay install launchd|systemd`
+# substitutes CTRLRELAY_TELEGRAM_TOKEN into a copy of the in-package
+# template and writes it to the system path (~/Library/LaunchAgents on
+# macOS, ~/.config/systemd/user on Linux). The default install command
+# never lands a rendered file inside the repo, but a future flag — or
+# an operator running it with --target-dir pointed at the working tree —
+# would. Defense-in-depth so a `git add .` after such a slip can't
+# scoop the literal token into a commit.
+*.plist
+*.service

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/CHANGELOG.md

@@ -7,6 +7,157 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-08
+
+Minor release. One new feature plus one schema simplification:
+
+- **`ctrlrelay setup`** — first-run onboarding command. Detects every
+  GitHub org you belong to, enumerates non-fork non-archived repos in
+  each, writes a fresh `~/.config/ctrlrelay/orchestrator.yaml`, clones
+  every repo to `~/Projects/<owner.lower()>/<repo>`, optionally
+  configures the personalization sync block, and optionally renders
+  launchd/systemd unit files. Replaces the multi-step manual playbook
+  operators previously had to follow on a new machine. Interactive by
+  default; `--yes` and `--owner` flags make it scriptable.
+- **`paths.owner_aliases` deprecated; lowercase-org-folder convention.**
+  The path resolver now always derives `local_path` as
+  `${repo_root}/${owner.lower()}/${repo}` (closes #128). The previous
+  `owner_aliases` indirection caused `clone-all`/`pull-all`/`status`
+  to disagree with the dev pipeline on where a given repo lived.
+  Parsing of `owner_aliases` is retained so 0.3.x configs still load;
+  a `DeprecationWarning` fires when the block is non-empty.
+
+### Added
+
+- **`ctrlrelay setup`** (closes the onboarding gap reported during the
+  v0.3.0 reinstall flow). Composes existing primitives (gh discovery,
+  config generation, `git clone`, `personalization init`, `install
+  launchd|systemd`) into a single command. Reads
+  `$CTRLRELAY_TELEGRAM_TOKEN` so the rendered plist isn't a
+  placeholder. Refuses to overwrite an existing `orchestrator.yaml`
+  without `--force`.
+- **`repos clone-all` / `pull-all` / `status` accept DEST as
+  optional**. When omitted, each command operates on the
+  config-resolved `local_path` of every repo, so the same path
+  resolution serves the bulk commands and the dev pipeline. Pass DEST
+  to override (lands at `DEST/<owner.lower()>/<repo>`).
+
+### Changed
+
+- **Path resolver: `owner.lower()` is the folder, always.** Closes #128.
+  Affects every command that touches `repo.local_path`. Operators on
+  v0.3.0 with mixed-case folders (e.g. `~/Projects/AInvirion/...`)
+  must either rename the folder, set per-repo `local_path` overrides,
+  or run `ctrlrelay setup --force` to land everything at the new
+  lowercase paths.
+
+### Migration from 0.3.0
+
+- Drop `paths.owner_aliases` from `orchestrator.yaml` (or ignore the
+  deprecation warning until you next regenerate the config).
+- Rename existing on-disk folders to lowercase (e.g.
+  `mv ~/Projects/AInvirion ~/Projects/ainvirion`) — or, easier, run
+  `ctrlrelay setup --force` to clone everything fresh under the new
+  convention.
+
+## [0.3.0] - 2026-05-08
+
+Minor release. Three additive features: cross-machine **personalization
+sync** of operator state through a private GitHub repo, **portability
+fixes** that let one `orchestrator.yaml` work unmodified across machines,
+and **label-driven issue matching** for the dev pipeline. One install
+fix (`PYTHONUNBUFFERED`) and a docs page covering the new
+personalization flow.
+
+### Added
+
+- **Personalization sync** (#123, #124). New `personalization:` config
+  block + `ctrlrelay personalization init/status/push/pull`
+  subcommands sync the operator's Claude Code state — global config,
+  per-project memory, spec/superpower outputs — across machines
+  through a separate (typically private) GitHub repo. Per-machine
+  branches (`personalization/<node_id>`) rebase onto `main` and FF
+  the integration branch, so two machines pushing concurrently never
+  overwrite each other; `--force-with-lease` is reserved for the
+  per-machine branch, never used on `main`. Source/target paths
+  support `${HOME}`, `${PROJECT}` (slug `<owner>--<repo>`),
+  `${PROJECT_ENCODED}` (matches Claude's path encoding),
+  `${PROJECT_LOCAL}`, and `${PROJECT_PARENT}` placeholders. An
+  allowlist limits commits to declared entries — random files in the
+  checkout aren't staged. **Adopt-flow** is on by default: `init`
+  moves pre-existing real targets (e.g. `~/.claude/CLAUDE.md` that
+  predates the sync setup) into the synced repo and lays a symlink in
+  their place; `--no-adopt` opts out. Both-real-content collisions
+  surface as `skipped-conflict-both-exist` for manual reconciliation.
+  See the new [Personalization sync](docs/personalization.md) page.
+- **Auto-pull on cron** (#124). New optional
+  `schedules.personalization_cron` runs `personalization pull` on the
+  poller daemon, with two safety rails: skip-on-dirty (never rebases
+  under uncommitted operator edits) and `adopt=False` on the re-wire
+  (a background sync never silently moves files; adoption stays
+  init-only). Auto-push is intentionally not scheduled — daemon-side
+  commits surprise people. Dispatched via `asyncio.to_thread` so a
+  slow remote can't stall the poller's event loop (Telegram dispatch,
+  pending-resume sweeper, secops cron).
+- **`paths.repo_root` + `paths.owner_aliases`** (#121). When set,
+  `repos[].local_path` is derived as
+  `${repo_root}/${owner_aliases.get(owner, owner)}/${repo}`. Per-repo
+  `local_path` still wins as an override. Without `repo_root`, the
+  legacy "local_path required per repo" behaviour is preserved.
+  Collapses 69 explicit `local_path` values to 20 in the maintainer's
+  config.
+- **`node_id` defaults to hostname** (#121). Falls back to
+  `socket.gethostname()` when missing, null, or blank. Heartbeats and
+  session logs still get a meaningful per-node label without forcing
+  every operator to edit the file.
+- **`ctrlrelay install launchd|systemd`** (#121). Renders
+  bridge/poller service unit files from in-package templates,
+  substituting `USER`, `HOME`, `CTRLRELAY_BIN`, `WORKDIR`,
+  `LABEL_PREFIX`, `POLLER_INTERVAL`, and (when set)
+  `CTRLRELAY_TELEGRAM_TOKEN`. Writes to the conventional locations
+  (`~/Library/LaunchAgents` on macOS, `~/.config/systemd/user` on
+  Linux) and refuses to clobber existing files unless `--force`.
+  Replaces the docs.operations.md copy-paste flow where every
+  operator hand-edited `/Users/$ME/...` strings — a tax on
+  portability and a common source of broken plists.
+- **Label-driven issue matching** (#115, closes #80). Two new
+  per-repo lists govern which issues the poller hands to the dev
+  pipeline:
+  - `repos[].automation.exclude_labels` (default `["manual",
+    "operator", "instruction"]`) — issues carrying any of these
+    labels are skipped, marked seen, logged as
+    `poll.issue.excluded_by_label`, and never trigger code changes.
+    For operator tasks and pure instruction issues.
+  - `repos[].automation.include_labels` (default `[]`) — when
+    non-empty, issues carrying any of these labels opt **in** to the
+    dev pipeline regardless of who is (or isn't) assigned. For repos
+    that drive the pipeline by triage label rather than assignment.
+  Matching is case-insensitive. Trust model documented in
+  [configuration.md](docs/configuration.md#repos-automation): anyone
+  with triage permission on a repo can apply a label, which matches
+  ctrlrelay's existing trust model.
+
+### Fixed
+
+- **`PYTHONUNBUFFERED=1` in launchd plists and systemd units** (#122).
+  Without it, daemon stdout/stderr buffered up to 4–8 KB before
+  flushing to the log file — so `tail -f` on a poller log looked
+  frozen for minutes during quiet periods, and crash diagnostics were
+  clipped at the last buffer boundary instead of the actual failure
+  point. Templates now set the env var and `ctrlrelay install
+  launchd|systemd` re-emits both unit files on next run.
+
+### Docs
+
+- **[Personalization sync](docs/personalization.md)** (#125). New
+  page (nav order 8) covering setup, the dotclaude 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
+  origin URL match). Pairs with new `schedules` and `personalization`
+  sections in [configuration.md](docs/configuration.md) and a new
+  `ctrlrelay personalization` block in [cli.md](docs/cli.md).
+
 ## [0.2.1] - 2026-04-28
 
 Patch release. Fixes a long-standing UX bug where `ctrlrelay` could

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrlrelay
-Version: 0.2.1
+Version: 0.4.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/
@@ -84,9 +84,12 @@ are on the roadmap (see [Roadmap](#roadmap)).
 
 ## Features
 
-- **Issue poller.** Detects issues assigned to you across every
-  configured repo, spawns a dev session in a dedicated git worktree,
-  and opens a PR.
+- **Issue poller.** Detects issues across every configured repo
+  (either assigned to you, or carrying a configurable opt-in label like
+  `ctrlrelay:auto`), spawns a dev session in a dedicated git worktree,
+  and opens a PR. Label triggers let a teammate without rights on your
+  account flag an issue as safe for the bot to pick up —
+  see [`include_labels`][docs-config].
 - **Telegram bridge.** When a session hits a blocking question, the
   bridge relays it to you as a DM and resumes the session once you
   reply.

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/README.md

@@ -45,9 +45,12 @@ are on the roadmap (see [Roadmap](#roadmap)).
 
 ## Features
 
-- **Issue poller.** Detects issues assigned to you across every
-  configured repo, spawns a dev session in a dedicated git worktree,
-  and opens a PR.
+- **Issue poller.** Detects issues across every configured repo
+  (either assigned to you, or carrying a configurable opt-in label like
+  `ctrlrelay:auto`), spawns a dev session in a dedicated git worktree,
+  and opens a PR. Label triggers let a teammate without rights on your
+  account flag an issue as safe for the bot to pick up —
+  see [`include_labels`][docs-config].
 - **Telegram bridge.** When a session hits a blocking question, the
   bridge relays it to you as a DM and resumes the session once you
   reply.

ctrlrelay-0.4.0/config/orchestrator.yaml.example

@@ -0,0 +1,141 @@
+# ctrlrelay orchestrator configuration
+# Copy to orchestrator.yaml and customize
+
+version: "1"
+# node_id defaults to socket.gethostname() when omitted. Set explicitly
+# only if the hostname is meaningless (CI runners, containers).
+# node_id: "studio-mac"
+timezone: "America/Santiago"
+
+paths:
+  state_db: "~/.ctrlrelay/state.db"
+  worktrees: "~/.ctrlrelay/worktrees"
+  bare_repos: "~/.ctrlrelay/repos"
+  contexts: "~/.ctrlrelay/contexts"
+  skills: "~/.ctrlrelay/claude-config/skills"
+  # Optional. When set, repo entries below can omit local_path and have
+  # it derived as ${repo_root}/${owner_aliases.get(owner, owner)}/${repo}.
+  # Per-repo local_path always wins as override.
+  # repo_root: "~/Projects"
+  # owner_aliases:
+  #   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.
+agent:
+  type: "claude"
+  binary: "claude"
+  default_timeout_seconds: 1800
+  output_format: "json"
+
+transport:
+  type: "file_mock"  # Use "telegram" for production
+  telegram:
+    bot_token_env: "CTRLRELAY_TELEGRAM_TOKEN"
+    chat_id: 123456789
+    socket_path: "~/.ctrlrelay/ctrlrelay.sock"
+  file_mock:
+    inbox: "~/.ctrlrelay/inbox.txt"
+    outbox: "~/.ctrlrelay/outbox.txt"
+
+dashboard:
+  enabled: false
+  url: "https://ctrlrelay-dashboard.example.com"
+  auth_token_env: "CTRLRELAY_DASHBOARD_TOKEN"
+
+# Scheduled jobs run in-process by the poller daemon. Cron expressions are
+# standard 5-field (minute hour dom month dow) and evaluate in the `timezone`
+# set above. Change `secops_cron` to e.g. "0 6 * * 1" for weekly (Mondays).
+schedules:
+  secops_cron: "0 6 * * *"
+  # Optional. When personalization is configured AND this is set, the
+  # poller daemon runs `ctrlrelay personalization pull` on this cron
+  # so machines converge without manual sync. Skip-on-dirty: never
+  # rebases under uncommitted operator edits. Defaults to None
+  # (manual sync only).
+  # personalization_cron: "*/15 * * * *"
+
+# Optional: cross-machine personalization sync.
+#
+# A separate (typically PRIVATE) GitHub repo holds the operator's Claude
+# config, per-project memory, spec/superpower outputs, and workspace
+# planning notes — anything that survives across sessions and computers
+# but doesn't belong inside any project's source tree. ctrlrelay clones
+# the repo to `checkout_path` and wires the symlinks in `paths`.
+#
+# Per-machine work happens on a `personalization/<node_id>` branch; push
+# rebases onto `main` (no force-push, ever), so two machines pushing
+# concurrently never overwrite each other's deltas.
+#
+# Slice 1: manual `ctrlrelay personalization init/status/push/pull`.
+# Daemon scheduling, Telegram conflict escalation, and adopt-flow for
+# pre-existing target files are deferred to Slice 2+.
+#
+# Placeholders allowed in `source` and `target`:
+#   ${HOME}             -- current user's home
+#   ${PROJECT}          -- <owner>--<repo> flat slug (project_scoped only;
+#                          double hyphen avoids collisions like a-b/c vs a/b-c)
+#   ${PROJECT_ENCODED}  -- Claude's path encoding (project_scoped only)
+#   ${PROJECT_LOCAL}    -- absolute path of the repo's local checkout
+#   ${PROJECT_PARENT}   -- parent dir of ${PROJECT_LOCAL}
+#
+# personalization:
+#   repo: "oscarvalenzuelab/dotclaude"
+#   # checkout_path: "~/.ctrlrelay/personalization"   # default
+#   # main_branch: "main"                              # default
+#   # node_id: "macbook"   # default: top-level node_id (i.e. hostname)
+#   paths:
+#     # Global Claude config — fixed paths, one entry each so individual
+#     # files can come and go without ripping a whole `~/.claude/` symlink.
+#     - source: "global/CLAUDE.md"
+#       target: "~/.claude/CLAUDE.md"
+#     - source: "global/skills/"
+#       target: "~/.claude/skills/"
+#     - source: "global/agents/"
+#       target: "~/.claude/agents/"
+#     - source: "global/commands/"
+#       target: "~/.claude/commands/"
+#     - source: "global/keybindings.json"
+#       target: "~/.claude/keybindings.json"
+#
+#     # Per-project Claude memory. ${PROJECT_ENCODED} resolves at
+#     # link-time from the repo's local_path, so the same config works
+#     # on machines with different home directories or repo layouts.
+#     - source: "claude-memory/${PROJECT}/"
+#       target: "~/.claude/projects/${PROJECT_ENCODED}/memory/"
+#       project_scoped: true
+#
+#     # Spec / superpower outputs Claude writes per the convention
+#     # documented in templates/global-CLAUDE.md.snippet. Lives next to
+#     # the repo (NOT inside it) so the project's own git history stays
+#     # uncontaminated.
+#     - source: "specs/${PROJECT}/"
+#       target: "${PROJECT_PARENT}/specs/${PROJECT}/"
+#       project_scoped: true
+#
+#     # Workspace-level planning docs (multi-repo workspace, e.g. a
+#     # research project that spans 3 repos under a single parent dir).
+#     # Use one entry per workspace; if you accumulate many, this will
+#     # be promoted to a first-class `workspaces:` config block.
+#     # - source: "workspaces/RESEARCH-DMP/"
+#     #   target: "~/Projects/RESEARCH/DMP/notes/"
+
+repos: []
+  # Example repo configuration:
+  # - name: "owner/repo"
+  #   # Optional when paths.repo_root is set; otherwise required.
+  #   local_path: "~/Projects/repo"
+  #   automation:
+  #     dependabot_patch: auto
+  #     dependabot_minor: ask
+  #     dependabot_major: never
+  #     # Issues carrying any of these labels are skipped by the poller:
+  #     # marked seen, logged as poll.issue.excluded_by_label, and never
+  #     # handed to the dev pipeline. Intended for operator tasks and
+  #     # pure instruction issues that should not trigger code changes.
+  #     # Matching is case-insensitive. Defaults to ["manual", "operator",
+  #     # "instruction"]; override with an empty list to disable.
+  #     exclude_labels: ["manual", "operator", "instruction"]

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/docs/architecture.md

@@ -1,7 +1,7 @@
 ---
 title: Architecture
 layout: default
-nav_order: 8
+nav_order: 9
 description: "Layer diagram, dispatcher / Claude interaction, state-DB shape, and worktree lifecycle for contributors."
 permalink: /architecture/
 ---

{ctrlrelay-0.2.1 → ctrlrelay-0.4.0}/docs/cli.md

@@ -41,6 +41,51 @@ ctrlrelay [--version] <command> ...
 Every command that reads config accepts `--config` / `-c` to point at a
 non-default `orchestrator.yaml` (default: `config/orchestrator.yaml`).
 
+## `ctrlrelay setup`
+
+```bash
+ctrlrelay setup [OPTIONS]
+```
+
+First-run onboarding: detect GitHub orgs, enumerate their non-fork
+non-archived repos, write a fresh `~/.config/ctrlrelay/orchestrator.yaml`,
+clone every repo to `~/Projects/<owner.lower()>/<repo>`, and (optionally)
+configure the personalization sync block plus install launchd/systemd unit
+files. Composes the building blocks operators previously had to wire by hand.
+
+The interactive flow asks one question at a time. `--yes` skips prompts and
+accepts every default. Repeat `--owner` to lock the owner list non-interactively.
+
+Key flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--owner OWNER` | (interactive prompt) | Repeatable. When omitted, prompts to pick from accessible owners. |
+| `--repo-root PATH` | `~/Projects` | Where repos land — `~/Projects/<owner.lower()>/<repo>`. |
+| `--config-out PATH` | `~/.config/ctrlrelay/orchestrator.yaml` | Where to write the generated config. |
+| `--timezone TZ` | `UTC` | IANA zone for cron schedules. |
+| `--transport TRANSPORT` | `file_mock` | `telegram` or `file_mock`. |
+| `--telegram-chat-id ID` | none | Required for `--transport=telegram`. |
+| `--personalization-repo OWNER/REPO` | none | Adds a personalization block. |
+| `--no-personalization` | off | Skip the personalization prompt entirely. |
+| `--install-daemons` | (prompted) | Render and write launchd/systemd unit files. Reads `$CTRLRELAY_TELEGRAM_TOKEN` so the rendered plist isn't a placeholder. |
+| `--skip-archived/--include-archived` | skip | gh repo list filter. |
+| `--skip-forks/--include-forks` | skip | gh repo list filter. |
+| `--yes` / `-y` | off | Accept every default; never prompt. |
+| `--force` | off | Overwrite an existing `orchestrator.yaml` (and existing daemon plists when `--install-daemons`). |
+
+Refuses to overwrite an existing config or daemon plist without `--force`.
+Refuses to proceed if `gh auth status` fails — run `gh auth login` first.
+
+After setup completes, the next manual steps are:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ctrlrelay.ctrlrelay-poller.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ctrlrelay.ctrlrelay-bridge.plist
+```
+
+(Or the systemd equivalents on Linux.)
+
 ## `ctrlrelay config`
 
 ### `config validate`
@@ -232,6 +277,85 @@ ctrlrelay poller status [-c PATH]
 
 Reports running / not-running.
 
+## `ctrlrelay personalization`
+
+See [Personalization sync]({{ '/personalization/' | relative_url }})
+for the conceptual walkthrough. All subcommands require a
+`personalization:` block in `orchestrator.yaml` and operate on the
+checkout at `personalization.checkout_path` (default
+`~/.ctrlrelay/personalization`).
+
+### `personalization init`
+
+```bash
+ctrlrelay personalization init [-c PATH] [--no-adopt]
+```
+
+Clones the personalization repo into `checkout_path`, creates the
+per-machine working branch (`personalization/<node_id>`), and lays
+down the symlinks declared in `personalization.paths`.
+
+By default, **adopt-flow** is on: a target that exists as a real file
+or directory while its corresponding source slot in the repo is empty
+is moved into the repo and replaced with a symlink. Your existing
+content is preserved and immediately under sync. Run `personalization
+push` after `init` to send the adopted content to GitHub.
+
+Pass `--no-adopt` to opt out of adoption — pre-existing real targets
+surface as `skipped-real-file-at-target` instead, and you back them up
++ remove them manually before re-running.
+
+If both the repo source and the on-disk target have real content,
+`init` refuses with `skipped-conflict-both-exist` regardless of
+`--no-adopt`. Reconcile manually before re-running.
+
+### `personalization status`
+
+```bash
+ctrlrelay personalization status [-c PATH]
+```
+
+Prints the working branch, repo URL, ahead/behind counts vs. origin,
+and per-symlink state — `correct`, `wrong-target`, `missing`,
+`source-missing`, etc. Read-only; doesn't touch the filesystem.
+
+### `personalization push`
+
+```bash
+ctrlrelay personalization push [-c PATH] -m "MESSAGE"
+```
+
+Stages the entries declared in `paths` (allowlist — random files in
+the checkout are not committed), commits with `MESSAGE`, rebases the
+per-machine branch onto `origin/<main_branch>`, and pushes. Retries
+the fast-forward of `origin/main` up to three times if another
+machine's push lands between fetch and push. Uses
+`--force-with-lease` on the per-machine branch only when the local
+working branch has diverged from the remote (after a rebase) — never
+on `main`.
+
+Conflicts during the rebase abort and list the unmerged files for you
+to resolve.
+
+### `personalization pull`
+
+```bash
+ctrlrelay personalization pull [-c PATH]
+```
+
+Fetches, rebases the per-machine branch onto `origin/<main_branch>`,
+fast-forwards local `main` if it's an ancestor of the remote, and
+re-wires symlinks (the config-as-code shipped in the repo may have
+changed). Uses `adopt=True` like `init` so newly-declared paths can
+adopt local content during a `pull`. Conflicts abort cleanly and list
+the unmerged files.
+
+The daemon-driven auto-pull (under
+[`schedules.personalization_cron`]({{ '/configuration/#schedules' | relative_url }}))
+calls the same code with two extra rails: skip when the working tree
+is dirty, and re-wire with `adopt=False` so a background sync never
+silently moves files.
+
 ## `ctrlrelay status`
 
 ```bash