ctrlrelay 0.12.0__tar.gz → 0.12.2__tar.gz

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/.github/workflows/test.yml

@@ -37,9 +37,4 @@ jobs:
         run: uv run ruff check src/ tests/
 
       - name: Pytest
-        # Deselect the pre-existing unrelated docs-site test that asserts
-        # nav_order uniqueness across docs/ — tracked separately and
-        # unchanged by this PR.
-        run: |
-          uv run pytest tests/ -v \
-            --deselect tests/test_docs_site.py::test_nav_order_unique_per_sibling_group
+        run: uv run pytest tests/ -v

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.2] - 2026-10-06
+
+### Fixed
+
+- Stay quiet when somebody is talking in the channel (#194)
+
+## [0.12.1] - 2026-10-06
+
+### Fixed
+
+- Every checkpoint snippet creates its own directory (#190)
+- Restate the checkpoint contract when resuming (#188)
+- Run the whole suite, and make the next exclusion defendable (#186)
+
+### Changed
+
+- Both-transports-at-once is not planned, not pending (#187)
+
 ## [0.12.0] - 2026-10-06
 
 ### Added
@@ -1671,7 +1689,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.12.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.2...HEAD
+[0.12.2]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.1...v0.12.2
+[0.12.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.3...v0.12.0
 [0.11.3]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.2...v0.11.3
 [0.11.2]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.1...v0.11.2

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.12.0
+Version: 0.12.2
 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/
@@ -97,9 +97,9 @@ are on the roadmap (see [Roadmap](#roadmap)).
   relays it to you and resumes the session once you reply. Choose
   **Telegram** (a DM from a bot) or **Mattermost** (a channel on your own
   server) with one `transport.type` setting. Exactly one is active at a
-  time; running both at once is not supported yet
-  ([#176](https://github.com/AInvirion/ctrlrelay/issues/176)). See
-  [configuration][docs-config].
+  time; running both at once is not supported and not planned
+  ([#176](https://github.com/AInvirion/ctrlrelay/issues/176), closed
+  won't-do). See [configuration][docs-config].
 - **PR watcher.** Tracks the opened PR to merge and closes the loop
   with a notification on whichever chat transport is configured.
 - **In-process scheduler** (APScheduler). Runs periodic jobs inside

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/README.md

@@ -56,9 +56,9 @@ are on the roadmap (see [Roadmap](#roadmap)).
   relays it to you and resumes the session once you reply. Choose
   **Telegram** (a DM from a bot) or **Mattermost** (a channel on your own
   server) with one `transport.type` setting. Exactly one is active at a
-  time; running both at once is not supported yet
-  ([#176](https://github.com/AInvirion/ctrlrelay/issues/176)). See
-  [configuration][docs-config].
+  time; running both at once is not supported and not planned
+  ([#176](https://github.com/AInvirion/ctrlrelay/issues/176), closed
+  won't-do). See [configuration][docs-config].
 - **PR watcher.** Tracks the opened PR to merge and closes the loop
   with a notification on whichever chat transport is configured.
 - **In-process scheduler** (APScheduler). Runs periodic jobs inside

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/config/orchestrator.yaml.example

@@ -34,7 +34,7 @@ agent:
 # 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
-# supported - that is tracked as issue #176.
+# supported and NOT planned - designed in issue #176 and closed won't-do.
 #
 # Choose:
 #   type: "telegram"    production, 1:1 chat with a bot

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/docs/bridge.md

@@ -22,9 +22,11 @@ one-line config change and no pipeline code moves.
 **One at a time.** `transport.type` names the transport that is active, and the
 other block is inert — it may stay in the file, but nothing reads it, including
 its `question_ttl_seconds`. There is no fallback: a question goes to the one
-you named or nowhere. Running both at once is
-[issue #176](https://github.com/AInvirion/ctrlrelay/issues/176) and is not
-built.
+you named or nowhere. Running both at once is **not supported and not
+planned** — it was designed in
+[#176](https://github.com/AInvirion/ctrlrelay/issues/176) and closed
+won't-do. Reopen that issue rather than re-deriving the design if you need
+it.
 
 | | Telegram | Mattermost |
 |---|---|---|

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/docs/configuration.md

@@ -104,10 +104,11 @@ block in the file is inert — it may stay there, but nothing reads it.
 | A channel on your own server | `"mattermost"` | A server URL, a bot token, and the channel's 26-character ID. |
 | No chat at all | `"file_mock"` | Nothing. Questions go to a file; **nobody is asked anything.** |
 
-**Running Telegram and Mattermost at the same time is not supported.** Setting
-`type` to one does not fall back to the other, and a question is delivered to
-one place or not at all. That is tracked as
-[issue #176](https://github.com/AInvirion/ctrlrelay/issues/176).
+**Running Telegram and Mattermost at the same time is not supported, and is
+not planned.** Setting `type` to one does not fall back to the other, and a
+question is delivered to one place or not at all. It was designed in
+[#176](https://github.com/AInvirion/ctrlrelay/issues/176) and closed won't-do;
+the design is still in that issue if anyone wants it.
 
 Switching is a two-line change — set `type`, add that transport's block — plus
 a restart of **both** daemons, which share `state.db`.

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/pyproject.toml

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

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/src/ctrlrelay/bridge/server.py

@@ -37,6 +37,35 @@ _log = logging.getLogger(__name__)
 _ASKED_SESSIONS_MAX = 500
 
 
+_PENDING_SHOWN = 5
+
+
+def _format_pending(rows: list[dict]) -> str:
+    """A sample of outstanding questions, never the whole catalogue.
+
+    Capped because this list is unbounded by nature - one row per blocked
+    session, and a config error can block every repo in a sweep. Measured
+    on the live channel at 20 pending: 4042 characters, about 202 per
+    row. This deployment sweeps 87 repos, and the server's MaxPostSize is
+    16383, so at roughly 81 blocked sessions the message exceeded the
+    limit and posted NOTHING - the notice whose job is to say a reply was
+    dropped, dropped.
+
+    The count of what is withheld is part of the message, not a detail:
+    truncating to "here are five" and not saying five of how many is the
+    same information loss one level down.
+    """
+    shown = rows[:_PENDING_SHOWN]
+    lines = [
+        f"  • `{r['session_id']}` ({r['repo']}): {(r['question'] or '')[:80]}"
+        for r in shown
+    ]
+    rest = len(rows) - len(shown)
+    if rest > 0:
+        lines.append(f"  … and {rest} more.")
+    return "Pending:\n" + "\n".join(lines)
+
+
 def names_session(text: str, session_id: str) -> bool:
     """True when ``text`` names ``session_id`` as a whole token.
 
@@ -617,7 +646,7 @@ class BridgeServer:
         match: _PendingQuestion | None = None
         hinted_session_id: str | None = None
         live_listing: str | None = None
-        ambiguous_notice: str | None = None
+        unaddressed_pending: int | None = None
 
         async with self._pending_lock:
             self._drop_expired_questions()
@@ -629,20 +658,16 @@ class BridgeServer:
             elif len(self._pending_questions) == 1:
                 match = next(iter(self._pending_questions.values()))
             elif len(self._pending_questions) > 1:
-                ambiguous_notice = (
-                    "Your message wasn't routed - "
-                    f"{len(self._pending_questions)} questions are waiting "
-                    "and a plain message doesn't say which one you "
-                    "mean.\n\n"
-                    "Reply to the question you want to answer "
-                    "(Telegram: reply; Mattermost: reply in its thread)."
-                    "\n\n"
-                    f"{self._live_question_listing()}"
-                )
+                # A plain message pointing at nothing, with several
+                # questions live. This used to post the whole list; the
+                # bridge shares its channel with people, so that made
+                # every sentence typed in it produce a wall. Counted,
+                # not inferred.
+                unaddressed_pending = len(self._pending_questions)
 
             if match is not None:
                 self._pending_questions.pop(match.request_id, None)
-            elif ambiguous_notice is None:
+            elif unaddressed_pending is None:
                 # Snapshot what the orphan branch needs, so the lock can be
                 # released before we touch the chat app or the database.
                 hinted_session_id = (
@@ -656,10 +681,20 @@ class BridgeServer:
                     else None
                 )
 
-        if ambiguous_notice is not None:
-            await self._send_notice(
-                ambiguous_notice,
-                log="bridge: ambiguous fresh reply, refusing to guess",
+        if unaddressed_pending is not None:
+            # Silent on purpose. See `_format_pending` for the measurement
+            # and the tradeoff: a plain message while several questions
+            # are open is ignored, so an answer typed without the reply
+            # gesture gets no response. The alternative was a notice on
+            # every message in a shared channel, which is what the
+            # operator reported.
+            log_event(
+                _logger,
+                "bridge.reply.unaddressed",
+                pending=unaddressed_pending,
+                live=True,
+                text_length=len(text),
+                text_hash=hash_text(text),
             )
             return
 
@@ -764,19 +799,27 @@ class BridgeServer:
                     f"({outcome['reason']})"
                 ),
             )
-        elif outcome["status"] == "ambiguous":
-            pending_list = "\n".join(
-                f"  • `{r['session_id']}` ({r['repo']}): "
-                f"{(r['question'] or '')[:80]}"
-                for r in outcome["rows"]
+        elif outcome["status"] == "unaddressed":
+            # Somebody is talking in the channel. Say nothing: the bridge
+            # does not own this channel and a message that points at no
+            # question is not a failed answer. Logged so a genuinely
+            # missed answer is still diagnosable.
+            log_event(
+                _logger,
+                "bridge.reply.unaddressed",
+                pending=len(outcome["rows"]),
+                text_length=len(text),
+                text_hash=hash_text(text),
             )
+        elif outcome["status"] == "ambiguous":
+            # Reached only when the operator DID point at something - they
+            # named more than one session id in one message. That is a
+            # failed answer and is worth a reply.
             await self._send_notice(
-                "⚠️ Your reply wasn't routed — multiple BLOCKED sessions "
-                "are unanswered and the reply didn't point at one of "
-                "them.\n\n"
-                f"Pending:\n{pending_list}\n\n"
-                "Reply to the question you mean, or paste "
-                "its session_id anywhere in your message."
+                "⚠️ Your reply wasn't routed — it names more than one "
+                "session.\n\n"
+                f"{_format_pending(outcome['rows'])}\n\n"
+                "Send one message per session."
             )
         elif live_listing is not None:
             # Reply-to pointed at a message this bridge no longer tracks
@@ -830,11 +873,16 @@ class BridgeServer:
         text.
 
         Caller must hold ``_pending_lock``."""
+        qs = list(self._pending_questions.values())
+        shown = qs[:_PENDING_SHOWN]
         rows = "\n".join(
             f"  - {q.repo or 'unknown repo'}"
             + (f" (session: {q.session_id})" if q.session_id else "")
-            for q in self._pending_questions.values()
+            for q in shown
         )
+        rest = len(qs) - len(shown)
+        if rest > 0:
+            rows += f"\n  … and {rest} more."
         return f"Still waiting:\n{rows}"
 
     async def _send_notice(self, text: str, log: str | None = None) -> None:
@@ -938,8 +986,16 @@ class BridgeServer:
         elif len(rows) == 1:
             target = rows[0]
         else:
-            # Multiple unanswered, no session_id hint — can't route safely.
-            return {"status": "ambiguous", "rows": rows}
+            # Multiple unanswered, and the message pointed at nothing: no
+            # reply-to, no session id. That is not a failed answer, it is
+            # somebody talking in the channel.
+            #
+            # This used to return "ambiguous", which posted every pending
+            # session as one block. Measured on the live channel: 4042
+            # characters, 29 lines, fired by `ok` and by a message
+            # addressed to @here. The operator could not hold a
+            # conversation in the channel the bot lives in.
+            return {"status": "unaddressed", "rows": rows}
 
         return await self._attach_orphan_answer(target, text)
 

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/src/ctrlrelay/pipelines/dev.py

@@ -318,7 +318,20 @@ class DevPipeline:
 
     async def resume(self, ctx: PipelineContext, answer: str) -> PipelineResult:
         """Resume blocked dev session with user answer."""
-        prompt = f"User answered: {answer}\n\nContinue from where you left off."
+        # The checkpoint contract is restated here, not just in the
+        # initial prompt (#173). A resumed agent that is told "continue"
+        # and nothing else can do its work, exit 0, write no state, and
+        # be indistinguishable from one that crashed - which is what
+        # happened on 2026-09-16, after three of four pull requests had
+        # already been merged.
+        contract = self._checkpoint_contract(
+            str(ctx.state_file), ctx.session_id
+        )
+        prompt = (
+            f"User answered: {answer}\n\n"
+            "Continue from where you left off.\n\n"
+            f"{contract}"
+        )
 
         # Resume uses Claude's own session UUID (captured on the first spawn
         # and persisted to state_db). Passing our composite id here makes
@@ -444,7 +457,34 @@ Do NOT merge the PR - wait for human review.
 The orchestrator re-verifies CI and mergeability after you hand off; if it
 finds the PR broken it will resume this session asking you to fix it.
 
-## Signaling Completion
+{self._checkpoint_contract(state_file_path, session_id)}"""
+
+    def _checkpoint_contract(
+        self, state_file_path: str, session_id: str
+    ) -> str:
+        """How the agent signals how it stopped.
+
+        Extracted so the RESUME prompt can carry it too (#173). The
+        initial prompt spent ~30 lines establishing this; the resume
+        prompt was 58 characters and said only "continue", so a resumed
+        agent could do its work, exit 0, write no state, and be
+        indistinguishable from one that crashed.
+
+        Measured case, 2026-09-16:
+        secops-AInvirion-Product-Telemetry-bbb99925 resumed after an
+        "Approved", ran 27.4s, exited 0 and wrote no checkpoint - having
+        in fact merged three of four pull requests. The operator was told
+        the resume failed, which was wrong in both directions: most of
+        the work had landed, and the one thing outstanding was never
+        named.
+
+        Per-pipeline rather than shared, because the three contracts
+        differ in substance and not only wording: the dev DONE block
+        carries pr_url and pr_number outputs, and each names different
+        conditions for DONE. One shared block would have quietly changed
+        what two of them promise.
+        """
+        return f"""## Signaling Completion
 
 **CRITICAL**: Before exiting, you MUST write a checkpoint file to signal completion.
 

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/src/ctrlrelay/pipelines/secops.py

@@ -126,7 +126,20 @@ class SecopsPipeline:
 
     async def resume(self, ctx: PipelineContext, answer: str) -> PipelineResult:
         """Resume blocked secops with user answer."""
-        prompt = f"User answered: {answer}\n\nContinue from where you left off."
+        # The checkpoint contract is restated here, not just in the
+        # initial prompt (#173). A resumed agent that is told "continue"
+        # and nothing else can do its work, exit 0, write no state, and
+        # be indistinguishable from one that crashed - which is what
+        # happened on 2026-09-16, after three of four pull requests had
+        # already been merged.
+        contract = self._checkpoint_contract(
+            str(ctx.state_file), ctx.session_id
+        )
+        prompt = (
+            f"User answered: {answer}\n\n"
+            "Continue from where you left off.\n\n"
+            f"{contract}"
+        )
 
         # Resume uses Claude's own session UUID (captured on the first spawn
         # and persisted to state_db). Our composite id is not a UUID and will
@@ -425,7 +438,34 @@ yourself about to write a phrase like "no open PRs at all" or "N open
 PRs total", you have already stepped outside the fence — you can only
 speak to the author-filtered results.
 
-## Signaling Completion
+{self._checkpoint_contract(state_file_path, session_id)}"""
+
+    def _checkpoint_contract(
+        self, state_file_path: str, session_id: str
+    ) -> str:
+        """How the agent signals how it stopped.
+
+        Extracted so the RESUME prompt can carry it too (#173). The
+        initial prompt spent ~30 lines establishing this; the resume
+        prompt was 58 characters and said only "continue", so a resumed
+        agent could do its work, exit 0, write no state, and be
+        indistinguishable from one that crashed.
+
+        Measured case, 2026-09-16:
+        secops-AInvirion-Product-Telemetry-bbb99925 resumed after an
+        "Approved", ran 27.4s, exited 0 and wrote no checkpoint - having
+        in fact merged three of four pull requests. The operator was told
+        the resume failed, which was wrong in both directions: most of
+        the work had landed, and the one thing outstanding was never
+        named.
+
+        Per-pipeline rather than shared, because the three contracts
+        differ in substance and not only wording: the dev DONE block
+        carries pr_url and pr_number outputs, and each names different
+        conditions for DONE. One shared block would have quietly changed
+        what two of them promise.
+        """
+        return f"""## Signaling Completion
 
 **CRITICAL**: Before exiting, you MUST write a checkpoint file to signal completion.
 

{ctrlrelay-0.12.0 → ctrlrelay-0.12.2}/src/ctrlrelay/pipelines/task.py

@@ -80,7 +80,20 @@ class TaskPipeline:
         return self._session_to_result(result)
 
     async def resume(self, ctx: PipelineContext, answer: str) -> PipelineResult:
-        prompt = f"User answered: {answer}\n\nContinue from where you left off."
+        # The checkpoint contract is restated here, not just in the
+        # initial prompt (#173). A resumed agent that is told "continue"
+        # and nothing else can do its work, exit 0, write no state, and
+        # be indistinguishable from one that crashed - which is what
+        # happened on 2026-09-16, after three of four pull requests had
+        # already been merged.
+        contract = self._checkpoint_contract(
+            str(ctx.state_file), ctx.session_id
+        )
+        prompt = (
+            f"User answered: {answer}\n\n"
+            "Continue from where you left off.\n\n"
+            f"{contract}"
+        )
         resume_uuid = self.state_db.get_agent_session_id(ctx.session_id)
         log_event(
             _logger,
@@ -181,7 +194,34 @@ pipeline. Don't BLOCK on things you can figure out yourself.
 
 ## Signaling completion
 
-**CRITICAL**: Before exiting, write a checkpoint file.
+{self._checkpoint_contract(state_file_path, session_id)}"""
+
+    def _checkpoint_contract(
+        self, state_file_path: str, session_id: str
+    ) -> str:
+        """How the agent signals how it stopped.
+
+        Extracted so the RESUME prompt can carry it too (#173). The
+        initial prompt spent ~30 lines establishing this; the resume
+        prompt was 58 characters and said only "continue", so a resumed
+        agent could do its work, exit 0, write no state, and be
+        indistinguishable from one that crashed.
+
+        Measured case, 2026-09-16:
+        secops-AInvirion-Product-Telemetry-bbb99925 resumed after an
+        "Approved", ran 27.4s, exited 0 and wrote no checkpoint - having
+        in fact merged three of four pull requests. The operator was told
+        the resume failed, which was wrong in both directions: most of
+        the work had landed, and the one thing outstanding was never
+        named.
+
+        Per-pipeline rather than shared, because the three contracts
+        differ in substance and not only wording: the dev DONE block
+        carries pr_url and pr_number outputs, and each names different
+        conditions for DONE. One shared block would have quietly changed
+        what two of them promise.
+        """
+        return f"""**CRITICAL**: Before exiting, write a checkpoint file.
 
 STATE_FILE: {state_file_path}
 SESSION_ID: {session_id}
@@ -196,6 +236,7 @@ printf '{{"version":"1","status":"DONE","session_id":"{session_id}",'\\
 
 **BLOCKED** (need operator input):
 ```bash
+mkdir -p "$(dirname '{state_file_path}')"
 printf '{{"version":"1","status":"BLOCKED_NEEDS_INPUT",'\\
 '"session_id":"{session_id}","timestamp":"%s","question":"%s"}}' \\
   "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "<QUESTION>" > '{state_file_path}'
@@ -203,6 +244,7 @@ printf '{{"version":"1","status":"BLOCKED_NEEDS_INPUT",'\\
 
 **FAILED** (genuine failure, no way forward):
 ```bash
+mkdir -p "$(dirname '{state_file_path}')"
 printf '{{"version":"1","status":"FAILED",'\\
 '"session_id":"{session_id}","timestamp":"%s","error":"%s"}}' \\
   "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "<ERROR>" > '{state_file_path}'