code-mower 0.8.0b1__tar.gz → 0.9.0b1__tar.gz

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 0.8.0b1
+Version: 0.9.0b1
 Summary: Multi-reviewer AI code audit orchestration
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
@@ -64,6 +64,8 @@ for a real repository. It checks your runtime, GitHub setup, provider CLIs,
 token posture, optional cloud setup, private-repo Actions cost traps, and
 first-run adoption gaps. `--preflight` remains the compatibility preset for
 older scripts; `--adoption` adds explicit repo targeting and setup guidance.
+Use `--hosted-builders` or `--orchestrator-only` when the current machine is
+observing/coordinating lanes and will not run local Codex or Claude wrappers.
 
 Example, shortened:
 
@@ -88,6 +90,12 @@ boundaries visible before you promote any reviewer lane.
 
 See a fuller static transcript: [docs/first-run-transcript.md](docs/first-run-transcript.md).
 
+For an existing repository that already has Code Mower generated workflows or
+wrappers, run `code-mower migration setup-drift --repo-path .` before copying a
+fresh `.code-mower.generated` tree. It is read-only and reports path-level
+classifications (`same`, `differs`, `new`, `repo-only`,
+`missing-from-output`) without file contents or diffs.
+
 After `init` and `doctor`, use `code-mower lanes status --repo OWNER/REPO` to
 see active builder/reviewer lanes, gate/check state, recent Code Mower
 workflows, local board/process hints when present, and the next operator
@@ -96,8 +104,10 @@ action. Text and JSON output redact local cwd paths by default; use
 
 For the same redacted metadata in a local browser view, run
 `code-mower board serve --repo OWNER/REPO` and open the printed localhost URL.
-Plain `board serve` is read-only. To build local history while the browser view
-is open, run `code-mower board serve --repo OWNER/REPO --record-events`; it
+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
 `code-mower board record --repo OWNER/REPO` from the repository checkout; it
@@ -143,7 +153,9 @@ observable.
 
 Install first from the [Install And Bootstrap](docs/install.md) matrix: pipx for
 laptops, uv tool installs for hosted agents or CI boxes, and an editable venv
-for Code Mower contributors. All paths require Python 3.12 or newer.
+for Code Mower contributors. All paths require Python 3.12 or newer. For
+upgrades, record `command -v code-mower` and `code-mower --version` before and
+after reinstalling, especially when switching between pipx and uv.
 
 | Path | Use When | Route | Guide |
 | --- | --- | --- | --- |
@@ -152,10 +164,10 @@ for Code Mower contributors. All paths require Python 3.12 or newer.
 | 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.8.0-beta.1/docs/try-in-10-minutes.md)
-guide. The v0.8 beta includes the completed adoption-polish and native Board
-work, so package-only users can start from the public package rather than a
-source checkout.
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.0-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, so package-only users can
+start from the public package rather than a source checkout.
 
 ## What Calibration Does And Does Not Prove
 
@@ -184,7 +196,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.8.0-beta.1` / `code-mower==0.8.0b1`. The
+the package-index procedure for `v0.9.0-beta.1` / `code-mower==0.9.0b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -370,8 +382,8 @@ measurement work.
 
 ## Installation Status
 
-The current package-index beta baseline is `v0.8.0-beta.1`, with pinned package
-install spec `code-mower==0.8.0b1`. Release evidence is recorded on the GitHub
+The current package-index beta baseline is `v0.9.0-beta.1`, with pinned package
+install spec `code-mower==0.9.0b1`. 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
@@ -434,6 +446,7 @@ first so local work exercises the same package entrypoint users install.
 - [v0.6 Truth Baseline](docs/v06-truth-baseline.md)
 - [v0.6 Release Notes](docs/v06-release-notes.md)
 - [v0.8 Release Notes](docs/v08-release-notes.md)
+- [v0.9 Release Notes](docs/v09-release-notes.md)
 - [Post-v0.8 Effectiveness Assessment](docs/post-v08-effectiveness-assessment.md)
 - [Demo Calibration Example](examples/demo-calibration/README.md)
 - [Board Demo Rehearsal](examples/board-demo/README.md)

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/README.md

@@ -47,6 +47,8 @@ for a real repository. It checks your runtime, GitHub setup, provider CLIs,
 token posture, optional cloud setup, private-repo Actions cost traps, and
 first-run adoption gaps. `--preflight` remains the compatibility preset for
 older scripts; `--adoption` adds explicit repo targeting and setup guidance.
+Use `--hosted-builders` or `--orchestrator-only` when the current machine is
+observing/coordinating lanes and will not run local Codex or Claude wrappers.
 
 Example, shortened:
 
@@ -71,6 +73,12 @@ boundaries visible before you promote any reviewer lane.
 
 See a fuller static transcript: [docs/first-run-transcript.md](docs/first-run-transcript.md).
 
+For an existing repository that already has Code Mower generated workflows or
+wrappers, run `code-mower migration setup-drift --repo-path .` before copying a
+fresh `.code-mower.generated` tree. It is read-only and reports path-level
+classifications (`same`, `differs`, `new`, `repo-only`,
+`missing-from-output`) without file contents or diffs.
+
 After `init` and `doctor`, use `code-mower lanes status --repo OWNER/REPO` to
 see active builder/reviewer lanes, gate/check state, recent Code Mower
 workflows, local board/process hints when present, and the next operator
@@ -79,8 +87,10 @@ action. Text and JSON output redact local cwd paths by default; use
 
 For the same redacted metadata in a local browser view, run
 `code-mower board serve --repo OWNER/REPO` and open the printed localhost URL.
-Plain `board serve` is read-only. To build local history while the browser view
-is open, run `code-mower board serve --repo OWNER/REPO --record-events`; it
+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
 `code-mower board record --repo OWNER/REPO` from the repository checkout; it
@@ -126,7 +136,9 @@ observable.
 
 Install first from the [Install And Bootstrap](docs/install.md) matrix: pipx for
 laptops, uv tool installs for hosted agents or CI boxes, and an editable venv
-for Code Mower contributors. All paths require Python 3.12 or newer.
+for Code Mower contributors. All paths require Python 3.12 or newer. For
+upgrades, record `command -v code-mower` and `code-mower --version` before and
+after reinstalling, especially when switching between pipx and uv.
 
 | Path | Use When | Route | Guide |
 | --- | --- | --- | --- |
@@ -135,10 +147,10 @@ for Code Mower contributors. All paths require Python 3.12 or newer.
 | 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.8.0-beta.1/docs/try-in-10-minutes.md)
-guide. The v0.8 beta includes the completed adoption-polish and native Board
-work, so package-only users can start from the public package rather than a
-source checkout.
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.0-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, so package-only users can
+start from the public package rather than a source checkout.
 
 ## What Calibration Does And Does Not Prove
 
@@ -167,7 +179,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.8.0-beta.1` / `code-mower==0.8.0b1`. The
+the package-index procedure for `v0.9.0-beta.1` / `code-mower==0.9.0b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -353,8 +365,8 @@ measurement work.
 
 ## Installation Status
 
-The current package-index beta baseline is `v0.8.0-beta.1`, with pinned package
-install spec `code-mower==0.8.0b1`. Release evidence is recorded on the GitHub
+The current package-index beta baseline is `v0.9.0-beta.1`, with pinned package
+install spec `code-mower==0.9.0b1`. 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
@@ -417,6 +429,7 @@ first so local work exercises the same package entrypoint users install.
 - [v0.6 Truth Baseline](docs/v06-truth-baseline.md)
 - [v0.6 Release Notes](docs/v06-release-notes.md)
 - [v0.8 Release Notes](docs/v08-release-notes.md)
+- [v0.9 Release Notes](docs/v09-release-notes.md)
 - [Post-v0.8 Effectiveness Assessment](docs/post-v08-effectiveness-assessment.md)
 - [Demo Calibration Example](examples/demo-calibration/README.md)
 - [Board Demo Rehearsal](examples/board-demo/README.md)

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/pyproject.toml

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

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/__init__.py

@@ -1,3 +1,3 @@
 """Code Mower package."""
 
-__version__ = "0.8.0b1"
+__version__ = "0.9.0b1"

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/board.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import errno
 import json
 import re
 import socket
@@ -41,6 +42,7 @@ class BoardConfig:
     repo: str
     host: str = DEFAULT_HOST
     port: int = DEFAULT_PORT
+    port_was_default: bool = True
     pr_limit: int = 50
     workflow_limit: int = 20
     stale_minutes: int = 30
@@ -111,6 +113,46 @@ def _server_url(host: str, port: int) -> str:
     return f"http://{display_host}:{port}/"
 
 
+def _candidate_ports(config: BoardConfig) -> list[int]:
+    if not config.port_was_default:
+        return [config.port]
+    last_port = min(65535, config.port + 9)
+    return list(range(config.port, last_port + 1))
+
+
+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 ""
+    return (
+        f"error: Code Mower Board port {port} is already in use on {host}. "
+        f"Pass --port with a free loopback port{suggestion_text}."
+    )
+
+
+def _bind_board_server(
+    config: BoardConfig,
+    handler: type[BaseHTTPRequestHandler],
+) -> ThreadingHTTPServer | None:
+    server_type = _server_class(config.host)
+    tried: list[int] = []
+    for port in _candidate_ports(config):
+        tried.append(port)
+        try:
+            return server_type((config.host, port), handler)
+        except OSError as exc:
+            if exc.errno != errno.EADDRINUSE:
+                raise
+            if not config.port_was_default:
+                print(_explicit_port_conflict_message(config.host, port), file=sys.stderr)
+                return None
+    print(
+        "error: Code Mower Board could not find a free loopback port in "
+        f"{tried[0]}-{tried[-1]}; pass --port with a free port.",
+        file=sys.stderr,
+    )
+    return None
+
+
 def status_payload(
     config: BoardConfig,
     *,
@@ -781,6 +823,9 @@ def serve(config: BoardConfig, *, open_browser: bool = False) -> int:
     if not _is_loopback(config.host):
         print("error: board host must be loopback; use 127.0.0.1 or localhost", file=sys.stderr)
         return 2
+    if not 0 <= config.port <= 65535:
+        print("error: --port must be between 0 and 65535", file=sys.stderr)
+        return 2
     if config.record_interval_seconds < 0:
         print("error: --record-interval-seconds must be non-negative", file=sys.stderr)
         return 2
@@ -791,10 +836,14 @@ def serve(config: BoardConfig, *, open_browser: bool = False) -> int:
         print("error: --max-events must be at least 1", file=sys.stderr)
         return 2
     handler = make_handler(config)
-    server_type = _server_class(config.host)
-    with server_type((config.host, config.port), handler) as server:
+    server = _bind_board_server(config, handler)
+    if server is None:
+        return 2
+    with server:
         port = int(server.server_address[1])
         url = _server_url(config.host, port)
+        if config.port_was_default and port != config.port:
+            print(f"Code Mower Board: default port {config.port} was busy; using {port}", file=sys.stderr)
         print(f"Code Mower Board: {url}", flush=True)
         if open_browser:
             webbrowser.open(url)
@@ -1057,22 +1106,32 @@ def main(argv: list[str] | None = None) -> int:
     subparsers = parser.add_subparsers(dest="command", required=True)
     serve_parser = subparsers.add_parser("serve")
     serve_parser.add_argument("--repo", required=True)
-    serve_parser.add_argument("--host", default=DEFAULT_HOST)
-    serve_parser.add_argument("--port", type=int, default=DEFAULT_PORT)
-    serve_parser.add_argument("--pr-limit", type=int, default=50)
-    serve_parser.add_argument("--workflow-limit", type=int, default=20)
-    serve_parser.add_argument("--stale-minutes", type=int, default=30)
-    serve_parser.add_argument("--refresh-seconds", type=int, default=15)
-    serve_parser.add_argument("--show-local-paths", action="store_true")
-    serve_parser.add_argument("--repo-path", default=".")
-    serve_parser.add_argument("--store-path")
-    serve_parser.add_argument("--spend-path")
-    serve_parser.add_argument("--agent-adapters-path")
-    serve_parser.add_argument("--event-limit", type=int, default=20)
-    serve_parser.add_argument("--record-events", action="store_true")
-    serve_parser.add_argument("--record-interval-seconds", type=int, default=60)
-    serve_parser.add_argument("--retention-days", type=int, default=board_store.DEFAULT_RETENTION_DAYS)
-    serve_parser.add_argument("--max-events", type=int, default=board_store.DEFAULT_MAX_EVENTS)
+    serve_parser.add_argument("--host", default=DEFAULT_HOST, help="loopback host to bind; default: 127.0.0.1")
+    serve_parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="loopback port; the default auto-falls forward when busy",
+    )
+    serve_parser.add_argument("--pr-limit", type=int, default=50, help="open PRs to show")
+    serve_parser.add_argument("--workflow-limit", type=int, default=20, help="recent Code Mower workflow runs to show")
+    serve_parser.add_argument("--stale-minutes", type=int, default=30, help="minutes before gate evidence is stale")
+    serve_parser.add_argument("--refresh-seconds", type=int, default=15, help="browser refresh interval")
+    serve_parser.add_argument("--show-local-paths", action="store_true", help="show local cwd paths for debugging")
+    serve_parser.add_argument("--repo-path", default=".", help="repository checkout used for local Board files")
+    serve_parser.add_argument("--store-path", help="custom local Board event store path")
+    serve_parser.add_argument("--spend-path", help="custom reviewer spend ledger path")
+    serve_parser.add_argument("--agent-adapters-path", help="custom local agent card directory")
+    serve_parser.add_argument("--event-limit", type=int, default=20, help="local history events to show")
+    serve_parser.add_argument("--record-events", action="store_true", help="append local history while the Board is open")
+    serve_parser.add_argument("--record-interval-seconds", type=int, default=60, help="minimum seconds between records")
+    serve_parser.add_argument(
+        "--retention-days",
+        type=int,
+        default=board_store.DEFAULT_RETENTION_DAYS,
+        help="local history retention window",
+    )
+    serve_parser.add_argument("--max-events", type=int, default=board_store.DEFAULT_MAX_EVENTS, help="maximum local events")
     serve_parser.add_argument("--open", action="store_true", help="open the local board in a browser")
     record_parser = subparsers.add_parser("record")
     record_parser.add_argument("--repo", required=True)
@@ -1115,7 +1174,8 @@ def main(argv: list[str] | None = None) -> int:
             BoardConfig(
                 repo=args.repo,
                 host=args.host,
-                port=args.port,
+                port=DEFAULT_PORT if args.port is None else args.port,
+                port_was_default=args.port is None,
                 pr_limit=args.pr_limit,
                 workflow_limit=args.workflow_limit,
                 stale_minutes=args.stale_minutes,

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/cli.py

@@ -556,7 +556,8 @@ def _top_level_help(show_all: bool) -> str:
             "  code-mower board serve --repo OWNER/REPO",
             (
                 "  code-mower migration package-install-rehearsal "
-                f"--package-spec {code_mower_next_steps.current_alpha_package_spec()} --json"
+                f"--package-spec {code_mower_next_steps.current_alpha_package_spec()} "
+                "--allow-package-index --json"
             ),
         ]
     )

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/doctor.py

@@ -51,6 +51,39 @@ detect_repo_slug = _doctor_checks.detect_repo_slug
 normalize_repo_slug = _doctor_checks.normalize_repo_slug
 
 
+def _source_repo_uses_starter_config(cwd: Path, config_path: Path) -> bool:
+    """Return true when doctor is running from Code Mower's source tree."""
+
+    try:
+        config_path.resolve().relative_to(cwd.resolve())
+    except ValueError:
+        return False
+    return (
+        config_path.name == "code-mower.example.yml"
+        and (cwd / "pyproject.toml").is_file()
+        and (cwd / "src" / "code_mower" / "templates" / "code-mower.example.yml").is_file()
+    )
+
+
+def _doctor_config_source_label(
+    *,
+    config_arg: str,
+    config_path: Path,
+    easy: bool,
+    cwd: Path | None = None,
+) -> str:
+    """Classify the config source for adoption-facing doctor output."""
+
+    cwd = cwd or Path.cwd()
+    if config_arg != "code-mower.yml":
+        return "explicit_config"
+    if config_path.name == "code-mower.example.yml" and easy:
+        if _source_repo_uses_starter_config(cwd, config_path):
+            return "source_tree_starter"
+        return "packaged_starter"
+    return "repository_config"
+
+
 _DOCTOR_COMPAT_EXPORTS = (
     DEFAULT_CLOUD_TOKEN_DIR,
     DEFAULT_CLOUD_TOKEN_ENV,
@@ -68,6 +101,7 @@ _DOCTOR_COMPAT_EXPORTS = (
     resolve_doctor_config_path_for_script,
     resolve_doctor_provider_templates_path,
     _token_file_mentions_cloud_token,
+    _doctor_config_source_label,
 )
 
 
@@ -202,12 +236,18 @@ def main(argv: Sequence[str] | None = None) -> int:
             repo_slug = detect_repo_slug(Path.cwd())
             repo_source = "git_remote" if repo_slug else ""
         provider_templates_path = resolve_doctor_provider_templates_path(args.provider_templates)
+        config_path = resolve_doctor_config_path(args.config, easy=args.easy)
         report = run_doctor(
-            config_path=resolve_doctor_config_path(args.config, easy=args.easy),
+            config_path=config_path,
             provider_templates_path=provider_templates_path,
             profile=args.profile,
             repo_slug=repo_slug,
             repo_source=repo_source,
+            config_source=_doctor_config_source_label(
+                config_arg=args.config,
+                config_path=config_path,
+                easy=args.easy,
+            ),
             adoption=args.adoption,
             adoption_posture=args.adoption_posture,
             probe_runtime=args.probe_runtime,

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/doctor_checks/adoption.py

@@ -111,6 +111,7 @@ def check_adoption_setup(
     repo_slug: str,
     repo_source: str,
     using_packaged_example: bool,
+    config_source: str = "",
 ) -> tuple[DoctorCheck, ...]:
     """Return first-run adoption posture checks."""
 
@@ -144,17 +145,28 @@ def check_adoption_setup(
         )
 
     repositories = _configured_repositories(config)
+    source = config_source or (
+        "packaged_starter" if using_packaged_example else "repository_config"
+    )
+    source_messages = {
+        "explicit_config": "using explicit Code Mower config",
+        "packaged_starter": "using packaged starter config for adoption checks",
+        "repository_config": "using repository Code Mower config",
+        "source_tree_starter": "using source-tree starter config for adoption checks",
+    }
+    detail = {
+        "config_path": str(config_path),
+        "config_source": source,
+        "configured_repositories": repositories,
+        "effective_repository": repo_slug,
+    }
     if using_packaged_example:
         checks.append(
             DoctorCheck(
                 name="doctor.adoption.config_source",
                 status=STATUS_WARN,
-                message="using packaged starter config for adoption checks",
-                detail={
-                    "config_path": str(config_path),
-                    "configured_repositories": repositories,
-                    "effective_repository": repo_slug,
-                },
+                message=source_messages.get(source, source_messages["packaged_starter"]),
+                detail=detail,
                 remediation=(
                     "Run `code-mower init --easy --apply`, review the generated "
                     "setup, and commit an edited code-mower.yml before relying "
@@ -167,12 +179,8 @@ def check_adoption_setup(
             DoctorCheck(
                 name="doctor.adoption.config_source",
                 status=STATUS_PASS,
-                message="using repository Code Mower config",
-                detail={
-                    "config_path": str(config_path),
-                    "configured_repositories": repositories,
-                    "effective_repository": repo_slug,
-                },
+                message=source_messages.get(source, source_messages["repository_config"]),
+                detail=detail,
             )
         )
 

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/doctor_checks/common.py

@@ -66,6 +66,7 @@ ACTIONS_METADATA_WORKFLOW_MARKERS = (
     "audit-label-cleanup",
     "devin-audit-bridge",
 )
+OBSERVER_ADOPTION_POSTURES = frozenset({"hosted-builders", "orchestrator-only"})
 
 __all__ = [
     "ACTIONS_BILLING_BLOCK_PATTERNS",
@@ -76,6 +77,7 @@ __all__ = [
     "DoctorCheck",
     "MAX_ACTIONS_FAILED_JOBS_TO_INSPECT",
     "MAX_ACTIONS_FAILED_RUNS_TO_INSPECT",
+    "OBSERVER_ADOPTION_POSTURES",
     "STATUS_FAIL",
     "STATUS_PASS",
     "STATUS_SKIP",

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/doctor_checks/github.py

@@ -36,6 +36,7 @@ def check_github_setup(
     lanes: Sequence[tuple[str, Mapping[str, Any]]],
     http_timeout: int,
     actions_cost_sample: int = ACTIONS_COST_SAMPLE_DEFAULT,
+    adoption_posture: str = "reviewer-gate",
 ) -> list[DoctorCheck]:
     checks: list[DoctorCheck] = []
     gh_path = shutil.which("gh")
@@ -142,6 +143,7 @@ def check_github_setup(
                 config=config,
                 lanes=lanes,
                 http_timeout=http_timeout,
+                adoption_posture=adoption_posture,
             )
         )
         if has_merge_authority:

{code_mower-0.8.0b1 → code_mower-0.9.0b1}/src/code_mower/doctor_checks/github_human_token.py

@@ -5,7 +5,14 @@ from __future__ import annotations
 from datetime import UTC, date, datetime
 from typing import Any, Mapping, Sequence
 
-from .common import DoctorCheck, STATUS_FAIL, STATUS_PASS, STATUS_SKIP, STATUS_WARN
+from .common import (
+    OBSERVER_ADOPTION_POSTURES,
+    DoctorCheck,
+    STATUS_FAIL,
+    STATUS_PASS,
+    STATUS_SKIP,
+    STATUS_WARN,
+)
 from .github_api import _github_api_json
 
 DEFAULT_HUMAN_TOKEN_SECRET = "DISPATCH_TOKEN"
@@ -93,6 +100,18 @@ def _is_expiry_placeholder(value: str) -> bool:
     return value.strip().upper() in EXPIRY_PLACEHOLDER_VALUES
 
 
+def _blocking_status_for_posture(adoption_posture: str) -> str:
+    return STATUS_WARN if adoption_posture in OBSERVER_ADOPTION_POSTURES else STATUS_FAIL
+
+
+def _token_readiness_context(adoption_posture: str) -> str:
+    if adoption_posture == "hosted-builders":
+        return "hosted-builder observer posture"
+    if adoption_posture == "orchestrator-only":
+        return "orchestrator-only posture"
+    return "reviewer-gate posture"
+
+
 def check_human_automation_token(
     *,
     gh_path: str,
@@ -100,6 +119,7 @@ def check_human_automation_token(
     config: Mapping[str, Any],
     lanes: Sequence[tuple[str, Mapping[str, Any]]],
     http_timeout: int,
+    adoption_posture: str = "reviewer-gate",
     now: datetime | None = None,
 ) -> DoctorCheck:
     token = human_automation_token_config(config)
@@ -110,6 +130,7 @@ def check_human_automation_token(
         "secret": secret_name,
         "expires_var": expires_var,
         "required": human_automation_token_required(config, lanes),
+        "adoption_posture": adoption_posture,
     }
     if not detail["required"]:
         return DoctorCheck(
@@ -125,15 +146,24 @@ def check_human_automation_token(
         http_timeout=http_timeout,
     )
     if secret_payload is None:
+        status = _blocking_status_for_posture(adoption_posture)
         return DoctorCheck(
             name="github.human_automation_token",
-            status=STATUS_FAIL,
-            message=f"{slug} is missing the {secret_name} human automation token secret",
+            status=status,
+            message=(
+                f"{slug} is missing the {secret_name} human automation token secret"
+                + (
+                    f" for {_token_readiness_context(adoption_posture)}"
+                    if status == STATUS_WARN
+                    else ""
+                )
+            ),
             detail={**detail, "secret_check": secret_detail},
             remediation=(
                 f"Create one human-owned fine-grained PAT secret with "
                 f"`gh secret set {secret_name}`. Grant repository Contents read, "
-                "Issues read/write, and Pull requests read/write."
+                "Issues read/write, and Pull requests read/write before relying "
+                "on unattended dispatch, labels, or fix-round mentions."
             ),
         )
 
@@ -143,9 +173,10 @@ def check_human_automation_token(
         http_timeout=http_timeout,
     )
     if variable_payload is None:
+        status = _blocking_status_for_posture(adoption_posture)
         return DoctorCheck(
             name="github.human_automation_token",
-            status=STATUS_FAIL,
+            status=status,
             message=f"{slug} is missing the {expires_var} human token expiry variable",
             detail={
                 **detail,
@@ -188,9 +219,10 @@ def check_human_automation_token(
         )
     expiry = _parse_expiry(expiry_text)
     if expiry is None:
+        status = _blocking_status_for_posture(adoption_posture)
         return DoctorCheck(
             name="github.human_automation_token",
-            status=STATUS_FAIL,
+            status=status,
             message=f"{slug} has an invalid {expires_var} value",
             detail={**detail, "expires_at": expiry_text},
             remediation=(
@@ -203,7 +235,7 @@ def check_human_automation_token(
     days_remaining = (expiry - today).days
     status = STATUS_PASS
     if days_remaining < 0:
-        status = STATUS_FAIL
+        status = _blocking_status_for_posture(adoption_posture)
     elif days_remaining <= EXPIRY_WARNING_DAYS:
         status = STATUS_WARN