code-coordinator 0.5.504__tar.gz → 0.5.505__tar.gz

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.504
+Version: 0.5.505
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.504
+Version: 0.5.505
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/code_coordinator.egg-info/SOURCES.txt

@@ -177,6 +177,7 @@ coord/commands/agent_ops.py
 coord/commands/audit.py
 coord/commands/backup.py
 coord/commands/chat.py
+coord/commands/ci.py
 coord/commands/codegen.py
 coord/commands/dispatch.py
 coord/commands/dispatch_workers.py
@@ -484,6 +485,7 @@ tests/test_cli_assign_provider.py
 tests/test_cli_assign_repo_drift_2219.py
 tests/test_cli_audit.py
 tests/test_cli_chat_continue.py
+tests/test_cli_ci.py
 tests/test_cli_codegen.py
 tests/test_cli_decide.py
 tests/test_cli_diagnose_capability_rules.py

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/code_coordinator.egg-info/scm_file_list.json

@@ -56,6 +56,7 @@
     "coord/commands/audit.py",
     "coord/commands/backup.py",
     "coord/commands/chat.py",
+    "coord/commands/ci.py",
     "coord/commands/codegen.py",
     "coord/commands/dispatch.py",
     "coord/commands/dispatch_workers.py",
@@ -510,6 +511,7 @@
     "tests/test_cli_assign_repo_drift_2219.py",
     "tests/test_cli_audit.py",
     "tests/test_cli_chat_continue.py",
+    "tests/test_cli_ci.py",
     "tests/test_cli_codegen.py",
     "tests/test_cli_decide.py",
     "tests/test_cli_diagnose_capability_rules.py",

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.504",
+  "tag": "0.5.505",
   "distance": 0,
-  "node": "g49844b3020453abade3c1f818b9dbe244559a8ce",
+  "node": "g5436dee520cfae2bc68cea2d0b9b08cbd47510d9",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-20"

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/coord/ci_github.py

@@ -19,7 +19,7 @@ from dataclasses import dataclass, field
 from datetime import datetime
 
 from coord import github_ops
-from coord.ci_store import CheckRun, CIFailureDetail, JobRun, JobStep, failed_checks
+from coord.ci_store import CheckRun, CIFailureDetail, JobRun, JobStep, RunSummary, failed_checks
 from coord.forge_availability import record_ci_check_fetch
 
 
@@ -671,6 +671,42 @@ class GitHubCi:
             )
         return jobs
 
+    def list_runs_for_branch(
+        self, repo: str, branch: str, *, event: str | None = None, limit: int = 20,
+    ) -> list["RunSummary"]:
+        """The last *limit* Actions runs pushed to *branch* on *repo* (#3405)
+        via ``gh run list``, newest first.
+
+        Best-effort like :meth:`list_jobs_for_run` — never gates a merge, so
+        any read failure (missing ``gh``, timeout, malformed JSON, an
+        unknown repo/branch) degrades to ``[]`` rather than raising or
+        synthesizing a failing placeholder (#1525's fail-closed posture is
+        specific to the merge *gate*; this is a visibility read only).
+        """
+        try:
+            raw = github_ops.get_runs_for_branch(repo, branch, event=event, limit=limit)
+        except (FileNotFoundError, subprocess.TimeoutExpired, RuntimeError, ValueError):
+            return []
+        if not isinstance(raw, list):
+            return []
+        runs: list[RunSummary] = []
+        for entry in raw:
+            if not isinstance(entry, dict):
+                continue
+            runs.append(
+                RunSummary(
+                    run_id=str(entry.get("databaseId", "") or ""),
+                    name=str(entry.get("workflowName") or entry.get("displayTitle") or ""),
+                    status=str(entry.get("status") or ""),
+                    conclusion=entry.get("conclusion") or None,
+                    event=str(entry.get("event") or ""),
+                    branch=str(entry.get("headBranch") or branch),
+                    url=str(entry.get("url") or ""),
+                    created_at=_parse_ts(entry.get("createdAt")),
+                )
+            )
+        return runs
+
     # ── Internal ────────────────────────────────────────────────────────────
 
     def _fetch(self, repo: str, number: int) -> list[CheckRun]:

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/coord/ci_gitlab.py

@@ -49,7 +49,7 @@ from datetime import datetime
 
 import httpx
 
-from coord.ci_store import CheckRun, JobRun, failed_checks
+from coord.ci_store import CheckRun, JobRun, RunSummary, failed_checks
 from coord.forge_availability import record_ci_check_fetch
 
 DEFAULT_HOST = "gitlab.com"
@@ -365,6 +365,57 @@ class GitLabCi:
             ))
         return out
 
+    def list_runs_for_branch(
+        self, repo: str, branch: str, *, event: str | None = None, limit: int = 20,
+    ) -> list[RunSummary]:
+        """The last *limit* pipelines run against *branch* on *repo* (#3405),
+        newest first, via GitLab's project pipelines list API.
+
+        *event* maps to GitLab's pipeline ``source`` field (``"push"``,
+        ``"web"``, ``"schedule"``, ``"merge_request_event"``, ...) — the
+        closest GitLab concept to GitHub Actions' ``event``. Best-effort like
+        :meth:`list_jobs_for_run`: any read failure (missing token, network
+        error, malformed JSON) degrades to ``[]`` rather than raising, since
+        this is a visibility read, not a gate.
+        """
+        token = self._token
+        if not token:
+            return []
+        params: dict[str, object] = {
+            "ref": branch, "per_page": limit, "order_by": "id", "sort": "desc",
+        }
+        if event:
+            params["source"] = event
+        try:
+            with self._client() as client:
+                resp = client.get(
+                    f"/projects/{_project_path(repo)}/pipelines", params=params,
+                )
+                resp.raise_for_status()
+                pipelines = resp.json()
+        except (httpx.HTTPError, ValueError):
+            return []
+        if not isinstance(pipelines, list):
+            return []
+        runs: list[RunSummary] = []
+        for pipeline in pipelines:
+            if not isinstance(pipeline, dict):
+                continue
+            status, conclusion = _map_status(str(pipeline.get("status", "")))
+            runs.append(
+                RunSummary(
+                    run_id=str(pipeline.get("id", "") or ""),
+                    name=str(pipeline.get("name") or pipeline.get("source") or ""),
+                    status=status,
+                    conclusion=conclusion,
+                    event=str(pipeline.get("source") or ""),
+                    branch=str(pipeline.get("ref") or branch),
+                    url=str(pipeline.get("web_url") or ""),
+                    created_at=_parse_ts(pipeline.get("created_at")),
+                )
+            )
+        return runs
+
     # ── writes ───────────────────────────────────────────────────────────
 
     def rerun_for_pr(self, repo: str, number: int) -> bool:

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/coord/ci_store.py

@@ -92,6 +92,39 @@ class JobRun:
     job_id: str = ""
 
 
+@dataclass
+class RunSummary:
+    """One CI run (a GitHub Actions run / GitLab pipeline) scoped to a
+    *branch*, not a PR (#3405).
+
+    ``CheckRun``/``JobRun`` are both PR-scoped (``list_checks_for_pr``/
+    ``list_jobs_for_run(repo, run_id)`` where ``run_id`` itself is only ever
+    discovered via a PR's checks) — there was no way to express "what
+    happened on the last N pushes to `main`", because a push-to-main run
+    belongs to no PR at all. That blind spot is what let a real `windows`
+    job failure on `main` get misattributed to the (advisory,
+    ``continue-on-error``) `postgres` job for weeks (#3378 item 1, #3380,
+    #3385): diagnosing "is trunk healthy, and why not" required raw
+    ``gh run list``/``gh run view``, with no `coord` seam to go through.
+
+    ``conclusion`` follows the same vocabulary as :class:`CheckRun`'s own
+    field (success/failure/cancelled/skipped/... while ``status ==
+    "completed"``, ``None`` while still in flight) — this is a read-only
+    surfacing view, so unlike ``CheckRun`` there is no allow-list/fail-closed
+    posture to preserve here; nothing in :mod:`coord.merge_queue`'s gate
+    reads a ``RunSummary``.
+    """
+
+    run_id: str
+    name: str
+    status: str
+    conclusion: str | None
+    event: str
+    branch: str
+    url: str
+    created_at: float | None
+
+
 @dataclass
 class CIFailureDetail:
     """Structured detail behind a CONFIRMED CI failure (#3114) — the failing
@@ -326,6 +359,23 @@ class CiStore(Protocol):
         """
         ...
 
+    def list_runs_for_branch(
+        self, repo: str, branch: str, *, event: str | None = None, limit: int = 20,
+    ) -> list[RunSummary]:
+        """The last *limit* CI runs pushed to *branch* on *repo* (#3405),
+        newest first — the branch/event-scoped read every method above this
+        one lacks (see :class:`RunSummary`'s docstring for why that gap
+        mattered).
+
+        *event* narrows to one GitHub Actions/GitLab pipeline trigger event
+        (``"push"``, ``"pull_request"``, ...) when given; ``None`` returns
+        every event. Purely a visibility read, same posture as
+        :meth:`list_jobs_for_run` — best-effort, returns ``[]`` on any read
+        failure rather than raising or synthesizing a failing placeholder,
+        since nothing here gates a merge.
+        """
+        ...
+
 
 class NoOpCi:
     """Always-available fallback that returns no checks and reruns nothing.
@@ -367,6 +417,13 @@ class NoOpCi:
         re-run (#2252)."""
         return False
 
+    def list_runs_for_branch(
+        self, repo: str, branch: str, *, event: str | None = None, limit: int = 20,
+    ) -> list[RunSummary]:
+        """No-op: CI gating is disabled entirely, so there is no run
+        history to report (#3405)."""
+        return []
+
 
 # ── Classification helpers ──────────────────────────────────────────────────
 

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/coord/cli.py

@@ -173,6 +173,11 @@ from coord.commands.plan_followup import (
 # completed assignment) — see coord/commands/pr.py's `_PrGroup`.
 from coord.commands.pr import pr_group
 
+# #3405: `coord ci` — the branch/event-scoped CI-history seam over CiStore
+# (`runs`/`jobs`/`checks`), so diagnosing a red `main` never has to fall back
+# to raw `gh run list`/`gh run view`.
+from coord.commands.ci import ci_group
+
 
 # #1182: thresholds past which a stale non-editable install escalates from the
 # mild "edits won't reach the CLI" note to a loud STALE INSTALL banner.
@@ -489,6 +494,7 @@ main.add_command(drive_queue_group)
 main.add_command(escalate_group)
 main.add_command(decide)
 main.add_command(pr_group)
+main.add_command(ci_group)
 main.add_command(fix)
 main.add_command(review)
 main.add_command(approve_plan)

code_coordinator-0.5.505/coord/commands/ci.py

@@ -0,0 +1,210 @@
+"""`coord ci` — the branch/event-scoped CI-history seam (#3405).
+
+Diagnosing "why is `main` red?" (2026-09-19, #3394) had no `coord` route at
+all: every read fell back to raw `gh run list`/`gh run view`, even though
+`coord.ci_store.CiStore` already models everything needed
+(`list_jobs_for_run` is exactly `gh run view <id> --json jobs`). The gap
+wasn't a missing wrapper, it was a missing *axis* — every existing `CiStore`
+method is PR-scoped (``..._for_pr(repo, number)``), and a push-to-`main` run
+belongs to no PR. :meth:`coord.ci_store.CiStore.list_runs_for_branch` closes
+that; this module is the CLI surface over it plus the two capabilities that
+already existed but had no verb: per-run job detail and per-PR checks.
+
+Read-only throughout — mirrors ``coord issue view``/``coord issue list``'s
+posture (see ``coord/commands/issues.py``): every subcommand here talks to
+the configured :class:`~coord.ci_store.CiStore` directly, the same way those
+two call ``github_ops`` directly, rather than routing through the daemon —
+there is no write here for the daemon seam to arbitrate. This is also what
+lets a worker (``gh`` deny-listed by policy, not by host capability) inspect
+CI state without asking the coordinator to relay it by hand: ``coord ci
+...`` is the sanctioned command, not a raw ``gh`` invocation.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from coord.commands._common import _CONFIG_OPTION, _load_config, _resolve_repo_slug
+from coord.config import Config
+
+
+def _build_ci_store(cfg: Config):
+    from coord.ci_store import build_ci_store  # noqa: PLC0415
+
+    return build_ci_store(
+        cfg.ci_store.type, host=cfg.ci_store.host, token_env=cfg.ci_store.token_env,
+    )
+
+
+def _default_branch(cfg: Config, repo: str) -> str:
+    entry = cfg.repo(repo)
+    return entry.default_branch if entry is not None else "main"
+
+
+# Mirrors `coord.ci_store._PASSING_CONCLUSIONS` — a job/check conclusion not
+# in this allow-list is what "failing" means throughout this module. Kept as
+# a local copy rather than importing the private constant: this is a
+# read-only rendering choice (which rows to flag), never a gate, so it must
+# not be mistaken for reuse of the merge gate's own fail-closed logic.
+_PASSING_JOB_CONCLUSIONS = frozenset({"success", "skipped", "neutral"})
+
+
+def _conclusion_is_failing(conclusion: str | None) -> bool:
+    """True when a job/check/run conclusion should render as a failure row.
+
+    Shared by all three subcommands below (job rows, run rows, check rows) —
+    same allow-list, same reasoning, one function. A still-in-flight
+    conclusion (``None``) and an affirmatively benign one
+    (success/skipped/neutral) both read as not-failing — only a completed,
+    non-benign conclusion (failure/cancelled/timed_out/... or anything this
+    module has never seen) does. #3405's whole point: a `skipped` job (e.g.
+    the advisory `postgres` job) must never render next to a real failure
+    (`windows`) as if both broke the build.
+    """
+    return conclusion is not None and conclusion not in _PASSING_JOB_CONCLUSIONS
+
+
+@click.group("ci")
+def ci_group() -> None:
+    """CI history/detail through the backend-agnostic seam (#3405).
+
+    Widens the pre-existing PR-scoped `CiStore` reads (`coord.ci_github`'s
+    `list_checks_for_pr`/`list_jobs_for_run`) with the branch/event-scoped
+    question that actually recurs: "what happened on the last N pushes to
+    `main`, and which job failed" — see `list_runs_for_branch`'s docstring.
+    """
+
+
+@ci_group.command(
+    "runs",
+    help=(
+        "List the last N CI runs on a branch. REPO is the local repo name "
+        "from coordinator.yml (or a raw OWNER/REPO slug). Defaults to the "
+        "repo's configured default branch and every event; --event narrows "
+        "to one trigger (push, pull_request, ...).\n\n"
+        "This is the read `gh run list --workflow=... --event=push` used to "
+        "be the only way to get: 'is trunk healthy, and since when.'"
+    ),
+)
+@click.argument("repo")
+@click.option("--branch", default=None, help="Branch to list runs for (default: repo's default branch).")
+@click.option("--event", default=None, help="Filter to one trigger event (e.g. push, pull_request).")
+@click.option("--limit", type=int, default=20, help="Max runs to return (default: 20).")
+@click.option("--json", "as_json", is_flag=True, help="Print raw JSON instead of a table.")
+@_CONFIG_OPTION
+def ci_runs_cmd(
+    repo: str,
+    branch: str | None,
+    event: str | None,
+    limit: int,
+    as_json: bool,
+    config_path: Path,
+) -> None:
+    cfg = _load_config(config_path)
+    slug = _resolve_repo_slug(cfg, repo)
+    branch = branch or _default_branch(cfg, repo)
+    ci_store = _build_ci_store(cfg)
+
+    try:
+        runs = ci_store.list_runs_for_branch(slug, branch, event=event, limit=limit)
+    except Exception as e:  # noqa: BLE001
+        click.echo(f"error: ci runs failed: {e}", err=True)
+        sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps([vars(r) for r in runs], indent=2))
+        return
+    if not runs:
+        suffix = f" event={event}" if event else ""
+        click.echo(f"no runs found for {slug}@{branch}{suffix}")
+        return
+    click.echo(f"{slug}@{branch} — {len(runs)} run(s)")
+    for r in runs:
+        marker = " FAILED" if _conclusion_is_failing(r.conclusion) else ""
+        click.echo(
+            f"{r.run_id}\t{r.event}\t{r.status}\t{r.conclusion or '-'}"
+            f"{marker}\t{r.name}\t{r.url}"
+        )
+
+
+@ci_group.command(
+    "jobs",
+    help=(
+        "Show the per-job breakdown of a single Actions run — the "
+        "coord equivalent of `gh run view <run-id> --json jobs`. REPO is "
+        "the local repo name from coordinator.yml; RUN_ID is the numeric "
+        "Actions run id (from `coord ci runs`, or a CheckRun's run_id).\n\n"
+        "One row per job, flagging exactly the jobs whose conclusion is a "
+        "real failure — a `skipped` (e.g. advisory) job is never flagged, "
+        "matching CiStore's own allow-list semantics."
+    ),
+)
+@click.argument("repo")
+@click.argument("run_id")
+@click.option("--json", "as_json", is_flag=True, help="Print raw JSON instead of a table.")
+@_CONFIG_OPTION
+def ci_jobs_cmd(repo: str, run_id: str, as_json: bool, config_path: Path) -> None:
+    cfg = _load_config(config_path)
+    slug = _resolve_repo_slug(cfg, repo)
+    ci_store = _build_ci_store(cfg)
+
+    try:
+        jobs = ci_store.list_jobs_for_run(slug, run_id)
+    except Exception as e:  # noqa: BLE001
+        click.echo(f"error: ci jobs failed: {e}", err=True)
+        sys.exit(1)
+
+    if as_json:
+        import dataclasses  # noqa: PLC0415
+
+        click.echo(json.dumps([dataclasses.asdict(j) for j in jobs], indent=2))
+        return
+    if not jobs:
+        click.echo(f"no jobs found for {slug} run {run_id}")
+        return
+    failing = [j for j in jobs if _conclusion_is_failing(j.conclusion)]
+    click.echo(f"{slug} run {run_id} — {len(jobs)} job(s), {len(failing)} failing")
+    for j in jobs:
+        marker = " FAILED" if _conclusion_is_failing(j.conclusion) else ""
+        runner = j.runner_name or "-"
+        click.echo(f"{j.name}\t{j.conclusion or 'pending'}{marker}\t{runner}")
+
+
+@ci_group.command(
+    "checks",
+    help=(
+        "List every CI check reported for a PR (required and advisory), "
+        "the coord equivalent of `gh pr checks`. REPO is the local repo "
+        "name from coordinator.yml; PR is the PR number."
+    ),
+)
+@click.argument("repo")
+@click.argument("pr", type=int)
+@click.option("--json", "as_json", is_flag=True, help="Print raw JSON instead of a table.")
+@_CONFIG_OPTION
+def ci_checks_cmd(repo: str, pr: int, as_json: bool, config_path: Path) -> None:
+    cfg = _load_config(config_path)
+    slug = _resolve_repo_slug(cfg, repo)
+    ci_store = _build_ci_store(cfg)
+
+    try:
+        checks = ci_store.list_all_checks_for_pr(slug, pr)
+    except Exception as e:  # noqa: BLE001
+        click.echo(f"error: ci checks failed: {e}", err=True)
+        sys.exit(1)
+
+    if as_json:
+        import dataclasses  # noqa: PLC0415
+
+        click.echo(json.dumps([dataclasses.asdict(c) for c in checks], indent=2))
+        return
+    if not checks:
+        click.echo(f"no checks reported for {slug}#{pr}")
+        return
+    for c in checks:
+        marker = " FAILED" if c.status == "completed" and _conclusion_is_failing(c.conclusion) else ""
+        click.echo(f"{c.name}\t{c.status}\t{c.conclusion or '-'}{marker}\t{c.url}")

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/coord/github_ops.py

@@ -2542,6 +2542,18 @@ PR_CHECKS_JSON_FIELDS: tuple[str, ...] = (
     "name", "state", "bucket", "link", "startedAt", "completedAt",
 )
 
+# #3405: fields requested from `gh run list --json` by :func:`get_runs_for_branch`
+# — the branch/event-scoped counterpart to `PR_CHECKS_JSON_FIELDS` above.
+# Pinned in the same style of regression test
+# (tests/test_github_ops.py::TestRunListJsonFieldsAreValid), which shells out
+# to `gh run list --help` and asserts every field here is one `gh` actually
+# advertises, so a `gh` schema change fails a test instead of silently
+# breaking `coord ci runs`.
+RUN_LIST_JSON_FIELDS: tuple[str, ...] = (
+    "databaseId", "displayTitle", "workflowName", "status", "conclusion",
+    "event", "headBranch", "url", "createdAt",
+)
+
 # #1564 Addendum 2: the fleet that surfaced this issue runs `gh` versions that
 # disagree about whether `gh pr checks` even *has* a `--json` flag —
 # dellserver's 2.45.0 (Ubuntu's apt package) does not: `gh pr checks --json
@@ -2715,6 +2727,38 @@ def get_pr_checks(repo: str, number: int) -> list[dict]:
     return json.loads(stdout or "[]")
 
 
+def get_runs_for_branch(
+    repo: str, branch: str, *, event: str | None = None, limit: int = 20,
+) -> list[dict]:
+    """Return ``gh run list``'s raw run list for *branch* on *repo* (#3405).
+
+    The branch/event-scoped sink :meth:`coord.ci_github.GitHubCi.
+    list_runs_for_branch` needs and :func:`get_pr_checks` structurally
+    cannot provide — a push-to-`main` run belongs to no PR, so there is no
+    PR number to key a ``gh pr checks`` read on. Backs the question that
+    actually recurs (#3378 item 1, #3380, #3385): "what happened on the last
+    N pushes to `main`, and which job failed" — previously answerable only
+    via raw ``gh run list --workflow=... --event=push``.
+
+    Uses ``_gh_json`` (not the hand-rolled subprocess call ``get_pr_checks``
+    needs for its exit-code nuance) since ``gh run list`` exits 0 with an
+    empty JSON array when nothing matches — there is no "exited non-zero but
+    still has usable stdout" case to special-case here. Raises
+    ``RuntimeError``/:class:`GhError` on a genuine read failure (bad repo,
+    auth, rate-limit); callers on the read-only surfacing path
+    (:meth:`~coord.ci_github.GitHubCi.list_runs_for_branch`) treat that the
+    same as "no runs to show", never as evidence either way — this is
+    visibility, not a gate.
+    """
+    args = [
+        "run", "list", "--repo", repo, "--branch", branch,
+        "--limit", str(limit), "--json", ",".join(RUN_LIST_JSON_FIELDS),
+    ]
+    if event:
+        args += ["--event", event]
+    return _gh_json(*args, default=[], caller="github_ops.get_runs_for_branch")
+
+
 def get_run_jobs(repo: str, run_id: str) -> list[dict]:
     """Return ``gh api .../actions/runs/{run_id}/jobs``' raw ``jobs`` list (#1892).
 

{code_coordinator-0.5.504 → code_coordinator-0.5.505}/tests/test_ci_gitlab.py

@@ -462,6 +462,75 @@ class TestGitLabCiListJobsForRun:
         assert store.list_jobs_for_run("acme/api", "55") == []
 
 
+def _pipeline(pid: int, *, ref: str = "main", source: str = "push",
+              status: str = "success", web_url: str = "",
+              created_at: str | None = None) -> dict:
+    return {
+        "id": pid, "ref": ref, "source": source, "status": status,
+        "web_url": web_url, "created_at": created_at,
+    }
+
+
+class TestGitLabCiListRunsForBranch:
+    """#3405: the branch/event-scoped read — GitLab's own concept of a
+    push-to-`main` run is a pipeline with ``ref == branch``, which no
+    existing (PR-scoped) `GitLabCi` method could express."""
+
+    def test_maps_pipeline_fields(self, monkeypatch) -> None:
+        store = GitLabCi(token_env="GL_TOK")
+        monkeypatch.setenv("GL_TOK", "secret")
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            if request.url.path.endswith("/pipelines"):
+                assert request.url.params["ref"] == "main"
+                return httpx.Response(200, json=[
+                    _pipeline(123, status="failed", web_url="https://gl/p/123",
+                              created_at="2026-09-19T00:00:00.000Z"),
+                    _pipeline(124, status="skipped"),
+                ])
+            raise AssertionError(f"unexpected request: {request.url}")
+
+        _install_transport(monkeypatch, store, handler)
+        runs = store.list_runs_for_branch("acme/api", "main")
+
+        assert [r.run_id for r in runs] == ["123", "124"]
+        failed_run = runs[0]
+        assert failed_run.conclusion == "failure"
+        assert failed_run.event == "push"
+        assert failed_run.branch == "main"
+        assert failed_run.url == "https://gl/p/123"
+        assert failed_run.created_at is not None
+        assert runs[1].conclusion == "skipped"
+
+    def test_event_forwarded_as_source_param(self, monkeypatch) -> None:
+        store = GitLabCi(token_env="GL_TOK")
+        monkeypatch.setenv("GL_TOK", "secret")
+        seen_params: dict = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            seen_params.update(request.url.params)
+            return httpx.Response(200, json=[])
+
+        _install_transport(monkeypatch, store, handler)
+        store.list_runs_for_branch("acme/api", "main", event="push")
+        assert seen_params.get("source") == "push"
+
+    def test_no_token_returns_empty(self, monkeypatch) -> None:
+        store = GitLabCi(token_env="GL_TOK_UNSET")
+        monkeypatch.delenv("GL_TOK_UNSET", raising=False)
+        assert store.list_runs_for_branch("acme/api", "main") == []
+
+    def test_read_error_returns_empty(self, monkeypatch) -> None:
+        store = GitLabCi(token_env="GL_TOK")
+        monkeypatch.setenv("GL_TOK", "secret")
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ConnectError("down", request=request)
+
+        _install_transport(monkeypatch, store, handler)
+        assert store.list_runs_for_branch("acme/api", "main") == []
+
+
 # ── build_ci_store / config ──────────────────────────────────────────────────
 
 class TestBuildCiStoreGitlab: