ctrlrelay 0.17.0__tar.gz → 0.17.1__tar.gz

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

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.1] - 2026-11-01
+
+### Fixed
+
+- Installed bridge and poller units carry the token variable the configured
+  transport names, not a fixed Telegram one. `ctrlrelay install
+  launchd|systemd` and `ctrlrelay setup --install-daemons` read
+  `transport.<type>.bot_token_env` and render `Environment=<that
+  name>=<value>` (systemd) or the matching plist entry (launchd), with the
+  value taken from that variable in the installing shell. A Mattermost
+  install previously got a unit naming `CTRLRELAY_TELEGRAM_TOKEN`, which it
+  never sets, so the bridge could not log in once systemd or launchd started
+  it — the server here only worked because the line had been added by hand.
+  The unresolved-variable hint names the same variable, and the install
+  commands take `--config` to say which `orchestrator.yaml` to read
+  (closes #267)
+- Updating a repository's clone no longer deletes local branches GitHub does
+  not have. The fetch paired `--prune` with `refs/heads/*:refs/heads/*`, which
+  tells git to delete every local branch missing from origin: a branch made in
+  the clone went with `- [deleted]  (none)  -> held`. The worktree stayed,
+  but its branch ref was gone, so a blocked session whose branch was never
+  pushed lost the branch the next time any run touched that repo, and its
+  commits could later be garbage-collected. The fetch is now two: the
+  `dependabot/*` branches, which never carry local work and are the refs that
+  actually pile up, are still pruned; every other branch is fetched without
+  `--prune`. The cost is that a branch GitHub deleted now lingers in the
+  clone, since a prune cannot tell it from one GitHub never had — the
+  branch-reuse path already recognises a local-only ref and decides whether
+  its commits are merged. Because a renamed default branch is no longer
+  pruned either, each update also asks GitHub which branch is the default
+  and points the clone at it when it changed and the branch here is at origin's
+  commit (#243).
+
 ## [0.17.0] - 2026-11-01
 
 Polling costs one GitHub search instead of one call per repo. **No config
@@ -2076,7 +2109,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.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.17.1...HEAD
+[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
 [0.16.3]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.2...v0.16.3

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.17.0
+Version: 0.17.1
 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.0 → ctrlrelay-0.17.1}/docs/cli.md

@@ -68,7 +68,7 @@ Key flags:
 | `--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. |
+| `--install-daemons` | (prompted) | Render and write launchd/systemd unit files. Reads the token variable the chosen transport names (`$CTRLRELAY_TELEGRAM_TOKEN`, `$CTRLRELAY_MATTERMOST_TOKEN`) so the rendered unit 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. |

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

@@ -34,12 +34,19 @@ and restart on failure — the templates below already do this.
 
 Recommended: let `ctrlrelay install launchd` render the plists for you.
 It substitutes `${USER}`, `${HOME}`, the absolute `ctrlrelay` path,
-your working directory, and (when exported) `CTRLRELAY_TELEGRAM_TOKEN`
-into the in-package templates and writes them to
-`~/Library/LaunchAgents/`.
+your working directory, and (when exported) your chat token into the
+in-package templates and writes them to `~/Library/LaunchAgents/`.
+
+The token goes into the plist under the variable your transport names
+in `transport.<type>.bot_token_env` — `CTRLRELAY_TELEGRAM_TOKEN` for
+Telegram, `CTRLRELAY_MATTERMOST_TOKEN` for Mattermost, or whatever you
+renamed that setting to. The command reads your `orchestrator.yaml` to
+find out which; pass `--config` if it is somewhere the usual search
+does not look. Export that variable before running, or the plist keeps
+a placeholder and the command says which variable to export.
 
 ```bash
-export CTRLRELAY_TELEGRAM_TOKEN=your-bot-token
+export CTRLRELAY_MATTERMOST_TOKEN=your-bot-token   # or _TELEGRAM_, per your config
 ctrlrelay install launchd \
   --workdir ~/Projects/ctrlrelay \
   --label-prefix com.yourname \
@@ -158,8 +165,13 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.ctrlrelay-po
 Recommended: `ctrlrelay install systemd` renders the user unit files
 for you (no root needed) and writes them to `~/.config/systemd/user/`.
 
+As on macOS, the bridge and poller units carry the token under the
+variable `transport.<type>.bot_token_env` names, read from your
+`orchestrator.yaml` (`--config` to point at a different one). Export
+that variable before running.
+
 ```bash
-export CTRLRELAY_TELEGRAM_TOKEN=your-bot-token
+export CTRLRELAY_MATTERMOST_TOKEN=your-bot-token   # or _TELEGRAM_, per your config
 ctrlrelay install systemd \
   --workdir ~/Projects/ctrlrelay \
   --poller-interval 300
@@ -190,6 +202,8 @@ After=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=%h/Projects/ctrlrelay
+# The variable your transport names in bot_token_env — use
+# CTRLRELAY_MATTERMOST_TOKEN on a Mattermost config.
 Environment=CTRLRELAY_TELEGRAM_TOKEN=your-bot-token-here
 ExecStart=%h/.local/bin/ctrlrelay bridge start --foreground
 Restart=always
@@ -211,6 +225,8 @@ After=network-online.target ctrlrelay-bridge.service
 [Service]
 Type=simple
 WorkingDirectory=%h/Projects/ctrlrelay
+# The variable your transport names in bot_token_env — use
+# CTRLRELAY_MATTERMOST_TOKEN on a Mattermost config.
 Environment=CTRLRELAY_TELEGRAM_TOKEN=your-bot-token-here
 ExecStart=%h/.local/bin/ctrlrelay poller start --foreground --interval 300
 Restart=always

{ctrlrelay-0.17.0 → ctrlrelay-0.17.1}/pyproject.toml

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

{ctrlrelay-0.17.0 → ctrlrelay-0.17.1}/src/ctrlrelay/cli.py

@@ -5052,6 +5052,12 @@ def setup(
         console.print("  daemon unit files:")
         for p in result.daemon_units:
             console.print(f"    - {p}")
+        if result.daemon_unresolved:
+            console.print(
+                "  [yellow]warning:[/yellow] the units still carry "
+                f"{', '.join('${'+v+'}' for v in result.daemon_unresolved)}; "
+                "export it and re-run with --force, or edit the files by hand."
+            )
         console.print(
             "\n[bold]Next:[/bold] bootstrap the daemons via:\n"
             "  launchctl bootstrap gui/$(id -u) <plist>"
@@ -5463,13 +5469,50 @@ def _print_install_summary(
                 f"  [yellow]warning:[/yellow] unresolved template variables: "
                 f"{', '.join('${'+v+'}' for v in unit.unresolved)}"
             )
-            if "CTRLRELAY_TELEGRAM_TOKEN" in unit.unresolved:
+            # Name the variable this install actually needs. It is
+            # whatever `transport.<type>.bot_token_env` says, so hinting
+            # a fixed CTRLRELAY_TELEGRAM_TOKEN sent a Mattermost
+            # operator to export a variable nothing reads (#267).
+            if unit.token_env_var in unit.unresolved:
                 console.print(
-                    "  [dim]hint: export CTRLRELAY_TELEGRAM_TOKEN before "
+                    f"  [dim]hint: export {unit.token_env_var} before "
                     "re-running, or edit the file by hand.[/dim]"
                 )
 
 
+def _install_token_env_var(config_path: str | None) -> str:
+    """Which env var the rendered units should carry the chat token in.
+
+    Reads the active transport's ``bot_token_env`` so a Mattermost box
+    gets its own variable (#267). Exits non-zero on a config that was
+    asked for and cannot be loaded: rendering the Telegram default on
+    the strength of a path the operator got wrong would write a unit for
+    a transport they are not running. Finding no config at all is a
+    different case — nothing names a transport, so the historical
+    default stands and the summary flags it as unresolved.
+    """
+    from ctrlrelay.install import DEFAULT_TOKEN_ENV_VAR, token_env_var_from_config
+
+    if config_path is None:
+        try:
+            path = resolve_config_path(None)
+        except ConfigError:
+            console.print(
+                f"[yellow]No orchestrator.yaml found, so nothing names the chat "
+                f"transport: the units carry ${DEFAULT_TOKEN_ENV_VAR}. Pass "
+                "--config to use your transport's token variable.[/yellow]"
+            )
+            return DEFAULT_TOKEN_ENV_VAR
+    else:
+        path = resolve_config_path(config_path)
+    try:
+        config = load_config(path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+    return token_env_var_from_config(config)
+
+
 @install_app.command("launchd")
 def install_launchd(
     workdir: Path = typer.Option(
@@ -5499,9 +5542,18 @@ def install_launchd(
         "--dry-run",
         help="Print what would be written without touching the filesystem.",
     ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
 ) -> None:
     """Render and install bridge + poller plists for macOS launchd.
 
+    The plists carry the chat token in the variable the configured
+    transport names, so export that variable before running.
+
     After running, load the agents with:
       launchctl bootstrap gui/$(id -u) <plist-path>
     """
@@ -5512,6 +5564,7 @@ def install_launchd(
         label_prefix=label_prefix,
         poller_interval=poller_interval,
         target_dir=target_dir,
+        token_env_var=_install_token_env_var(config_path),
     )
     written: list[Path] = []
     if not dry_run:
@@ -5547,9 +5600,18 @@ def install_systemd(
         "--dry-run",
         help="Print what would be written without touching the filesystem.",
     ),
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
+    ),
 ) -> None:
     """Render and install bridge, poller and status-page systemd user units (Linux).
 
+    The bridge and poller units carry the chat token in the variable the
+    configured transport names, so export that variable before running.
+
     After running, enable with:
       systemctl --user daemon-reload
       systemctl --user enable --now ctrlrelay-bridge.service
@@ -5562,6 +5624,7 @@ def install_systemd(
         workdir=workdir,
         poller_interval=poller_interval,
         target_dir=target_dir,
+        token_env_var=_install_token_env_var(config_path),
     )
     written: list[Path] = []
     if not dry_run:

{ctrlrelay-0.17.0 → ctrlrelay-0.17.1}/src/ctrlrelay/core/worktree.py

@@ -51,6 +51,13 @@ _GIT_TRANSFER_TIMEOUT_SECONDS = 1800
 # a non-fast-forward rejection.
 _BOT_BRANCH_REFSPEC = "+refs/heads/dependabot/*:refs/heads/dependabot/*"
 
+# ...and the same pattern as a negative refspec, so the fetch that
+# carries every other branch leaves them alone. Keeping the two fetches
+# disjoint is what lets only one of them prune (#243), and it also
+# removes the ordering dependency that made a rebased bot branch a
+# tolerated rejection under the plain refspec.
+_NOT_BOT_BRANCHES_REFSPEC = "^refs/heads/dependabot/*"
+
 
 def _rejections_are_only_non_fast_forward(stderr: str) -> list[str]:
     """Return the refs a fetch declined to rewind, or ``[]`` if the
@@ -1335,23 +1342,36 @@ class WorktreeManager:
           gets to inspect divergence and decide.
         - Local and origin equal: no-op.
 
-        ``--prune`` drops refs that no longer exist on origin so
-        deleted branches don't linger forever.
-
-        Two things keep that non-force refspec from failing the
-        caller, both learned from a secops sweep that died on
-        ``AInvirion/zzsites`` with ``main`` already updated:
-
-        - ``dependabot/*`` is fetched with a force refspec first.
+        Two fetches, not one, and only the first prunes (#243).
+        ``--prune`` is per command and scoped to that command's
+        refspecs, so ``--prune`` paired with ``refs/heads/*`` deletes
+        every local branch origin does not have — measured on 31 Oct,
+        a branch made in the clone went with
+        ``- [deleted]  (none)  -> held``. A blocked session whose
+        branch was never pushed lost it the next time any run touched
+        that repo, and its commits were then reachable only from the
+        worktree's HEAD, one ``git gc`` from gone. So:
+
+        - ``dependabot/*`` with a force refspec **and** ``--prune``.
           Dependabot rebases its branches, which rewrites their tips,
-          so under a plain refspec every rebase is a rejection. These
-          branches are bot-authored and never carry local work, so
-          rewinding one destroys nothing. Twelve bare repos were
-          holding such a ref when this was found.
-        - Any rejection that survives is tolerated rather than raised.
-          Git exits 1 on a declined rewind even when every other ref
-          applied, and that exit code was aborting the whole session
-          for a branch it had correctly protected.
+          so under a plain refspec every rebase is a rejection — a
+          secops sweep died on ``AInvirion/zzsites`` that way with
+          ``main`` already updated, and twelve bare repos were holding
+          such a ref. These branches are bot-authored, never carry
+          local work, and are the ones that actually pile up, so this
+          is where pruning belongs.
+        - Everything else with the plain refspec and **no** ``--prune``,
+          with ``dependabot/*`` excluded by a negative refspec so the
+          two never overlap. A branch origin deleted therefore lingers
+          here; that is the trade, and the branch-reuse path in
+          :meth:`create_worktree_with_new_branch` already has to
+          recognise a local-only ref and decide whether its commits
+          are already merged.
+
+        Any rejection that survives either fetch is tolerated rather
+        than raised. Git exits 1 on a declined rewind even when every
+        other ref applied, and that exit code was aborting the whole
+        session for a branch it had correctly protected.
 
         The default branch is the exception: tolerating a rejection
         there would swap a loud failure for work done quietly on a stale
@@ -1391,11 +1411,26 @@ class WorktreeManager:
                 for branch in await self._checked_out_branches(bare_path)
                 if branch != default_branch
             ] if default_branch else []
+            # The bot branches: force refspec, and the only --prune.
+            # `skip` applies here too — git refuses the WHOLE fetch over
+            # a checked-out branch, and a secops run can have a
+            # dependabot branch checked out. Excluding one also spares
+            # it the prune, which is the answer we want anyway.
+            await self._run_git(
+                "fetch", "--prune", "origin",
+                _BOT_BRANCH_REFSPEC,
+                *skip,
+                cwd=bare_path,
+                timeout=_GIT_TRANSFER_TIMEOUT_SECONDS,
+                tolerate_non_fast_forward=True,
+            )
+            # Every other branch: no --prune, so a local-only branch
+            # survives (#243).
             try:
                 await self._run_git(
-                    "fetch", "--prune", "origin",
-                    _BOT_BRANCH_REFSPEC,
+                    "fetch", "origin",
                     "refs/heads/*:refs/heads/*",
+                    _NOT_BOT_BRANCHES_REFSPEC,
                     *skip,
                     cwd=bare_path,
                     timeout=_GIT_TRANSFER_TIMEOUT_SECONDS,
@@ -1407,11 +1442,72 @@ class WorktreeManager:
                 )
             except DefaultBranchDivergedError as e:
                 await self._set_aside_and_reclone(repo, bare_path, e)
+            else:
+                await self._follow_origin_default(repo, bare_path, default_branch)
         else:
             await self._clone_bare(repo, bare_path)
 
         return bare_path
 
+    async def _follow_origin_default(
+        self, repo: str, bare_path: Path, default_branch: str,
+    ) -> None:
+        """Point the clone's HEAD at origin's default branch when origin
+        changed it. The fetch no longer prunes branches (#243), so a
+        renamed default's old branch stays here, and without this the
+        clone would keep cutting sessions from it. HEAD moves only when
+        the new default is here at the commit origin reports, so a stale
+        or diverged local branch is never adopted; anything else is left
+        for the next update and logged, never silent."""
+        try:
+            out = await self._run_git(
+                "ls-remote", "--symref", "origin", "HEAD",
+                cwd=bare_path, timeout=_GIT_TRANSFER_TIMEOUT_SECONDS,
+            )
+        except WorktreeError as exc:
+            log_event(
+                _logger, "worktree.default_branch_unchecked", repo=repo,
+                reason=str(exc)[:200],
+            )
+            return
+        prefix, suffix = "ref: refs/heads/", "\tHEAD"
+        new = next(
+            (line[len(prefix):-len(suffix)] for line in out.splitlines()
+             if line.startswith(prefix) and line.endswith(suffix)),
+            "",
+        )
+        remote_sha = next(
+            (line.split("\t", 1)[0] for line in out.splitlines()
+             if line.endswith("\tHEAD") and not line.startswith("ref: ")),
+            "",
+        )
+        if not new or new == default_branch:
+            return
+        try:
+            local_sha = (await self._run_git(
+                "rev-parse", "--verify", "--quiet", f"refs/heads/{new}",
+                cwd=bare_path,
+            )).strip()
+        except WorktreeError:
+            local_sha = ""
+        if not remote_sha or local_sha != remote_sha:
+            log_event(
+                _logger, "worktree.default_branch_not_followed", repo=repo,
+                old=default_branch or None, new=new,
+                reason="not here yet" if not local_sha else "not current",
+            )
+            return
+        try:
+            await self._run_git(
+                "symbolic-ref", "HEAD", f"refs/heads/{new}", cwd=bare_path,
+            )
+        except WorktreeError:
+            return
+        log_event(
+            _logger, "worktree.default_branch_changed", repo=repo,
+            old=default_branch or None, new=new,
+        )
+
     async def _checked_out_branches(self, bare_path: Path) -> list[str]:
         """Branches checked out in this clone's linked worktrees."""
         listing = await self._run_git(
@@ -1444,8 +1540,9 @@ class WorktreeManager:
 
         The old clone is never deleted here, and the operator is told
         where it went so they can delete it. It holds what the failed
-        fetch left: that fetch's ``--prune`` may already have dropped
-        local branches origin does not have, as every fetch here does.
+        fetch left: the bot-branch fetch that ran before it prunes
+        ``dependabot/*`` refs origin no longer has. Branches outside
+        that namespace are not pruned by any fetch here (#243).
 
         Refused, re-raising ``cause``, while any worktree is registered
         in the clone: a BLOCKED session keeps its worktree for the