ctrlrelay 0.8.1__tar.gz → 0.10.0__tar.gz

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/.github/workflows/publish.yml

@@ -12,9 +12,17 @@ name: Publish to PyPI
 #   Workflow:    publish.yml
 #   Environment: pypi
 #
-# The `pypi` environment adds a manual approval gate — releases pause
-# at the "Publish" step until a repo maintainer approves, so a
-# compromised tag alone can't silently push to PyPI.
+# Publishing is intentionally automatic: tag, publish the GitHub
+# release, and this ships to PyPI with no human step. The `pypi`
+# environment scopes the OIDC trust to this workflow — it is NOT an
+# approval gate and carries no protection rules. Anything that can
+# publish a release here can publish to PyPI.
+#
+# (This comment previously claimed the environment paused for a
+# maintainer. It never did, and someone reading it planned a release
+# around a checkpoint that was not there. If a gate is ever wanted,
+# it is a required reviewer on the `pypi` environment in repo
+# settings — not something this file can assert.)
 
 on:
   release:

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/CHANGELOG.md

@@ -7,6 +7,276 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-08
+
+### Added
+
+- **The dispatcher now logs.** `core/dispatcher.py` is the module that
+  spawns and supervises every agent session, and it was the only core
+  module with no structured logging at all — so the one place where a
+  session is born, times out or dies was the one place with no trail.
+  It now emits `dispatcher.session.start` / `.finished` / `.timeout` /
+  `.subprocess_failed` / `.spawn_failed` / `.cancelled`, plus
+  `dispatcher.checkpoint.missing` when a session ends without
+  signalling and `dispatcher.checkpoint.read_failed` when the file
+  won't parse. Every failure event carries `error_type`, so a bare
+  `asyncio.TimeoutError` — whose `str()` is empty — is still
+  identifiable in the log. Prompts and agent output are never logged in
+  plaintext: only a `hash_text()` prefix and a length. See
+  [Tracing one agent session](https://ainvirion.github.io/ctrlrelay/operations/#tracing-one-agent-session).
+- **`dispatcher.binary.fallback` / `.unresolved` warn when `claude`
+  isn't on `PATH`.** Under systemd and launchd the unit's `PATH` is
+  minimal, and falling through to a hard-coded path is the usual
+  precursor to every session failing to spawn. It used to happen
+  silently.
+
+### Changed
+
+- `spawn_session` takes optional `repo` and `issue_number` arguments,
+  which the dev, task and secops pipelines now pass. They are
+  observability-only — they let dispatcher events be correlated with
+  pipeline events without re-parsing the composite session id.
+
+### Fixed
+
+- **A slow post is no longer logged as a failed one.** The bridge ACKs
+  only after Telegram has accepted a question, so a post slower than the
+  transport's wait meant the transport timed out first and logged
+  `dev.question.post_failed` while the bridge logged
+  `dev.question.posted` for the same request — a false claim in the
+  opposite direction to the one being fixed. A timeout now emits
+  `dev.question.post_unknown`, because the outcome genuinely is unknown;
+  a write that actually failed keeps the definite `post_failed`.
+  Delivery is only ever confirmed by the far side's acknowledgement;
+  everything else divides into "the bytes provably never left" (a
+  definite failure) and "they may have" (unknown). A `drain()` failure
+  is unknown — `write()` had already handed the data over — and on the
+  bridge, a Telegram timeout or bare transport error is unknown too,
+  while `BadRequest`/`Forbidden`/`InvalidToken` are Telegram answering
+  "no". Note `BadRequest` subclasses `NetworkError` in
+  python-telegram-bot, so that check cannot be a plain isinstance; it
+  lives in `is_ambiguous_delivery` next to the library that defines the
+  taxonomy. `TransportTimeoutError` subclasses
+  `TransportUnknownDeliveryError` subclasses `TransportError`, so
+  existing handlers are unaffected. The bridge's ERROR response carries
+  which of the two it was (`telegram_delivery_unknown` vs
+  `telegram_api_error`) rather than letting the transport re-derive it —
+  the transport cannot see the Telegram exception, so a generic error
+  forced it to assume the worst and contradict the bridge's own record
+  for the same `request_id`.
+
+  **Known limit:** python-telegram-bot raises `TimedOut` for an HTTPX
+  connection-pool timeout too, where the request was never sent. That
+  case is currently reported as unknown rather than as the definite
+  non-delivery it is. Separating it means matching on library internals,
+  which is more fragile than the mislabelling is harmful.
+
+- **`dev.question.posted` no longer claims a delivery that never
+  happened.** The transport logged it before writing to the socket and the
+  bridge logged it before calling Telegram, so a failed write or a Telegram
+  outage still left a record saying the operator had been asked. The
+  transport now emits it on the bridge's ACK — the only signal that says
+  the question actually reached Telegram — and the bridge emits it after
+  the API accepts the message, tagged with `telegram_msg_id`. Both sides
+  emit `dev.question.post_failed` (with `reason` and a truncated `error`)
+  on the failure path instead. A question that is posted and then goes
+  unanswered still logs only `posted`: the delivery succeeded, the operator
+  just did not reply.
+- **Questions and operator answers are no longer written to logs in
+  plaintext.** Every event already carried `question_hash` / `answer_hash`,
+  and then defeated it by logging the raw text in the field next door.
+  These records go to stdout and are captured into `~/.ctrlrelay/logs` and
+  the systemd journal, so free-text operator replies — and questions that
+  now enumerate every open PR in a repo — persisted there indefinitely with
+  no retention policy tuned for that content. The hash and length remain,
+  which is enough to correlate the same question across the poller and
+  bridge logs. A test walks the source and fails on any `log_event()` call
+  that passes a raw payload field.
+- **A broken `gh` install no longer reports itself as "network
+  unavailable".** `subprocess.run` raising `OSError` means the child could
+  not be exec'd — a non-executable binary, a bad path, a wrong
+  architecture. Python does no networking here, `gh` does, so an `OSError`
+  raised on our side can never mean offline. Reporting it that way was the
+  exact misdiagnosis this classification exists to prevent: it sends the
+  operator to check their wifi while their `gh` install is broken. Only a
+  hung `gh` (timeout) still reads as connectivity — there the child
+  launched and then stopped responding.
+- **`broken pipe` now reads as a network failure.** A peer that vanished
+  mid-write carries none of the other network markers, so it fell through
+  to a generic API error — a miss of the classifier's own purpose. Bare
+  `EOF` is deliberately still not matched: `gh` passes API response
+  bodies through verbatim, so matching it would misclassify real API
+  errors as outages, the same mistake in the other direction.
+- **A resource limit is no longer blamed on the `gh` install.** `EMFILE`
+  and `ENOMEM` also reach the classifier as `OSError` from a failed spawn,
+  but answering those with "install GitHub CLI" is the same misdirection
+  wearing a different hat. Only exec-family errnos say the install is
+  broken; the rest surface the errno.
+- **Go transport failures are no longer reported as API errors.** `gh`
+  renders a failed round-trip as `Get "https://…": <cause>`, which by
+  construction means no HTTP response arrived — so `EOF`, `http2: client
+  connection lost`, `request canceled` and `remote error: tls: handshake
+  failure` were all landing as "GitHub API call failed". Matching the
+  shape rather than each wording catches the family; a real API error
+  carries `(HTTP nnn)` instead and is unaffected. `read tcp …: connection
+  timed out` (a link dropped mid-request) is matched too.
+- **TLS trust failures are no longer called transient.** An untrusted CA
+  or a skewed clock is a persistent local problem, and "retry later" can
+  never fix it. These now report as `tls_trust` with remediation pointing
+  at the CA bundle and the system clock. A certificate valid for the
+  wrong host stays a network failure — that is the captive-portal case.
+- **`gh` stderr is escaped before Rich renders it.** Stderr containing
+  bracketed text (e.g. `[/docs]`) raised `MarkupError`, replacing the
+  diagnostic with a traceback and skipping the exit — losing the raw
+  detail the line exists to show.
+- **The startup `gh` probe is time-bounded.** Without a timeout a hung
+  `gh` wedged `poller start` indefinitely, and the one exception branch
+  that really does mean connectivity could never fire.
+
+- **Startup no longer blames your GitHub auth when you are offline.**
+  `poller start` probes `gh api user` before it does anything else, and
+  every way that probe can fail — unplugged network, expired token, a
+  500 from the API — exits 1, so the CLI printed
+  `Command '[...]' returned non-zero exit status 1.` for all of them.
+  A new `core/network.py` classifies the failure from gh's own stderr
+  into network / auth / rate-limit / API-error (plus "gh not
+  installed"), and the CLI prints the matching message —
+  `Network unavailable — could not reach api.github.com` in yellow when
+  it is transient, a pointer to `gh auth status` when the credentials are the
+  problem, the HTTP status when the API answered. gh's raw stderr is
+  still printed underneath.
+
+## [0.9.0] - 2026-09-07
+
+### Added
+
+- **`transport.telegram.question_ttl_seconds`: unanswered questions now
+  expire.** A `pending_resumes` row deliberately outlives the in-session
+  wait so a late reply can still drive the resume — but nothing ever
+  retired one, so the table only grew. Measured on one deployment: 46
+  questions posted, 4 ever answered, 16 still live and five repos
+  re-asking the same question on consecutive days. An expired row stops
+  being offered as the routing target for an orphan Telegram reply, and
+  a late answer can no longer revive it. Defaults to 172800 (48h),
+  minimum 3600.
+- **New hourly `question_expiry_sweeper` job.** Retires a question early
+  once every issue and PR it cites is closed or merged — the case where
+  someone merged the PR by hand and the question became meaningless
+  rather than merely unanswered. Fails safe in both directions: a
+  question citing nothing is never expired this way, and any probe error
+  leaves the row alone, because re-asking a dead question is recoverable
+  while dropping a live one is not. The TTL pass runs first and needs no
+  network, so a GitHub outage still lets age-based expiry make progress.
+  Probing is capped at 200 numbers per run so one pass cannot outlive its
+  own hourly interval — unbounded, a 2000-row backlog against a slow
+  GitHub would be 8.3h of serialized `gh api` reads. Rows past the cap
+  are examined on the next run, and the TTL pass retires them on age
+  regardless.
+
+- **`transport.telegram.ask_timeout_seconds`: how long a pipeline waits on
+  your Telegram reply.** Was a hard-coded 300s in `SocketTransport.ask`,
+  with no call site overriding it and no way to configure it. Defaults to
+  900s — deliberately short, because a sweep runs its repos sequentially
+  and holds each repo's lock and worktree for the whole wait, and the
+  poller awaits its issue handler inline. This value only buys the
+  in-session fast path; answering later is covered by the pending-resume
+  path below, so raising it to cover an overnight gap would turn a daily
+  sweep into a multi-day one for no benefit.
+
+### Fixed
+
+- **An expired question can no longer be resumed by a stale bridge.**
+  `answer_pending_resume` already refuses to answer an expired row, but
+  that guard only holds while every process runs the same code. The
+  bridge writes the answer and the poller reads it back — separate
+  daemons — so a deploy that restarts one before the other leaves a
+  window where an old bridge stamps `answered_at` on a row the new
+  poller has already expired, and the resume fires against state that
+  moved on. Seen live: the bridge ran three-day-old code for an hour
+  after the poller was upgraded. `list_pending_resumes_to_execute` now
+  filters expired rows too, closing the window from the side that acts
+  on them.
+
+- **A secops repo failure now says what broke.** A sweep that died before
+  the `sessions` INSERT — anything raised by `ensure_bare_repo` or
+  `create_worktree`, both network-bound and both ahead of it — left no
+  trace at all: the DB update is guarded on the insert having happened,
+  and the `except` block had no logging. With an exception whose `str()`
+  is empty the Telegram alert then fell back to its generic summary, so
+  the operator got `Error processing <repo>` and nothing else. The
+  failure is now logged as `secops.repo.failed` regardless of which
+  branch runs, and both `summary` and `error` carry the exception type.
+- **`git` timeouts stringify to something.** `asyncio.wait_for` raises a
+  bare `TimeoutError` whose message is the empty string; it is now
+  re-raised as the same type with the command, timeout, and cwd
+  attached, so it stays useful wherever it surfaces.
+- **Bare clone and fetch get a transfer-sized timeout.** Both inherited
+  the 120s budget meant for local git plumbing, which a multi-gigabyte
+  repo cannot meet on any normal link — a 1.8 GB repo failed its sweep
+  this way every day. Network transfers now use 1800s, matching claude's
+  own `default_timeout_seconds`.
+- **secops no longer looks at PRs outside its two author-filtered queries.**
+  The prompt only ever tells the agent to run `gh pr list` with
+  `--author "app/dependabot"` and `--author "$OPERATOR"` — but a step-5
+  bullet for "PRs from anyone else" implied a wider list existed, so the
+  agent ran its own unfiltered `gh pr list` to populate the category and
+  then signalled BLOCKED on PRs it can never merge. That fired a Telegram
+  question every sweep, forever, and every one timed out unanswered; run
+  summaries reporting "no open PRs at all" were the fingerprint of the
+  out-of-scope query. A third party's PR is now explicitly out of scope:
+  not fetched, not evaluated, not named in the summary. An explicit scope
+  fence forbids broadening the search. Operator-authored code PRs still
+  ASK, because there the answer genuinely decides what happens next.
+- **BLOCKED questions may no longer be padded with already-decided items.**
+  Real questions were bundling a genuine Dependabot decision with a
+  non-actionable tail ("...confirm no action wanted"), burying the part
+  that needed an answer. Decided items belong in the run summary; a repo
+  with nothing to decide now finishes DONE instead of signalling BLOCKED.
+- **Telegram questions now say which repo and session they belong to.** A
+  secops sweep posts one consolidated question per repo back-to-back and
+  the agent's text rarely names its own repo, so the operator saw a run of
+  near-identical "approve #387?" messages with nothing to tell them apart.
+  Worse, the orphan router's "reply again with the session_id included"
+  instruction was impossible to follow — the session_id had never been sent
+  to the operator in the first place. `ASK` now prefixes the question with
+  `[owner/repo]`, the session_id, and (for dev) the issue number.
+- **Replying to one question no longer answers a different one.** When the
+  bridge couldn't match an incoming reply it fell back to FIFO and
+  delivered the answer to the *oldest* outstanding question. Replying to
+  the third question while the first was still open silently answered the
+  first, with nothing shown to the operator. Reply-to now matches strictly;
+  a plain message routes only when exactly one question is outstanding, and
+  otherwise the operator is told to use Telegram's reply and shown what is
+  waiting.
+- **A late reply now resumes the session it was actually aimed at.** The
+  bridge remembers which session each posted question belongs to (bounded
+  to the last 500), so a reply arriving after the ASK timed out resolves
+  its `pending_resumes` row exactly instead of reporting "multiple BLOCKED
+  sessions are unanswered" and asking for a session_id the operator was
+  never given.
+- **An answer given after the pipeline stopped waiting is no longer thrown
+  away.** When `ask()` timed out, the client discarded the request but did
+  not close the socket — a secops sweep reuses one transport across every
+  repo — so the bridge went on treating the question as live. A later
+  reply-to matched that dead entry, and the ANSWER was written into a
+  request nobody was listening for: no log, no notice, nothing. The
+  operator replied exactly as instructed and the answer vanished. The
+  bridge now tracks each question's deadline and drops expired entries
+  before routing, sending the reply down the pending-resume path instead.
+  Expired entries also no longer inflate the "more than one question is
+  waiting" count, which was refusing plain answers to the one real
+  question.
+- **The post-sweep "blocked on `<repo>`" message is answerable.** It is
+  sent as a one-way notice and its Telegram id was never recorded, so
+  replying to the most recent and most prominent message for a repo landed
+  in the ambiguous branch. A `SEND` that names a session is now tracked the
+  same way an `ASK` is.
+- **Operator notices name repos and sessions, not internal ids.** The
+  "still waiting" listing rendered `telegram_msg_id: request_id` — Telegram
+  never shows message ids in its UI and `request_id` means nothing to a
+  human. It now uses the same `[owner/repo] (session: …)` shape as the
+  question header.
+
 ## [0.8.1] - 2026-09-04
 
 ### Fixed
@@ -1267,7 +1537,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.8.1...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.6.0...v0.7.0

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.8.1
+Version: 0.10.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/config/orchestrator.yaml.example

@@ -37,6 +37,13 @@ transport:
     bot_token_env: "CTRLRELAY_TELEGRAM_TOKEN"
     chat_id: 123456789
     socket_path: "~/.ctrlrelay/ctrlrelay.sock"
+    # Seconds a pipeline waits on your reply before giving up and
+    # persisting the session as BLOCKED. This is only the in-session fast
+    # path — a reply that arrives later still attaches to the saved
+    # session and the pending-resume sweeper drives it. Don't raise this
+    # to cover being asleep: a sweep runs its repos one at a time and
+    # holds each repo's lock and worktree for the whole wait.
+    ask_timeout_seconds: 900
   file_mock:
     inbox: "~/.ctrlrelay/inbox.txt"
     outbox: "~/.ctrlrelay/outbox.txt"

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/docs/configuration.md

@@ -118,6 +118,8 @@ transport:
 | `bot_token_env` | string | `"CTRLRELAY_TELEGRAM_TOKEN"` | Name of the environment variable holding the bot token. ctrlrelay never reads the token directly — only the variable name. |
 | `chat_id` | int | `0` | Telegram chat ID the bridge sends messages to and accepts replies from. |
 | `socket_path` | path | `"~/.ctrlrelay/ctrlrelay.sock"` | Unix socket path the bridge listens on. Pipelines connect to this socket as clients. |
+| `ask_timeout_seconds` | int | `900` | How long a pipeline blocks waiting on your reply in-session. Minimum `60`. A reply arriving later still works: the question is persisted to `pending_resumes` and the every-minute sweeper drives the resume. |
+| `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. |
 
 See [Telegram bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.
 

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/docs/operations.md

@@ -305,6 +305,57 @@ tail -f ~/.ctrlrelay/logs/poller.error.log
 The poller prints one line per detected issue and one line per pipeline outcome.
 The bridge prints connection events and Telegram API errors.
 
+### Tracing one agent session
+
+Log lines are newline-delimited JSON, and the dispatcher — the module that
+spawns and supervises every agent subprocess — tags each of its events with
+the session id, so one grep reconstructs a whole run:
+
+```bash
+grep dev-owner-repo-42- ~/.ctrlrelay/logs/poller.log | jq -c '{ts, level, event}'
+```
+
+The events it emits:
+
+| Event | Level | When |
+|---|---|---|
+| `dispatcher.session.start` | INFO | Subprocess about to launch. Carries `binary`, `timeout`, `resume`, `prompt_hash`, `prompt_len`. |
+| `dispatcher.session.finished` | INFO | Subprocess exited. Carries `exit_code`, `checkpoint_status`, `elapsed_ms`. |
+| `dispatcher.session.subprocess_failed` | ERROR | Non-zero exit, with `stderr_tail`. |
+| `dispatcher.session.timeout` | ERROR | The `timeout` seconds elapsed and the child was killed. |
+| `dispatcher.session.spawn_failed` | ERROR | The binary could not be exec'd at all. |
+| `dispatcher.session.cancelled` | INFO | Daemon shutdown killed the child mid-run. |
+| `dispatcher.checkpoint.missing` | WARNING | The session ended without writing a checkpoint. |
+| `dispatcher.checkpoint.read_failed` | ERROR | A checkpoint file existed but would not parse. |
+| `dispatcher.binary.fallback` | WARNING | `claude` was not on `PATH`; a well-known path was used instead. Expect this when the unit's `PATH` is minimal. |
+| `dispatcher.binary.unresolved` | WARNING | Not on `PATH` and not at any known path — sessions are about to start failing to spawn. |
+
+Prompts and agent output never appear in plaintext: only a short SHA-256
+prefix and a length are logged.
+
+### Blocked-question events
+
+When a session blocks on a question, the transport and the bridge each emit
+their own record:
+
+| Event | When |
+|---|---|
+| `dev.question.posted` | The question reached the operator. The transport emits it on the bridge's ACK; the bridge emits it once the Telegram API has accepted the message, and adds `telegram_msg_id`. |
+| `dev.question.post_failed` | Delivery failed. Carries `reason` (`send_failed`, `bridge_error`, or the exception class on the bridge side) and a truncated `error`. |
+| `dev.answer.received` | The operator's reply came back. |
+
+Neither the question nor the answer is written to the log. Each event carries
+`question_hash` / `question_length` (or `answer_hash` / `answer_length`)
+instead — the hash is stable, so it still joins the poller's record to the
+bridge's record for the same question:
+
+```bash
+grep 44509098fa6eeaf3 ~/.ctrlrelay/logs/*.log | jq -c '{ts, logger, event}'
+```
+
+This matters because these files and the systemd journal have no retention
+policy tuned for human-entered content, and operator replies are free text.
+
 ## Inspecting state
 
 ### `ctrlrelay status`

{ctrlrelay-0.8.1 → ctrlrelay-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.8.1"
+version = "0.10.0"
 description = "Local-first orchestrator for headless coding agents across multiple GitHub repos"
 readme = "README.md"
 requires-python = ">=3.12"