ctrlrelay 0.15.0__tar.gz → 0.16.1__tar.gz

{ctrlrelay-0.15.0 → ctrlrelay-0.16.1}/CHANGELOG.md

@@ -7,6 +7,143 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.1] - 2026-11-01
+
+Fixes the chat bridge, which did not start on 0.16.0. **No config edit is
+required.** If you upgraded to 0.16.0, upgrade to this.
+
+### Fixed
+
+- `ctrlrelay bridge start` (what the bridge service runs) exited at startup
+  on 0.16.0 with `BridgeServer.__init__() missing 1 required keyword-only
+  argument: 'node'`, for Telegram and Mattermost alike, so chat questions
+  and answers stopped. It now passes the machine's name and the shared
+  setting, like `python -m ctrlrelay.bridge` (#265)
+
+### Changed
+
+- The bridge's systemd unit is described as "ctrlrelay chat bridge
+  (Telegram or Mattermost)", and the docs call it the chat bridge. An
+  installed unit keeps its old description until it is re-rendered (#266)
+
+## [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;
@@ -1839,7 +1976,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.15.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.1...HEAD
+[0.16.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.16.0...v0.16.1
+[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

{ctrlrelay-0.15.0 → ctrlrelay-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.15.0
+Version: 0.16.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/
@@ -128,11 +128,11 @@ are on the roadmap (see [Roadmap](#roadmap)).
       new issue  │       │  blocked session
                  │       │
       ┌──────────▼──┐  ┌─▼───────────────────┐
-      │ dev pipeline│  │ Telegram bridge     │
-      │ in worktree │  │ (socket ↔ bot API)  │
+      │ dev pipeline│  │ chat bridge         │
+      │ in worktree │  │ (socket ↔ chat API) │
       │ agent CLI   │  └──────────┬──────────┘
       └──────┬──────┘             │
-             │ PR opened          │ DM you
+             │ PR opened          │ asks you
              ▼                    ▼
       ┌────────────┐         ┌─────────┐
       │ PR watcher │         │   You   │
@@ -207,7 +207,7 @@ Run as a supervised daemon (launchd on macOS / systemd on Linux) — see
 
 - [Getting started][docs-start]
 - [Configuration][docs-config]
-- [Telegram bridge][docs-bridge]
+- [Chat bridge (Telegram or Mattermost)][docs-bridge]
 - [Feedback loop][docs-feedback]
 - [CLI reference][docs-cli]
 - [Operations (launchd / systemd / scheduled jobs)][ops-docs]

{ctrlrelay-0.15.0 → ctrlrelay-0.16.1}/README.md

@@ -87,11 +87,11 @@ are on the roadmap (see [Roadmap](#roadmap)).
       new issue  │       │  blocked session
                  │       │
       ┌──────────▼──┐  ┌─▼───────────────────┐
-      │ dev pipeline│  │ Telegram bridge     │
-      │ in worktree │  │ (socket ↔ bot API)  │
+      │ dev pipeline│  │ chat bridge         │
+      │ in worktree │  │ (socket ↔ chat API) │
       │ agent CLI   │  └──────────┬──────────┘
       └──────┬──────┘             │
-             │ PR opened          │ DM you
+             │ PR opened          │ asks you
              ▼                    ▼
       ┌────────────┐         ┌─────────┐
       │ PR watcher │         │   You   │
@@ -166,7 +166,7 @@ Run as a supervised daemon (launchd on macOS / systemd on Linux) — see
 
 - [Getting started][docs-start]
 - [Configuration][docs-config]
-- [Telegram bridge][docs-bridge]
+- [Chat bridge (Telegram or Mattermost)][docs-bridge]
 - [Feedback loop][docs-feedback]
 - [CLI reference][docs-cli]
 - [Operations (launchd / systemd / scheduled jobs)][ops-docs]

{ctrlrelay-0.15.0 → ctrlrelay-0.16.1}/SECURITY.md

@@ -25,7 +25,7 @@ mitigation within **14 days** for high-severity issues.
 In-scope:
 
 - The `ctrlrelay` CLI and its pipelines (`dev`, `secops`, scheduled jobs).
-- The Telegram bridge and socket transport.
+- The chat bridge (Telegram or Mattermost) and socket transport.
 - Anything in `src/` and `config/`.
 
 Out-of-scope:

ctrlrelay-0.16.1/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.15.0 → ctrlrelay-0.16.1}/docs/cli.md

@@ -27,7 +27,7 @@ ctrlrelay [--version] <command> ...
 | `ctrlrelay status` | Show active locks and the 5 most-recent sessions. |
 | `ctrlrelay config ...` | Configuration helpers. |
 | `ctrlrelay skills ...` | Skill discovery / audit. |
-| `ctrlrelay bridge ...` | Manage the Telegram bridge daemon. |
+| `ctrlrelay bridge ...` | Manage the chat bridge daemon (Telegram or Mattermost). |
 | `ctrlrelay run ...` | Run a pipeline interactively. |
 | `ctrlrelay ci ...` | CI helpers used by the dev pipeline prompt. |
 | `ctrlrelay poller ...` | Manage the issue-poller daemon. |
@@ -128,7 +128,7 @@ Lists discovered skills as a table (name, path).
 
 ## `ctrlrelay bridge`
 
-See [Telegram bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.
+See [Chat bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.
 
 ### `bridge start`
 

{ctrlrelay-0.15.0 → ctrlrelay-0.16.1}/docs/configuration.md

@@ -19,7 +19,7 @@ pydantic schema in
 
 ```yaml
 version: "1"
-node_id: "my-laptop"
+node_id: "node-a"
 timezone: "America/New_York"
 
 paths:        { ... }
@@ -33,13 +33,14 @@ repos:        [ ... ]
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `version` | string | no | `"1"` | Config schema version. Currently always `"1"`. |
-| `node_id` | string | no | `socket.gethostname()` | Free-form identifier for this machine. Surfaces in dashboard heartbeats and session logs. Defaults to the OS hostname when omitted, null, or blank — set explicitly only if the hostname is meaningless (CI runners, ephemeral containers). |
+| `node_id` | string | no | `socket.gethostname()` | Free-form identifier for this machine. Surfaces in dashboard heartbeats, session logs, and the claim comment on every issue it takes, so machines sharing one account must each have a different one. `unknown` is reserved (it names claims from older versions). Defaults to the OS hostname when omitted, null, or blank — set explicitly only if the hostname is meaningless (CI runners, ephemeral containers). |
 | `timezone` | string | no | `"UTC"` | IANA timezone (e.g. `America/Santiago`). Used for scheduling. |
 | `paths` | object | **yes** | — | See [paths](#paths). |
 | `claude` | object | no | (defaults) | See [claude](#claude). |
 | `transport` | object | **yes** | — | See [transport](#transport). |
 | `dashboard` | object | no | (defaults) | See [dashboard](#dashboard). |
 | `web` | object | no | (defaults) | The read-only status page. See [web](#web). |
+| `claims` | object | no | (defaults) | Claim timings for several machines on one account. See [claims](#claims). |
 | `repos` | list | no | `[]` | See [repos](#repos). |
 | `schedules` | object | no | (defaults) | See [schedules](#schedules). |
 | `personalization` | object | no | unset | Cross-machine sync of Claude state. See [personalization](#personalization) and [Personalization sync]({{ '/personalization/' | relative_url }}). |
@@ -84,7 +85,7 @@ claude:
 |---|---|---|---|
 | `binary` | string | `"claude"` | Path to the `claude` executable. The bare name `"claude"` is auto-resolved at startup using `shutil.which("claude")`, then `~/.local/bin/claude`, `/usr/local/bin/claude`, `/opt/homebrew/bin/claude`. Set an absolute path to skip lookup (useful under launchd/systemd where PATH is minimal). |
 | `default_timeout_seconds` | int | `1800` | Per-session timeout passed to `asyncio.wait_for`. Sessions that exceed this are killed and reported as failed. |
-| `output_format` | string | `"json"` | Forwarded as `--output-format` to `claude -p`. |
+| `output_format` | string | `"json"` | Not used. The relay always runs `claude -p --output-format stream-json --verbose`, because only that output carries the subscription usage it reads (see [usage](#usage)). Kept so existing configs still load. |
 
 ctrlrelay always invokes claude with `--dangerously-skip-permissions` so the
 agent does not pause on tool-permission prompts in headless runs. This is
@@ -146,20 +147,118 @@ push. The push itself runs from a fresh relay-owned git dir under
 `~/.ctrlrelay/push/`, reads the clone's branch heads from its ref files, and
 never reads the clone's config, which every worktree shares.
 
-**What it does not guarantee.** The agent still runs as your user. A
-deliberately hostile agent can read `~/.config/gh/hosts.yml`, `~/.ssh` and
-anything else in your home directory and use them by hand; it can write
-anywhere your user can, including your dotfiles and ctrlrelay's install; and
-it can write to `~/.ctrlrelay/push/`, the bare clone's object store and any
-`objects/info/alternates` chain it adds there, racing a push. On macOS the
-login keychain is reachable whatever the environment says. Closing that needs
-a separate user or a read-only home (#236). The next setting hides the
-credential paths; it does not stop the writes.
+**What it does not guarantee without a sandbox.** The agent still runs as
+your user. With `sandbox: "none"` a deliberately hostile agent can read
+`~/.config/gh/hosts.yml`, `~/.ssh` and anything else in your home directory
+and use them by hand, and it can write anywhere your user can, including your
+dotfiles and ctrlrelay's install. On macOS the login keychain is reachable
+whatever the environment says. `sandbox: "bwrap"` closes this on Linux.
+
+**`sandbox: "bwrap"` (#236).** The dev and task agents run under bubblewrap
+in a read-only copy of the machine (the secops agent, which needs your GitHub
+login, does not):
+
+- everything is read-only, so the toolchain you installed (in `/usr`, in
+  `~/.local`, `~/.cargo`, ...) still runs;
+- writable: the run's worktree, its repository's git directories (so it can
+  commit), a private `/tmp`, the run's own empty `gh` and runtime
+  directories, `sandbox_writable_paths` and `sandbox_cache_dir`. The agent
+  CLI's state directory is opened entry by entry (`~/.claude/*`): what is in
+  it can be written, but nothing can be added to it, removed or replaced, so
+  a `settings.json` that is a link elsewhere cannot be swapped for a file of
+  the agent's. Log the agent CLI in on the machine before turning the
+  sandbox on, so its files exist. The CLI's main config, `~/.claude.json`,
+  which also holds your MCP server commands, is a private copy for each run
+  (the agent can read it, so keep secrets out of `mcpServers[].env`). The
+  sandbox refuses to start when `CLAUDE_CONFIG_DIR` is set, since it knows
+  only the default state paths;
+- `sandbox_hide_paths` are empty, also inside a writable path: your SSH keys,
+  `gh`'s login, the other credentials listed below, the sockets in your
+  session's runtime directory and Docker's (a read-only mount does not stop
+  a connection to a socket, so add any other socket here), and the agent
+  CLI's shell snapshots, session environment files, IDE locks and rewind
+  snapshots, which your own sessions run or write back (the sandboxed run
+  gets an empty, writable one of each);
+- read-only again, over those: `sandbox_readonly_paths` (the agent CLI's
+  settings, rules, hooks, plugins, skills, browser host and install, and each
+  project's memory under `~/.claude/projects/*/memory`, which your own
+  sessions load) and, in the repository, `config`, `config.worktree`,
+  `hooks`, `modules`, the other runs' worktree directories, a linked
+  worktree's `commondir` and `gitdir`, and the worktree's `.git` pointer,
+  which every later git command there reads. So the agent cannot change git
+  config (`git config`, `git remote add`, a branch with `--track`), and a
+  global `commit.gpgsign = true` makes its commits fail, since your GPG
+  agent is hidden. Submodules cannot be updated or committed in from a
+  sandboxed run. One that does not exist yet inside a
+  writable path is created first so the agent cannot create it (`{}` for a
+  JSON file; an empty file for a Markdown file or git's `config`,
+  `config.worktree`, `commondir` and `gitdir`; otherwise an empty directory); if it cannot be created, the run does
+  not start. Every directory between a writable path and one of these is
+  pinned too, so it cannot be renamed away and recreated.
+
+Package caches (`XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`,
+`npm_config_cache`, `GOMODCACHE`, `GRADLE_USER_HOME` and `CARGO_HOME`) point at
+`sandbox_cache_dir`: the agent's own, never yours, so a run cannot poison a
+cache you build from. It must not contain your home directory. The first run
+of each project downloads its packages again. `CARGO_HOME` and `GRADLE_USER_HOME` also
+move those tools' own config, so `~/.cargo/config.toml` and
+`~/.gradle/gradle.properties` do not apply there. A tool that writes
+elsewhere in your home fails there; point it at a directory of its own
+rather than opening one of yours, which your own builds would then run.
+
+What it still allows: the agent reads the agent CLI's login (it needs it to
+run) and anything readable that is not hidden. The login file is opened as a
+file, so a refresh that replaces it by renaming fails inside the sandbox; a
+long-lived token from `claude setup-token`, in the environment, avoids
+refreshes there. It writes objects and refs in its repository's git
+directory, which the relay's push already treats as untrusted, and session
+transcripts under `~/.claude/projects`, which a later `--resume` of that
+session reads. A read-only path that is a link, in a directory the agent
+can write, could be swapped for a file of the agent's, so a run with one
+does not start; the error names it.
+`~/.claude/*` opens every entry not listed as read-only or hidden, so an
+entry a later agent CLI version adds that your own sessions run needs adding
+to one of those lists. The run's checkpoint file must be inside its worktree (it
+always is for dev and task runs). It does not account for your own setup
+giving another way in: a hidden file with a second hard link elsewhere, your
+home mounted at a second path, or an `include.path` in a clone's git config
+pointing at a file the agent can write. ctrlrelay's own clones have none of
+these.
+
+**Setting it up.** Linux only. Install bubblewrap (`sudo apt install
+bubblewrap`), then check it runs as your user:
+
+```bash
+bwrap --ro-bind / / --dev /dev --proc /proc --unshare-pid true && echo works
+```
+
+If that prints `works`, set `agent.sandbox: "bwrap"` and restart the daemons.
+ctrlrelay refuses to start if it is set and `bwrap` is missing. If it fails
+with `setting up uid map: Permission denied` (Ubuntu 24.04 and later restrict
+unprivileged user namespaces through AppArmor), allow it for `bwrap` only:
+
+```bash
+sudo tee /etc/apparmor.d/bwrap >/dev/null <<'PROFILE'
+abi <abi/4.0>,
+include <tunables/global>
+
+profile bwrap /usr/bin/bwrap flags=(unconfined) {
+  userns,
+  include if exists <local/bwrap>
+}
+PROFILE
+sudo apparmor_parser -r /etc/apparmor.d/bwrap
+```
+
+then run the check again. On a single-user laptop this is the whole setup.
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `sandbox` | `"none"` or `"bwrap"` | `"none"` | `"bwrap"` runs the dev and task agents under bubblewrap with `sandbox_hide_paths` replaced by empty mounts. Linux only; needs `bwrap` installed and unprivileged user namespaces allowed (on Ubuntu 24.04+ an AppArmor profile for `bwrap`). ctrlrelay refuses to start if it is set and `bwrap` is missing. |
-| `sandbox_hide_paths` | list of strings | `~/.ssh`, `~/.config/gh`, `~/.git-credentials`, `~/.config/git/credentials`, `~/.netrc`, `~/.local/share/keyrings`, `$XDG_RUNTIME_DIR/bus` | Paths hidden under `sandbox: bwrap`. A directory becomes an empty tmpfs, a file or socket becomes `/dev/null`, a missing path is skipped. |
+| `sandbox` | `"none"` or `"bwrap"` | `"none"` | `"bwrap"` runs the dev and task agents in the read-only sandbox above. |
+| `sandbox_hide_paths` | list of strings | `~/.ssh`, `~/.config/gh`, `~/.git-credentials`, `~/.config/git/credentials`, `~/.netrc`, `~/.local/share/keyrings`, `$XDG_RUNTIME_DIR/bus`, `~/.gnupg`, `~/.aws`, `~/.azure`, `~/.config/gcloud`, `~/.kube`, `~/.docker/config.json`, `~/.npmrc`, `~/.pypirc`, `~/.cargo/credentials`, `~/.cargo/credentials.toml`, `~/.config/doctl`, `~/.password-store`, `~/.1password`, `~/.docker/run`, `~/.docker/desktop`, `~/.config/ctrlrelay`, `$XDG_RUNTIME_DIR`, `/run/user/<uid>`, `/run/docker.sock`, `/var/run/docker.sock`, `~/.claude/shell-snapshots`, `~/.claude/session-env`, `~/.claude/ide`, `~/.claude/file-history` | Made empty under `sandbox: bwrap`. A directory becomes an empty tmpfs, a file or socket becomes `/dev/null`, a missing path is skipped. |
+| `sandbox_writable_paths` | list of strings | `~/.claude/*` | Writable under `sandbox: bwrap`, besides the run's own paths. A last part of `*` opens each entry in the directory now (not links), not the directory itself. |
+| `sandbox_readonly_paths` | list of strings | `~/.claude/settings.json`, `settings.local.json`, `CLAUDE.md`, `agents`, `commands`, `skills`, `hooks`, `plugins`, `output-styles`, `scripts`, `rules`, `chrome`, `local`, `projects/*/memory` (all under `~/.claude`) | Read-only again inside a writable path. One `*` part matches the directories there at the start of each run; a missing path under a writable one is created first (an empty `memory` directory in each project, for one). |
+| `sandbox_cache_dir` | string | `~/.ctrlrelay/agent-cache` | The agent's own package cache under `sandbox: bwrap`. |
 
 ## transport
 
@@ -203,7 +302,7 @@ transport:
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `type` | enum | no | `"file_mock"` | One of `"telegram"`, `"mattermost"`, `"file_mock"`. |
-| `telegram` | object | required when `type=telegram` | — | Telegram bridge settings — see below. |
+| `telegram` | object | required when `type=telegram` | — | Telegram settings — see below. |
 | `mattermost` | object | required when `type=mattermost` | — | Mattermost bridge settings — see below. |
 | `file_mock` | object | required when `type=file_mock` | — | Local-file fake transport, used for tests/dev. |
 
@@ -222,7 +321,7 @@ reach anybody.
 | `question_ttl_seconds` | int | `172800` (48h) | How long an **unanswered** question stays routable before it is retired. Minimum `3600`. Without a ceiling those rows never die — a question whose PR was merged by hand weeks ago stays a live target for an orphan reply. The hourly `question_expiry_sweeper` also retires a question early once every issue/PR it cites is closed or merged. |
 | `question_retention_days` | int | `90` | How long a **finished** question (expired, or answered and resumed) is kept before the hourly sweeper deletes it. Minimum `1`. Open questions are never deleted. The kept history is what lets a re-asked question be marked as a repeat. |
 
-See [Telegram bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.
+See [Chat bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.
 
 ### transport.mattermost
 
@@ -235,6 +334,7 @@ See [Telegram bridge]({{ '/bridge/' | relative_url }}) for the full setup walkth
 | `ask_timeout_seconds` | int | `900` | Same meaning as the Telegram key above: it bounds only the in-session wait, and a later reply still resolves through `pending_resumes`. |
 | `question_ttl_seconds` | int | `172800` (48h) | Same meaning as the Telegram key above. |
 | `question_retention_days` | int | `90` | Same meaning as the Telegram key above. |
+| `shared` | bool | `false` | Other machines use this same bot and channel (see [Operations: chat with several machines]({{ '/operations/' | relative_url }}#chat-with-several-machines)). Each machine then acts only on replies to its own questions and on messages that name it (`node-a: ...`); a message that names no machine is left alone. |
 
 **The bot must be a member of that channel.** A bot without `post:all` cannot
 post where it is not a member — and, the part that is easy to miss, it does not
@@ -308,6 +408,94 @@ web:
 The page has no login and shows repository names, issue titles and the
 questions agents asked. **Never expose it to the internet.**
 
+## claims
+
+How machines that share one GitHub account keep off each other's issues.
+See [Operations: several machines on one account]({{ '/operations/' | relative_url }}#several-machines-on-one-account).
+
+```yaml
+claims:
+  race_wait_seconds: 5
+  refresh_seconds: 300
+  stale_after_seconds: 1800
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `race_wait_seconds` | number (0-60) | `5` | Wait between posting a claim and reading the comments back to see who won. |
+| `refresh_seconds` | number (>= 30) | `300` | How often a working machine edits its claim to show it is alive. |
+| `stale_after_seconds` | number (>= 300) | `1800` | A working claim not refreshed for this long is treated as a stopped machine's, and another machine may take the issue. Must be at least three times `refresh_seconds`. |
+
+## usage
+
+Pausing before the agent subscription's limit. Each run reports the
+subscription's 5-hour and 7-day usage; the status page shows it, and a
+machine stops taking new issues near the limit.
+
+```yaml
+usage:
+  pause_at: 0.9
+  probe_minutes: 30
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `pause_at` | number (above 0, up to 1) | `0.9` | Take no new issues while the 5-hour or 7-day window is at or above this share, or while the status is anything but `allowed`. Runs already going finish. New issues are taken again after the window's reset time; when the reset time cannot be read, after an hour, when the next reading decides again. |
+| `probe_minutes` | int (>= 0) | `30` | When the last reading, or the last attempt that found none, is older than this, the daemon makes one tiny agent call (no tools, no MCP servers, no user or project settings and so no hooks, one turn, in an empty directory) to read the usage again, so an idle machine's numbers do not go stale. `0` turns it off. Each probe is one short call on the subscription. |
+
+The usage comes from a field of the agent CLI's output that is not
+documented. When it is missing or cannot be read, the page says
+**unknown**, never 0%, and the machine does not pause on it. A run whose output carries no readable usage records unknown too, so an older number stops pausing the machine.
+
+## github_api
+
+Watching the account's GitHub API budget. Every machine and session on the
+account spends the same budget per bucket (`core`, `search`,
+`graphql`).
+
+```yaml
+github_api:
+  low_at: 0.2
+  check_minutes: 5
+  slow_factor: 3
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `low_at` | number (between 0 and 1) | `0.2` | A bucket below this share of its limit is low: the poll interval is multiplied by `slow_factor`, the status page skips its waiting-line refresh, and one chat line goes out. |
+| `check_minutes` | int dividing 60 (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60) | `5` | How often the daemon reads `/rate_limit`. That call does not count against the budget. |
+| `slow_factor` | number (1-20) | `3` | The poll interval multiplier while any bucket is low. |
+
+When a bucket is used up, the daemon makes no call it knows spends that
+bucket until its reset (`gh api` calls and `gh search`; other `gh` commands do
+not say which bucket they spend and are not held back): such a call fails at
+once as rate limited, one chat line says when it
+resets, and the poller picks up again on its own afterwards. A budget it
+could not read is shown as unknown and slows nothing.
+
+## fleet
+
+The other machines this one's status page shows (see
+[Operations: several machines on one account]({{ '/operations/' | relative_url }}#several-machines-on-one-account)).
+
+```yaml
+fleet:
+  peers:
+    - "http://node-b:8787"
+  check_seconds: 60
+  timeout_seconds: 5
+  silent_after_seconds: 300
+  account_label: "max-2"
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `peers` | list of URLs | `[]` | Each peer's status page. The web server reads each one's `/api/status` itself, so the browser needs no access to them. **Each peer must accept the name this machine uses for it**: add that name to the peer's `web.allowed_hosts`, or it answers HTTP 421 and shows here as "not reachable from here: bad host header". Its `web.host` must also listen on an address this machine can reach. |
+| `check_seconds` | int (>= 10) | `60` | How often each peer is read. |
+| `timeout_seconds` | number (0-60] | `5` | The longest wait for any one network step of a read; a whole read gets twice this before the peer is reported as `timeout`. |
+| `silent_after_seconds` | int (>= 60) | `300` | A machine whose daemon heartbeat is older than this is shown as **silent**: its web server answers, but the daemon's heartbeat is missing or old, so its poller cannot be confirmed to be working. |
+| `account_label` | string | unset | A name for this machine's agent subscription, shown on its card, such as `max-2`. Never an email address (refused). |
+
 ## repos
 
 A list of repositories the orchestrator manages.
@@ -606,7 +794,7 @@ matches Claude Code's own path encoding rule (`/Users/foo/Projects/bar`
 
 ```yaml
 version: "1"
-node_id: "studio-mac"
+node_id: "node-b"
 timezone: "America/Santiago"
 
 paths: