ctrlrelay 0.27.0__tar.gz → 0.28.0__tar.gz

{ctrlrelay-0.27.0 → ctrlrelay-0.28.0}/CHANGELOG.md

@@ -7,6 +7,175 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-11-11
+
+### Added
+
+- `ctrlrelay agent check <agent_type>` proves one backend writes its
+  checkpoint, without starting a dev run (#381). It spawns a single session
+  in a throwaway git repository in a temporary directory, with GitHub
+  credentials stripped and a prompt whose whole content is the `DONE`
+  checkpoint snippet, then reports the exit code, the checkpoint and its
+  status, the native session id the adapter captured, the selected identity
+  and the elapsed time — one line each, because they fail separately. Exits
+  0 only on a `DONE` checkpoint from a session that exited on its own: a
+  CLI that exits zero having written nothing is the failure the command
+  exists to find, and one that writes `DONE` and then has to be stopped
+  would hang every dev run. The throwaway repository is a working
+  directory, not a sandbox. `--timeout` defaults to 300 seconds and must
+  be at least 1, `--json` prints the same report as one object including on
+  the failure paths — with the structured log moved to stderr so stdout is
+  exactly that object — and an unknown type exits non-zero naming every type
+  enrolled on the node. As an operator tool it may select any enrolled
+  backend and does not consult `agent.assignable_types`, which governs what
+  an assignment arriving from outside the machine may ask for.
+- `ctrlrelay agent check <agent_type> --resume` proves the other half of the
+  contract: that the backend comes back knowing what it was doing (#382). A
+  backend that cannot resume fails every run that has to ask a question, and
+  the only way to exercise it before this was a real dev run that blocked and
+  waited for a chat answer. Round 1 is told a freshly generated 8-character
+  token and must write `BLOCKED_NEEDS_INPUT`; round 2 spawns with
+  `resume_session_id` set to the native id round 1 reported — the same argv a
+  pipeline resume builds — and must write `DONE` whose summary is that token.
+  The token is not in the second prompt, so a round that answered from its
+  own prompt could not pass, and a decoy fresh session with a different token
+  runs between the rounds, so a manifest that resumes the most recent session
+  instead of the id it is given fails rather than passing by luck. Round 1 must report both the blocked checkpoint
+  and a native session id or the command stops and says which was missing,
+  rather than spending a second fresh session that could only report a pass
+  for a backend that never resumed. A backend reporting no `resume`
+  capability fails with `resume not configured for <type>` without spawning.
+  A native session id that changes between rounds is a warning, not a
+  failure. Each round gets its own report line, each failure its own, and
+  `--json` carries both rounds plus `resume: true`.
+- A plugin identity and capability contract for coding-agent CLIs (#379).
+  Claude and OpenCode now expose the same identity metadata, and local
+  `agent.plugins` manifests can enroll simple non-interactive CLIs with fixed
+  argv, prompt-over-argument or stdin, checkpoint handling, and optional
+  native-session mapping. `agent.assignable_types` defines the smaller set a
+  future control-plane assignment may select; assignments cannot supply a
+  binary or arbitrary arguments. The selected plugin, model, and canonical
+  invocation fingerprint are persisted before dispatch and pinned across CI
+  fixes, retries, and pending resumes. Generic executables must resolve to an
+  absolute path, native session IDs are validated before argv substitution,
+  and a pre-#379 native session with unknown identity is refused rather than
+  resumed through the current default backend.
+- Repo context is linked under each backend's own instruction filename, so
+  Codex and Copilot see `AGENTS.md` or `.github/copilot-instructions.md`
+  instead of only Claude's `CLAUDE.md` (#379). A name the repository already
+  has is left alone: the repo's own file wins under that name, and the relay
+  context goes only under names that are free.
+- Built-in identity pins use the stable launcher path, so Claude's normal
+  self-update does not invalidate a pending resume. Generic manifests still
+  pin their full invocation mapping (#379).
+- A checked GitHub Copilot CLI manifest in `docs/configuration.md` and the
+  example config, with resume through its `sessionId`. It passes
+  `--disable-builtin-mcps`, because Copilot's built-in GitHub MCP server
+  otherwise gives the agent GitHub access under Copilot's own login,
+  bypassing credential stripping (#379).
+
+- Copilot and Codex as built-in agent presets (#384, #385). Set
+  `repos[].agent_type: copilot` or `codex` (or `agent.type`) with no
+  `agent.plugins` entry. Their arguments are fixed in code, because some of them
+  are what make the backend safe unattended: Copilot's `--disable-builtin-mcps`
+  keeps its own GitHub login away from the agent. `agent.presets.<name>` may
+  change only `binary`, `model` and `default_timeout_seconds`. Both presets
+  run unconfined and refuse to start on a `sandbox: "bwrap"` node.
+- Generic plugins can have their token usage measured, so the token budget
+  applies to them (#387). A manifest's `usage` mapping says which JSON-lines
+  event carries usage and where each count is. The reading is taken when the
+  CLI exits, a resumed round is charged only the difference from the
+  session's last total, and anything unreadable is recorded as unknown, never
+  zero. Both presets carry mappings measured against real output.
+- Each agent backend receives only its own model-provider keys (#390). A
+  well-known provider variable such as `OPENAI_API_KEY` or
+  `ANTHROPIC_API_KEY` reaches an agent only if its backend allows it:
+  Claude gets `ANTHROPIC_*` and `CLAUDE_*`, the presets their own, and
+  `opencode` and plugins what `env_allow` lists (default none). The security
+  sweep keeps GitHub access but loses the relay's secrets and other backends'
+  keys.
+- One agent backends table in the docs, with resume, usage, stuck detection
+  and sandbox for each backend, and how to log the Copilot and Codex CLIs in
+  for relay use (#386).
+
+### Fixed
+
+- An agent can no longer outlive its session or stall the relay through
+  what it leaves behind (#394). Agents are spawned in their own session, so
+  each leads its own process group, and every exit path signals that group
+  rather than the direct child alone: after a normal exit and on a timeout
+  with SIGTERM, a 3-second grace, then SIGKILL; on cancellation, a stuck or
+  over-budget stop and a pipe error with an immediate SIGKILL, as the child
+  alone was before. A job the agent put in the background used
+  to keep running as the relay user after the run was reported done; and
+  because agents shared the relay's own process group, an agent that
+  signalled its group stopped the relay with it. The relay never signals a
+  group that is not provably the agent's own. The checkpoint read now opens
+  only a small regular file (`O_NOFOLLOW | O_NONBLOCK`, `fstat` on the same
+  descriptor, a 256 KiB cap, and the `.ctrlrelay` directory itself opened
+  without following a symlink, so an agent cannot point it at another run's
+  and have the relay read — and delete — that run's checkpoint): a FIFO at the state path blocked the read
+  forever, past the session timeout and with every other run on the event
+  loop stalled behind it, and a huge file or a symlink to `/dev/zero` was
+  read whole. A checkpoint that breaks the JSON parser (an integer past the
+  int-string limit, deep nesting, bad UTF-8) is now an unreadable checkpoint
+  rather than an exception. Known limit: a process group does not contain a
+  process that leaves it on purpose — one that calls `setsid` or
+  `setpgid` survives without a sandbox. Under `sandbox: "bwrap"` the PID
+  namespace ends it with the sandbox; full containment for the other
+  backends is #352. A narrow race also remains: if the agent's group id is
+  recycled for another group during a session and that group's leader has
+  exited too, the relay cannot tell the two apart and may signal it.
+- An agent no longer inherits the daemon's stdin; it gets `/dev/null`
+  unless its prompt is sent on stdin. `codex exec` appends piped stdin to
+  its prompt and waits for end-of-file, so with the daemon's stdin an open
+  pipe every Codex run sat until the timeout without starting (#379).
+- A repository's own instruction link that points outside the checkout,
+  such as `AGENTS.md -> /opt/shared/AGENTS.md`, was taken for the relay's
+  context link: it was replaced while the agent ran and deleted at cleanup.
+  Only links to the repo's context file are now replaced or removed (#379).
+- When the daemon's `PATH` held a relative entry (`.`, an empty entry,
+  `bin`), a file committed to the repository could run in place of a bare
+  agent `binary`, of an `#!/usr/bin/env` interpreter, or of a command the
+  agent ran, because the agent starts inside the worktree. Agents now start
+  with relative `PATH` entries removed, sandboxed or not. This predates the
+  plugin runtime.
+- Context-link cleanup walks the worktree without following symlinks, so a
+  directory swapped for a link during a run cannot redirect it outside the
+  checkout (#379).
+- The relay no longer replaces a repository's own `CLAUDE.md` with its repo
+  context link. The tracked file became a type change while the agent ran
+  and a deletion after cleanup, so an agent that staged everything could put
+  either into its pull request. Cleanup now removes only links the relay
+  made (#379).
+- A plugin listed under `agent.plugins` but not routed to by any repo or by
+  `agent.assignable_types` is built only when a pinned run selects it, so
+  one that cannot run under `agent.sandbox: bwrap` no longer stops the
+  daemon at startup. A routed one still does, naming where it was routed
+  from. A backend that fails to build on demand is refused for that run
+  instead of raising out of the pipeline (#379).
+
+### Upgrade notes
+
+- `agent.plugins.copilot` and `agent.plugins.codex` are now refused at load,
+  because those names are built-in presets (#384, #385). Remove the entry and
+  set `agent.presets.<name>` if you changed its binary, model or timeout.
+- An `opencode` setup, or a plugin, that reads a model-provider key from the
+  environment now needs that key listed in its `env_allow` (#390).
+- On Linux, log the Copilot CLI in with the keyring out of reach
+  (`DBUS_SESSION_BUS_ADDRESS=disabled: copilot`, then `/login`) or set
+  `COPILOT_GITHUB_TOKEN`: the relay blocks the desktop keyring, so a
+  keyring-stored login cannot be read.
+- A run waiting on a question from before this release has no recorded
+  agent identity. If its agent session had already started, it is refused
+  with `agent_identity_unknown` instead of being resumed on whatever backend
+  is configured now. Answer or close those questions before upgrading, or
+  re-run the issue afterwards (#379).
+- A repo that commits its own `CLAUDE.md` now runs with that file instead of
+  the relay's context under that name. Move anything the agent must see into
+  the repo's file, or into the contexts entry for a name the repo does not
+  use (#379).
+
 ## [0.27.0] - 2026-11-06
 
 ### Added
@@ -2650,7 +2819,8 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.27.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.28.0...HEAD
+[0.28.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.24.0...v0.25.0

{ctrlrelay-0.27.0 → ctrlrelay-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.27.0
+Version: 0.28.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/
@@ -66,7 +66,8 @@ 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
+  (or add a label) and the work starts. Teammates you allow can hand it work
+  the same way. 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
@@ -81,8 +82,11 @@ work you don't want to sit and watch.
 - **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.
+- **Pick your agent per repo.** Claude Code, OpenCode, GitHub Copilot CLI or
+  Codex, plus simple non-interactive CLIs enrolled through a local plugin
+  manifest ([what each one supports](https://ainvirion.github.io/ctrlrelay/configuration/#agent-backends)).
+  Choose the default per repo; a future control plane can select from the
+  agents you allow.
 - **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.
@@ -116,7 +120,8 @@ flowchart LR
     PR -->|CI + review| YOU(["You merge"])
 ```
 
-1. **You assign an issue** to yourself, or add a label you pick.
+1. **You assign an issue** to yourself, or add a label you pick. Teammates
+   on your `allowed_accounts` list can do the same.
 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.

{ctrlrelay-0.27.0 → ctrlrelay-0.28.0}/README.md

@@ -25,7 +25,8 @@ 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
+  (or add a label) and the work starts. Teammates you allow can hand it work
+  the same way. 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
@@ -40,8 +41,11 @@ work you don't want to sit and watch.
 - **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.
+- **Pick your agent per repo.** Claude Code, OpenCode, GitHub Copilot CLI or
+  Codex, plus simple non-interactive CLIs enrolled through a local plugin
+  manifest ([what each one supports](https://ainvirion.github.io/ctrlrelay/configuration/#agent-backends)).
+  Choose the default per repo; a future control plane can select from the
+  agents you allow.
 - **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.
@@ -75,7 +79,8 @@ flowchart LR
     PR -->|CI + review| YOU(["You merge"])
 ```
 
-1. **You assign an issue** to yourself, or add a label you pick.
+1. **You assign an issue** to yourself, or add a label you pick. Teammates
+   on your `allowed_accounts` list can do the same.
 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.

{ctrlrelay-0.27.0 → ctrlrelay-0.28.0}/config/orchestrator.yaml.example

@@ -39,6 +39,9 @@ agent:
   binary: "claude"
   default_timeout_seconds: 1800
   output_format: "json"
+  # Enrolled types a future control-plane assignment may explicitly select.
+  # Empty keeps selection entirely local. Standalone repo defaults are unaffected.
+  assignable_types: []
 
   # Read only when a backend of type "opencode" is built, so this block
   # is inert on a claude-only deployment and harmless to leave in place.
@@ -67,6 +70,34 @@ agent:
   #   # model is usually slower per token than a hosted one.
   #   default_timeout_seconds: 3600
 
+  # Optional generic CLI manifests (#379). Each key becomes an agent_type you
+  # can use as agent.type, repos[].agent_type, or an allowlisted assignment.
+  # Arguments run directly (no shell). Supported placeholders: {prompt},
+  # {session_id}, {state_file}, {resume_session_id}, {model}, {provider}.
+  # Generic plugins have no live transcript, usage reading, or bwrap support.
+  # plugins:
+  #   example:
+  #     binary: "/opt/example/bin/agent"
+  #     args: ["run", "{prompt}"]
+  #     prompt_mode: "arg"  # or "stdin"
+  #     resume_args: ["resume", "{resume_session_id}", "{prompt}"]
+  #     session_id_path: "info.session.id"  # required with resume_args
+  #     model: "model-x"
+  #     provider: "provider-y"
+  #     plugin_version: "1"
+  #     instructions_files: ["AGENTS.md"]  # names the CLI reads for context
+  #     default_timeout_seconds: 1800
+  # Copilot and Codex are built-in presets: set repos[].agent_type to
+  # "copilot" or "codex" with no entry here. Only these three keys can be
+  # changed; the arguments are fixed. See docs/configuration.md.
+  # presets:
+  #   copilot:
+  #     binary: "copilot"
+  #     model: "claude-sonnet-4.5"
+  #     default_timeout_seconds: 3600
+  #   codex:
+  #     model: "gpt-5.1-codex"
+
 # EXACTLY ONE transport is active, and it is the one named by `type`.
 # The other blocks below are inert: they may stay in the file, but nothing
 # reads them. Running Telegram and Mattermost at the same time is NOT

{ctrlrelay-0.27.0 → ctrlrelay-0.28.0}/docs/architecture.md

@@ -40,11 +40,15 @@ 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.
+owns the shared subprocess lifecycle. Thin adapters provide CLI-specific argv
+and native-session parsing: `ClaudeDispatcher`, `OpenCodeDispatcher`, and
+`GenericCliDispatcher` for local manifests. All expose the same async
+`spawn_session` shape, so pipelines stay agent-agnostic.
+`make_repo_agent_dispatcher` enrolls the configured plugins and selects the
+standalone default per repo: `agent.type` is the global default and
+`repos[].agent_type` overrides it. `select_agent` additionally resolves an
+allowlisted assignment override or a previously pinned identity to one concrete
+adapter at the run boundary.
 
 - **Spawn shape:** Claude Code runs
   `claude -p <prompt> --output-format stream-json --verbose --dangerously-skip-permissions [--resume <id>]`;
@@ -70,11 +74,20 @@ with the same async `spawn_session` shape, so pipelines stay agent-agnostic:
   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.
+  Code), `--session <id>` (OpenCode), or a generic manifest's `resume_args`.
+  Pipelines look up the agent's own id (persisted as
+  `sessions.agent_session_id` by the prior spawn) and pass it through. A
+  generic plugin without a resume mapping refuses the request instead of
+  silently starting fresh. Claude retains its existing fresh-session fallback
+  when no native id was captured.
+- **Identity and capabilities (#379):** every concrete adapter reports an
+    `AgentIdentity` (`agent_type`, plugin id/version, model, provider and an
+  invocation fingerprint) and conservative `AgentCapabilities` (resume,
+  structured events, usage and sandbox). The selected identity is written to
+ `sessions` before dispatch and
+  checked again before storing a native session id. A conflicting identity is
+  an error, never a silent backend switch. Capabilities default to false;
+  missing usage or structured-event support is not guessed.
 
 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.
@@ -87,7 +100,7 @@ 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). |
+| `sessions` | `id`, `pipeline`, `repo`, `issue_number`, `worktree_path`, `status`, `blocked_question`, `started_at`, `ended_at`, `claude_exit_code`, `summary`, `agent_session_id`, `agent_type`, `agent_plugin_id`, `agent_plugin_version`, `agent_model`, `agent_provider`, `agent_fingerprint`, `output_tail` | Indexed on `repo` and `status`. One row per pipeline run. `agent_session_id` stores the agent's own session id for resume; the `agent_*` columns pin the selected plugin identity and invocation fingerprint (#379); `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. |
@@ -99,8 +112,9 @@ SQLite, single file at `paths.state_db`.
 | `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`
+`list_locks`, `set_agent_session_id`, `get_agent_session_id`,
+`pin_agent_identity`, `get_agent_identity`, plus raw `execute` / `commit`.
+ The pipeline code uses raw SQL for the `sessions`
 table on purpose — kept thin and grep-able.
 
 ## Worktree lifecycle

{ctrlrelay-0.27.0 → ctrlrelay-0.28.0}/docs/cli.md

@@ -203,7 +203,8 @@ ctrlrelay run dev -i ISSUE [-r REPO] [-c PATH] [--from-step STEP]
 | `--from-step` | no | — | Start again from `plan`, `code` or `publish`, taking the earlier steps from the issue's newest run that saved them and moving the branch back. See [A run whose process died](operations.md#a-run-whose-process-died). |
 
 Acquires the per-repo lock, creates the worktree, spawns the repo's agent
-(Claude Code or OpenCode, per `agent.type` / `repos[].agent_type`) with the
+(Claude Code, OpenCode, Copilot, Codex or a plugin, per `agent.type` /
+`repos[].agent_type`) with the
 issue's title/body in the prompt, and reports the result. If the agent blocks
 and a chat transport (Telegram or Mattermost) is configured, posts the question
 to your chat and waits for a reply (up to `DEFAULT_MAX_BLOCKED_ROUNDS` rounds).
@@ -263,7 +264,9 @@ ctrlrelay poller start [-c PATH] [-F|--foreground] [-i SECONDS]
 | `--config` / `-c` | `config/orchestrator.yaml` | Config path. |
 
 Polls each configured repo for issues assigned to your GitHub user (resolved
-via `gh api user --jq .login`). On the first run, seeds the seen-issue set
+via `gh api user --jq .login`), by you or by an account in
+`allowed_accounts`, plus issues carrying a trigger label one of those
+accounts added. On the first run, seeds the seen-issue set
 with current assignments so it does not replay your existing backlog.
 
 For each newly assigned issue, runs `run_dev_issue(...)` (i.e. the dev pipeline)