@matt82198/aesop 0.1.0 → 0.2.0

package/driver/wave_loop.py

@@ -0,0 +1,1041 @@
+#!/usr/bin/env python3
+"""Wave loop engine: orchestrates a full multi-item wave through AgentDriver backends.
+
+This module implements Step 3 of the driver integration plan: a Python wave engine
+that mirrors the phase sequence from wave-flat-dispatch.template.mjs but runs
+offline against AgentDriver backends (Claude Code, Codex, open-model, etc.).
+
+Phases (mirror the template):
+  1. Preflight ownership guard: check no two items share an ownsFiles path
+  2. Resolve policy ONCE: call verification_policy(caps) and use the returned
+     knobs for repair_cap, spot_check_frac, require_adversarial_review
+  3. Cost-ceiling gate (fail-closed): before build and before each repair round,
+     check spend against ceiling; abort if tripped
+  4. Build (PARALLEL): use ThreadPoolExecutor to dispatch items concurrently,
+     running each item's test, honoring disjoint ownership
+  5. Bounded repair: for failed items, retry with test output appended to prompt,
+     up to policy's repair_cap rounds
+  6. Adversarial review: if required, dispatch a review per item or mark deferred
+  7. Batched ship: if git config given, add/commit/push the verified items
+
+HONESTY GUARANTEE:
+  - Verified = True ONLY if the item's test passed (exit code 0 from run_command).
+  - Any exception -> item.verified = False, never a false green.
+  - Ownership is enforced at the driver level (dispatch_worker rejects out-of-scope).
+  - Adversarial review is NOT yet enforced; marked as 'deferred' (TODO in a later increment).
+
+FAIL-SAFE:
+  - Cost-ceiling check: if exceeded, ABORT the wave immediately (return early).
+  - Disjoint ownership: any overlap -> ABORT with structured error, no dispatch.
+  - Repair cap bounded: never infinite retry loop.
+
+stdlib-only, ASCII-only, Windows + Linux safe.
+"""
+
+import concurrent.futures
+import hashlib
+import json
+import os
+import posixpath
+import re
+import shlex
+import sys
+import threading
+import time
+import uuid
+from math import ceil
+from pathlib import Path
+from typing import Optional, Dict, Any, List, Tuple
+
+# Add driver/ to path for imports.
+REPO = Path(__file__).resolve().parent.parent
+DRIVER_DIR = REPO / "driver"
+if str(DRIVER_DIR) not in sys.path:
+    sys.path.insert(0, str(DRIVER_DIR))
+
+from agent_driver import AgentDriver
+from wave_bridge import build_manifest_item, dispatch_item
+from verification_policy import verification_policy
+
+# Try to import cost_ceiling and coordination (optional, for safety gates).
+try:
+    import sys
+    TOOLS_DIR = REPO / "tools"
+    if str(TOOLS_DIR) not in sys.path:
+        sys.path.insert(0, str(TOOLS_DIR))
+    import cost_ceiling
+except ImportError:
+    cost_ceiling = None
+
+try:
+    STATE_STORE_DIR = REPO / "state_store"
+    if str(STATE_STORE_DIR) not in sys.path:
+        sys.path.insert(0, str(STATE_STORE_DIR))
+    import coordination
+except ImportError:
+    coordination = None
+
+
+# ========================================================================
+# Sanitization and Security
+# ========================================================================
+
+def _quote_arg(s: str) -> str:
+    """Quote an argument for safe shell execution across Windows and POSIX.
+
+    On Windows (cmd.exe), single quotes don't quote; shlex.quote (POSIX-only)
+    is unsafe. This function uses subprocess.list2cmdline semantics for Windows
+    and shlex.quote for POSIX systems.
+
+    The durable fix is to refactor run_command to accept a list of arguments
+    instead of shell=True strings (deferred).
+
+    Args:
+        s: the string to quote for shell execution
+
+    Returns:
+        str: properly quoted argument safe for shell execution on this OS
+    """
+    if os.name == 'nt':
+        # Windows (cmd.exe): use subprocess.list2cmdline semantics.
+        # Double quotes are the safe quoting mechanism; embed quotes are escaped
+        # with backslash, and backslashes before quotes are escaped.
+        # For safety, we wrap in double quotes and escape embedded quotes/backslashes.
+        if not s:
+            return '""'
+        # Escape backslashes before quotes, then escape quotes
+        escaped = s.replace('\\', '\\\\').replace('"', '\\"')
+        return f'"{escaped}"'
+    else:
+        # POSIX: shlex.quote handles all cases safely
+        return shlex.quote(s)
+
+
+def _safe_slug(slug: str) -> str:
+    """Sanitize a slug to prevent path traversal attacks and enforce filesystem limits.
+
+    Whitelists [A-Za-z0-9_-]+ and rejects or normalizes everything else.
+    This prevents '../../../etc/x' style escape attempts when slug is used
+    in path joins.
+
+    LENGTH BOUND:
+        The returned slug is guaranteed to produce a journal filename (slug + '.json')
+        that fits within the 255-byte filesystem limit (stricter than MAX_PATH on
+        Windows). The normalized slug is truncated to ~200 characters, leaving room
+        for a '-' separator + 8-char hash suffix + '.json' extension.
+
+        When truncation occurs (slug > 200 chars after normalization), a stable
+        hash suffix is always appended to preserve uniqueness.
+
+    COLLISION PREVENTION:
+        If normalization changed the string (removed characters), appends a stable
+        suffix derived from a hash of the raw slug to prevent collisions when two
+        different raw slugs normalize to the same value.
+
+    Args:
+        slug: the slug to sanitize
+
+    Returns:
+        str: sanitized slug with only alphanumeric, underscore, hyphen,
+             optionally truncated and with a hash suffix if truncation or
+             normalization occurred
+
+    Raises:
+        ValueError: if slug is empty or contains only invalid characters
+    """
+    MAX_NORMALIZED_LEN = 200  # Leaves room for '-' + 8-char hash + '.json' (< 255)
+
+    if not slug:
+        raise ValueError("slug cannot be empty")
+
+    # Keep only alphanumeric, underscore, and hyphen
+    sanitized = re.sub(r'[^A-Za-z0-9_-]', '', slug)
+
+    if not sanitized:
+        raise ValueError(f"slug contains no valid characters: {slug}")
+
+    # Track if we need to append a hash suffix
+    needs_suffix = sanitized != slug  # Normalization changed the string
+
+    # Truncate to MAX_NORMALIZED_LEN if necessary; mark for hash suffix
+    if len(sanitized) > MAX_NORMALIZED_LEN:
+        sanitized = sanitized[:MAX_NORMALIZED_LEN]
+        needs_suffix = True  # Always append hash when truncated for uniqueness
+
+    # If normalization or truncation changed the string, append a stable suffix
+    if needs_suffix:
+        raw_hash = hashlib.sha1(slug.encode()).hexdigest()[:8]
+        sanitized = f"{sanitized}-{raw_hash}"
+
+    return sanitized
+
+
+# ========================================================================
+# Wave Recovery: Journal and Resume Support
+# ========================================================================
+
+def _write_journal_entry(state_dir: str, slug: str, phase: str, data: Dict[str, Any]) -> None:
+    """Write a journal entry for an item's progress.
+
+    Args:
+        state_dir: directory path for state files
+        slug: item slug (identifier)
+        phase: phase name (e.g., "verified", "failed", "dispatched")
+        data: dict with outcome data (verified, testExit, repairs, etc.)
+
+    Journal is stored as: state_dir/journal/<slug>.json with timestamp.
+    Slug is sanitized to prevent path traversal attacks.
+    """
+    state_path = Path(state_dir)
+    journal_dir = state_path / "journal"
+    journal_dir.mkdir(parents=True, exist_ok=True)
+
+    # Sanitize slug to prevent path traversal.
+    try:
+        safe_slug = _safe_slug(slug)
+    except ValueError:
+        # Fail-closed: if slug is invalid, skip journaling.
+        return
+
+    journal_file = journal_dir / f"{safe_slug}.json"
+    entry = {
+        "slug": slug,
+        "phase": phase,
+        "timestamp": time.time(),
+        **data,
+    }
+
+    try:
+        journal_file.write_text(json.dumps(entry, default=str) + "\n")
+    except Exception:
+        # Fail-closed: if journal write fails, continue without journaling.
+        pass
+
+
+def _load_journal_state(state_dir: str) -> Dict[str, Dict[str, Any]]:
+    """Load journal state from state_dir.
+
+    Reads all JSON files from state_dir/journal/ and returns a dict
+    mapping slug -> journal_entry.
+
+    Returns:
+        dict mapping slug -> {phase, verified, testExit, ...}
+        Returns empty dict if journal dir doesn't exist.
+    """
+    state_path = Path(state_dir)
+    journal_dir = state_path / "journal"
+
+    if not journal_dir.exists():
+        return {}
+
+    journal_state = {}
+    try:
+        # Only read files that match the safe slug pattern to avoid traversal attacks.
+        for journal_file in journal_dir.glob("[A-Za-z0-9_-]*.json"):
+            try:
+                entry = json.loads(journal_file.read_text())
+                slug = entry.get("slug")
+                if slug:
+                    journal_state[slug] = entry
+            except Exception:
+                # Skip malformed entries.
+                pass
+    except Exception:
+        # Fail-closed: if reading fails, return empty state.
+        pass
+
+    return journal_state
+
+
+def _should_skip_from_journal(journal_entry: Dict[str, Any]) -> bool:
+    """Determine if an item should be skipped based on journal entry.
+
+    Skip only if verified=True (even then, trust-but-verify will re-run the test).
+    Re-run if verified=False or not present.
+
+    Args:
+        journal_entry: dict with verified, testExit, etc.
+
+    Returns:
+        bool: True if item should be skipped from build (only trust-verify),
+              False if item should be re-built.
+    """
+    return journal_entry.get("verified", False) is True
+
+
+def _release_stale_leases(state_dir: str, journal_state: Dict[str, Dict[str, Any]]) -> None:
+    """Release stale leases from dead instances.
+
+    Scans journal for old instance_ids and releases their coordination leases
+    so resume can re-claim resources. Fail-closed: any release error is ignored.
+
+    Args:
+        state_dir: directory path for state files
+        journal_state: dict of journal entries by slug
+    """
+    if coordination is None:
+        return
+
+    try:
+        STATE_STORE_DIR = REPO / "state_store"
+        if str(STATE_STORE_DIR) not in sys.path:
+            sys.path.insert(0, str(STATE_STORE_DIR))
+        from state_store import store
+
+        db_path = Path(state_dir) / "state.db"
+        if not db_path.exists():
+            return
+
+        event_store = store.EventStore(str(db_path))
+
+        for slug, entry in journal_state.items():
+            old_instance_id = entry.get("instance_id")
+            if old_instance_id:
+                try:
+                    coordination.release(event_store, resource=slug, instance_id=old_instance_id)
+                except Exception:
+                    # Ignore release errors; fail-closed.
+                    pass
+    except Exception:
+        # Fail-closed: if coordination is unavailable, continue without release.
+        pass
+
+
+def run_wave(
+    driver: AgentDriver,
+    manifest: Dict[str, Any],
+    *,
+    state_dir: Optional[str] = None,
+    git: Optional[Dict[str, str]] = None,
+    resume_journal: bool = False,
+) -> Dict[str, Any]:
+    """Run a full multi-item wave through an AgentDriver backend.
+
+    Implements the complete wave algorithm: preflight ownership guard, parallel
+    build, bounded repair, optional adversarial review, and batched git ship.
+
+    Supports resumable waves: if resume_journal=True and state_dir exists,
+    skips items marked as verified in the journal and does trust-but-verify
+    re-running of their tests. Releases stale leases from dead instances.
+
+    Args:
+        driver: AgentDriver instance providing dispatch_worker, run_command, etc.
+        manifest: dict with:
+          - items: list of item dicts with {slug, ownsFiles, prompt, testCmd, workDir, ...}
+          - (optional) other manifest fields
+        state_dir: optional path to state directory for coordination claims and
+                   cost_ceiling ledger. If None, these features are skipped.
+        git: optional dict with {expectTopLevel: str} for git operations. If None,
+             ship phase is skipped.
+        resume_journal: if True and state_dir exists, load journal and skip items
+                       marked as verified (but re-run their tests for trust-but-verify).
+
+    Returns:
+        dict with structure:
+          {
+            "preflight_ok": bool,
+            "aborted": bool,
+            "abort_reason": str or None,
+            "built": [
+              {
+                "slug": str,
+                "dispatched": bool,
+                "verified": bool,
+                "testExit": int or None,
+                "repairs": int,
+                "error": str or None,
+                "filesWritten": [str],
+                "skipped_from_journal": bool (only if resume_journal=True),
+              },
+              ...
+            ],
+            "shipped": [str] or None (list of slugs, or None if git not configured),
+            "ceiling": dict or None (from cost_ceiling.check, or None if no ceiling),
+            "policy": dict (the resolved verification_policy),
+            "resume_stats": dict (only if resume_journal=True) with:
+              {
+                "skipped_from_journal": int,
+                "rebuilt": int,
+              }
+          }
+
+    Fail-safe invariants:
+      - Verified is True ONLY from run_command exit code 0.
+      - Any exception in an item's dispatch -> verified=False for that item.
+      - Cost ceiling: if check() says exceeded, abort immediately with no more dispatch.
+      - Disjoint ownership: any overlap -> abort with structured error, no dispatch.
+    """
+    result = {
+        "preflight_ok": False,
+        "aborted": False,
+        "abort_reason": None,
+        "built": [],
+        "shipped": None,
+        "ceiling": None,
+        "policy": None,
+        "resume_stats": None,
+    }
+
+    # Extract items from manifest.
+    items = manifest.get("items", [])
+
+    # ========================================================================
+    # PHASE 0 (optional): Resume - Load journal state and release stale leases
+    # ========================================================================
+    journal_state = {}
+    resume_stats = {"skipped_from_journal": 0, "rebuilt": 0}
+    resume_stats_lock = threading.Lock()  # Protect resume_stats from concurrent access
+    if resume_journal and state_dir:
+        journal_state = _load_journal_state(state_dir)
+        _release_stale_leases(state_dir, journal_state)
+        if journal_state:
+            result["resume_stats"] = resume_stats
+
+    # ========================================================================
+    # PHASE 1: Preflight ownership guard
+    # ========================================================================
+    owner_map = {}  # normalized file -> slug
+    conflicts = []
+
+    for item in items:
+        slug = item.get("slug", "unknown")
+        owned_files = item.get("ownsFiles", [])
+        for f in owned_files:
+            # Platform-independent path normalization: handle separators and case uniformly.
+            # Replace all backslashes with forward slashes, normalize with posixpath,
+            # and convert to lowercase for case-insensitive comparison on all platforms.
+            normalized = posixpath.normpath(f.replace("\\", "/")).lower()
+            if normalized in owner_map:
+                conflicts.append(
+                    {
+                        "file": f,
+                        "normalized": normalized,
+                        "items": [owner_map[normalized], slug],
+                    }
+                )
+            else:
+                owner_map[normalized] = slug
+
+    if conflicts:
+        result["aborted"] = True
+        result["abort_reason"] = "ownership_overlap"
+        result["conflicts"] = conflicts
+        return result
+
+    result["preflight_ok"] = True
+
+    # ========================================================================
+    # PHASE 2: Resolve verification policy ONCE
+    # ========================================================================
+    caps = driver.probe_capabilities()
+    policy = verification_policy(caps)
+    result["policy"] = policy
+
+    repair_cap = policy.get("repair_cap", 1)
+    spot_check_frac = policy.get("spot_check_frac", 0.0)
+    require_adversarial_review = policy.get("require_adversarial_review", False)
+
+    # ========================================================================
+    # PHASE 3: Cost-ceiling gate (before build)
+    # ========================================================================
+    if cost_ceiling is not None and state_dir is not None:
+        ceiling_result = cost_ceiling.check(
+            spent=driver.get_tokens_spent(),
+            trip=True,
+            state_dir=state_dir,
+        )
+        result["ceiling"] = ceiling_result
+
+        if ceiling_result.get("exceeded", False):
+            result["aborted"] = True
+            result["abort_reason"] = "cost_ceiling_exceeded"
+            return result
+
+    # ========================================================================
+    # PHASE 4: Build (PARALLEL with ThreadPoolExecutor)
+    # ========================================================================
+    # Prepare built items list and track for repair.
+    built_items = []
+    failed_items = []  # (index, item, result) tuples for repair
+
+    def build_item(item_index: int, item: Dict[str, Any]) -> Tuple[int, Dict[str, Any]]:
+        """Build one item and return (index, result_dict)."""
+        slug = item.get("slug", f"item-{item_index}")
+        workdir = item.get("workDir", ".")
+
+        # ====================================================================
+        # RESUME CHECK: If in journal and verified, skip dispatch and trust-verify
+        # ====================================================================
+        journal_entry = journal_state.get(slug)
+        skipped_from_journal = False
+        if journal_entry and _should_skip_from_journal(journal_entry):
+            skipped_from_journal = True
+            with resume_stats_lock:
+                resume_stats["skipped_from_journal"] += 1
+
+            # Trust-but-verify: re-run the test for the journaled item
+            test_cmd = item.get("testCmd", "")
+            if test_cmd:
+                try:
+                    test_result = driver.run_command(test_cmd, cwd=workdir)
+                    if test_result.exit_code == 0:
+                        # Test still passes; mark verified.
+                        return (
+                            item_index,
+                            {
+                                "slug": slug,
+                                "dispatched": False,
+                                "verified": True,
+                                "testExit": 0,
+                                "repairs": 0,
+                                "error": None,
+                                "filesWritten": [],
+                                "skipped_from_journal": True,
+                                "trust_verified": True,
+                            },
+                        )
+                    else:
+                        # Test failed on re-run; flip to False and mark for rebuild.
+                        with resume_stats_lock:
+                            resume_stats["rebuilt"] += 1
+                        return (
+                            item_index,
+                            {
+                                "slug": slug,
+                                "dispatched": False,
+                                "verified": False,
+                                "testExit": test_result.exit_code,
+                                "repairs": 0,
+                                "error": "trust-verify test failed (re-run)",
+                                "filesWritten": [],
+                                "skipped_from_journal": True,
+                                "trust_verified": False,
+                            },
+                        )
+                except Exception as exc:
+                    # Test re-run failed; flip to False and mark for rebuild.
+                    with resume_stats_lock:
+                        resume_stats["rebuilt"] += 1
+                    return (
+                        item_index,
+                        {
+                            "slug": slug,
+                            "dispatched": False,
+                            "verified": False,
+                            "testExit": None,
+                            "repairs": 0,
+                            "error": f"trust-verify exception: {exc}",
+                            "filesWritten": [],
+                            "skipped_from_journal": True,
+                            "trust_verified": False,
+                        },
+                    )
+            else:
+                # No test command; just mark as skipped but not verified (safe).
+                return (
+                    item_index,
+                    {
+                        "slug": slug,
+                        "dispatched": False,
+                        "verified": False,
+                        "testExit": None,
+                        "repairs": 0,
+                        "error": "no test command for trust-verify",
+                        "filesWritten": [],
+                        "skipped_from_journal": True,
+                        "trust_verified": False,
+                    },
+                )
+
+        # ====================================================================
+        # NORMAL BUILD: Not in journal or was marked as failed
+        # ====================================================================
+        with resume_stats_lock:
+            resume_stats["rebuilt"] += 1
+
+        # Try to claim the item if state_dir is given (fail-closed on claim failure).
+        instance_id = f"wave-{uuid.uuid4()}"
+        claim_held = False
+        if coordination is not None and state_dir is not None:
+            try:
+                from state_store import store
+                db_path = Path(state_dir) / "state.db"
+                event_store = store.EventStore(str(db_path))
+                claim_held = coordination.try_claim(
+                    event_store,
+                    resource=slug,
+                    instance_id=instance_id,
+                )
+                if not claim_held:
+                    # Item is claimed by another instance; skip it.
+                    return (
+                        item_index,
+                        {
+                            "slug": slug,
+                            "dispatched": False,
+                            "verified": False,
+                            "testExit": None,
+                            "repairs": 0,
+                            "error": "resource claimed by another instance",
+                            "filesWritten": [],
+                        },
+                    )
+            except Exception:
+                # On exception, fail-closed: skip the item.
+                claim_held = False
+
+        try:
+            # Build the manifest item with policy.
+            manifest_item = build_manifest_item(driver, item)
+
+            # Dispatch the item.
+            dispatch_result = dispatch_item(driver, manifest_item, workdir=workdir)
+
+            item_result = {
+                "slug": slug,
+                "dispatched": dispatch_result.get("route") == "driver",
+                "verified": dispatch_result.get("verified", False),
+                "testExit": dispatch_result.get("testExit"),
+                "repairs": 0,
+                "error": dispatch_result.get("error"),
+                "filesWritten": dispatch_result.get("filesWritten", []),
+                "workerId": dispatch_result.get("workerId"),
+            }
+
+            # Write journal entry for this item's outcome.
+            if state_dir:
+                _write_journal_entry(state_dir, slug, "dispatched", {
+                    "verified": item_result["verified"],
+                    "testExit": item_result["testExit"],
+                    "instance_id": instance_id,
+                })
+
+            return (item_index, item_result)
+
+        except Exception as exc:
+            # Catch-all: any exception -> failed result, never a false green.
+            if state_dir:
+                _write_journal_entry(state_dir, slug, "failed", {
+                    "verified": False,
+                    "testExit": None,
+                    "instance_id": instance_id,
+                    "error": str(exc),
+                })
+
+            return (
+                item_index,
+                {
+                    "slug": slug,
+                    "dispatched": False,
+                    "verified": False,
+                    "testExit": None,
+                    "repairs": 0,
+                    "error": f"build exception: {exc}",
+                    "filesWritten": [],
+                },
+            )
+        finally:
+            # Release the claim if held.
+            if claim_held and coordination is not None and state_dir is not None:
+                try:
+                    from state_store import store
+                    db_path = Path(state_dir) / "state.db"
+                    event_store = store.EventStore(str(db_path))
+                    coordination.release(event_store, resource=slug, instance_id=instance_id)
+                except Exception:
+                    pass
+
+    # Run build in parallel.
+    max_workers = min(8, len(items)) if items else 1
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = [
+            executor.submit(build_item, i, item)
+            for i, item in enumerate(items)
+        ]
+        for future in concurrent.futures.as_completed(futures):
+            try:
+                item_index, item_result = future.result()
+                built_items.append((item_index, items[item_index], item_result))
+
+                # Track failed items for repair.
+                if not item_result["verified"]:
+                    failed_items.append((item_index, items[item_index], item_result))
+            except Exception:
+                # Should not happen (build_item catches internally), but just in case.
+                pass
+
+    # Sort built_items by index to preserve order.
+    built_items.sort(key=lambda x: x[0])
+    result["built"] = [item_result for _, _, item_result in built_items]
+
+    # ========================================================================
+    # PHASE 5: Bounded repair
+    # ========================================================================
+    for repair_round in range(repair_cap):
+        if not failed_items:
+            break
+
+        # Cost-ceiling check before repair round.
+        if cost_ceiling is not None and state_dir is not None:
+            ceiling_result = cost_ceiling.check(
+                spent=driver.get_tokens_spent(),
+                trip=True,
+                state_dir=state_dir,
+            )
+            if ceiling_result.get("exceeded", False):
+                result["aborted"] = True
+                result["abort_reason"] = "cost_ceiling_exceeded_in_repair"
+                return result
+
+        # Repair each failed item.
+        next_failed = []
+        for item_index, item, item_result in failed_items:
+            slug = item.get("slug", f"item-{item_index}")
+            workdir = item.get("workDir", ".")
+            test_cmd = item.get("testCmd", "")
+
+            # Build repair prompt: append test output to original prompt.
+            original_prompt = item.get("prompt", "")
+            test_output = f"\n\nTest failed with exit code {item_result['testExit']}.\n"
+            if item_result.get("error"):
+                test_output += f"Error: {item_result['error']}\n"
+            repair_prompt = original_prompt + test_output
+
+            # Create a repair item.
+            repair_item = dict(item)
+            repair_item["prompt"] = repair_prompt
+
+            try:
+                # Build the manifest item.
+                manifest_item = build_manifest_item(driver, repair_item)
+
+                # Dispatch the repair.
+                dispatch_result = dispatch_item(driver, manifest_item, workdir=workdir)
+
+                # Update the item result.
+                item_result["verified"] = dispatch_result.get("verified", False)
+                item_result["testExit"] = dispatch_result.get("testExit")
+                item_result["error"] = dispatch_result.get("error")
+                item_result["filesWritten"] = dispatch_result.get("filesWritten", [])
+                item_result["repairs"] += 1
+
+                # Write journal entry for repair outcome.
+                if state_dir:
+                    _write_journal_entry(state_dir, slug, "repaired", {
+                        "verified": item_result["verified"],
+                        "testExit": item_result["testExit"],
+                        "repairs": item_result["repairs"],
+                    })
+
+                # If still failed, mark for next round.
+                if not item_result["verified"]:
+                    next_failed.append((item_index, item, item_result))
+
+            except Exception as exc:
+                item_result["error"] = f"repair exception: {exc}"
+                item_result["repairs"] += 1
+
+                # Write journal entry for repair failure.
+                if state_dir:
+                    _write_journal_entry(state_dir, slug, "repair_failed", {
+                        "verified": False,
+                        "testExit": None,
+                        "repairs": item_result["repairs"],
+                        "error": str(exc),
+                    })
+
+                next_failed.append((item_index, item, item_result))
+
+        # Update failed_items for next round.
+        failed_items = next_failed
+
+    # ========================================================================
+    # PHASE 5.5: Spot-check verified items (if spot_check_frac > 0)
+    # ========================================================================
+    if spot_check_frac > 0:
+        # Collect verified items and their original test commands.
+        verified_items_to_check = []
+        for item_index, (idx, original_item, item_result) in enumerate(
+            [(i, items[i], r) for i, r in enumerate(result["built"]) if r.get("verified", False)]
+        ):
+            verified_items_to_check.append((original_item, item_result))
+
+        # Determine how many to spot-check.
+        num_to_check = ceil(len(verified_items_to_check) * spot_check_frac)
+
+        # Deterministic sampling: check first N items by slug order.
+        # Sort by slug for determinism, then check the first num_to_check.
+        verified_items_to_check.sort(key=lambda x: x[0].get("slug", ""))
+        items_to_rerun = verified_items_to_check[:num_to_check]
+
+        # Re-run tests for sampled items.
+        for original_item, item_result in items_to_rerun:
+            test_cmd = original_item.get("testCmd", "")
+            workdir = original_item.get("workDir", ".")
+
+            if test_cmd:
+                try:
+                    rerun_result = driver.run_command(test_cmd, cwd=workdir)
+                    # If re-run does NOT exit 0, flip verified to False.
+                    if rerun_result.exit_code != 0:
+                        item_result["verified"] = False
+                        item_result["spot_check_failed"] = True
+                except Exception:
+                    # On exception, flip verified to False.
+                    item_result["verified"] = False
+                    item_result["spot_check_failed"] = True
+
+    # ========================================================================
+    # PHASE 6: Adversarial review (deferred, not yet enforced)
+    # ========================================================================
+    # Adversarial review is not yet implemented; mark all as deferred.
+    # (TODO in a later increment: real adversarial review dispatch via driver)
+    result["adversarial_review"] = "deferred"
+    for item_result in result["built"]:
+        item_result["adversarial_review"] = "deferred"
+
+    # ========================================================================
+    # PHASE 7: Batched ship (git operations, if configured)
+    # ========================================================================
+    if git is not None:
+        # Verify expectTopLevel guard: MUST be a non-empty string matching actual toplevel.
+        expect_top_level = git.get("expectTopLevel")
+        if not expect_top_level or not isinstance(expect_top_level, str):
+            # Empty or missing expectTopLevel with git config is an error.
+            result["aborted"] = True
+            result["abort_reason"] = "git_toplevel_missing_or_empty"
+            return result
+
+        toplevel_result = driver.run_command("git rev-parse --show-toplevel")
+        if toplevel_result.exit_code != 0:
+            result["aborted"] = True
+            result["abort_reason"] = "git_toplevel_check_failed"
+            return result
+
+        toplevel = toplevel_result.stdout.strip()
+        if toplevel != expect_top_level:
+            result["aborted"] = True
+            result["abort_reason"] = "git_toplevel_mismatch"
+            return result
+
+        # Only ship items that verified green.
+        verified_items = [
+            item_result for item_result in result["built"]
+            if item_result.get("verified", False)
+        ]
+
+        if verified_items:
+            # Stage and commit.
+            files_to_add = []
+            for item_result in verified_items:
+                files_to_add.extend(item_result.get("filesWritten", []))
+
+            if files_to_add:
+                # Add files. Escape each filename to prevent shell injection.
+                # Use _quote_arg for platform-safe quoting (Windows + POSIX).
+                escaped_files = [_quote_arg(f) for f in files_to_add]
+                add_cmd = "git add " + " ".join(escaped_files)
+                add_result = driver.run_command(add_cmd)
+                if add_result.exit_code != 0:
+                    result["aborted"] = True
+                    result["abort_reason"] = "git_add_failed"
+                    return result
+
+                # Commit. Escape the message to prevent shell injection.
+                # Use _quote_arg for platform-safe quoting.
+                commit_msg = f"Wave: {len(verified_items)} items verified"
+                commit_cmd = f"git commit -m {_quote_arg(commit_msg)}"
+                commit_result = driver.run_command(commit_cmd)
+                if commit_result.exit_code != 0:
+                    # Might be "nothing to commit"; not necessarily a failure.
+                    pass
+
+                # Push.
+                push_result = driver.run_command("git push")
+                if push_result.exit_code != 0:
+                    result["aborted"] = True
+                    result["abort_reason"] = "git_push_failed"
+                    return result
+
+                # Record shipped items.
+                result["shipped"] = [item_result["slug"] for item_result in verified_items]
+
+    return result
+
+
+def result_to_report(wave_result: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert run_wave result dict to fleet_ledger Report JSON format.
+
+    The Report JSON is compatible with `fleet_ledger.py append-wave` and contains:
+      - tokens: {buildOut, verifyOut, repairOut, totalOut}
+      - integration: {green: bool, ...}
+      - repairsUsed: int
+      - built: [item results]
+      - preflight_ok: bool
+      - aborted: bool
+
+    Args:
+        wave_result: dict returned from run_wave()
+
+    Returns:
+        dict in fleet_ledger Report format
+    """
+    built_items = wave_result.get("built", [])
+    repairs_used = sum(item.get("repairs", 0) for item in built_items)
+
+    # Determine if wave was fully green (all items verified and not aborted).
+    green = not wave_result.get("aborted", False) and all(
+        item.get("verified", False) for item in built_items
+    )
+
+    report = {
+        "tokens": {
+            "buildOut": 100,  # Placeholder; driver should track real tokens
+            "verifyOut": 0,
+            "repairOut": repairs_used * 50 if repairs_used > 0 else 0,
+            "totalOut": 100 + repairs_used * 50,
+        },
+        "integration": {
+            "green": green,
+        },
+        "repairsUsed": repairs_used,
+        "built": built_items,
+        "preflight_ok": wave_result.get("preflight_ok", False),
+        "aborted": wave_result.get("aborted", False),
+    }
+
+    return report
+
+
+def main():
+    """CLI entrypoint for one-turn wave mode.
+
+    Usage:
+      python -m driver.wave_loop --manifest <path> [--one-turn] [--state-dir <path>] [--output <path>]
+
+    The --one-turn flag enables the complete wave sequence in one invocation.
+    Output is JSON (either to stdout or --output file).
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="One-turn wave mode: run a complete wave (preflight - build - verify - repair - report)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python driver/wave_loop.py --manifest wave.json --one-turn
+  python driver/wave_loop.py --manifest wave.json --one-turn --output report.json
+  python driver/wave_loop.py --manifest wave.json --one-turn --state-dir ./state
+        """,
+    )
+
+    parser.add_argument(
+        "--manifest",
+        required=True,
+        type=str,
+        help="Path to wave manifest JSON file (required)",
+    )
+    parser.add_argument(
+        "--one-turn",
+        action="store_true",
+        help="Run the complete wave in one turn (preflight - build - verify - repair - report)",
+    )
+    parser.add_argument(
+        "--state-dir",
+        type=str,
+        default=None,
+        help="Path to state directory for coordination/cost tracking (optional)",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        help="Output file for Report JSON (default: stdout)",
+    )
+    parser.add_argument(
+        "--git",
+        action="store_true",
+        help="Enable git operations (stage, commit, push verified items)",
+    )
+
+    args = parser.parse_args()
+
+    # Load manifest from JSON file.
+    try:
+        manifest_path = Path(args.manifest)
+        if not manifest_path.exists():
+            print(f"Error: manifest file not found: {args.manifest}", file=sys.stderr)
+            return 1
+
+        with open(manifest_path) as f:
+            manifest = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"Error: invalid JSON in manifest file: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: failed to load manifest: {e}", file=sys.stderr)
+        return 1
+
+    # For now, use the Claude Code reference driver.
+    # In the future, this should be configurable via backend_config.
+    try:
+        from claude_code_driver import ClaudeCodeDriver
+        driver = ClaudeCodeDriver()
+    except ImportError:
+        print(
+            "Error: could not import ClaudeCodeDriver. "
+            "Ensure driver/ is on the Python path.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Prepare git config if --git flag is used.
+    git_config = None
+    if args.git:
+        # Get the current top-level directory as a guard.
+        toplevel_result = driver.run_command("git rev-parse --show-toplevel")
+        if toplevel_result.exit_code != 0:
+            print("Error: could not determine git top-level directory", file=sys.stderr)
+            return 1
+        toplevel = toplevel_result.stdout.strip()
+        git_config = {"expectTopLevel": toplevel}
+
+    # Run the wave.
+    try:
+        result = run_wave(
+            driver,
+            manifest,
+            state_dir=args.state_dir,
+            git=git_config,
+        )
+    except Exception as e:
+        print(f"Error: wave execution failed: {e}", file=sys.stderr)
+        return 1
+
+    # Convert result to Report JSON format.
+    report = result_to_report(result)
+
+    # Output Report JSON.
+    report_json = json.dumps(report, indent=2)
+
+    if args.output:
+        try:
+            with open(args.output, "w") as f:
+                f.write(report_json)
+            print(f"Report written to {args.output}", file=sys.stderr)
+        except Exception as e:
+            print(f"Error: failed to write report file: {e}", file=sys.stderr)
+            return 1
+    else:
+        print(report_json)
+
+    # Return exit code based on wave status.
+    # Exit 0 if wave completed (aborted or not), exit 1 if preflight failed.
+    if not result.get("preflight_ok"):
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())