code-mower 0.9.2b1__tar.gz → 0.9.3b1__tar.gz

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 0.9.2b1
+Version: 0.9.3b1
 Summary: Multi-reviewer AI code audit orchestration
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
@@ -113,8 +113,9 @@ Plain `board serve` is read-only. If the default Board port is busy, the CLI
 uses a nearby free loopback port and prints the URL; an explicit `--port` stays
 strict and reports a friendly conflict. To build local history while the browser
 view is open, run `code-mower board serve --repo OWNER/REPO --record-events`; it
-records at most one snapshot every 60 seconds by default. To append one snapshot
-without serving the browser view, run
+records at most one snapshot every 60 seconds by default. The Board header shows
+the Code Mower version serving the page and flags when a restart is needed after
+an upgrade. To append one snapshot without serving the browser view, run
 `code-mower board record --repo OWNER/REPO` from the repository checkout; it
 writes metadata-only snapshots to `.code-mower/board/events.jsonl` with default
 14-day and 500-event retention. `code-mower board events` prints recent stored
@@ -169,13 +170,13 @@ after reinstalling, especially when switching between pipx and uv.
 | C. Builder experiment | You want to compare authoring loops before trusting them broadly. | Use a work order or experiment spec, run `code-mower builder-experiment run` around an explicit command, then review the source-free `authoringRun` artifact and normal audit evidence. | [Builder Experiments](docs/builder-experiments.md) |
 
 The current package-index announcement entry point is the tagged
-[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.2-beta.1/docs/try-in-10-minutes.md)
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.3-beta.1/docs/try-in-10-minutes.md)
 guide. The v0.9 beta includes the completed native Board work plus the adoption
-and upgrade hardening from recent install rehearsals; v0.9.2 keeps the path
-simple by removing the retired third-party observe bridge, softening
-dispatch-token expiry metadata when the secret is present, and making
-stale-audit waits name the runner/dispatcher requeue path. Package-only users
-can start from the public package rather than a source checkout.
+and upgrade hardening from recent install rehearsals; v0.9.3 keeps the path
+smooth by clarifying starter-package diagnostics, surfacing richer top-level
+lane status detail, showing Board version drift, and reporting standalone pin
+drift during existing-repo upgrades. Package-only users can start from the
+public package rather than a source checkout.
 
 ## What Calibration Does And Does Not Prove
 
@@ -206,7 +207,7 @@ Provider-contract baseline for the next release train:
 
 For release verification,
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the package-index procedure for `v0.9.2-beta.1` / `code-mower==0.9.2b1`. The
+the package-index procedure for `v0.9.3-beta.1` / `code-mower==0.9.3b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -392,8 +393,8 @@ measurement work.
 
 ## Installation Status
 
-The current package-index beta baseline is `v0.9.2-beta.1`, with pinned package
-install spec `code-mower==0.9.2b1`. Release evidence is recorded on the GitHub
+The current package-index beta baseline is `v0.9.3-beta.1`, with pinned package
+install spec `code-mower==0.9.3b1`. Release evidence is recorded on the GitHub
 release and in the first-user install rehearsal. The public repository is
 [codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), and
 GitHub releases remain the auditable source for tags, build artifacts, and

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/README.md

@@ -96,8 +96,9 @@ Plain `board serve` is read-only. If the default Board port is busy, the CLI
 uses a nearby free loopback port and prints the URL; an explicit `--port` stays
 strict and reports a friendly conflict. To build local history while the browser
 view is open, run `code-mower board serve --repo OWNER/REPO --record-events`; it
-records at most one snapshot every 60 seconds by default. To append one snapshot
-without serving the browser view, run
+records at most one snapshot every 60 seconds by default. The Board header shows
+the Code Mower version serving the page and flags when a restart is needed after
+an upgrade. To append one snapshot without serving the browser view, run
 `code-mower board record --repo OWNER/REPO` from the repository checkout; it
 writes metadata-only snapshots to `.code-mower/board/events.jsonl` with default
 14-day and 500-event retention. `code-mower board events` prints recent stored
@@ -152,13 +153,13 @@ after reinstalling, especially when switching between pipx and uv.
 | C. Builder experiment | You want to compare authoring loops before trusting them broadly. | Use a work order or experiment spec, run `code-mower builder-experiment run` around an explicit command, then review the source-free `authoringRun` artifact and normal audit evidence. | [Builder Experiments](docs/builder-experiments.md) |
 
 The current package-index announcement entry point is the tagged
-[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.2-beta.1/docs/try-in-10-minutes.md)
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.3-beta.1/docs/try-in-10-minutes.md)
 guide. The v0.9 beta includes the completed native Board work plus the adoption
-and upgrade hardening from recent install rehearsals; v0.9.2 keeps the path
-simple by removing the retired third-party observe bridge, softening
-dispatch-token expiry metadata when the secret is present, and making
-stale-audit waits name the runner/dispatcher requeue path. Package-only users
-can start from the public package rather than a source checkout.
+and upgrade hardening from recent install rehearsals; v0.9.3 keeps the path
+smooth by clarifying starter-package diagnostics, surfacing richer top-level
+lane status detail, showing Board version drift, and reporting standalone pin
+drift during existing-repo upgrades. Package-only users can start from the
+public package rather than a source checkout.
 
 ## What Calibration Does And Does Not Prove
 
@@ -189,7 +190,7 @@ Provider-contract baseline for the next release train:
 
 For release verification,
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the package-index procedure for `v0.9.2-beta.1` / `code-mower==0.9.2b1`. The
+the package-index procedure for `v0.9.3-beta.1` / `code-mower==0.9.3b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -375,8 +376,8 @@ measurement work.
 
 ## Installation Status
 
-The current package-index beta baseline is `v0.9.2-beta.1`, with pinned package
-install spec `code-mower==0.9.2b1`. Release evidence is recorded on the GitHub
+The current package-index beta baseline is `v0.9.3-beta.1`, with pinned package
+install spec `code-mower==0.9.3b1`. Release evidence is recorded on the GitHub
 release and in the first-user install rehearsal. The public repository is
 [codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), and
 GitHub releases remain the auditable source for tags, build artifacts, and

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-mower"
-version = "0.9.2b1"
+version = "0.9.3b1"
 description = "Multi-reviewer AI code audit orchestration"
 requires-python = ">=3.12"
 readme = "README.md"

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/__init__.py

@@ -1,3 +1,3 @@
 """Code Mower package."""
 
-__version__ = "0.9.2b1"
+__version__ = "0.9.3b1"

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/board.py

@@ -15,11 +15,13 @@ from dataclasses import dataclass
 from datetime import UTC, datetime
 from http import HTTPStatus
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import metadata
 from pathlib import Path
 from threading import Lock
 from typing import Any
 from urllib.parse import urlparse
 
+from . import __version__ as CODE_MOWER_VERSION
 from . import board_store
 from . import lane_status
 from . import reviewer_spend
@@ -120,6 +122,22 @@ def _candidate_ports(config: BoardConfig) -> list[int]:
     return list(range(config.port, last_port + 1))
 
 
+def _installed_package_version() -> str:
+    try:
+        return metadata.version("code-mower")
+    except metadata.PackageNotFoundError:
+        return ""
+
+
+def board_version_payload() -> dict[str, Any]:
+    installed_version = _installed_package_version()
+    return {
+        "serving_version": CODE_MOWER_VERSION,
+        "installed_version": installed_version,
+        "restart_recommended": bool(installed_version and installed_version != CODE_MOWER_VERSION),
+    }
+
+
 def _explicit_port_conflict_message(host: str, port: int) -> str:
     suggestions = list(range(port + 1, min(65535, port + 3) + 1))
     suggestion_text = f" such as {', '.join(str(candidate) for candidate in suggestions)}" if suggestions else ""
@@ -171,6 +189,7 @@ def status_payload(
     payload["board"] = {
         "schema": "code_mower.board.v1",
         "mode": "local_recording" if config.record_events else "local_read_only",
+        "version": board_version_payload(),
         "refresh_seconds": config.refresh_seconds,
         "local_paths": "shown" if config.show_local_paths else "redacted",
         "recording": {
@@ -628,7 +647,7 @@ def render_board_html(config: BoardConfig) -> str:
 </head>
 <body>
   <header>
-    <div><h1>Code Mower Board</h1><div class="muted" id="repo"></div></div>
+    <div><h1>Code Mower Board</h1><div class="muted" id="repo"></div><div class="muted" id="version"></div></div>
     <div class="muted" id="generated">Loading...</div>
   </header>
   <main>
@@ -671,6 +690,12 @@ def render_board_html(config: BoardConfig) -> str:
     }}
     function render(data) {{
       document.getElementById("repo").textContent = REPO;
+      const version = data.board?.version || {{}};
+      const servingVersion = version.serving_version || "unknown";
+      const installedVersion = version.installed_version || servingVersion;
+      document.getElementById("version").textContent = version.restart_recommended
+        ? `serving ${{servingVersion}}; installed ${{installedVersion}} available after restart`
+        : `serving ${{servingVersion}}`;
       document.getElementById("generated").innerHTML = data.generated_at ? `Generated ${{localTime(data.generated_at)}}` : "Loading...";
       const prs = data.remote?.pull_requests || [];
       const runs = data.remote?.workflow_runs || [];
@@ -683,6 +708,7 @@ def render_board_html(config: BoardConfig) -> str:
       const spendGroups = spend.groups || [];
       put("summary", [
         `<div class="metric"><span class="muted">Next action</span><b>${{esc(data.next_action || "inspect")}}</b></div>`,
+        data.next_detail ? `<div class="metric"><span class="muted">Detail</span><b>${{esc(data.next_detail)}}</b></div>` : "",
         `<div class="metric"><span class="muted">GitHub</span><b class="${{data.remote?.available ? "ok" : "warn"}}">${{data.remote?.available ? "available" : "unavailable"}}</b></div>`,
         `<div class="metric"><span class="muted">Open PRs</span><b>${{prs.length}}</b></div>`,
         `<div class="metric"><span class="muted">Owner queue</span><b class="${{ownerQueue.length ? "warn" : "ok"}}">${{ownerQueue.length}}</b></div>`,

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/doctor_checks/__init__.py

@@ -32,7 +32,10 @@ from .github_human_token import (
     human_automation_token_config,
     human_automation_token_required,
 )
-from .github_trusted_authors import trusted_author_variable_statuses
+from .github_trusted_authors import (
+    trusted_author_variable_probe,
+    trusted_author_variable_statuses,
+)
 from .groups import GROUP_LABELS, doctor_check_group_id
 from .models import (
     STATUS_FAIL,
@@ -113,6 +116,7 @@ __all__ = [
     "check_macos_runner_launchagent",
     "check_github_setup",
     "check_human_automation_token",
+    "trusted_author_variable_probe",
     "trusted_author_variable_statuses",
     "check_repository_posture",
     "check_lane_runtime",

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/doctor_checks/adoption.py

@@ -170,7 +170,7 @@ def check_adoption_posture_guidance(
             name="doctor.adoption.posture_hint",
             status=STATUS_WARN,
             message=(
-                "default reviewer-gate posture found local provider setup gaps"
+                "default reviewer-gate posture checks local reviewer CLIs on this host"
             ),
             detail={
                 "adoption_posture": adoption_posture,
@@ -186,9 +186,12 @@ def check_adoption_posture_guidance(
                 ],
             },
             remediation=(
-                "If this host only coordinates or observes hosted builders, "
-                "rerun with `--orchestrator-only` or `--hosted-builders`; "
-                "otherwise finish the local CLI/token setup for the listed lanes."
+                "If this host only coordinates work, rerun "
+                "`code-mower doctor --adoption --orchestrator-only --repo OWNER/REPO`. "
+                "If it observes hosted builder lanes, rerun "
+                "`code-mower doctor --adoption --hosted-builders --repo OWNER/REPO`. "
+                "Only keep the default reviewer-gate posture on machines that "
+                "run local reviewer CLIs."
             ),
         ),
     )
@@ -205,6 +208,7 @@ def check_adoption_setup(
     config_source: str = "",
     repo_root: Path | None = None,
     trusted_author_variables: Mapping[str, str] | None = None,
+    trusted_author_variable_errors: Mapping[str, Any] | None = None,
 ) -> tuple[DoctorCheck, ...]:
     """Return first-run adoption posture checks."""
 
@@ -371,10 +375,16 @@ def check_adoption_setup(
     }
     if trusted_author_variables is not None:
         variable_status = {
-            name: str(trusted_author_variables.get(name) or "missing")
+            name: str(trusted_author_variables.get(name) or "not_confirmed")
             for name in TRUSTED_AUDIT_AUTHOR_VARIABLES
         }
         trusted_detail["variable_status"] = variable_status
+        if trusted_author_variable_errors:
+            trusted_detail["variable_read_errors"] = {
+                name: trusted_author_variable_errors[name]
+                for name in sorted(trusted_author_variable_errors)
+                if name in TRUSTED_AUDIT_AUTHOR_VARIABLES
+            }
         all_present = all(
             variable_status[name] == "present" for name in TRUSTED_AUDIT_AUTHOR_VARIABLES
         )
@@ -388,6 +398,27 @@ def check_adoption_setup(
                 )
             )
             return tuple(checks)
+        if any(
+            variable_status[name] == "not_confirmed"
+            for name in TRUSTED_AUDIT_AUTHOR_VARIABLES
+        ):
+            checks.append(
+                DoctorCheck(
+                    name="doctor.adoption.trusted_authors",
+                    status=STATUS_WARN,
+                    message=(
+                        "trusted audit-comment author variables were not fully confirmed"
+                    ),
+                    detail=trusted_detail,
+                    remediation=(
+                        "Ensure `gh auth status` can read repository Actions "
+                        "variables for this repo, then set CLAUDE_AUDIT_BOT_AUTHORS "
+                        "and CODEX_BOT_AUTHORS to the GitHub logins that may post "
+                        "trusted audit verdicts."
+                    ),
+                )
+            )
+            return tuple(checks)
 
     checks.append(
         DoctorCheck(

code_mower-0.9.3b1/src/code_mower/doctor_checks/github_trusted_authors.py

@@ -0,0 +1,72 @@
+"""GitHub repository variable checks for trusted audit-comment authors."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from .github_api import _github_api_json
+
+
+def trusted_author_variable_probe(
+    *,
+    gh_path: str,
+    slug: str,
+    variables: Iterable[str],
+    http_timeout: int,
+) -> dict[str, Any]:
+    """Return safe probe results for trusted-author repository variables."""
+
+    statuses: dict[str, str] = {}
+    read_errors: dict[str, dict[str, Any]] = {}
+    for variable in variables:
+        name = str(variable).strip()
+        if not name:
+            continue
+        payload, _detail = _github_api_json(
+            gh_path,
+            f"repos/{slug}/actions/variables/{name}",
+            http_timeout=http_timeout,
+        )
+        if payload is None:
+            statuses[name] = "not_confirmed"
+            read_errors[name] = {
+                key: value
+                for key, value in _detail.items()
+                if key
+                in {
+                    "endpoint",
+                    "returncode",
+                    "error_type",
+                    "parse_error",
+                    "output_redacted",
+                    "output_line_count",
+                }
+            }
+        elif str(payload.get("value") or "").strip():
+            statuses[name] = "present"
+        else:
+            statuses[name] = "empty"
+    return {"statuses": statuses, "read_errors": read_errors}
+
+
+def trusted_author_variable_statuses(
+    *,
+    gh_path: str,
+    slug: str,
+    variables: Iterable[str],
+    http_timeout: int,
+) -> dict[str, str]:
+    """Return safe presence statuses for trusted-author repository variables."""
+
+    probe = trusted_author_variable_probe(
+        gh_path=gh_path,
+        slug=slug,
+        variables=variables,
+        http_timeout=http_timeout,
+    )
+    statuses = probe.get("statuses")
+    return dict(statuses) if isinstance(statuses, dict) else {}
+
+
+__all__ = ("trusted_author_variable_probe", "trusted_author_variable_statuses")

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/doctor_checks/provider_review_hygiene.py

@@ -21,6 +21,7 @@ def check_review_hygiene(
     *,
     effective_lane: Mapping[str, Any] | None = None,
     repo_root: Path | None = None,
+    missing_workflow_is_warning: bool = False,
 ) -> DoctorCheck:
     """Verify that merge-authority lanes have stale terminal-label protection."""
 
@@ -108,24 +109,35 @@ def check_review_hygiene(
     if not workflow_path.is_absolute():
         workflow_path = repo_root / workflow_path
     if not workflow_path.is_file():
+        status = STATUS_WARN if missing_workflow_is_warning else STATUS_FAIL
+        message = (
+            "starter config names stale terminal-label workflow, but it is not "
+            f"present in this checkout yet: {workflow}"
+            if missing_workflow_is_warning
+            else "merge-authority lane stale terminal-label workflow is "
+            f"configured but missing from the repo: {workflow}"
+        )
+        remediation = (
+            "This is expected before generated workflows are applied. Run "
+            "`code-mower init --easy --apply` from the repository root, review "
+            "and commit the generated clear-stale workflow, then rerun doctor."
+            if missing_workflow_is_warning
+            else "Run `code-mower init --easy --apply` from the repository "
+            "root, commit the generated clear-stale workflow, then rerun "
+            "doctor before relying on this lane as merge authority."
+        )
         return DoctorCheck(
             name="provider.review_hygiene",
-            status=STATUS_FAIL,
+            status=status,
             lane=lane_id,
-            message=(
-                "merge-authority lane stale terminal-label workflow is "
-                f"configured but missing from the repo: {workflow}"
-            ),
+            message=message,
             detail={
                 **detail,
                 "workflow_exists": False,
                 "workflow_path": str(workflow_path),
+                "missing_workflow_is_warning": missing_workflow_is_warning,
             },
-            remediation=(
-                "Run `code-mower init --easy --apply` from the repository "
-                "root, commit the generated clear-stale workflow, then rerun "
-                "doctor before relying on this lane as merge authority."
-            ),
+            remediation=remediation,
         )
     detail = {
         **detail,

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/doctor_checks/providers.py

@@ -176,6 +176,7 @@ def check_lane_runtime(
     probe_runtime: bool,
     http_timeout: int,
     adoption_posture: str = "reviewer-gate",
+    missing_workflow_is_warning: bool = False,
 ) -> list[DoctorCheck]:
     hygiene_source = source_lane if source_lane is not None else lane
     checks = [
@@ -184,6 +185,7 @@ def check_lane_runtime(
             hygiene_source,
             effective_lane=lane,
             repo_root=repo_root,
+            missing_workflow_is_warning=missing_workflow_is_warning,
         )
     ]
     driver = str(lane.get("driver", ""))

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/doctor_checks/runner.py

@@ -19,7 +19,7 @@ from .cloud import check_cloud_token_surface
 from .common import ACTIONS_COST_SAMPLE_DEFAULT, load_inputs
 from .github import check_github_setup
 from .github_config import check_repository_posture
-from .github_trusted_authors import trusted_author_variable_statuses
+from .github_trusted_authors import trusted_author_variable_probe
 from .models import STATUS_FAIL, STATUS_PASS, DoctorCheck, DoctorReport
 from .providers import check_lane_runtime, effective_lane, provider_template_coverage, selected_lanes
 from .registry import DoctorCheckStage, build_doctor_run_plan
@@ -109,13 +109,15 @@ def run_doctor(
         adoption=adoption or bool(repo_slug),
     )
     enabled_stages = {stage.id for stage in plan}
-    # `doctor --easy` can inspect the packaged example before a repo has written
-    # code-mower.yml. In that mode the example should teach the user about stale
-    # guards without failing because product workflow files are not installed yet.
-    repo_root = None if config_path.name == "code-mower.example.yml" else config_path.parent
     config, templates, checks = load_inputs(config_path, provider_templates_path)
     using_packaged_example = config_path.name == "code-mower.example.yml"
+    # `doctor --easy` can inspect the packaged example before a repo has written
+    # code-mower.yml. In that mode the example should teach the user about stale
+    # guards without failing because product workflow files are not installed
+    # yet, but it may still verify workflows already present in the checkout.
+    repo_root = Path.cwd() if using_packaged_example else config_path.parent
     trusted_author_variables = None
+    trusted_author_variable_errors = None
     trusted_author_repo_slug = repo_slug
     if not trusted_author_repo_slug and isinstance(config, Mapping):
         for repository in config.get("repositories") or []:
@@ -125,12 +127,21 @@ def run_doctor(
     if github and trusted_author_repo_slug:
         gh_path = shutil.which("gh")
         if gh_path:
-            trusted_author_variables = trusted_author_variable_statuses(
+            trusted_author_probe = trusted_author_variable_probe(
                 gh_path=gh_path,
                 slug=trusted_author_repo_slug,
                 variables=TRUSTED_AUDIT_AUTHOR_VARIABLES,
                 http_timeout=http_timeout,
             )
+            statuses = trusted_author_probe.get("statuses")
+            if isinstance(statuses, Mapping):
+                trusted_author_variables = {
+                    str(name): str(status)
+                    for name, status in statuses.items()
+                }
+            errors = trusted_author_probe.get("read_errors")
+            if isinstance(errors, Mapping):
+                trusted_author_variable_errors = dict(errors)
     checks.extend(
         check_adoption_setup(
             config=config,
@@ -142,6 +153,7 @@ def run_doctor(
             using_packaged_example=using_packaged_example,
             repo_root=Path.cwd() if using_packaged_example else config_path.parent,
             trusted_author_variables=trusted_author_variables,
+            trusted_author_variable_errors=trusted_author_variable_errors,
         )
     )
     if config is not None and repo_slug:
@@ -237,6 +249,7 @@ def run_doctor(
                 effective,
                 source_lane=lane,
                 repo_root=repo_root,
+                missing_workflow_is_warning=using_packaged_example,
                 adoption_posture=adoption_posture,
                 probe_runtime=probe_runtime,
                 http_timeout=http_timeout,

{code_mower-0.9.2b1 → code_mower-0.9.3b1}/src/code_mower/lane_status.py

@@ -472,7 +472,7 @@ def _redact_local_paths(report: dict[str, Any]) -> None:
             process["cwd_redacted"] = True
 
 
-def _global_next(report: Mapping[str, Any]) -> str:
+def _global_next(report: Mapping[str, Any]) -> tuple[str, str]:
     prs = report["remote"].get("pull_requests", [])
     local_active = bool(report["local_boards"].get("boards")) or bool(report["local_processes"].get("processes"))
     if not report["remote"].get("available"):
@@ -480,7 +480,7 @@ def _global_next(report: Mapping[str, Any]) -> str:
             "remote unavailable; inspect local lanes"
             if local_active
             else "remote unavailable; fix GitHub access"
-        )
+        ), ""
     for action in (
         "fix BLOCKED audit",
         "fix failing check",
@@ -491,9 +491,12 @@ def _global_next(report: Mapping[str, Any]) -> str:
         "waiting for checks",
         "ready for merge or auto-merge",
     ):
-        if any(pr.get("next_action") == action for pr in prs):
-            return action
-    return "inspect PRs" if prs else ("local lanes visible; connect them to PR evidence" if local_active else "no active lanes")
+        for pr in prs:
+            if pr.get("next_action") == action:
+                return action, str(pr.get("next_detail") or "")
+    return (
+        "inspect PRs" if prs else ("local lanes visible; connect them to PR evidence" if local_active else "no active lanes")
+    ), ""
 
 
 def collect_status(
@@ -518,7 +521,7 @@ def collect_status(
     }
     if not show_local_paths:
         _redact_local_paths(report)
-    report["next_action"] = _global_next(report)
+    report["next_action"], report["next_detail"] = _global_next(report)
     return report
 
 
@@ -589,6 +592,8 @@ def render_text(report: Mapping[str, Any]) -> str:
         cwd = f" cwd={process['cwd']}" if process.get("cwd") else ""
         lines.append(f"- {process['provider']} pid={process['pid']} process={process['process']}{cwd}")
     lines.extend(["", f"Next: {report['next_action']}"])
+    if report.get("next_detail"):
+        lines.append(f"Detail: {report['next_detail']}")
     return "\n".join(lines) + "\n"