@event4u/agent-config 3.3.0 → 4.1.0

package/scripts/annotate_discovery.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python3
 """R3 Phase 4 mass-annotator — discovery frontmatter helper.
 
-Walks a list of artefacts in `.agent-src.uncompressed/` and:
+Walks a list of artefacts in `.agent-src.uncondensed/` and:
   1. Inserts the 5 ADR-013 frontmatter keys (workspaces, packs, lifecycle,
      trust, install) before the closing `---`, deterministically.
   2. Mirrors the new keys into the matching `.agent-src/` counterpart so
-     the compressed projection stays consistent (body preserved).
-  3. Refreshes `.compression-hashes.json` for each touched source path so
-     `task check-compression` stays green.
+     the condensed projection stays consistent (body preserved).
+  3. Refreshes `internal/.condensation-hashes.json` for each touched source path so
+     `task check-condensation` stays green.
 
 Idempotent: re-runs leave already-annotated files untouched.
 
@@ -24,9 +24,9 @@ import sys
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[1]
-SRC = ROOT / ".agent-src.uncompressed"
+SRC = ROOT / ".agent-src.uncondensed"
 DST = ROOT / ".agent-src"
-HASH_FILE = ROOT / ".compression-hashes.json"
+HASH_FILE = ROOT / "internal" / ".condensation-hashes.json"
 
 # Pack → (workspace_id, trust_level, default_install, removable, lifecycle).
 PACK_DEFAULTS: dict[str, tuple[str, str, bool, bool, str]] = {
@@ -92,11 +92,11 @@ def _annotate(path: Path, pack: str) -> bool:
     return True
 
 
-def _mirror_to_compressed(rel: Path, pack: str) -> None:
+def _mirror_to_condensed(rel: Path, pack: str) -> None:
     src = SRC / rel
     dst = DST / rel
     if not dst.exists():
-        return  # no compressed counterpart yet (e.g. new file)
+        return  # no condensed counterpart yet (e.g. new file)
     text = dst.read_text(encoding="utf-8")
     m = _FM_RE.match(text)
     if not m:
@@ -119,7 +119,7 @@ def _refresh_hash(rel: Path, hashes: dict) -> None:
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     ap.add_argument("--pack", required=True, choices=sorted(PACK_DEFAULTS))
-    ap.add_argument("paths", nargs="+", help="repo-relative paths under .agent-src.uncompressed/")
+    ap.add_argument("paths", nargs="+", help="repo-relative paths under .agent-src.uncondensed/")
     args = ap.parse_args(argv)
 
     hashes: dict = json.loads(HASH_FILE.read_text()) if HASH_FILE.exists() else {}
@@ -128,17 +128,17 @@ def main(argv: list[str] | None = None) -> int:
         p = Path(raw)
         if p.is_absolute():
             p = p.relative_to(ROOT)
-        if not p.is_relative_to(Path(".agent-src.uncompressed")):
-            print(f"  skip (not under .agent-src.uncompressed/): {p}", file=sys.stderr)
+        if not p.is_relative_to(Path(".agent-src.uncondensed")):
+            print(f"  skip (not under .agent-src.uncondensed/): {p}", file=sys.stderr)
             continue
-        rel = p.relative_to(".agent-src.uncompressed")
+        rel = p.relative_to(".agent-src.uncondensed")
         src_file = SRC / rel
         if not src_file.is_file():
             print(f"  skip (missing): {p}", file=sys.stderr)
             continue
         if _annotate(src_file, args.pack):
             changed += 1
-        _mirror_to_compressed(rel, args.pack)
+        _mirror_to_condensed(rel, args.pack)
         _refresh_hash(rel, hashes)
     HASH_FILE.write_text(json.dumps(hashes, indent=2, sort_keys=True) + "\n", encoding="utf-8")
     print(f"annotated {changed} files with pack={args.pack}")

package/scripts/apply_modules_config.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Persist a ``modules:`` block into ``.agent-project-settings.yml``.
+
+Phase E Step 1 of road-to-configurable-modules — the persistence side
+of the GUI wizard's modules step. Reads a JSON payload (stdin or
+``--input-file``) and patches the ``modules.*`` keys in the team file
+while preserving comments, ordering, and surrounding YAML blocks.
+
+The patch logic mirrors :func:`scripts.install._replace_template_value_raw`
+so the wizard, ``/agents init``, and a hand-edit all converge on the
+same on-disk shape. Comment-preserving by design — never round-trips
+through PyYAML, which strips block comments.
+
+Usage:
+    cat payload.json | python3 scripts/apply_modules_config.py --project <root>
+    python3 scripts/apply_modules_config.py --project <root> --input-file <path>
+
+JSON payload shape (matches ``proposed_block`` from
+``propose_modules_config.py --json``):
+
+    {
+      "enabled": true,
+      "root_paths": ["app/Modules"],
+      "namespace_template": "App\\\\Modules\\\\{ModuleName}\\\\App",
+      "agent_folder": "agents",
+      "skip_dirs": [".module-template", ".example"]
+    }
+
+Exit codes:
+    0 — patched successfully (or no-op when payload says decline).
+    2 — invalid arguments, unreachable project root, or malformed JSON.
+    3 — template-resolve failure (cannot bootstrap a missing team file).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
+TEAM_FILE = ".agent-project-settings.yml"
+TEMPLATE_LOGICAL = "templates/agents/agent-project-settings.example.yml"
+
+_BARE_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+def _yaml_scalar(value: str) -> str:
+    """Format a string as a YAML scalar with minimal quoting.
+
+    Mirror of :func:`scripts.install._yaml_scalar` — duplicated here so
+    the persistence helper stays self-contained (importing ``install``
+    drags 4.8k lines of installer surface).
+    """
+    if value == "":
+        return '""'
+    if value in ("true", "false"):
+        return value
+    if value.isdigit():
+        return value
+    if _BARE_ID_RE.match(value):
+        return value
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _replace_template_value_raw(template: str, dotted_path: str, raw_yaml: str) -> str:
+    """Replace the value at *dotted_path* with the pre-formatted *raw_yaml*.
+
+    Port of :func:`scripts.install._replace_template_value_raw`. Tracks
+    parent sections by indent (2-space stride) so the leaf scalar is
+    only patched when every parent matches. Comments + indentation are
+    preserved. Returns *template* unchanged if the path is missing.
+    """
+    parts = dotted_path.split(".")
+    if not parts:
+        return template
+    sections = parts[:-1]
+    key = parts[-1]
+    target_indent = "  " * len(sections)
+    header_re = re.compile(r"^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*$")
+    scalar_re = re.compile(r"^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*\S.*$")
+    current_path: list[str | None] = [None] * len(sections)
+    lines = template.splitlines()
+    for idx, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        m_header = header_re.match(line)
+        if m_header:
+            indent = m_header.group(1)
+            name = m_header.group(2)
+            depth = len(indent) // 2
+            if depth < len(sections):
+                current_path[depth] = name
+                for d in range(depth + 1, len(sections)):
+                    current_path[d] = None
+            continue
+        m_scalar = scalar_re.match(line)
+        if not m_scalar:
+            continue
+        indent = m_scalar.group(1)
+        name = m_scalar.group(2)
+        if name != key or indent != target_indent:
+            continue
+        if current_path != list(sections):
+            continue
+        lines[idx] = f"{indent}{key}: {raw_yaml}"
+        return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
+    return template
+
+
+def _yaml_flow_list(items: list[str]) -> str:
+    """Render a list as a flow-style YAML sequence (`[a, b, c]`)."""
+    if not items:
+        return "[]"
+    return "[" + ", ".join(_yaml_scalar(item) for item in items) + "]"
+
+
+def _yaml_bool(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _resolve_template_path() -> Path | None:
+    """Resolve the bundled ``agent-project-settings.example.yml``.
+
+    Used to bootstrap the team file when the consumer project has not
+    committed one yet. Mirrors :func:`scripts.check_template_pin_drift._template_files`
+    so source-of-truth resolution is identical across helpers.
+    """
+    src = resolve_logical(TEMPLATE_LOGICAL)
+    if src is not None and src.is_file():
+        return src
+    fallback = REPO_ROOT / ".agent-src.uncondensed" / TEMPLATE_LOGICAL
+    if fallback.is_file():
+        return fallback
+    return None
+
+
+def _load_payload(args: argparse.Namespace) -> dict[str, object]:
+    if args.input_file:
+        raw = Path(args.input_file).read_text(encoding="utf-8")
+    else:
+        raw = sys.stdin.read()
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(f"error: invalid JSON payload: {exc}", file=sys.stderr)
+        sys.exit(2)
+    if not isinstance(data, dict):
+        print("error: payload must be a JSON object", file=sys.stderr)
+        sys.exit(2)
+    return data
+
+
+def _coerce_str_list(value: object, field: str) -> list[str]:
+    if not isinstance(value, list):
+        print(f"error: payload.{field} must be a list", file=sys.stderr)
+        sys.exit(2)
+    out: list[str] = []
+    for item in value:
+        if not isinstance(item, str):
+            print(f"error: payload.{field}[*] must be strings", file=sys.stderr)
+            sys.exit(2)
+        out.append(item)
+    return out
+
+
+def _patch_modules(template: str, payload: dict[str, object]) -> str:
+    """Patch the four modules.* leaves in *template* per *payload*.
+
+    Missing keys in *payload* fall back to safe defaults that match the
+    bundled template (``enabled=false``, empty paths, ``agents``,
+    template skip-dirs). Patching is no-op for any key whose dotted
+    path is absent from *template* (returns the section untouched).
+    """
+    enabled = bool(payload.get("enabled", False))
+    root_paths = _coerce_str_list(payload.get("root_paths", []), "root_paths")
+    ns_template = payload.get("namespace_template", "")
+    if not isinstance(ns_template, str):
+        print("error: payload.namespace_template must be a string", file=sys.stderr)
+        sys.exit(2)
+    agent_folder = payload.get("agent_folder", "agents")
+    if not isinstance(agent_folder, str) or agent_folder == "":
+        agent_folder = "agents"
+    skip_dirs = _coerce_str_list(
+        payload.get("skip_dirs", [".module-template", ".example"]),
+        "skip_dirs",
+    )
+
+    acknowledged = bool(payload.get("detection_acknowledged", False))
+
+    out = template
+    out = _replace_template_value_raw(out, "modules.enabled", _yaml_bool(enabled))
+    out = _replace_template_value_raw(out, "modules.root_paths", _yaml_flow_list(root_paths))
+    out = _replace_template_value_raw(out, "modules.namespace_template", _yaml_scalar(ns_template))
+    out = _replace_template_value_raw(out, "modules.agent_folder", _yaml_scalar(agent_folder))
+    out = _replace_template_value_raw(out, "modules.skip_dirs", _yaml_flow_list(skip_dirs))
+    out = _replace_template_value_raw(
+        out, "modules.detection_acknowledged", _yaml_bool(acknowledged)
+    )
+    return out
+
+
+def _patch_acknowledge_only(template: str) -> str:
+    """Flip ``modules.detection_acknowledged`` to ``true`` without touching siblings.
+
+    Used by the ``--acknowledge-only`` flag: the user said "not now" to
+    the on-the-fly prompt and we only want to silence future nags. Every
+    other ``modules.*`` key stays at whatever the template / team file
+    already had.
+    """
+    return _replace_template_value_raw(
+        template, "modules.detection_acknowledged", _yaml_bool(True)
+    )
+
+
+def _bootstrap_team_file(team_path: Path) -> str:
+    template_path = _resolve_template_path()
+    if template_path is None:
+        print(
+            "error: cannot bootstrap .agent-project-settings.yml — "
+            f"template missing at {TEMPLATE_LOGICAL}",
+            file=sys.stderr,
+        )
+        sys.exit(3)
+    return template_path.read_text(encoding="utf-8")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="apply_modules_config.py",
+        description=(
+            "Patch the modules: block in .agent-project-settings.yml "
+            "from a JSON payload (stdin or --input-file). Comment- and "
+            "ordering-preserving."
+        ),
+    )
+    parser.add_argument(
+        "--project",
+        default=None,
+        help="project root containing .agent-project-settings.yml (default: cwd)",
+    )
+    parser.add_argument(
+        "--input-file",
+        default=None,
+        help="read JSON payload from this file instead of stdin",
+    )
+    parser.add_argument(
+        "--decline",
+        action="store_true",
+        help="payload represents an explicit decline — write nothing, exit 0",
+    )
+    parser.add_argument(
+        "--acknowledge-only",
+        action="store_true",
+        help=(
+            "flip modules.detection_acknowledged=true without touching any "
+            "other modules.* key — used by the on-the-fly detection skill "
+            "when the user said 'not now'. Reads no payload."
+        ),
+    )
+    args = parser.parse_args(argv)
+    if args.decline:
+        return 0
+    root = Path(args.project).expanduser().resolve() if args.project else Path.cwd().resolve()
+    if not root.is_dir():
+        print(f"error: project root is not a directory: {root}", file=sys.stderr)
+        return 2
+    team_path = root / TEAM_FILE
+    if team_path.is_file():
+        template = team_path.read_text(encoding="utf-8")
+    else:
+        template = _bootstrap_team_file(team_path)
+    if args.acknowledge_only:
+        patched = _patch_acknowledge_only(template)
+    else:
+        payload = _load_payload(args)
+        patched = _patch_modules(template, payload)
+    team_path.write_text(patched, encoding="utf-8")
+    print(str(team_path))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/audit_adr_coverage.py

@@ -25,8 +25,8 @@ CONTRACT_ROOT = ROOT / "docs" / "contracts"
 AREAS: dict[str, dict[str, str]] = {
     "cost":    {"contract": "cost-enforcement.md",
                 "scope":    "Budget ladder, hard-stop hook, cost reporting and dashboards."},
-    "caveman": {"contract": "compression-default-kill-criterion.md",
-                "scope":    "Caveman-speak compression, decompression, reversibility guards."},
+    "telegraph": {"contract": "condensation-default-kill-criterion.md",
+                "scope":    "Telegraph-speak condensation, decondensation, reversibility guards."},
     "schema":  {"contract": "agents/reference/docs/frontmatter-contract.md",
                 "scope":    "Frontmatter schemas, v2 rigor, lint behaviour for skills / rules / commands."},
     "router":  {"contract": "rule-router.md",

package/scripts/audit_auto_rules.py

@@ -2,7 +2,7 @@
 """Audit auto-rules for the Rule-Governance pass (Phase 5.1 of
 road-to-augment-limit-fit).
 
-Walk `.agent-src.uncompressed/rules/*.md`, collect per-rule frontmatter
+Walk `.agent-src.uncondensed/rules/*.md`, collect per-rule frontmatter
 (`description`, `triggers`, `routes_to`, `tier`), measure body and
 registry-stub costs, and emit:
 
@@ -25,7 +25,7 @@ from pathlib import Path
 import yaml
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-SRC_RULES = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+SRC_RULES = REPO_ROOT / ".agent-src.uncondensed" / "rules"
 PROJECTED_RULES = REPO_ROOT / ".augment" / "rules"
 REPORT_DIR = REPO_ROOT / "agents" / "reports"
 JSON_OUT = REPORT_DIR / "auto-rules-audit.json"

package/scripts/audit_cloud_compatibility.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """audit_cloud_compatibility.py — tier each artefact for cloud distribution.
 
-Classifies every .md under .agent-src.uncompressed/{skills,rules,commands,
+Classifies every .md under .agent-src.uncondensed/{skills,rules,commands,
 guidelines} into a tier:
 
   T1  Universal       no script / no FS / pure guidance
@@ -30,7 +30,7 @@ from collections import Counter
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
-SOURCE = ROOT / ".agent-src.uncompressed"
+SOURCE = ROOT / ".agent-src.uncondensed"
 SCAN_DIRS = ["skills", "rules", "commands", "guidelines"]
 
 # patterns
@@ -47,7 +47,7 @@ HARD_RE = re.compile(
     re.IGNORECASE | re.MULTILINE,
 )
 FS_RE = re.compile(
-    r"(?:\.agent-src(?:\.uncompressed)?/|"
+    r"(?:\.agent-src(?:\.uncondensed)?/|"
     r"\.augment/|\.claude/|\.cursor/|\.clinerules/|"
     r"agents/|\.agent-settings\.yml|\.agent-chat-history)"
 )

package/scripts/audit_command_surface.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Command-surface inventory + overlap detection + usage signal.
 
-Walks ``.agent-src.uncompressed/commands/**/*.md``, collects metadata for
+Walks ``.agent-src.uncondensed/commands/**/*.md``, collects metadata for
 each command (path, description, aliases, line count, last-modified),
 flags overlap pairs by keyword-cosine similarity, and adds a usage
 signal from git history (commands not touched in 90+ days are
@@ -37,7 +37,7 @@ from pathlib import Path
 from typing import List
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-DEFAULT_ROOT = REPO_ROOT / ".agent-src.uncompressed" / "commands"
+DEFAULT_ROOT = REPO_ROOT / ".agent-src.uncondensed" / "commands"
 REPORT_DIR = REPO_ROOT / "agents" / "reports"
 OUT_JSON = REPORT_DIR / "command-surface.json"
 OUT_MD = REPORT_DIR / "command-surface.md"
@@ -142,8 +142,8 @@ def git_last_modified(path: Path) -> tuple[str, int | None]:
 def git_history(path: Path) -> tuple[int, str, int | None]:
     """Return (commit_count, first_commit_iso, days_since_first_commit).
 
-    Uses ``--follow`` so renames (e.g. the ``.augment.uncompressed`` →
-    ``.agent-src.uncompressed`` rename) don't reset the per-file history.
+    Uses ``--follow`` so renames (e.g. the ``.augment.uncondensed`` →
+    ``.agent-src.uncondensed`` rename) don't reset the per-file history.
     """
     try:
         out = subprocess.check_output(
@@ -226,7 +226,7 @@ def render_md(commands: List[Command], pairs: list[dict]) -> str:
         "# Command-Surface Inventory",
         "",
         f"> Generated by `scripts/audit_command_surface.py`. "
-        f"Source: `.agent-src.uncompressed/commands/`.",
+        f"Source: `.agent-src.uncondensed/commands/`.",
         "",
         "## Summary",
         "",
@@ -267,10 +267,10 @@ def render_md(commands: List[Command], pairs: list[dict]) -> str:
         "were considered:",
         "",
         "- **Filesystem mtime** — useless: `task sync` rewrites every file when the "
-        "  compressed and uncompressed trees are regenerated.",
-        "- **Git history (`--follow`)** — uninformative here: the `.agent-src.uncompressed/` "
-        "  directory is the result of a recent rename (`.augment.uncompressed/` → "
-        "  `.agent-src.uncompressed/`), so almost every file shows a single recent commit "
+        "  condensed and uncondensed trees are regenerated.",
+        "- **Git history (`--follow`)** — uninformative here: the `.agent-src.uncondensed/` "
+        "  directory is the result of a recent rename (`.augment.uncondensed/` → "
+        "  `.agent-src.uncondensed/`), so almost every file shows a single recent commit "
         f"  on the current branch. {len(low_signal)} of {len(commands)} commands fall into the "
         f"  ≤{LOW_SIGNAL_COMMIT_COUNT}-commits / ≤{LOW_SIGNAL_AGE_DAYS}d-old bucket purely as a "
         "  rename artefact, not as a real cold-tail signal.",

package/scripts/audit_likelihood.py

@@ -32,8 +32,8 @@ AUDIT_MD = REPORT_DIR / "auto-rules-audit.md"
 LIKELIHOOD_JSON = REPORT_DIR / "auto-rules-likelihood.json"
 
 CORPUS_GLOBS = [
-    ".agent-src.uncompressed/skills/**/SKILL.md",
-    ".agent-src.uncompressed/commands/**/*.md",
+    ".agent-src.uncondensed/skills/**/SKILL.md",
+    ".agent-src.uncondensed/commands/**/*.md",
     "agents/settings/contexts/**/*.md",
     "docs/guidelines/**/*.md",
 ]

package/scripts/audit_user_type_axis.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Audit the user-type axis frontmatter coverage (step-9 Phase 4).
 
-Two checks across `.agent-src.uncompressed/skills/`:
+Two checks across `.agent-src.uncondensed/skills/`:
 
 1. **Orphan values** — every `recommended_for_user_types` value must have
    a corresponding `user-types/<value>.yml` config. Orphans are FATAL
@@ -27,7 +27,7 @@ from collections import defaultdict
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-SKILLS_ROOT = REPO_ROOT / ".agent-src.uncompressed" / "skills"
+SKILLS_ROOT = REPO_ROOT / ".agent-src.uncondensed" / "skills"
 USER_TYPES_ROOT = REPO_ROOT / "user-types"
 REPORT_PATH = REPO_ROOT / "agents" / "reports" / "user-type-axis-audit.md"
 

package/scripts/bench_ab_cache_dispatch.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Cache-aware dispatch for `task bench:ab` arms.
+
+Phase 5 supporting helper. Wraps the Phase 2 cache lookup so the Taskfile
+entries can stay readable. Given a corpus name (`tracka` / `trackb`),
+checks whether the cached `without` report is fresh; if so, runs only the
+`with` arm of the corresponding runner. Otherwise runs both.
+
+Cost-saving math: a daily `task bench:ab` re-runs only the `with` arm
+when the corpus, claude CLI version, and target shape haven't changed.
+That halves the wall-time + cost of the daily run.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from _lib import bench_ab_cache  # type: ignore[import-not-found]  # noqa: E402
+
+RUNNER_FOR = {
+    "tracka": (REPO_ROOT / "scripts" / "bench_ab_tracka_run.py", "ab-tracka.yaml"),
+    "trackb": (REPO_ROOT / "scripts" / "bench_ab_task_runner.py", "ab-trackb.yaml"),
+}
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Cache-aware dispatch.")
+    parser.add_argument("corpus", choices=tuple(RUNNER_FOR))
+    parser.add_argument(
+        "extra",
+        nargs=argparse.REMAINDER,
+        help="Extra args forwarded to the underlying runner.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    runner, corpus_name = RUNNER_FOR[args.corpus]
+    corpus_path = REPO_ROOT / "internal" / "bench" / "corpora" / corpus_name
+    if not corpus_path.exists():
+        sys.stderr.write(f"bench_ab_cache_dispatch: corpus missing at {corpus_path}\n")
+        return 1
+    lookup = bench_ab_cache.lookup(corpus_path)
+    if lookup.fresh and lookup.report_path is not None:
+        sys.stdout.write(
+            f"bench_ab_cache_dispatch ({args.corpus}): reusing fresh without baseline "
+            f"({lookup.report_path.name}) — running with-arm only\n"
+        )
+        variants = ("with",)
+    else:
+        sys.stdout.write(
+            f"bench_ab_cache_dispatch ({args.corpus}): cache {lookup.reason} — running both arms\n"
+        )
+        variants = ("with", "without")
+    cmd = [sys.executable, str(runner), "--variant", variants[0]] + list(args.extra)
+    if len(variants) == 2:
+        cmd = [sys.executable, str(runner), "--variant", "both"] + list(args.extra)
+    return subprocess.run(cmd, check=False).returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())