ctrlrelay 0.14.0__tar.gz → 0.16.0__tar.gz

{ctrlrelay-0.14.0 → ctrlrelay-0.16.0}/CHANGELOG.md

@@ -7,6 +7,167 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-11-01
+
+Several machines can now run ctrlrelay on one GitHub account, each claiming
+an issue before it works it, and the dev and task agents can run in a
+read-only sandbox. Every new config value has a default and nothing is added
+to the database, so for most installs **no config edit is required**. Check
+three things before upgrading:
+
+- **A placeholder `node_id` is refused at startup**: `localhost`,
+  `localhost.localdomain`, `unknown`, `my-laptop`, `studio-mac` (both were
+  examples in earlier docs), `changeme`, `example`, `node`, `hostname`. Set a
+  name no other machine on the account uses. A missing `node_id` still
+  defaults to the hostname.
+- **If you already run `agent.sandbox: bwrap`**, it is now much stricter:
+  by default the agent can write its worktree, its git dirs, a private
+  `/tmp`, its own empty `gh` and runtime dirs, the entries of `~/.claude`,
+  its own cache and any `sandbox_writable_paths`, minus the read-only and
+  hidden paths inside those. Anything else a run wrote
+  (a cache in your home, `git config`, submodules, commit signing) fails
+  there. It also refuses to start with `CLAUDE_CONFIG_DIR` set or with a
+  read-only path that is a replaceable link. Read the sandbox section of the
+  configuration docs before upgrading such a machine.
+- **Upgrade every machine on an account to the same version.** Claims now
+  name the machine and the process that wrote them, and an older version
+  reads them differently. A claim comment left by an older version counts
+  as taken by `unknown` and never goes stale: once nothing is working that
+  issue, delete the comment to free it. With a shared Mattermost bot, a
+  question asked before the upgrade carries no machine tag: answer it with
+  `node-a: ...`.
+
+### Added
+
+- Several machines on one account: before a dev or task run, the machine
+  claims the issue with a comment naming itself, waits
+  `claims.race_wait_seconds` and backs off if another machine's claim came
+  first; claims are refreshed while the run lasts and taken over once stale
+  (`claims.refresh_seconds`, `claims.stale_after_seconds`). A run whose
+  machine cannot refresh its claim for longer than the stale time (a long
+  GitHub outage) can be taken over while it still runs, so keep the
+  machines' clocks synchronised and the stale time well above any outage
+  you expect. A run that fails after being resumed from a question leaves
+  its claim held; delete the claim comment to free that issue (#252,
+  closes #245)
+- The scheduled security sweep runs at most once per repository and
+  scheduled time across machines: the first to create the ref
+  `refs/ctrlrelay/claims/secops/<window>` in the repository runs it. A
+  machine that dies holding a window, or a ref that cannot be created,
+  leaves that repository unswept for that window; the next window is new.
+  Keep `repos`, `schedules` and `timezone` the same on every machine, or
+  they name different windows (#259, closes #246)
+- Chat with several machines: questions are tagged with the machine's name
+  and a machine ignores replies to another's. Mattermost machines can share
+  one bot and channel with `transport.mattermost.shared: true` (a message
+  that is not a reply must start with `node-b: ...`); Telegram needs one bot
+  per machine. When a second process starts reading the same bot, Telegram
+  cuts off the one already running, which now says so once, in its log and
+  in the chat, and stops reading (#260, closes #248)
+- Subscription usage: read from each agent run and shown on the status
+  page. New issues wait while the 5-hour or 7-day window is at or above
+  `usage.pause_at` (default 90%), or the status is anything but `allowed`,
+  until the window's reset (or an hour, when the reset time cannot be read,
+  and then the next reading decides); runs already going finish, and a usage that
+  could not be read never pauses. An idle probe every `usage.probe_minutes`
+  keeps the reading fresh (#254, closes #247)
+- GitHub API budget: watched every `github_api.check_minutes`; polling slows
+  by `github_api.slow_factor` while the `core` or `graphql` bucket is below
+  `github_api.low_at` (not `search`, which resets every minute), with one
+  chat line. When a bucket is used up, calls known to spend it
+  (`gh api`, `gh search`) fail at once as rate limited until its reset, and
+  the poller resumes after it; other `gh` commands are not held back (#256,
+  closes #237)
+- Status page: a Machines strip and who-has-what for every machine listed in
+  `fleet.peers` (each machine's `web.allowed_hosts` must hold the name the
+  others use for it), plus this machine's usage and API budget (#258,
+  closes #249)
+- `ctrlrelay node check [--no-agent]`: node id, GitHub login, agent login
+  and peers, exit 1 on any failure; the poller warns at startup and while
+  running if another process uses this machine's `node_id`; new guide
+  `docs/adding-a-machine.md` (#261, closes #250)
+- `agent.sandbox: bwrap` is now a read-only copy of the machine: by default
+  only the run's worktree, its git dirs, a private `/tmp`, the entries of
+  `~/.claude` and an agent-only cache (`agent.sandbox_cache_dir`) are
+  writable; the
+  agent CLI's settings, hooks, plugins, skills and project memory, and the
+  repository's git config and hooks, stay read-only; more credentials and
+  the session's sockets are hidden; `~/.claude.json` is a private copy per
+  run. New `agent.sandbox_writable_paths` and `agent.sandbox_readonly_paths`.
+  Still off by default. The configuration docs list what it costs a run
+  (no git config changes, no commit signing, no submodule updates) and how
+  to set it up (#262, closes #236)
+- Status page: PR and issue numbers in Needs you questions are links (#242,
+  closes #241)
+
+### Changed
+
+- The agent runs with `--output-format stream-json` (the only output that
+  carries the usage reading); `agent.output_format` is read and ignored
+  (#254)
+- A repository whose history was replaced upstream is re-cloned, unless a
+  worktree still uses the clone (finish or clean up the run first); an issue
+  that failed before the agent started is retried on the next polls, up to
+  three tries, then left as seen like any other failed run, with a chat
+  line saying so (#244, closes #234)
+
+### Fixed
+
+- A dev run whose PR went BEHIND mid-run no longer dies fetching its own
+  checked-out branch, and a late failure names the PR it opened (#255,
+  closes #253)
+
+### Known limits
+
+- With several machines, chat and status-page names are only as unique as
+  each machine's `node_id`; the duplicate-name warning does not catch every
+  case
+- The relay's own git calls in a worktree after the agent exits still read
+  that repository's config; only the push ignores it (#263)
+
+## [0.15.0] - 2026-10-31
+
+The dev and task agents no longer inherit the usual GitHub credentials;
+ctrlrelay does the pushing, PR opening and commenting itself
+after the agent exits. One new
+database table is added automatically and the new config values have
+defaults, so **no config edit is required** to upgrade.
+
+### Changed
+
+- Dev and task agents run with inherited `GH_*` and `GITHUB_*` variables
+  and gh's login removed from their environment, git credential helpers and
+  git's SSH disabled, and the D-Bus and runtime-dir variables pointed away
+  from the desktop keyring. After the agent exits the
+  relay pushes the run branch from a relay-private git dir to an explicit
+  GitHub URL, opens the PR from the DONE checkpoint (or reuses an open PR on the run
+  branch), pushes fix rounds,
+  fetches failed CI logs and posts task reports. It refuses to push the
+  default branch and only overwrites a remote branch whose head it recorded
+  pushing. secops keeps GitHub access (#235, closes #219)
+- Status page: the phase bar shows the furthest phase seen in the recent
+  transcript and pipeline events, CI waits are
+  shown as waiting rather than reading, and the PR is linked (#239, closes
+  #238)
+
+### Added
+
+- Optional `agent.sandbox: bwrap` with `agent.sandbox_hide_paths` to run the
+  dev and task agents under bubblewrap with credential paths hidden. Off by
+  default (#235)
+- A `relay_pushes` table recording the heads ctrlrelay pushed (#235)
+- Status page: a live counter and dot, server health, GitHub links, and the
+  list of skipped issues (#233, closes #232)
+
+### Known limits
+
+- The agent still runs as the same OS user. Without the bwrap sandbox it
+  can read credential files on disk; with it, only the paths in
+  `agent.sandbox_hide_paths` are hidden. It can still run ssh directly, reach
+  the Linux keyring by resetting the D-Bus address, or read a token kept
+  under some other variable name, and the macOS keychain is not covered. Running the agent as a separate user
+  is tracked in #236
+
 ## [0.14.0] - 2026-10-31
 
 A read-only status page. `state.db` switches to WAL mode and gains an
@@ -1796,7 +1957,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.14.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.15.0...v0.16.0
+[0.15.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.4...v0.13.0
 [0.12.4]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.2...v0.12.4

{ctrlrelay-0.14.0 → ctrlrelay-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.14.0
+Version: 0.16.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.16.0/docs/adding-a-machine.md

@@ -0,0 +1,120 @@
+---
+title: Adding a machine
+layout: default
+nav_order: 11
+description: "Run ctrlrelay on a second machine, on the same GitHub account and repositories, without the two taking the same work."
+permalink: /adding-a-machine/
+---
+
+# Adding a machine
+
+Several machines can run ctrlrelay on the same GitHub account and the same
+repositories. Each one takes issues the others have not claimed, each
+scheduled sweep runs once across them, and any machine's status page shows
+all of them. This page sets up a second machine, `node-b`, next to a running
+`node-a`.
+
+Read [Operations: several machines on one account]({{ '/operations/' | relative_url }}#several-machines-on-one-account)
+for how the claims work.
+
+## 1. Install
+
+Install ctrlrelay the same way as on the first machine
+([Getting started]({{ '/getting-started/' | relative_url }})), the **same
+version** on every machine. A machine on a version from before the
+multi-machine work reads every failure comment as freeing every claim and
+posts claims with no machine name.
+
+## 2. Its own GitHub login
+
+Log `gh` in on this machine with its own token:
+
+```bash
+gh auth login
+```
+
+Use the same GitHub **account** as the other machines (claims only count when
+they come from the account the relay runs as), but a **token of its own**.
+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.
+
+## 4. A config with its own `node_id`
+
+Copy `orchestrator.yaml` from the first machine and change:
+
+```yaml
+node_id: "node-b"          # a name no other machine on this account uses
+```
+
+The `node_id` is on every claim, every chat message and the status page, so
+two machines with the same one look like one. If you leave it out, the
+hostname is used, which is fine when hostnames differ. ctrlrelay refuses to
+start with a placeholder such as `my-laptop`, `localhost` or `unknown`.
+
+Keep `repos`, `schedules` and `timezone` the same on every machine: the
+scheduled sweep is split by its scheduled time, so machines must agree on the
+schedule.
+
+## 5. Peers, for the status page
+
+To see every machine on any machine's page, list the others' status pages:
+
+```yaml
+# on node-b
+web:
+  host: "192.168.1.21"           # an address node-a can reach
+  allowed_hosts: ["node-b"]      # the name node-a uses for this machine
+fleet:
+  peers: ["http://node-a:8787"]
+  account_label: "max-2"         # optional: which subscription, never an email
+```
+
+and the mirror image on `node-a`. A peer refuses a name it does not know
+(HTTP 421, shown as "bad host header"): each machine's `web.allowed_hosts`
+must hold the name the others use for it.
+
+## 6. Chat
+
+- **Mattermost:** machines can share one bot and channel. Set
+  `transport.mattermost.shared: true` on every machine. Answer a question by
+  replying to it; a message that is not a reply must start with the machine's
+  name, `node-b: ...`.
+- **Telegram:** each machine needs **its own bot** (create one with
+  @BotFather). Telegram lets one process read a bot at a time.
+
+See [Operations: chat with several machines]({{ '/operations/' | relative_url }}#chat-with-several-machines).
+
+## 7. Check it
+
+```bash
+ctrlrelay node check
+```
+
+```
+✓ node_id: node-b (named on claims, chat and the page)
+✓ GitHub login: <the account>
+✓ agent login: works; 12% of the 5-hour window
+✓ 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
+machines share a `node_id` (or the URL points back here).
+
+## 8. Start it
+
+Start the bridge, the poller and the status page as on the first machine
+([Operations]({{ '/operations/' | relative_url }})). At startup, and while it
+runs, the poller warns, in its log and in chat, if another process uses its
+name: at startup, a peer whose status page answers with its name; while it
+runs, a claim under its name that another process is refreshing, on an issue
+it looks at. Neither is certain to catch every case, so give each machine
+its own `node_id` rather than relying on the warning.
+
+Then open either machine's status page: the **Machines** strip shows both.

{ctrlrelay-0.14.0 → ctrlrelay-0.16.0}/docs/architecture.md

@@ -70,6 +70,14 @@ is the only place ctrlrelay calls out to Claude Code.
 - **Environment additions:** `CTRLRELAY_SESSION_ID` and `CTRLRELAY_STATE_FILE`
   are the only contract between dispatcher and child. Anything else the agent
   needs (issue body, PR rules, etc.) goes into the prompt.
+- **Credentials (#219):** every spawn says whether it gets GitHub access
+  (`spawn_session(..., github_access=...)`, no default). dev and task spawn
+  without it: GitHub tokens, `gh`'s login, git credential helpers, SSH and
+  the desktop keyring are cut off (`core/agent_env.py`), and ctrlrelay
+  pushes the branch, opens the PR or posts the report itself afterwards
+  (`core/publish.py`, `WorktreeManager.push_run_branch`). secops still
+  spawns with access. See
+  [What the agent can reach](configuration.md#what-the-agent-can-reach-219).
 - **Result:** `SessionResult(session_id, exit_code, state, stdout, stderr,
   agent_session_id)`. `session_id` is our composite orchestrator id;
   `agent_session_id` is Claude's own UUID, parsed from the JSON stdout and