ctrlrelay 0.28.0__tar.gz → 0.28.1__tar.gz

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

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.1] - 2026-11-11
+
+### Fixed
+
+- The relay's own clone, fetch and `ls-remote` now use gh's login on a node
+  where git has no credential for github.com (#398). The first dev run on
+  such a node failed before the agent started with `could not read
+  Username for 'https://github.com'`. `gh auth git-credential` is appended
+  as a helper for `https://github.com` through `GIT_CONFIG_COUNT`, after
+  any entries already in the environment, so a unit's `insteadOf` rewrite
+  keeps working and an operator's own helper is still asked first. These
+  calls also set `GIT_TERMINAL_PROMPT=0`, so a missing credential fails at
+  once. Pushes already used gh's login; the agent's environment is
+  unchanged.
+- The checkpoint snippets in the dev, task and secops prompts, and in
+  `ctrlrelay agent check --resume`, no longer give an agent anything to
+  re-quote (#397). The BLOCKED and FAILED snippets (and secops' DONE) were a
+  `printf` built from single-quoted pieces joined by backslash
+  continuations. Agents sometimes rewrote the quoting or dropped a
+  continuation, and the round ended with a malformed or missing checkpoint
+  after the work was done. They now write the file with `python3` from a
+  quoted heredoc, the shape the DONE snippets already used. The text goes on
+  its own lines in a raw string and `json.dump` escapes it, so a question or
+  error may hold double quotes, newlines and backslashes; the old `%s`
+  pasted those into the JSON unescaped. One function renders the snippet for
+  every pipeline and for `agent check`, so the check runs exactly the shell
+  a real run uses.
+- A run paused on a question is no longer abandoned half an hour later
+  while its issue is still open (#400). The hourly sweep that retires a
+  question once everything it cites is closed read `oaf-kernel#118` as
+  this repository's `#118`, found an unrelated issue closed days before,
+  and retired a live question 33 minutes after it was asked. A reference
+  written `owner/repo#N`, or linked, is now looked up in that repository;
+  one whose repository cannot be told (`name#N`, `PR#N`) keeps the
+  question; and the issue the question was asked on must be closed too.
+  Closing that issue now retires its question even when the question
+  cites nothing else. The 48-hour
+  `question_ttl_seconds` was never the cause.
+- A question asked on an issue that expires unanswered now says on the
+  issue that the run has stopped and how to go on, and labels the issue
+  `ctrlrelay:unanswered` so it can be found. Adding it creates the label
+  in the repository if it is missing; nothing removes it. If the label
+  cannot be added, the comment still posts and does not mention it. A question retired
+  because its issue was closed is not labelled.
+
 ## [0.28.0] - 2026-11-11
 
 ### Added
@@ -2819,7 +2864,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.28.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.28.1...HEAD
+[0.28.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.28.0...v0.28.1
 [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

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

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

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/docs/configuration.md

@@ -958,7 +958,7 @@ reach anybody.
 | `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. |
+| `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, and the issue it was asked on is closed too. A question asked on an issue that expires on age labels the issue `ctrlrelay:unanswered`, when the label can be added. |
 | `question_retention_days` | int | `90` | How long a **finished** question (expired, or answered and resumed) is kept before the hourly sweeper deletes it. Minimum `1`. Open questions are never deleted. The kept history is what lets a re-asked question be marked as a repeat. |
 
 See [Chat bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/docs/feedback-loop.md

@@ -182,6 +182,16 @@ Step-by-step:
   that arrives later still lands on the session's `pending_resumes` row and
   the scheduled sweeper drives the resume. An unanswered question stays
   routable for `question_ttl_seconds` (default 48 hours), then expires.
+  When it was asked on an issue, the expiry is said there and the issue is
+  labelled `ctrlrelay:unanswered` (when the label can be added): the run has stopped, and someone has to
+  decide the question and start the issue again. Nothing removes the label.
+- **A question is retired early only when everything it rests on is
+  closed:** each `#N` it cites (in the question's repository), each
+  `owner/repo#N` or link to an issue or pull request (in that
+  repository), and the issue it was asked on. A question citing a
+  reference whose repository cannot be told, such as `name#N` or
+  `PR#N`, is never retired early: it stays open until it is answered or
+  its TTL ends.
 - **Maximum 5 BLOCKED rounds per session.** This bounds the chat noise from a
   pathological loop. After 5 rounds the pipeline gives up.
 - **State is durable.** The checkpoint file and the SQLite state DB persist
@@ -193,17 +203,33 @@ Step-by-step:
 ## Implementing your own BLOCKED in an agent session
 
 If you write a custom prompt or skill that runs under ctrlrelay, signal a
-question from inside the agent session using a shell `printf`:
+question from inside the agent session by writing the checkpoint with
+`python3`, so the question is JSON-escaped for you and the shell has
+nothing to re-quote:
 
 ```bash
 # Inside an agent session — both vars are set by the dispatcher.
-printf '{"version":"1","status":"BLOCKED_NEEDS_INPUT","session_id":"%s","timestamp":"%s","question":"%s"}' \
-  "$CTRLRELAY_SESSION_ID" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-  "Should I migrate the schema in this PR or split it?" \
-  > "$CTRLRELAY_STATE_FILE"
+python3 - "$CTRLRELAY_STATE_FILE" <<'CTRLRELAY_STATE'
+import datetime, json, os, sys
+text = r'''
+Should I migrate the schema in this PR or split it?
+'''.strip()
+state = {
+    "version": "1",
+    "status": "BLOCKED_NEEDS_INPUT",
+    "session_id": os.environ["CTRLRELAY_SESSION_ID"],
+    "timestamp": datetime.datetime.now(datetime.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    ),
+    "question": text,
+}
+with open(sys.argv[1], "w") as f:
+    json.dump(state, f)
+CTRLRELAY_STATE
 exit 0
 ```
 
-The dev-pipeline prompt template embeds this exact pattern — see the
-`_build_prompt` method in
-[`src/ctrlrelay/pipelines/dev.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/pipelines/dev.py).
+The question may span lines and hold any quotes, but not three single
+quotes in a row. The pipelines' prompts build the same shape with
+`shell_checkpoint` in
+[`src/ctrlrelay/core/checkpoint.py`](https://github.com/AInvirion/ctrlrelay/blob/main/src/ctrlrelay/core/checkpoint.py).

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/pyproject.toml

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

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/core/agent_check.py

@@ -51,6 +51,7 @@ from ctrlrelay.core.checkpoint import (
     CheckpointState,
     CheckpointStatus,
     read_checkpoint,
+    shell_checkpoint,
 )
 from ctrlrelay.core.dispatcher import (
     SessionResult,
@@ -162,12 +163,13 @@ def resume_round1_prompt(
 ) -> str:
     """Round 1: remember ``token``, then write ``BLOCKED_NEEDS_INPUT``.
 
-    The ``printf`` snippet is the shape of
-    :func:`ctrlrelay.pipelines.dev._blocked_and_failed_blocks` rather than
-    a shared block with it, for the same reason :func:`check_prompt` gives:
-    what is under test is the *mechanics* a real run uses — the quoted
-    path, the ``date`` substitution, the single line of shell — and the
-    dev contract's own blocks carry placeholders a check must not leave in.
+    The snippet comes from
+    :func:`ctrlrelay.core.checkpoint.shell_checkpoint`, the same function
+    the pipelines' BLOCKED and FAILED blocks use (#397), so the check
+    proves the exact shell a real run depends on — the quoted path, the
+    quoted heredoc, ``json.dump`` — and cannot drift from it. Only the
+    text differs: the dev contract's blocks carry a placeholder a check
+    must not leave in.
 
     The question is fixed rather than a ``<QUESTION>`` placeholder because
     the relay only has to see that a question arrived; what it says is the
@@ -182,11 +184,10 @@ SESSION_ID: {session_id}
 TOKEN: {token}
 
 ```bash
-mkdir -p -- {quoted_dir}
-printf '{{"version":"1","status":"{ROUND1_EXPECTED}",'\
-'"session_id":"{session_id}","timestamp":"%s",'\
-'"question":"{RESUME_QUESTION}"}}' \\
-  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > {quoted_path}
+{shell_checkpoint(
+    quoted_dir, quoted_path, session_id=session_id,
+    status=ROUND1_EXPECTED, field="question", text=RESUME_QUESTION,
+)}
 ```
 
 Do nothing else. There is no repository to read and nothing to change.

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/core/checkpoint.py

@@ -125,6 +125,67 @@ def failed(error: str, recoverable: bool = True) -> None:
 # A checkpoint is a few hundred bytes; a DONE with a long pull-request
 # description is a few kilobytes. Anything past this is not a checkpoint,
 # and reading it whole is how an agent would exhaust the relay's memory.
+# What an agent is told about free text it puts in a checkpoint written
+# by :func:`shell_checkpoint`. The text sits on its own lines inside a
+# Python raw triple-quoted string in a quoted heredoc, so quotes,
+# backslashes, `$`, backticks and newlines all arrive as written (a
+# carriage return arrives as a newline). Two things end it early: three
+# single quotes in a row close the string, and a line that is exactly the
+# heredoc's delimiter closes the heredoc.
+CHECKPOINT_TEXT_RULE = (
+    "Put your text on the line between the triple quotes. It may span "
+    "lines and contain any quotes, but not three single quotes in a row "
+    "and no line that is exactly CTRLRELAY_STATE."
+)
+
+
+def shell_checkpoint(
+    quoted_dir: str,
+    quoted_path: str,
+    *,
+    session_id: str,
+    status: str,
+    field: str,
+    text: str,
+) -> str:
+    """The shell an agent runs to write a one-text-field checkpoint (#397).
+
+    ``quoted_dir`` and ``quoted_path`` must already be shell-quoted
+    (#191). ``text`` is a placeholder such as ``<QUESTION>`` for the agent
+    to replace, or fixed text when the caller knows it.
+
+    The earlier snippet was a ``printf`` whose format string was several
+    single-quoted pieces joined by backslash continuations. Agents
+    re-quoted it (``'…''…'``) or dropped a continuation, and the round
+    ended with no checkpoint after the work was done. It also could not
+    carry a question holding a double quote or a newline: ``%s`` pasted it
+    into the JSON unescaped. Here the shell sees one plain command and a
+    heredoc whose delimiter is quoted, so nothing is expanded and nothing
+    needs re-quoting, and ``json.dump`` does the escaping.
+
+    The text goes on its own lines and is stripped, so a backslash at its
+    end cannot escape the closing quotes.
+    """
+    return f"""mkdir -p -- {quoted_dir}
+python3 - {quoted_path} <<'CTRLRELAY_STATE'
+import datetime, json, sys
+text = r'''
+{text}
+'''.strip()
+state = {{
+    "version": "1",
+    "status": "{status}",
+    "session_id": "{session_id}",
+    "timestamp": datetime.datetime.now(datetime.timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    ),
+    "{field}": text,
+}}
+with open(sys.argv[1], "w") as f:
+    json.dump(state, f)
+CTRLRELAY_STATE"""
+
+
 MAX_CHECKPOINT_BYTES = 256 * 1024
 
 

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/core/github.py

@@ -894,6 +894,18 @@ class GitHubCLI:
                 f"posting a comment returned no id: {output.strip()[:200]!r}"
             ) from None
 
+    async def add_issue_label(
+        self, repo: str, issue_number: int, label: str,
+    ) -> None:
+        """Add one label to an issue or PR. GitHub creates a label the
+        repository does not have yet."""
+        await self._run_gh(
+            "api", "-X", "POST",
+            f"repos/{repo}/issues/{issue_number}/labels",
+            "-f", f"labels[]={label}",
+            "--jq", ".[].name",
+        )
+
     async def edit_issue_comment(
         self, repo: str, comment_id: int, body: str,
     ) -> None:

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/core/issue_questions.py

@@ -98,13 +98,42 @@ def chat_answer_comment(session_id: str, answer: str, full: bool) -> str:
     return f"{body}\n{_marker('answer', session_id)}"
 
 
-def expired_comment(session_id: str, reason: str | None) -> str:
-    why = f" ({reason})" if reason else ""
-    return (
-        f"**The question above expired unanswered{why}.** An answer to it "
-        "is no longer applied, here or in chat.\n"
-        f"{_marker('expired', session_id)}"
-    )
+# Put on an issue whose question expired unanswered (#400), so a run that
+# stopped for want of an answer is findable work rather than a comment
+# nobody re-reads. Nothing removes it: a person does, once they have
+# decided the question and started the issue again.
+UNANSWERED_LABEL = "ctrlrelay:unanswered"
+
+
+def expired_comment(
+    session_id: str, reason: str | None, *, labelled: bool = False,
+) -> str:
+    if reason == "ttl":
+        found = (
+            f" The issue is labelled `{UNANSWERED_LABEL}` so it can be found."
+            if labelled else ""
+        )
+        body = (
+            "**The question above expired unanswered.** This issue's run "
+            "has stopped and will not continue on its own, and an answer "
+            f"to that question is no longer applied, here or in chat.{found} "
+            "To go on, decide the question in a comment, then remove the "
+            "issue number from seen_issues in poller_state.json so the "
+            "relay runs it again."
+        )
+    elif reason == "resolved_elsewhere":
+        body = (
+            "**The question above was retired:** this issue is closed, "
+            "along with any issue or pull request the question cites. An "
+            "answer to it is no longer applied, here or in chat."
+        )
+    else:
+        why = f" ({reason})" if reason else ""
+        body = (
+            f"**The question above expired unanswered{why}.** An answer "
+            "to it is no longer applied, here or in chat."
+        )
+    return f"{body}\n{_marker('expired', session_id)}"
 
 
 def already_answered_comment(session_id: str, login: str) -> str:
@@ -429,14 +458,33 @@ async def note_chat_answer_on_issue(
 
 
 async def note_expiry_on_issue(github: Any, row: dict[str, Any]) -> bool:
-    """Say on the issue that its question expired. Returns whether a
-    comment was posted."""
+    """Say on the issue that its question expired, and label an issue
+    whose question aged out unanswered. Returns whether a comment was
+    posted."""
     if row.get("issue_comment_id") is None or row.get("issue_number") is None:
         return False
+    labelled = False
+    if row.get("expired_reason") == "ttl":
+        # Before the comment, so the comment says whether it worked; a
+        # label that cannot be added still leaves the comment.
+        try:
+            await github.add_issue_label(
+                row["repo"], int(row["issue_number"]), UNANSWERED_LABEL,
+            )
+            labelled = True
+        except Exception as e:
+            log_event(
+                _logger, "issue_question.unanswered_label_failed",
+                session_id=row["session_id"], repo=row["repo"],
+                error_type=type(e).__name__, error=str(e)[:200],
+            )
     try:
         await github.post_issue_comment(
             row["repo"], int(row["issue_number"]),
-            expired_comment(row["session_id"], row.get("expired_reason")),
+            expired_comment(
+                row["session_id"], row.get("expired_reason"),
+                labelled=labelled,
+            ),
         )
     except Exception as e:
         log_event(
@@ -451,6 +499,7 @@ async def note_expiry_on_issue(github: Any, row: dict[str, Any]) -> bool:
 __all__ = [
     "QUESTION_ON_ISSUE_MODES",
     "RELAY_MARKER_PREFIX",
+    "UNANSWERED_LABEL",
     "ask_on_issue",
     "check_issue_answer",
     "note_chat_answer_on_issue",

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/core/question_expiry.py

@@ -82,6 +82,70 @@ def extract_referenced_numbers(question: str) -> list[str]:
     return out
 
 
+# A ``#N`` and whatever word sits right before it. ``#118`` is in the
+# question's own repository; ``owner/repo#118`` names another one; and
+# ``oaf-kernel#118`` names another one without saying whose, so it cannot
+# be looked up at all. Reading every one of those as ``#118`` here probed
+# an unrelated, long-closed issue of the same number and retired a live
+# question as resolved 33 minutes after it was asked (#400). A ``#12a`` is
+# not a reference.
+# The prefix takes every slash-joined part, so ``group/sub/repo#12`` is
+# read whole (and refused) rather than as ``sub/repo#12``.
+_REF_WITH_PREFIX_RE = re.compile(r"([\w.-]+(?:/[\w.-]+)*)?#(\d+)(?!\w)")
+# A link to an issue or PR names its repository outright. The host must
+# start the link (after a scheme, or standing alone), so neither
+# ``notgithub.com/…`` nor ``example.com/github.com/…`` is read as one.
+_REF_URL_RE = re.compile(
+    r"(?:https?://|(?<![\w./-]))(?:www\.)?github\.com/"
+    r"([\w.-]+/[\w.-]+)/(?:issues|pull)/"
+    r"(\d+)(?!\w)",
+    re.IGNORECASE,
+)
+
+
+def resolution_targets(row: dict[str, Any]) -> list[tuple[str, int]] | None:
+    """The issues and PRs that must ALL be closed before ``row``'s
+    question counts as resolved elsewhere, as ``(repo, number)``.
+
+    Each ``#N`` the question cites, in its own repository, or in
+    ``owner/repo`` when written ``owner/repo#N`` or as a link to the
+    issue; plus the issue the question was asked on, when it was asked on
+    one. A markdown link ``[#12](…/other/thing/issues/12)`` yields both
+    targets, so both must be closed. A run paused on an open issue is still waiting for
+    its answer whatever else the question mentions, so that issue being
+    open keeps the question.
+
+    None when the question cites something that cannot be looked up
+    (``name#N`` with no owner, ``PR#N`` written without a space): that reference can never be shown
+    closed, so the question cannot be resolved this way. An empty list
+    means there is nothing to check.
+    """
+    repo = row["repo"]
+    question = row.get("question") or ""
+    found: list[tuple[str, int]] = []
+    for prefix, number in _REF_WITH_PREFIX_RE.findall(question):
+        if not prefix:
+            found.append((repo, int(number)))
+        elif prefix.count("/") == 1:
+            found.append((prefix, int(number)))
+        else:
+            # ``PR#12`` included: ``PR`` could as well be a repository's
+            # name, and guessing wrong retires a live question.
+            return None
+    found.extend(
+        (owner_repo, int(number))
+        for owner_repo, number in _REF_URL_RE.findall(question)
+    )
+    targets: list[tuple[str, int]] = []
+    for target in found:
+        if target not in targets:
+            targets.append(target)
+    issue_number = row.get("issue_number")
+    if issue_number is not None and (repo, int(issue_number)) not in targets:
+        targets.append((repo, int(issue_number)))
+    return targets
+
+
 def _normalise(question: str) -> str:
     return re.sub(r"\s+", " ", (question or "").lower()).strip(" .?!")
 
@@ -358,10 +422,9 @@ def prune_finished_questions(
 async def _all_references_resolved(
     github: GitHubCLI,
     *,
-    repo: str,
-    numbers: list[str],
+    targets: list[tuple[str, int]],
 ) -> bool:
-    """True when every cited number is closed or merged.
+    """True when every target is closed or merged.
 
     Conservative on purpose. One still-open reference means the question
     retains something to decide, so the row stays. Any probe error at
@@ -370,14 +433,14 @@ async def _all_references_resolved(
     one, since the operator can ignore noise but cannot recover a
     question that was never posted.
     """
-    if not numbers:
+    if not targets:
         return False
 
-    for number in numbers:
+    for repo, number in targets:
         try:
             state = await github.get_issue_or_pr_state(
                 repo,
-                int(number),
+                number,
                 timeout=_STATE_PROBE_TIMEOUT_SECONDS,
             )
         except (GitHubError, TimeoutError, OSError, ValueError):
@@ -442,11 +505,13 @@ async def expire_stale_questions(
 
     probes_used = 0
     for row in state_db.list_unanswered_pending_resumes():
-        numbers = extract_referenced_numbers(row["question"])
-        # Rows citing nothing are skipped without spending budget —
-        # they can never be resolution-expired anyway.
-        if not numbers:
+        targets = resolution_targets(row)
+        # Rows with nothing to check, or citing something that cannot be
+        # looked up, are skipped without spending budget: they can never
+        # be resolution-expired. The TTL pass still retires them on age.
+        if not targets:
             continue
+        numbers = [f"{r}#{n}" for r, n in targets]
 
         # Check the budget against what this row will actually COST,
         # before spending any of it. Testing `probes_used` alone lets a
@@ -477,9 +542,7 @@ async def expire_stale_questions(
             )
             break
         probes_used += len(numbers)
-        if not await _all_references_resolved(
-            github, repo=row["repo"], numbers=numbers
-        ):
+        if not await _all_references_resolved(github, targets=targets):
             continue
         if state_db.expire_pending_resume(
             row["session_id"], EXPIRY_REASON_RESOLVED

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/core/worktree.py

@@ -7,11 +7,12 @@ import contextlib
 import os
 import re
 import secrets
+import shlex
 import shutil
 import stat
 import tempfile
 import time
-from collections.abc import Awaitable, Callable, Iterator, Sequence
+from collections.abc import Awaitable, Callable, Iterator, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -550,6 +551,81 @@ def _relay_git_env(global_config: Path) -> dict[str, str]:
     return env
 
 
+# The git subcommands that talk to origin. The relay runs them on the
+# operator's own config (their helpers, rewrites and proxies apply), so
+# these get only an extra credential helper appended, never a
+# replacement config.
+_NETWORK_SUBCOMMANDS = frozenset({"clone", "fetch", "ls-remote"})
+
+_GH_CREDENTIAL_KEY = "credential.https://github.com.helper"
+
+
+# Global options whose value is the next argument.
+_GIT_OPTIONS_WITH_VALUE = frozenset({
+    "-c", "-C", "--git-dir", "--work-tree", "--namespace",
+    "--config-env", "--super-prefix",
+})
+
+
+def _git_subcommand(args: tuple[str, ...]) -> str | None:
+    """The subcommand in ``git <args>``, skipping global options and the
+    values of those that take one as the next argument."""
+    skip_next = False
+    for arg in args:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg in _GIT_OPTIONS_WITH_VALUE:
+            skip_next = True
+            continue
+        if arg.startswith("-"):
+            continue
+        return arg
+    return None
+
+
+def _with_gh_credential(base: Mapping[str, str]) -> dict[str, str]:
+    """``base`` with gh's login appended as a credential helper for
+    https://github.com, for the relay's own fetch, clone and ls-remote
+    (#398).
+
+    The relay clones over https. On a node where gh is logged in but
+    ``gh auth setup-git`` was never run, git has no credential for a
+    private repository and the first run failed before the agent
+    started. The helper goes in through ``GIT_CONFIG_COUNT``, appended
+    after any entries already there (a unit's ``insteadOf`` rewrite
+    keeps working). Config from the environment is read after every
+    config file, so this helper comes last in git's list: an operator's
+    own helper is asked first and wins when it answers. When gh has no
+    login and no token, the helper answers nothing and git fails as before.
+
+    ``GIT_TERMINAL_PROMPT=0`` is set in every case, including when no
+    helper is added: the relay runs unattended, so a missing credential
+    fails at once instead of waiting on a prompt nobody will answer.
+    No helper is added when gh cannot be found, when
+    ``GIT_CONFIG_COUNT`` is set and is not at most six plain digits (left for git to read or
+    refuse as it does), or when the slot it would take is already set: an
+    entry is never overwritten. An empty count reads as zero.
+    """
+    from ctrlrelay.core.github import _find_gh
+
+    env = dict(base)
+    env["GIT_TERMINAL_PROMPT"] = "0"
+    gh = shutil.which(_find_gh())
+    if gh is None:
+        return env
+    raw = env.get("GIT_CONFIG_COUNT", "").strip()
+    if raw and not (raw.isascii() and raw.isdigit() and len(raw) <= 6):
+        return env
+    count = int(raw) if raw else 0
+    if f"GIT_CONFIG_KEY_{count}" in env or f"GIT_CONFIG_VALUE_{count}" in env:
+        return env
+    env[f"GIT_CONFIG_KEY_{count}"] = _GH_CREDENTIAL_KEY
+    env[f"GIT_CONFIG_VALUE_{count}"] = f"!{shlex.quote(gh)} auth git-credential"
+    env["GIT_CONFIG_COUNT"] = str(count + 1)
+    return env
+
+
 @dataclass
 class WorktreeManager:
     """Manages git worktrees for session isolation."""
@@ -599,6 +675,8 @@ class WorktreeManager:
         would run against a tree origin no longer has.
         """
         cmd = ["git", *args]
+        if env is None and _git_subcommand(args) in _NETWORK_SUBCOMMANDS:
+            env = _with_gh_credential(os.environ)
         effective_timeout = timeout if timeout is not None else self.timeout
         proc = await asyncio.create_subprocess_exec(
             *cmd,

{ctrlrelay-0.28.0 → ctrlrelay-0.28.1}/src/ctrlrelay/pipelines/dev.py

@@ -22,7 +22,11 @@ from ctrlrelay.core.agent_plugins import (
     agent_identity_from_mapping,
 )
 from ctrlrelay.core.budget import is_budget_reason, label_names, session_scope
-from ctrlrelay.core.checkpoint import CheckpointStatus
+from ctrlrelay.core.checkpoint import (
+    CHECKPOINT_TEXT_RULE,
+    CheckpointStatus,
+    shell_checkpoint,
+)
 from ctrlrelay.core.claims import (
     CLAIM_MARKER_PREFIX,
     DISPATCH_FAILED_MARKER,
@@ -943,20 +947,22 @@ def _blocked_and_failed_blocks(
 ) -> str:
     """The BLOCKED and FAILED checkpoint snippets, shared by the code and
     plan contracts (#220). Their DONE blocks differ; these do not."""
-    return f"""**BLOCKED** (need input):
+    blocked = shell_checkpoint(
+        quoted_dir, quoted_path, session_id=session_id,
+        status="BLOCKED_NEEDS_INPUT", field="question", text="<QUESTION>",
+    )
+    failed = shell_checkpoint(
+        quoted_dir, quoted_path, session_id=session_id,
+        status="FAILED", field="error", text="<ERROR>",
+    )
+    return f"""**BLOCKED** (need input). {CHECKPOINT_TEXT_RULE}
 ```bash
-mkdir -p -- {quoted_dir}
-printf '{{"version":"1","status":"BLOCKED_NEEDS_INPUT",'\
-'"session_id":"{session_id}","timestamp":"%s","question":"%s"}}' \\
-  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "<QUESTION>" > {quoted_path}
+{blocked}
 ```
 
-**FAILED**:
+**FAILED**. {CHECKPOINT_TEXT_RULE}
 ```bash
-mkdir -p -- {quoted_dir}
-printf '{{"version":"1","status":"FAILED","session_id":"{session_id}",'\
-'"timestamp":"%s","error":"%s"}}' \\
-  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "<ERROR>" > {quoted_path}
+{failed}
 ```"""