ctrlrelay 0.19.0__tar.gz → 0.20.0__tar.gz

{ctrlrelay-0.19.0 → ctrlrelay-0.20.0}/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-11-04
+
+### Added
+
+- `repos[].steps.plan` (`off`, `on`, `required`; unset is `off`) runs a
+  planning session before the dev pipeline's code session. It changes no
+  files and writes a plan with numbered acceptance criteria, saved under
+  `<paths.contexts>/<owner>-<repo>/plans/issue-<n>.md` (outside the worktree),
+  posted on the issue as the criteria list, and added to the code session's
+  prompt. A vague issue gets one question instead of a pull request. A plan
+  without criteria is a failed plan: `on` reports it and codes without one,
+  `required` fails the run (#220).
+- On the status page, a peer machine's name links to that machine's own
+  page: in the machine strip, in "Who has what" and on a "Needs you" card.
+  The address is the `fleet.peers` entry from this machine's config, cut to
+  `<scheme>://<host>[:port]/`; nothing a peer answers changes it, and an
+  entry with userinfo or a non-http scheme gives plain text (#319).
+
+### Fixed
+
+- A run whose relay process died mid-run (the machine ran out of memory, or
+  the service was stopped) no longer stays `running` for ever. Sessions now
+  record the process running them (`owner_pid`, `owner_run`) and their claim
+  id. When the poller starts, it finds `running` sessions whose process is
+  gone, and in whose worktree no process is still working, and marks them
+  failed, dropping any repo lock they held. A dev or task issue goes back to
+  the next poll unless an open pull request was found for its branch. Where
+  the run had claimed the issue, the relay posts a comment that names the
+  worktree and releases the claim. The relay deletes nothing in the
+  worktree. It detaches the worktree's HEAD, when that can be done safely,
+  so the next run can check the issue's branch out. Rows written by an older
+  version name no process and are left alone (#312).
+- A dev run whose agent session hits its time limit no longer throws away
+  the agent's work. Before the worktree is removed, the files on disk are
+  committed on top of the commit it sits on, and that commit, or the
+  unpushed commits alone, are pushed to a new `wip/issue-<n>-<run id>`
+  branch. The run's own branch is not pushed, no pull request is opened, and
+  the local run branch is kept, since it can hold commits the worktree's
+  HEAD does not reach. The failure comment on the issue names the wip branch
+  and, when it is known, how long the run took. If the work cannot be saved,
+  the worktree is kept on disk and the comment names it. A run with nothing
+  new loses only its worktree. Files the worktree's `.gitignore` ignores are
+  not saved; files that cannot be read are not saved either, and then the
+  worktree is kept and the comment says so. The files are read by a git with
+  a private git dir, index, config and attributes override, so filters,
+  hooks and attributes named by the agent do not take effect (#311).
+
+## [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
@@ -2257,7 +2313,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.19.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.19.1...v0.20.0
+[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

ctrlrelay-0.20.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: ctrlrelay
+Version: 0.20.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/
+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.20.0/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.19.0 → ctrlrelay-0.20.0}/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.19.0 → ctrlrelay-0.20.0}/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

ctrlrelay-0.20.0/docs/architecture.md

@@ -0,0 +1,231 @@
+---
+title: Architecture
+layout: default
+nav_order: 9
+description: "Layer diagram, dispatcher / agent interaction, state-DB shape, and worktree lifecycle for contributors."
+permalink: /architecture/
+---
+
+# Architecture
+
+This page is for people working _on_ ctrlrelay, not just _with_ it. For an
+operator-level view of the BLOCKED protocol see
+[Feedback loop]({{ '/feedback-loop/' | relative_url }}).
+
+## Layered overview
+
+```mermaid
+flowchart TD
+    CLI["CLI / daemons<br/>cli.py (Typer app)<br/>bridge/__main__.py (bridge daemon)"]
+    PIPE["Pipelines — pipelines/<br/>dev · secops · task · post_merge · base"]
+    BRIDGE["Bridge — bridge/<br/>server · protocol · factory · node_tag<br/>telegram_handler · mattermost_handler"]
+    CORE["Core — core/<br/>Dispatcher (claude / opencode) · WorktreeManager<br/>GitHub CLI wrapper · Checkpoint · StateDB (SQLite)<br/>Poller · PRWatcher · Config (pydantic)"]
+    TRANS["Transports — transports/<br/>SocketTransport (to the bridge)<br/>FileMockTransport (tests)"]
+    DASH["Dashboard (optional, push-only) — dashboard/<br/>DashboardClient"]
+    CHAT["Chat: Telegram or Mattermost"]
+    CLI --> PIPE
+    CLI --> BRIDGE
+    PIPE --> CORE
+    PIPE --> TRANS
+    PIPE --> DASH
+    TRANS -- "Unix socket" --> BRIDGE
+    BRIDGE --> CHAT
+```
+
+The CLI is a thin shell over async functions in `pipelines/` and `core/`. The
+bridge is a separate daemon that pipelines reach over a Unix socket — it is
+deliberately decoupled so it can be restarted without affecting in-flight
+pipeline work.
+
+## Dispatcher ↔ agent interaction
+
+[`src/ctrlrelay/core/dispatcher.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/dispatcher.py)
+is the only place ctrlrelay calls out to a coding agent. It has two adapters
+with the same async `spawn_session` shape, so pipelines stay agent-agnostic:
+`ClaudeDispatcher` (Claude Code) and `OpenCodeDispatcher` (OpenCode).
+`make_repo_agent_dispatcher` picks one per repo: `agent.type` is the default,
+`repos[].agent_type` overrides it for a single repo.
+
+- **Spawn shape:** Claude Code runs
+  `claude -p <prompt> --output-format stream-json --verbose --dangerously-skip-permissions [--resume <id>]`;
+  OpenCode runs `opencode run ... --format json --dangerously-skip-permissions [--session <id>]`.
+- **Working directory:** the session's worktree (so file edits land on the
+  right branch).
+- **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 the agent's own session id, parsed from its JSON
+  stdout and the value its resume flag actually expects. `state` is the parsed
+  `CheckpointState` if a state file was written, else `None`. The wrapper
+  exposes `.success`, `.blocked`, `.failed` properties for pattern-matching
+  pipelines.
+- **Resume:** `resume_session_id` translates to `--resume <id>` (Claude
+  Code) or `--session <id>` (OpenCode). Pipelines look up the agent's own id
+  (persisted as `sessions.agent_session_id` by the prior spawn) and pass it
+  through — newer `claude` CLI builds reject non-UUID values. If state_db
+  has no id (session predates capture or stdout wasn't JSON), the spawn falls back to a fresh session rather than
+  hard-failing.
+
+The dispatcher does NOT proxy or wrap the agent session — it shells out the
+same way you'd shell out to `gh` or `git`. This is deliberate.
+
+## State DB shape
+
+Schema in
+[`src/ctrlrelay/core/state.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/state.py).
+SQLite, single file at `paths.state_db`.
+
+| Table | Columns | Notes |
+|---|---|---|
+| `sessions` | `id`, `pipeline`, `repo`, `issue_number`, `worktree_path`, `status`, `blocked_question`, `started_at`, `ended_at`, `claude_exit_code`, `summary`, `agent_session_id`, `output_tail` | Indexed on `repo` and `status`. One row per pipeline run. `agent_session_id` stores the agent's own session id for resume; `claude_exit_code` holds the worker's exit code whichever backend ran; `output_tail` is a scrubbed, capped tail of its output (#204). |
+| `repo_locks` | `repo` (PK), `session_id`, `acquired_at` | Acquired with `acquire_lock`, released in the pipeline's `finally`. |
+| `github_cursor` | `repo`, `last_checked_at`, `last_seen_issue_update` | Bounds GitHub API calls in the poller. |
+| `pending_resumes` | `session_id` (PK), `pipeline`, `repo`, `question`, `created_at`, `answer`, `answered_at`, `resumed_at`, `expired_at`, `expired_reason`, `held_until`, `posted`, `last_answered_at` | One row per BLOCKED session awaiting an answer, whichever chat it was asked on. An answer arriving after the in-session wait lands here and the poller's sweeper drives the resume. |
+| `pr_watches` | `repo`, `pr_number` (PK pair), `session_id`, `issue_number`, `pr_url`, `started_at`, `cleanup_phase` | In-flight post-merge watchers, rehydrated on poller start. |
+| `automation_decisions` | `id`, `repo`, `operation`, `policy`, `item_id`, `decision`, `decided_by`, `decided_at`, `context` | Audit trail for `ask`-policy decisions. |
+| `dispatch_health` | single row: `consecutive_failures`, `alerted_at`, `alert_claim_token`, `alert_delivered_at`, `last_failure_at`, `last_success_at` | Whether the relay can still run a worker at all (#204). |
+| `relay_pushes` | `id`, `repo`, `branch`, `session_id`, `sha`, `pushed_at` | Every branch head ctrlrelay pushed for an agent (#219); the push lease is taken from here. |
+| `events` | `id`, `ts`, `kind`, `repo`, `issue_number`, `session_id`, `detail` | Feed for the status page, written best-effort. |
+| `telegram_pending` | `request_id`, `session_id`, `question`, `asked_at`, `answered_at`, `answer` | Legacy: still created by the schema, but no code reads or writes it. Outstanding questions live in `pending_resumes`. |
+
+Methods on `StateDB`: `acquire_lock`, `release_lock`, `get_lock_holder`,
+`list_locks`, `set_agent_session_id`, `get_agent_session_id`, plus raw
+`execute` / `commit`. The pipeline code uses raw SQL for the `sessions`
+table on purpose — kept thin and grep-able.
+
+## Worktree lifecycle
+
+`WorktreeManager` (in
+[`src/ctrlrelay/core/worktree.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/worktree.py))
+is a thin wrapper over `git worktree`. Conventions:
+
+- **Bare repo path:** `<paths.bare_repos>/<owner>-<repo>.git`. Cloned on first
+  use, fetched on each subsequent use.
+- **Worktree path:** `<paths.worktrees>/<owner>-<repo>-<session_id>`.
+- **Branch:** for the dev pipeline, derived from `dev_branch_template` with
+  `{n}` → issue number. Default `fix/issue-{n}`.
+
+Lifecycle in `run_dev_issue`:
+
+```
+ensure_bare_repo(repo)
+branch_preexisted = await branch_exists_locally(repo, branch)
+worktree_path = create_worktree_with_new_branch(repo, session_id, branch)
+... agent session runs ...
+on DONE:    remove_worktree (keep branch — open PR refs it)
+on BLOCKED: keep both (operator may resume)
+on FAILED:  remove_worktree
+            if not branch_preexisted and not on remote: delete_branch
+```
+
+The "preexisted" guard prevents a retry from clobbering a branch that already
+holds an open PR from a previous successful session.
+
+## PR verifier and post-merge
+
+After a `DONE`-with-`pr_url` checkpoint, the dev pipeline runs
+[`PRVerifier`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/pr_verifier.py)
+to confirm the PR is mergeable and CI is green. If not, it builds a fix prompt
+(merge conflicts → "rebase and resolve", failing checks → "investigate and
+fix"), resumes the same agent session with that prompt, and re-verifies. Up
+to `DEFAULT_MAX_FIX_ATTEMPTS` (3) attempts.
+
+`PRWatcher` (in
+[`src/ctrlrelay/core/pr_watcher.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/pr_watcher.py))
+polls a PR for merge status; the post-merge handler in
+[`src/ctrlrelay/pipelines/post_merge.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/pipelines/post_merge.py)
+closes the originating issue and notifies the operator once the PR lands.
+The poller starts one `pr_watch_task` per PR the dev pipeline hands off, and
+persists it in `pr_watches` so a poller restart resumes the watch.
+
+## Bridge architecture
+
+The bridge daemon (`ctrlrelay/bridge/server.py`) listens on a Unix socket
+(mode `0o600` — owner-only). It speaks newline-delimited JSON, defined in
+`bridge/protocol.py`:
+
+The bridge builds exactly one chat handler from `transport.type`
+(`bridge/factory.py`): `TelegramHandler` or `MattermostHandler`. The server
+knows only the handler interface, so the flow is the same for both:
+
+```mermaid
+sequenceDiagram
+    participant Cl as Client (pipeline)
+    participant S as Bridge server
+    participant H as Chat handler
+    participant Ch as Telegram or Mattermost
+    Cl->>S: ask(q)
+    S->>H: ask(q, options)
+    H->>Ch: post (sendMessage / POST /api/v4/posts)
+    Note over S,H: server records post id → session
+    Ch-->>H: reply (getUpdates long-poll / WebSocket posted event)
+    H-->>S: on_reply(text, reply_to_post_id)
+    S-->>Cl: answer(text)
+```
+
+The handler reports the post the reply points at — Telegram's
+`reply_to_message_id`, or Mattermost's thread `root_id`. Matching reply →
+pending question:
+
+1. The reply points at a live pending question — route to that question.
+   This is the only route that is right when several are outstanding.
+2. The reply points at a question that is no longer live (its ask timed
+   out, or the bridge restarted) — hand it to the orphan router, which
+   attaches the answer to that session's `pending_resumes` row.
+3. A fresh message with exactly one question outstanding — route there.
+4. A fresh message with several outstanding — refuse, and tell the operator
+   to reply to the question they mean. There is no FIFO fallback.
+
+When several machines share one Mattermost bot and channel
+(`transport.mattermost.shared: true`), each machine prefixes its posts with
+`[<node>]` and ignores replies to other machines' posts (`bridge/node_tag.py`).
+
+Multiple in-flight asks are supported. The bridge retains the original
+socket for each ask so the answer routes back to the correct caller.
+
+Bridge restart safety: pending in-memory state is lost on bridge restart.
+Pipelines waiting on `transport.ask` stop waiting and persist the session as
+`BLOCKED` with a `pending_resumes` row; a later answer still drives the
+resume through the sweeper. Restart the bridge **before** restarting the
+poller to minimise this window.
+
+## Why this shape
+
+A few decisions worth flagging:
+
+- **Local-first, file-based protocol.** Everything between ctrlrelay and the
+  agent is a file under the worktree. No long-lived shared memory, no socket
+  contract with the agent. Survives orchestrator restart trivially.
+- **Subprocess-not-library.** `claude` or `opencode` is invoked as a
+  subprocess. ctrlrelay has no Python coupling to either agent's internals — it exchanges a prompt
+  in and a JSON file out. Versioning is decoupled.
+- **Per-repo serial, parallel across repos.** Repo locks in SQLite enforce
+  this. A failed lock acquisition fails the session immediately rather than
+  queueing.
+- **No background event loop.** Each CLI command spins up its own
+  `asyncio.run(...)`. The poller and bridge each own one event loop while they
+  run. Simpler to reason about than a long-lived shared loop.
+- **Bridge as separate process.** Restartable independent of pipelines. The
+  cost is the small in-memory pending-asks state that does not survive a
+  bridge restart.
+
+## Where to read next
+
+- [`src/ctrlrelay/core/config.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/config.py)
+  — pydantic schema, the source of truth for the YAML.
+- [`src/ctrlrelay/pipelines/dev.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/pipelines/dev.py)
+  — full dev-pipeline orchestration including BLOCKED loop and PR-fix loop.
+- [`src/ctrlrelay/core/dispatcher.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/dispatcher.py)
+  — the only place we call `claude` or `opencode`.
+- [`tests/`](https://github.com/AInvirion/ctrlrelay/tree/main/tests) — covers
+  every public surface; treat tests as executable specifications.