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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 0.8.0b1
+Version: 0.9.1b1
 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,16 +90,29 @@ 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.
+Use [Upgrade An Existing Repository](docs/upgrade-existing-repo.md) for the
+reviewed PR flow, repo-only file handling, builder identity checks, and
+wrapper/pin drift checks.
+
 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
 action. Text and JSON output redact local cwd paths by default; use
-`--show-local-paths` only for local debugging.
+`--show-local-paths` only for local debugging. Local Board discovery is
+best-effort across common macOS and Linux listener tools; when a host restricts
+listener inventory, remote PR/check status still reports normally.
 
 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 +158,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,9 +169,11 @@ 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
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.1-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.1 adds a smaller
+announcement-hardening pass on Board visibility, doctor guidance, and safer
+setup docs. Package-only users can start from the public package rather than a
 source checkout.
 
 ## What Calibration Does And Does Not Prove
@@ -178,13 +197,15 @@ review-request signals to propose known-clean and known-blocked cases. Review
 every disposition before using it for lane promotion or merge policy.
 
 Full walkthrough: [docs/try-in-10-minutes.md](docs/try-in-10-minutes.md).
+Existing-repo upgrade flow:
+[docs/upgrade-existing-repo.md](docs/upgrade-existing-repo.md).
 First-time command map: [docs/launch-command-surface.md](docs/launch-command-surface.md).
 Provider-contract baseline for the next release train:
 [docs/v06-truth-baseline.md](docs/v06-truth-baseline.md).
 
 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.1-beta.1` / `code-mower==0.9.1b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -370,8 +391,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.1-beta.1`, with pinned package
+install spec `code-mower==0.9.1b1`. 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
@@ -412,6 +433,7 @@ first so local work exercises the same package entrypoint users install.
 ## Docs Map
 
 - [Install And Bootstrap](docs/install.md)
+- [Upgrade An Existing Repository](docs/upgrade-existing-repo.md)
 - [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md)
 - [Build Loop In 30 Minutes](docs/build-loop-in-30-minutes.md)
 - [Quickstart Reference](docs/quickstart.md)
@@ -434,6 +456,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.1b1}/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,16 +73,29 @@ 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.
+Use [Upgrade An Existing Repository](docs/upgrade-existing-repo.md) for the
+reviewed PR flow, repo-only file handling, builder identity checks, and
+wrapper/pin drift checks.
+
 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
 action. Text and JSON output redact local cwd paths by default; use
-`--show-local-paths` only for local debugging.
+`--show-local-paths` only for local debugging. Local Board discovery is
+best-effort across common macOS and Linux listener tools; when a host restricts
+listener inventory, remote PR/check status still reports normally.
 
 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 +141,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,9 +152,11 @@ 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
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.1-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.1 adds a smaller
+announcement-hardening pass on Board visibility, doctor guidance, and safer
+setup docs. Package-only users can start from the public package rather than a
 source checkout.
 
 ## What Calibration Does And Does Not Prove
@@ -161,13 +180,15 @@ review-request signals to propose known-clean and known-blocked cases. Review
 every disposition before using it for lane promotion or merge policy.
 
 Full walkthrough: [docs/try-in-10-minutes.md](docs/try-in-10-minutes.md).
+Existing-repo upgrade flow:
+[docs/upgrade-existing-repo.md](docs/upgrade-existing-repo.md).
 First-time command map: [docs/launch-command-surface.md](docs/launch-command-surface.md).
 Provider-contract baseline for the next release train:
 [docs/v06-truth-baseline.md](docs/v06-truth-baseline.md).
 
 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.1-beta.1` / `code-mower==0.9.1b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -353,8 +374,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.1-beta.1`, with pinned package
+install spec `code-mower==0.9.1b1`. 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
@@ -395,6 +416,7 @@ first so local work exercises the same package entrypoint users install.
 ## Docs Map
 
 - [Install And Bootstrap](docs/install.md)
+- [Upgrade An Existing Repository](docs/upgrade-existing-repo.md)
 - [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md)
 - [Build Loop In 30 Minutes](docs/build-loop-in-30-minutes.md)
 - [Quickstart Reference](docs/quickstart.md)
@@ -417,6 +439,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.1b1}/pyproject.toml

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

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

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

{code_mower-0.8.0b1 → code_mower-0.9.1b1}/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,
     *,
@@ -613,6 +655,14 @@ def render_board_html(config: BoardConfig) -> str:
     const stateClass = (value) => /fail|error|blocked/i.test(text(value)) ? "bad" : /warn|pending|waiting|queued|progress/i.test(text(value)) ? "warn" : "ok";
     const seconds = (value) => Number.isFinite(Number(value)) ? `${{Number(value).toFixed(1)}}s` : "n/a";
     const money = (value) => Number.isFinite(Number(value)) ? `$${{Number(value).toFixed(3)}}` : "n/a";
+    const localTime = (value) => {{
+      const raw = text(value);
+      if (!raw) return "";
+      const date = new Date(raw);
+      if (Number.isNaN(date.getTime())) return esc(raw);
+      const local = new Intl.DateTimeFormat(undefined, {{year:"numeric", month:"short", day:"numeric", hour:"numeric", minute:"2-digit", second:"2-digit", timeZoneName:"short"}}).format(date);
+      return `<time datetime="${{esc(raw)}}" title="UTC ${{esc(raw)}}">${{esc(local)}}</time>`;
+    }};
     function labels(groups) {{
       return Object.values(groups || {{}}).flat().map(pill).join(" ") || '<span class="muted">none</span>';
     }}
@@ -621,7 +671,7 @@ def render_board_html(config: BoardConfig) -> str:
     }}
     function render(data) {{
       document.getElementById("repo").textContent = REPO;
-      document.getElementById("generated").textContent = `Generated ${{data.generated_at || ""}}`;
+      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 || [];
       const alerts = data.remote?.gate_health?.alerts || [];
@@ -639,18 +689,18 @@ def render_board_html(config: BoardConfig) -> str:
         `<div class="metric"><span class="muted">Agent cards</span><b>${{agentCards.length}}</b></div>`,
         `<div class="metric"><span class="muted">Gate alerts</span><b class="${{alerts.length ? "warn" : "ok"}}">${{alerts.length}}</b></div>`
       ].join(""));
-      put("owner", ownerQueue.length ? ownerQueue.map(item => `<div class="row"><div class="line"><a href="${{esc(href(item.url))}}">#${{esc(item.pr_number)}} ${{esc(item.kind)}}</a>${{pill(item.next_action)}}${{pill(item.head_sha_prefix)}}</div><div class="muted">${{esc(item.branch)}} by ${{esc(item.author)}} updated ${{esc(item.updated_at)}}</div></div>`).join("") : empty(data.owner_queue?.message || "No owner queue items."));
-      put("agents", agentCards.length ? agentCards.map(agent => `<div class="row"><div class="line"><b>${{esc(agent.provider)}}</b>${{pill(agent.role)}}${{pill(agent.status)}}${{agent.lane ? pill(agent.lane) : ""}}${{agent.pr_number ? pill(`#${{agent.pr_number}}`) : ""}}</div><div>${{esc(agent.title || agent.next_action || "local agent")}}</div><div class="muted">${{esc(agent.branch || agent.repo || "")}}${{agent.pid ? ` pid=${{esc(agent.pid)}}` : ""}}${{agent.cwd ? ` cwd=${{esc(agent.cwd)}}` : ""}}${{agent.updated_at ? ` updated ${{esc(agent.updated_at)}}` : ""}}</div></div>`).join("") : empty(data.agent_adapters?.message || "No local agent adapter cards."));
+      put("owner", ownerQueue.length ? ownerQueue.map(item => `<div class="row"><div class="line"><a href="${{esc(href(item.url))}}">#${{esc(item.pr_number)}} ${{esc(item.kind)}}</a>${{pill(item.next_action)}}${{pill(item.head_sha_prefix)}}</div><div class="muted">${{esc(item.branch)}} by ${{esc(item.author)}}${{item.updated_at ? ` updated ${{localTime(item.updated_at)}}` : ""}}</div></div>`).join("") : empty(data.owner_queue?.message || "No owner queue items."));
+      put("agents", agentCards.length ? agentCards.map(agent => `<div class="row"><div class="line"><b>${{esc(agent.provider)}}</b>${{pill(agent.role)}}${{pill(agent.status)}}${{agent.lane ? pill(agent.lane) : ""}}${{agent.pr_number ? pill(`#${{agent.pr_number}}`) : ""}}</div><div>${{esc(agent.title || agent.next_action || "local agent")}}</div><div class="muted">${{esc(agent.branch || agent.repo || "")}}${{agent.pid ? ` pid=${{esc(agent.pid)}}` : ""}}${{agent.cwd ? ` cwd=${{esc(agent.cwd)}}` : ""}}${{agent.updated_at ? ` updated ${{localTime(agent.updated_at)}}` : ""}}</div></div>`).join("") : empty(data.agent_adapters?.message || "No local agent adapter cards."));
       put("prs", prs.length ? prs.map(pr => `<div class="row">
         <div class="line"><a href="${{esc(href(pr.url))}}">#${{esc(pr.number)}} ${{esc(pr.title)}}</a>${{pill(pr.merge_state)}}${{pr.is_draft ? pill("draft") : ""}}${{pr.stale ? pill("stale") : ""}}</div>
-        <div class="muted">${{esc(pr.branch)}} by ${{esc(pr.author)}} updated ${{esc(pr.updated_at)}}</div>
+        <div class="muted">${{esc(pr.branch)}} by ${{esc(pr.author)}}${{pr.updated_at ? ` updated ${{localTime(pr.updated_at)}}` : ""}}</div>
         <div>labels: ${{labels(pr.labels)}}</div>
         <div>checks: ${{checks(pr.checks)}}</div>
         <div>next: <b>${{esc(pr.next_action)}}</b></div>
       </div>`).join("") : empty("No open pull requests."));
       put("alerts", alerts.length ? alerts.map(a => `<div class="row"><b class="warn">${{esc(a.kind)}}</b> ${{esc(a.message)}}</div>`).join("") : empty("No gate alerts."));
-      put("runs", runs.length ? runs.slice(0, 8).map(run => `<div class="row"><div class="line"><a href="${{esc(href(run.url))}}">${{esc(run.workflow || "workflow")}}</a>${{pill(run.conclusion || run.status || "unknown")}}</div><div class="muted">${{esc(run.branch)}} updated ${{esc(run.updated_at)}}</div></div>`).join("") : empty("No recent Code Mower workflow runs."));
-      put("verdicts", verdicts.length ? verdicts.map(v => `<div class="row"><div class="line"><a href="${{esc(href(v.url))}}">#${{esc(v.pr_number)}} ${{esc(v.lane)}}</a>${{pill(v.verdict)}}${{pill(v.head_sha_prefix)}}</div><div class="muted">${{esc(v.created_at)}}</div></div>`).join("") : empty(timelines.verdicts?.message || "No local reviewer verdict history yet."));
+      put("runs", runs.length ? runs.slice(0, 8).map(run => `<div class="row"><div class="line"><a href="${{esc(href(run.url))}}">${{esc(run.workflow || "workflow")}}</a>${{pill(run.conclusion || run.status || "unknown")}}</div><div class="muted">${{esc(run.branch)}}${{run.updated_at ? ` updated ${{localTime(run.updated_at)}}` : ""}}</div></div>`).join("") : empty("No recent Code Mower workflow runs."));
+      put("verdicts", verdicts.length ? verdicts.map(v => `<div class="row"><div class="line"><a href="${{esc(href(v.url))}}">#${{esc(v.pr_number)}} ${{esc(v.lane)}}</a>${{pill(v.verdict)}}${{pill(v.head_sha_prefix)}}</div><div class="muted">${{localTime(v.created_at)}}</div></div>`).join("") : empty(timelines.verdicts?.message || "No local reviewer verdict history yet."));
       const spendRows = [
         ...spendGroups.map(g => `<div class="row"><div class="line"><b>${{esc(g.lane)}}</b>${{pill(g.verdict)}}${{pill(`${{g.runs}} runs`)}}</div><div class="muted">${{seconds(g.wall_seconds_total)}} total / ${{seconds(g.wall_seconds_avg)}} avg / ${{money(g.cost_usd_total)}} / ${{esc(g.total_tokens || 0)}} tokens</div></div>`),
         spend.skipped_rows ? `<div class="row muted">Skipped ${{esc(spend.skipped_rows)}} malformed spend row(s).</div>` : "",
@@ -666,7 +716,7 @@ def render_board_html(config: BoardConfig) -> str:
       put("history", events.length ? events.slice().reverse().map(event => {{
         const s = event.summary || {{}};
         const remote = s.remote_available ? "remote available" : "remote unavailable";
-        return `<div class="row"><div class="line"><b>${{esc(event.created_at)}}</b>${{pill(remote)}}</div><div>next: <b>${{esc(s.next_action || "inspect")}}</b></div><div class="muted">PRs ${{esc(s.open_prs ?? 0)}} / alerts ${{esc(s.gate_alerts ?? 0)}} / local ${{esc((s.local_boards ?? 0) + (s.local_processes ?? 0))}}</div></div>`;
+        return `<div class="row"><div class="line"><b>${{localTime(event.created_at)}}</b>${{pill(remote)}}</div><div>next: <b>${{esc(s.next_action || "inspect")}}</b></div><div class="muted">PRs ${{esc(s.open_prs ?? 0)}} / alerts ${{esc(s.gate_alerts ?? 0)}} / local ${{esc((s.local_boards ?? 0) + (s.local_processes ?? 0))}}</div></div>`;
       }}).join("") : empty(history.message || "No local board events recorded yet."));
     }}
     async function load() {{
@@ -781,6 +831,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 +844,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 +1114,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 +1182,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.1b1}/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.1b1}/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.1b1}/src/code_mower/doctor_checks/__init__.py

@@ -13,6 +13,7 @@ from .cloud import (
     token_file_mentions_cloud_token,
 )
 from .adoption import (
+    check_adoption_posture_guidance,
     check_adoption_setup,
     config_with_repository_target,
     detect_repo_slug,
@@ -31,6 +32,7 @@ from .github_human_token import (
     human_automation_token_config,
     human_automation_token_required,
 )
+from .github_trusted_authors import trusted_author_variable_statuses
 from .groups import GROUP_LABELS, doctor_check_group_id
 from .models import (
     STATUS_FAIL,
@@ -105,11 +107,13 @@ __all__ = [
     "auth_probe_output_detail",
     "build_doctor_run_plan",
     "check_cloud_token_surface",
+    "check_adoption_posture_guidance",
     "check_adoption_setup",
     "check_github_auth_surface",
     "check_macos_runner_launchagent",
     "check_github_setup",
     "check_human_automation_token",
+    "trusted_author_variable_statuses",
     "check_repository_posture",
     "check_lane_runtime",
     "check_review_hygiene",