ctrlrelay 0.18.0__tar.gz → 0.19.1__tar.gz

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

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.1] - 2026-11-03
+
+### Fixed
+
+- A synced or live `settings.json` nested more than 64 levels deep is now
+  refused right after it is read. On Python 3.14 the parser accepts about
+  65,000 levels, and writing that back out used all the memory on the
+  machine instead of failing (#313).
+
+## [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 +108,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 +2266,9 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.18.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.19.1...HEAD
+[0.19.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.19.0...v0.19.1
+[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.19.1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: ctrlrelay
+Version: 0.19.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/
+Project-URL: Repository, https://github.com/AInvirion/ctrlrelay
+Project-URL: Issues, https://github.com/AInvirion/ctrlrelay/issues
+Project-URL: Changelog, https://github.com/AInvirion/ctrlrelay/blob/main/CHANGELOG.md
+Author-email: Oscar Valenzuela <oscar.valenzuela.b@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: automation,claude,github,orchestrator
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: apscheduler>=3.10.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ctrlrelay
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI](https://img.shields.io/pypi/v/ctrlrelay.svg)](https://pypi.org/project/ctrlrelay/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/ctrlrelay/)
+[![Tests and lint](https://github.com/AInvirion/ctrlrelay/actions/workflows/test.yml/badge.svg)](https://github.com/AInvirion/ctrlrelay/actions/workflows/test.yml)
+
+**Assign an issue. Get a reviewed pull request. Answer questions from your phone.**
+
+ctrlrelay turns the coding agent you already use into a teammate that works
+your GitHub backlog in the background. It picks up issues, writes the code in
+a clean branch, opens a pull request, waits for CI, gets the change reviewed,
+and pings you on **Telegram** or **Mattermost** only when it truly needs you.
+
+It runs on your own machine. Your code, your credentials, your agent
+subscription. No hosted service in the middle.
+
+**[Documentation](https://ainvirion.github.io/ctrlrelay/)** ·
+**[Get started](https://ainvirion.github.io/ctrlrelay/getting-started/)** ·
+**[Why ctrlrelay](https://ainvirion.github.io/ctrlrelay/#why-ctrlrelay)**
+
+## Why ctrlrelay
+
+Coding agents are great when you sit and watch them. ctrlrelay is for the
+work you don't want to sit and watch.
+
+- **Your backlog is the to-do list.** No new tool to learn. Assign an issue
+  (or add a label) and the work starts. The result is a normal pull request
+  your team already knows how to review.
+- **Runs where your code already lives.** ctrlrelay is a small program on your
+  laptop or server — not a cloud service. Nothing leaves your machine except
+  the calls your agent and GitHub already make. No per-seat platform fee on
+  top of the agent you already pay for.
+- **It asks instead of guessing.** When the agent is stuck, you get the
+  question in chat. You reply from your phone and the *same* session picks up
+  where it stopped.
+- **Safe by default.** Every issue gets its own isolated copy of the repo.
+  One job per repo at a time. Optional Linux sandbox that hides your secrets
+  from the agent. Nothing merges without your rules allowing it.
+- **Done means done.** It waits for CI, fixes failing checks, and posts an
+  independent review on the pull request — so what reaches you is ready to
+  read, not a first draft.
+- **Pick your agent per repo.** Claude Code today, or OpenCode — which can
+  run on a local model — for the repos where that fits.
+- **Grows with you.** Start on one laptop. Add more machines later; they share
+  the work without stepping on each other.
+- **Open source.** Apache 2.0. Read every line of what runs on your machine.
+
+## What it does
+
+- **Issues → pull requests.** Watches every repo you choose and works each new
+  issue end to end.
+- **Questions in your chat.** Telegram (a private bot) or Mattermost (a channel
+  on your own server).
+- **Automatic review.** Every agent pull request gets a second-opinion review
+  comment before you look at it.
+- **Daily security sweep.** Reviews Dependabot alerts and pull requests across
+  your repos every morning.
+- **Status page.** See what each agent is doing, what is waiting, and what
+  needs you — at a glance.
+- **Many machines, one account.** Spread work across machines, with one chat
+  and one status page.
+- **Settings follow you.** Optional sync of your agent setup across machines
+  through a private GitHub repo.
+
+## How it works
+
+```mermaid
+flowchart LR
+    GH[("GitHub<br/>issues")] -->|new issue| CR["ctrlrelay<br/>on your machine"]
+    CR -->|works in a clean branch| AG["Coding agent<br/>Claude Code · OpenCode"]
+    AG -->|stuck?| CH["Your chat<br/>Telegram · Mattermost"]
+    CH -->|your answer| AG
+    AG -->|opens| PR["Pull request"]
+    PR -->|CI + review| YOU(["You merge"])
+```
+
+1. **You assign an issue** to yourself, or add a label you pick.
+2. **ctrlrelay starts the agent** in a fresh, isolated copy of the repo.
+3. **If the agent has a question**, it lands in your chat. Your reply goes
+   straight back to the same session.
+4. **A pull request opens.** ctrlrelay waits for CI, fixes what fails, and
+   posts a review.
+5. **You merge** — or ask for changes, like with any teammate.
+
+## Quick start
+
+```bash
+pipx install ctrlrelay
+ctrlrelay setup          # finds your repos and writes your config
+ctrlrelay poller start   # starts working assigned issues
+```
+
+You need Python 3.12+, the GitHub CLI, and a coding agent CLI. The
+**[getting started guide](https://ainvirion.github.io/ctrlrelay/getting-started/)**
+covers prerequisites, chat setup and running it as a background service.
+
+## Documentation
+
+Everything lives at **[ainvirion.github.io/ctrlrelay](https://ainvirion.github.io/ctrlrelay/)**:
+
+- [Getting started](https://ainvirion.github.io/ctrlrelay/getting-started/) — install and first run
+- [Chat bridge](https://ainvirion.github.io/ctrlrelay/bridge/) — set up Telegram or Mattermost
+- [Configuration](https://ainvirion.github.io/ctrlrelay/configuration/) — every setting
+- [Operations](https://ainvirion.github.io/ctrlrelay/operations/) — background services, status page, several machines
+- [CLI reference](https://ainvirion.github.io/ctrlrelay/cli/) — every command
+
+## Contributing
+
+Contributions are welcome. Read the [contributing guide](CONTRIBUTING.md) and
+the [code of conduct](CODE_OF_CONDUCT.md). First-time contributors sign a
+one-time Contributor Assignment Agreement in the pull request.
+
+## Security
+
+Found a vulnerability? Please follow the [security policy](SECURITY.md) and open
+a private advisory — not a public issue.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).
+
+Copyright (c) 2026 AInvirion LLC. All Rights Reserved.

ctrlrelay-0.19.1/README.md

@@ -0,0 +1,123 @@
+# ctrlrelay
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI](https://img.shields.io/pypi/v/ctrlrelay.svg)](https://pypi.org/project/ctrlrelay/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/ctrlrelay/)
+[![Tests and lint](https://github.com/AInvirion/ctrlrelay/actions/workflows/test.yml/badge.svg)](https://github.com/AInvirion/ctrlrelay/actions/workflows/test.yml)
+
+**Assign an issue. Get a reviewed pull request. Answer questions from your phone.**
+
+ctrlrelay turns the coding agent you already use into a teammate that works
+your GitHub backlog in the background. It picks up issues, writes the code in
+a clean branch, opens a pull request, waits for CI, gets the change reviewed,
+and pings you on **Telegram** or **Mattermost** only when it truly needs you.
+
+It runs on your own machine. Your code, your credentials, your agent
+subscription. No hosted service in the middle.
+
+**[Documentation](https://ainvirion.github.io/ctrlrelay/)** ·
+**[Get started](https://ainvirion.github.io/ctrlrelay/getting-started/)** ·
+**[Why ctrlrelay](https://ainvirion.github.io/ctrlrelay/#why-ctrlrelay)**
+
+## Why ctrlrelay
+
+Coding agents are great when you sit and watch them. ctrlrelay is for the
+work you don't want to sit and watch.
+
+- **Your backlog is the to-do list.** No new tool to learn. Assign an issue
+  (or add a label) and the work starts. The result is a normal pull request
+  your team already knows how to review.
+- **Runs where your code already lives.** ctrlrelay is a small program on your
+  laptop or server — not a cloud service. Nothing leaves your machine except
+  the calls your agent and GitHub already make. No per-seat platform fee on
+  top of the agent you already pay for.
+- **It asks instead of guessing.** When the agent is stuck, you get the
+  question in chat. You reply from your phone and the *same* session picks up
+  where it stopped.
+- **Safe by default.** Every issue gets its own isolated copy of the repo.
+  One job per repo at a time. Optional Linux sandbox that hides your secrets
+  from the agent. Nothing merges without your rules allowing it.
+- **Done means done.** It waits for CI, fixes failing checks, and posts an
+  independent review on the pull request — so what reaches you is ready to
+  read, not a first draft.
+- **Pick your agent per repo.** Claude Code today, or OpenCode — which can
+  run on a local model — for the repos where that fits.
+- **Grows with you.** Start on one laptop. Add more machines later; they share
+  the work without stepping on each other.
+- **Open source.** Apache 2.0. Read every line of what runs on your machine.
+
+## What it does
+
+- **Issues → pull requests.** Watches every repo you choose and works each new
+  issue end to end.
+- **Questions in your chat.** Telegram (a private bot) or Mattermost (a channel
+  on your own server).
+- **Automatic review.** Every agent pull request gets a second-opinion review
+  comment before you look at it.
+- **Daily security sweep.** Reviews Dependabot alerts and pull requests across
+  your repos every morning.
+- **Status page.** See what each agent is doing, what is waiting, and what
+  needs you — at a glance.
+- **Many machines, one account.** Spread work across machines, with one chat
+  and one status page.
+- **Settings follow you.** Optional sync of your agent setup across machines
+  through a private GitHub repo.
+
+## How it works
+
+```mermaid
+flowchart LR
+    GH[("GitHub<br/>issues")] -->|new issue| CR["ctrlrelay<br/>on your machine"]
+    CR -->|works in a clean branch| AG["Coding agent<br/>Claude Code · OpenCode"]
+    AG -->|stuck?| CH["Your chat<br/>Telegram · Mattermost"]
+    CH -->|your answer| AG
+    AG -->|opens| PR["Pull request"]
+    PR -->|CI + review| YOU(["You merge"])
+```
+
+1. **You assign an issue** to yourself, or add a label you pick.
+2. **ctrlrelay starts the agent** in a fresh, isolated copy of the repo.
+3. **If the agent has a question**, it lands in your chat. Your reply goes
+   straight back to the same session.
+4. **A pull request opens.** ctrlrelay waits for CI, fixes what fails, and
+   posts a review.
+5. **You merge** — or ask for changes, like with any teammate.
+
+## Quick start
+
+```bash
+pipx install ctrlrelay
+ctrlrelay setup          # finds your repos and writes your config
+ctrlrelay poller start   # starts working assigned issues
+```
+
+You need Python 3.12+, the GitHub CLI, and a coding agent CLI. The
+**[getting started guide](https://ainvirion.github.io/ctrlrelay/getting-started/)**
+covers prerequisites, chat setup and running it as a background service.
+
+## Documentation
+
+Everything lives at **[ainvirion.github.io/ctrlrelay](https://ainvirion.github.io/ctrlrelay/)**:
+
+- [Getting started](https://ainvirion.github.io/ctrlrelay/getting-started/) — install and first run
+- [Chat bridge](https://ainvirion.github.io/ctrlrelay/bridge/) — set up Telegram or Mattermost
+- [Configuration](https://ainvirion.github.io/ctrlrelay/configuration/) — every setting
+- [Operations](https://ainvirion.github.io/ctrlrelay/operations/) — background services, status page, several machines
+- [CLI reference](https://ainvirion.github.io/ctrlrelay/cli/) — every command
+
+## Contributing
+
+Contributions are welcome. Read the [contributing guide](CONTRIBUTING.md) and
+the [code of conduct](CODE_OF_CONDUCT.md). First-time contributors sign a
+one-time Contributor Assignment Agreement in the pull request.
+
+## Security
+
+Found a vulnerability? Please follow the [security policy](SECURITY.md) and open
+a private advisory — not a public issue.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).
+
+Copyright (c) 2026 AInvirion LLC. All Rights Reserved.

{ctrlrelay-0.18.0 → ctrlrelay-0.19.1}/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.1}/docs/_config.yml

@@ -1,7 +1,8 @@
 title: ctrlrelay
 description: >-
-  Local-first orchestrator for headless coding agents across multiple GitHub
-  repos — operator guides and architecture reference.
+  Assign a GitHub issue, get a reviewed pull request. ctrlrelay runs your
+  coding agent in the background and asks you on Telegram or Mattermost
+  when it needs you.
 url: "https://ainvirion.github.io"
 baseurl: "/ctrlrelay"
 
@@ -26,6 +27,10 @@ search:
 
 heading_anchors: true
 
+# Render ```mermaid fences as diagrams
+mermaid:
+  version: "10.9.1"
+
 # Aux links appear in the top right of the layout
 aux_links:
   "GitHub":

{ctrlrelay-0.18.0 → ctrlrelay-0.19.1}/docs/adding-a-machine.md

@@ -39,10 +39,12 @@ A token copied between machines is revoked for all of them at once.
 
 ## 3. Its own agent login
 
-Log the agent CLI in on this machine. Each machine can use its own
-subscription; it pauses on its own when its usage nears the limit
-(`usage.pause_at`). Two machines on one subscription share one set of usage
-numbers and pause together, which is correct.
+Log the agent CLI in on this machine — whichever your repos use (`claude`,
+`opencode` or both, per `agent.type` and `repos[].agent_type`). For Claude Code, each
+machine can use its own subscription; it pauses on its own when its usage
+nears the limit (`usage.pause_at`). Two machines on one subscription share one
+set of usage numbers and pause together, which is correct. OpenCode has no
+usage reading of its own.
 
 ## 4. A config with its own `node_id`
 
@@ -103,8 +105,9 @@ ctrlrelay node check
 ✓ peer http://node-a:8787: reachable, node-a
 ```
 
-`--no-agent` skips the agent check, which makes one tiny call on the
-subscription. A peer that answers with this machine's own name means two
+`--no-agent` skips the agent check, which makes one tiny `claude` call on the
+subscription. The row is skipped when no repo routes to `claude`, and it never
+checks `opencode`: run that CLI once by hand. A peer that answers with this machine's own name means two
 machines share a `node_id` (or the URL points back here).
 
 ## 8. Start it