code-mower 0.5.0b52__tar.gz → 0.6.0b1__tar.gz

{code_mower-0.5.0b52 → code_mower-0.6.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 0.5.0b52
+Version: 0.6.0b1
 Summary: Multi-reviewer AI code audit orchestration
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
@@ -59,9 +59,8 @@ Code Mower should feel like an engineering tool, not a demo harness:
 
 `code-mower doctor --preflight` is the first useful command. It checks your
 runtime, GitHub setup, provider CLIs, token posture, optional cloud setup, and
-private-repo Actions cost traps. `--preflight` is the friendly name for the
-versioned v0.5 first-run preset, so `doctor --v05` remains equivalent for
-scripts.
+private-repo Actions cost traps. `--preflight` is the friendly first-run preset;
+`doctor --v05` remains an equivalent compatibility alias for older scripts.
 
 Example, shortened:
 
@@ -86,6 +85,10 @@ boundaries visible before you promote any reviewer lane.
 
 See a fuller static transcript: [docs/first-run-transcript.md](docs/first-run-transcript.md).
 
+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 AgentTrail boards when present, and the next operator action.
+
 ## See The Value Shape First
 
 If you want to understand the product before installing anything, start with
@@ -103,14 +106,18 @@ fast, or eligible for stronger merge policy on your actual codebase.
 ## Start Here
 
 Choose one path. Each path has one guide and gets to one visible outcome.
+Cold adopters should start with the reviewer gate, then add builders, then
+measure builder experiments; provider experiments come after that base loop is
+observable.
 
 | Path | Use When | Route | Guide |
 | --- | --- | --- | --- |
 | A. Reviewer gate in 10 minutes | You want one audited PR before recurring workflows or builder dispatch. | Install, run `init --easy`, run `doctor --preflight`, open a small setup PR, run Codex and Claude audits, then merge manually when the audit evidence is clean. | [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md) |
 | B. Build loop in 30 minutes | You want builders plus an orchestrator pattern after the reviewer gate works. | Complete path A, then add the automation token, require `code-mower/gate` from Any source, enable repository auto-merge, prove the self-hosted Mac lane runner with `doctor --runner`, run `init --builders`, and dispatch the first issue. | [Build Loop In 30 Minutes](docs/build-loop-in-30-minutes.md) |
+| 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 beta.52 announcement entry point remains the tagged
-[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.5.0-beta.52/docs/try-in-10-minutes.md)
+The v0.6 beta announcement entry point is the tagged
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.6.0-beta.1/docs/try-in-10-minutes.md)
 guide.
 
 ## What Calibration Does And Does Not Prove
@@ -135,10 +142,13 @@ 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).
 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).
 
-The current PyPI beta has been rehearsed end-to-end from a clean install:
+For release verification,
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the latest 10/10 public-package readiness proof for `code-mower==0.5.0b52`.
+the package-index procedure for `v0.6.0-beta.1` / `code-mower==0.6.0b1`. The
+GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
 
@@ -197,6 +207,11 @@ optional work order, single-writer branch, reviewer lanes, and fix rounds. Code
 Mower's templates now support that loop end to end; humans still own
 credentials, branch protection, calibration, and owner decisions.
 
+The reference adoption shape is Claude Code as orchestrator; Claude Code,
+Codex, and Cursor as builder lanes; Claude Code and Codex as reviewer lanes;
+and Gitar or Antigravity as informational reviewer signal until local
+calibration says otherwise.
+
 ## Why Not Just Run Codex Or Claude Yourself?
 
 You should, at first. Code Mower is not a replacement for a good local agent or
@@ -274,6 +289,10 @@ Everything else starts manual or informational until your own calibration data
 proves it is useful: Antigravity/Gemini, Hermes, CodeRabbit CLI, Cursor BugBot,
 Qodo, Greptile, Devin, local LLMs, and future ACP bridges.
 
+Gemini CLI and Antigravity are distinct lane ids even though both are Google
+surfaces and may use Gemini model infrastructure. Keep their auth, model
+provenance, calibration evidence, and release notes separate.
+
 Provider details: [docs/provider-matrix.md](docs/provider-matrix.md).
 Setup/auth fixes: [docs/troubleshooting.md](docs/troubleshooting.md).
 
@@ -285,12 +304,13 @@ engineer can:
 1. install Code Mower in a clean repo;
 2. understand the local/cloud trust boundary;
 3. run `init --easy` and `doctor --preflight`;
-4. detect and run the repo's native lint/test/build surface instead of assuming
+4. run `lanes status --repo OWNER/REPO` to see active lanes and gate state;
+5. detect and run the repo's native lint/test/build surface instead of assuming
    every project uses the same tools;
-5. produce a local value report from known PR outcomes;
-6. decide which lanes should stay informational, selective, or merge-gating;
+6. produce a local value report from known PR outcomes;
+7. decide which lanes should stay informational, selective, or merge-gating;
    and
-7. optionally upload sanitized metadata to CodeMower.com and see useful team
+8. optionally upload sanitized metadata to CodeMower.com and see useful team
    dashboard signal.
 
 Build-loop templates extend the same loop from "who reviews best?" to "which AI
@@ -302,9 +322,10 @@ measurement work.
 
 ## Installation Status
 
-The current public beta is `v0.5.0-beta.52` from
-[codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), published
-as `code-mower==0.5.0b52` on [PyPI](https://pypi.org/project/code-mower/).
+The current public beta baseline is `v0.6.0-beta.1`, with pinned package-index
+install spec `code-mower==0.6.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
 release notes.
 
@@ -317,6 +338,8 @@ scripts/dev-python -m venv .venv
 ```
 
 The wrapper resolves Python 3.12+ and refuses stale or old system Python shims.
+Do not run the CLI by hand-wiring source import paths; install the editable venv
+first so local work exercises the same package entrypoint users install.
 
 ## Known Limitations
 
@@ -351,13 +374,15 @@ The wrapper resolves Python 3.12+ and refuses stale or old system Python shims.
 - [Lane Standing Instructions](docs/lanes/README.md)
 - [Codex Lane Standing Instructions](docs/lanes/codex.md)
 - [Claude Lane Standing Instructions](docs/lanes/claude.md)
-- [Cursor Hosted Lane Standing Instructions](docs/lanes/grok.md)
+- [Cursor Hosted Lane Standing Instructions](docs/lanes/cursor.md)
 - [Provider Matrix](docs/provider-matrix.md)
 - [GitHub Setup](docs/github-setup.md)
 - [First Run Transcript](docs/first-run-transcript.md)
 - [First-User Demo Transcript](docs/first-user-demo-transcript.md)
 - [First-User Install Rehearsal](docs/first-user-install-rehearsal.md)
 - [Launch Command Surface](docs/launch-command-surface.md)
+- [v0.6 Truth Baseline](docs/v06-truth-baseline.md)
+- [v0.6 Release Notes](docs/v06-release-notes.md)
 - [Demo Calibration Example](examples/demo-calibration/README.md)
 - [PyPI Release Runbook](docs/pypi-release.md)
 - [Sample Doctor Output](docs/sample-doctor-output.md)

{code_mower-0.5.0b52 → code_mower-0.6.0b1}/README.md

@@ -44,9 +44,8 @@ Code Mower should feel like an engineering tool, not a demo harness:
 
 `code-mower doctor --preflight` is the first useful command. It checks your
 runtime, GitHub setup, provider CLIs, token posture, optional cloud setup, and
-private-repo Actions cost traps. `--preflight` is the friendly name for the
-versioned v0.5 first-run preset, so `doctor --v05` remains equivalent for
-scripts.
+private-repo Actions cost traps. `--preflight` is the friendly first-run preset;
+`doctor --v05` remains an equivalent compatibility alias for older scripts.
 
 Example, shortened:
 
@@ -71,6 +70,10 @@ boundaries visible before you promote any reviewer lane.
 
 See a fuller static transcript: [docs/first-run-transcript.md](docs/first-run-transcript.md).
 
+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 AgentTrail boards when present, and the next operator action.
+
 ## See The Value Shape First
 
 If you want to understand the product before installing anything, start with
@@ -88,14 +91,18 @@ fast, or eligible for stronger merge policy on your actual codebase.
 ## Start Here
 
 Choose one path. Each path has one guide and gets to one visible outcome.
+Cold adopters should start with the reviewer gate, then add builders, then
+measure builder experiments; provider experiments come after that base loop is
+observable.
 
 | Path | Use When | Route | Guide |
 | --- | --- | --- | --- |
 | A. Reviewer gate in 10 minutes | You want one audited PR before recurring workflows or builder dispatch. | Install, run `init --easy`, run `doctor --preflight`, open a small setup PR, run Codex and Claude audits, then merge manually when the audit evidence is clean. | [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md) |
 | B. Build loop in 30 minutes | You want builders plus an orchestrator pattern after the reviewer gate works. | Complete path A, then add the automation token, require `code-mower/gate` from Any source, enable repository auto-merge, prove the self-hosted Mac lane runner with `doctor --runner`, run `init --builders`, and dispatch the first issue. | [Build Loop In 30 Minutes](docs/build-loop-in-30-minutes.md) |
+| 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 beta.52 announcement entry point remains the tagged
-[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.5.0-beta.52/docs/try-in-10-minutes.md)
+The v0.6 beta announcement entry point is the tagged
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.6.0-beta.1/docs/try-in-10-minutes.md)
 guide.
 
 ## What Calibration Does And Does Not Prove
@@ -120,10 +127,13 @@ 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).
 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).
 
-The current PyPI beta has been rehearsed end-to-end from a clean install:
+For release verification,
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the latest 10/10 public-package readiness proof for `code-mower==0.5.0b52`.
+the package-index procedure for `v0.6.0-beta.1` / `code-mower==0.6.0b1`. The
+GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
 
@@ -182,6 +192,11 @@ optional work order, single-writer branch, reviewer lanes, and fix rounds. Code
 Mower's templates now support that loop end to end; humans still own
 credentials, branch protection, calibration, and owner decisions.
 
+The reference adoption shape is Claude Code as orchestrator; Claude Code,
+Codex, and Cursor as builder lanes; Claude Code and Codex as reviewer lanes;
+and Gitar or Antigravity as informational reviewer signal until local
+calibration says otherwise.
+
 ## Why Not Just Run Codex Or Claude Yourself?
 
 You should, at first. Code Mower is not a replacement for a good local agent or
@@ -259,6 +274,10 @@ Everything else starts manual or informational until your own calibration data
 proves it is useful: Antigravity/Gemini, Hermes, CodeRabbit CLI, Cursor BugBot,
 Qodo, Greptile, Devin, local LLMs, and future ACP bridges.
 
+Gemini CLI and Antigravity are distinct lane ids even though both are Google
+surfaces and may use Gemini model infrastructure. Keep their auth, model
+provenance, calibration evidence, and release notes separate.
+
 Provider details: [docs/provider-matrix.md](docs/provider-matrix.md).
 Setup/auth fixes: [docs/troubleshooting.md](docs/troubleshooting.md).
 
@@ -270,12 +289,13 @@ engineer can:
 1. install Code Mower in a clean repo;
 2. understand the local/cloud trust boundary;
 3. run `init --easy` and `doctor --preflight`;
-4. detect and run the repo's native lint/test/build surface instead of assuming
+4. run `lanes status --repo OWNER/REPO` to see active lanes and gate state;
+5. detect and run the repo's native lint/test/build surface instead of assuming
    every project uses the same tools;
-5. produce a local value report from known PR outcomes;
-6. decide which lanes should stay informational, selective, or merge-gating;
+6. produce a local value report from known PR outcomes;
+7. decide which lanes should stay informational, selective, or merge-gating;
    and
-7. optionally upload sanitized metadata to CodeMower.com and see useful team
+8. optionally upload sanitized metadata to CodeMower.com and see useful team
    dashboard signal.
 
 Build-loop templates extend the same loop from "who reviews best?" to "which AI
@@ -287,9 +307,10 @@ measurement work.
 
 ## Installation Status
 
-The current public beta is `v0.5.0-beta.52` from
-[codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), published
-as `code-mower==0.5.0b52` on [PyPI](https://pypi.org/project/code-mower/).
+The current public beta baseline is `v0.6.0-beta.1`, with pinned package-index
+install spec `code-mower==0.6.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
 release notes.
 
@@ -302,6 +323,8 @@ scripts/dev-python -m venv .venv
 ```
 
 The wrapper resolves Python 3.12+ and refuses stale or old system Python shims.
+Do not run the CLI by hand-wiring source import paths; install the editable venv
+first so local work exercises the same package entrypoint users install.
 
 ## Known Limitations
 
@@ -336,13 +359,15 @@ The wrapper resolves Python 3.12+ and refuses stale or old system Python shims.
 - [Lane Standing Instructions](docs/lanes/README.md)
 - [Codex Lane Standing Instructions](docs/lanes/codex.md)
 - [Claude Lane Standing Instructions](docs/lanes/claude.md)
-- [Cursor Hosted Lane Standing Instructions](docs/lanes/grok.md)
+- [Cursor Hosted Lane Standing Instructions](docs/lanes/cursor.md)
 - [Provider Matrix](docs/provider-matrix.md)
 - [GitHub Setup](docs/github-setup.md)
 - [First Run Transcript](docs/first-run-transcript.md)
 - [First-User Demo Transcript](docs/first-user-demo-transcript.md)
 - [First-User Install Rehearsal](docs/first-user-install-rehearsal.md)
 - [Launch Command Surface](docs/launch-command-surface.md)
+- [v0.6 Truth Baseline](docs/v06-truth-baseline.md)
+- [v0.6 Release Notes](docs/v06-release-notes.md)
 - [Demo Calibration Example](examples/demo-calibration/README.md)
 - [PyPI Release Runbook](docs/pypi-release.md)
 - [Sample Doctor Output](docs/sample-doctor-output.md)

{code_mower-0.5.0b52 → code_mower-0.6.0b1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-mower"
-version = "0.5.0b52"
+version = "0.6.0b1"
 description = "Multi-reviewer AI code audit orchestration"
 requires-python = ">=3.11"
 readme = "README.md"
@@ -47,8 +47,13 @@ target-version = "py311"
 line-length = 100
 
 [tool.ruff.lint]
-select = ["E", "F"]
-ignore = ["E501"]
+select = ["E", "F", "W", "B"]
+ignore = [
+    "E501",
+    # LaneConfig instances are finite config objects; keep the callable helper
+    # shape stable instead of churning call sites for cached_property.
+    "B019",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*.py" = ["E402"]

{code_mower-0.5.0b52 → code_mower-0.6.0b1}/src/code_mower/__init__.py

@@ -1,3 +1,3 @@
 """Code Mower package."""
 
-__version__ = "0.5.0b52"
+__version__ = "0.6.0b1"

code_mower-0.6.0b1/src/code_mower/antigravity_sdk_probe.py

@@ -0,0 +1,129 @@
+"""Optional Antigravity SDK probe helpers."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from importlib import metadata
+from typing import Any
+
+PACKAGE_NAME = "google-antigravity"
+IMPORT_NAME = "google.antigravity"
+EXPECTED_EXPORTS = (
+    "Agent",
+    "LocalAgentConfig",
+    "CapabilitiesConfig",
+    "UsageMetadata",
+    "GeminiAPIEndpoint",
+    "VertexEndpoint",
+)
+LOCAL_HARNESS_PATH = "google/antigravity/bin/localharness"
+
+
+def _dependency_name(requirement: str) -> str:
+    text = requirement.split(";", 1)[0].strip()
+    for separator in ("<", ">", "=", "!", "~", " "):
+        if separator in text:
+            text = text.split(separator, 1)[0].strip()
+    return text
+
+
+def _dependency_names(requirements: list[str] | None) -> tuple[list[str], list[str]]:
+    required: set[str] = set()
+    optional: set[str] = set()
+    for requirement in requirements or []:
+        name = _dependency_name(requirement)
+        if not name:
+            continue
+        if "extra ==" in requirement:
+            optional.add(name)
+        else:
+            required.add(name)
+    return sorted(required), sorted(optional)
+
+
+def _distribution_details(package_name: str) -> dict[str, Any]:
+    try:
+        distribution = metadata.distribution(package_name)
+    except metadata.PackageNotFoundError:
+        return {
+            "installed": False,
+            "package_version": "",
+            "dependencies": [],
+            "optional_dependencies": [],
+            "has_local_harness_binary": False,
+        }
+    files = distribution.files or []
+    dependencies, optional_dependencies = _dependency_names(distribution.requires)
+    return {
+        "installed": True,
+        "package_version": metadata.version(package_name),
+        "dependencies": dependencies,
+        "optional_dependencies": optional_dependencies,
+        "has_local_harness_binary": any(
+            str(path).replace("\\", "/") == LOCAL_HARNESS_PATH for path in files
+        ),
+    }
+
+
+def _is_importable(import_name: str) -> bool:
+    try:
+        return importlib.util.find_spec(import_name) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def probe_antigravity_sdk(*, import_api: bool = False) -> dict[str, Any]:
+    """Return metadata-only facts about the optional Antigravity SDK surface."""
+
+    details = _distribution_details(PACKAGE_NAME)
+    importable = _is_importable(IMPORT_NAME)
+    report: dict[str, Any] = {
+        "mode": "antigravity-sdk-probe",
+        "package": PACKAGE_NAME,
+        "import_name": IMPORT_NAME,
+        "installed": details["installed"],
+        "package_version": details["package_version"],
+        "dependencies": details["dependencies"],
+        "optional_dependencies": details["optional_dependencies"],
+        "has_local_harness_binary": details["has_local_harness_binary"],
+        "importable": importable,
+        "import_api": import_api,
+        "api_exports": {},
+        "research_posture": "optional_research",
+        "privacy": {
+            "model_call": False,
+            "auth_probe": False,
+            "source_or_diff": False,
+            "raw_output": False,
+        },
+    }
+    if import_api and importable:
+        module = importlib.import_module(IMPORT_NAME)
+        report["api_exports"] = {
+            name: hasattr(module, name) for name in EXPECTED_EXPORTS
+        }
+
+    missing_exports = [
+        name for name, present in report["api_exports"].items() if not present
+    ]
+    if not report["installed"]:
+        report["status"] = "warn"
+        report["message"] = (
+            "optional Antigravity SDK package is not installed; install "
+            "google-antigravity in a disposable venv before SDK lane research"
+        )
+    elif not report["importable"]:
+        report["status"] = "warn"
+        report["message"] = "optional Antigravity SDK package is installed but not importable"
+    elif import_api and missing_exports:
+        report["status"] = "warn"
+        report["message"] = (
+            "optional Antigravity SDK import succeeded but expected API exports "
+            "are missing"
+        )
+        report["missing_exports"] = missing_exports
+    else:
+        report["status"] = "pass"
+        report["message"] = "optional Antigravity SDK probe completed without model calls"
+    return report

{code_mower-0.5.0b52 → code_mower-0.6.0b1}/src/code_mower/bootstrap.py

@@ -235,7 +235,7 @@ def _acquire_venv_lock(
                 raise RuntimeError(
                     "timed out waiting for Code Mower venv lock: "
                     f"{lock_dir}"
-                )
+                ) from None
             time.sleep(poll_seconds)
             continue
         owner_id = f"{os.getpid()}-{uuid.uuid4().hex}"

{code_mower-0.5.0b52 → code_mower-0.6.0b1}/src/code_mower/builder_experiment.py

@@ -7,8 +7,11 @@ import argparse
 import hashlib
 import json
 import re
+import subprocess
 import sys
+import time
 import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence
 
@@ -16,6 +19,7 @@ BUILDER_PLAN_MODE = "code-mower-builder-experiment-plan"
 BUILDER_PLAN_SCHEMA = "code_mower.builderExperimentPlan.v1"
 BUILDER_REPORT_MODE = "code-mower-builder-experiment-report"
 BUILDER_REPORT_SCHEMA = "code_mower.builderExperimentReport.v1"
+AUTHORING_RUN_SCHEMA = "code_mower.authoringRun.v1"
 SAFE_SLUG_RE = re.compile(r"[^A-Za-z0-9_.-]+")
 DEFAULT_METRICS = (
     "elapsed_seconds",
@@ -39,6 +43,16 @@ def _stable_suffix(value: Any, length: int = 8) -> str:
     return hashlib.sha256(str(value or "").encode("utf-8")).hexdigest()[:length]
 
 
+def _sha256_text(value: Any) -> str:
+    return "sha256:" + hashlib.sha256(
+        json.dumps(value, sort_keys=True).encode("utf-8")
+    ).hexdigest()
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
 def _identity_slug(value: Any, fallback: str) -> str:
     return f"{_safe_slug(value, fallback)}-{_stable_suffix(value)}"
 
@@ -494,6 +508,111 @@ def render_report_text(report: Mapping[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _load_plan_or_spec(
+    path: Path,
+    *,
+    output_dir: Path = Path(".code-mower/builder-experiments"),
+    replicates: int = 1,
+) -> dict[str, Any]:
+    payload = dict(_load_json(path))
+    if payload.get("schema") == BUILDER_PLAN_SCHEMA or payload.get("runs"):
+        return payload
+    return build_plan(normalize_spec(payload), output_dir=output_dir, replicates=replicates)
+
+
+def _planned_run(plan: Mapping[str, Any], run_id: str) -> Mapping[str, Any]:
+    for run in plan.get("runs", []) or []:
+        if isinstance(run, Mapping) and str(run.get("run_id") or "") == run_id:
+            return run
+    raise ValueError(f"run_id not found in builder experiment plan: {run_id}")
+
+
+def _safe_command_metadata(command: Sequence[str]) -> dict[str, Any]:
+    executable = Path(str(command[0])).name if command else ""
+    return {
+        "executable": executable,
+        "arg_count": len(command),
+        "argv_sha256": _sha256_text(list(command)),
+        "stdout_stderr": "not_captured",
+    }
+
+
+def run_authoring_subprocess(
+    planned_run: Mapping[str, Any],
+    *,
+    command: Sequence[str],
+    dry_run: bool = False,
+    cwd: Path | None = None,
+    timeout: float | None = None,
+    branch: str = "",
+    pull_request: str = "",
+) -> dict[str, Any]:
+    if not command:
+        raise ValueError("builder-experiment run requires an explicit command after --")
+    if cwd is not None and not cwd.is_dir():
+        raise ValueError(f"--cwd must be an existing directory: {cwd}")
+    started_at = _utc_now()
+    ended_at = started_at
+    elapsed_seconds = 0.0
+    status = "planned"
+    exit_code: int | None = None
+    if not dry_run:
+        started = time.monotonic()
+        try:
+            result = subprocess.run(
+                list(command),
+                cwd=str(cwd) if cwd is not None else None,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=timeout,
+                check=False,
+            )
+            exit_code = result.returncode
+            status = "completed" if exit_code == 0 else "failed"
+        except subprocess.TimeoutExpired:
+            status = "timeout"
+        except OSError as exc:
+            raise ValueError(
+                f"unable to start builder command {Path(str(command[0])).name!r}: "
+                f"{getattr(exc, 'strerror', '') or exc}"
+            ) from None
+        elapsed_seconds = round(time.monotonic() - started, 3)
+        ended_at = _utc_now()
+
+    return {
+        "schema": AUTHORING_RUN_SCHEMA,
+        "run_id": str(planned_run.get("run_id") or ""),
+        "experiment_id": str(planned_run.get("experiment_id") or ""),
+        "repo": str(planned_run.get("repo") or ""),
+        "task_id": str(planned_run.get("task_id") or ""),
+        "task_class": str(planned_run.get("task_class") or ""),
+        "builder": {
+            "provider": str(planned_run.get("provider") or ""),
+            "tool": str(planned_run.get("tool") or ""),
+            "model": str(planned_run.get("model") or ""),
+        },
+        "started_at": started_at,
+        "ended_at": ended_at,
+        "elapsed_seconds": elapsed_seconds,
+        "status": status,
+        "branch": branch,
+        "pull_request": pull_request,
+        "executor": {
+            "type": "subprocess",
+            "dry_run": dry_run,
+            "exit_code": exit_code,
+            "command": _safe_command_metadata(command),
+        },
+        "privacy": {
+            "source_or_diff": False,
+            "transcript": False,
+            "raw_stdout_stderr": False,
+            "auth_output": False,
+            "secrets": False,
+        },
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="code-mower builder-experiment")
     subparsers = parser.add_subparsers(dest="command", required=True)
@@ -510,16 +629,59 @@ def main(argv: list[str] | None = None) -> int:
     report_parser.add_argument("--replicates", type=int, default=1)
     report_parser.add_argument("--output", type=Path)
     report_parser.add_argument("--json", action="store_true")
-    args = parser.parse_args(argv)
+    run_parser = subparsers.add_parser("run")
+    run_parser.add_argument("spec", type=Path)
+    run_parser.add_argument("--run-id", required=True)
+    run_parser.add_argument("--output-dir", type=Path, default=Path(".code-mower/builder-experiments"))
+    run_parser.add_argument("--replicates", type=int, default=1)
+    run_parser.add_argument("--output", type=Path)
+    run_parser.add_argument("--cwd", type=Path)
+    run_parser.add_argument("--timeout", type=float)
+    run_parser.add_argument("--dry-run", action="store_true")
+    run_parser.add_argument("--branch", default="")
+    run_parser.add_argument("--pull-request", default="")
+    run_parser.add_argument("--json", action="store_true")
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    builder_command: list[str] = []
+    parse_argv = raw_argv
+    if raw_argv[:1] == ["run"] and "--" in raw_argv:
+        command_index = raw_argv.index("--")
+        builder_command = raw_argv[command_index + 1 :]
+        parse_argv = raw_argv[:command_index]
+    args = parser.parse_args(parse_argv)
 
     try:
-        spec = load_spec(args.spec)
-        plan = build_plan(spec, output_dir=args.output_dir, replicates=args.replicates)
         if args.command == "plan":
+            spec = load_spec(args.spec)
+            plan = build_plan(spec, output_dir=args.output_dir, replicates=args.replicates)
             if args.output:
                 _write_json(args.output, plan)
             print(json.dumps(plan, indent=2, sort_keys=True) if args.json else render_plan_text(plan))
             return 0
+        if args.command == "run":
+            plan = _load_plan_or_spec(
+                args.spec,
+                output_dir=args.output_dir,
+                replicates=args.replicates,
+            )
+            command = builder_command
+            planned = _planned_run(plan, args.run_id)
+            artifact = run_authoring_subprocess(
+                planned,
+                command=command,
+                dry_run=args.dry_run,
+                cwd=args.cwd,
+                timeout=args.timeout,
+                branch=args.branch,
+                pull_request=args.pull_request,
+            )
+            run_dir = Path(str(planned.get("output_dir") or ".code-mower/authoring-runs"))
+            output = args.output or run_dir / f"{_safe_slug(args.run_id)}.json"
+            _write_json(output, artifact)
+            print(json.dumps(artifact, indent=2, sort_keys=True) if args.json else f"wrote {output}")
+            return 0
+        spec = load_spec(args.spec)
+        plan = build_plan(spec, output_dir=args.output_dir, replicates=args.replicates)
         run_results = load_run_results(args.runs)
         report = build_report(plan, run_results)
         if args.output: