@codemeall/agent-fleet 0.1.0-preview.1

package/skill/bin/fleet

@@ -0,0 +1,1028 @@
+#!/usr/bin/env python3
+"""fleet: the mechanics of running coding agents in cmux panes.
+
+The lead agent decides what to run; this tool launches, watches and stops it.
+Standard library only (Python 3.11+), so any harness with a shell can drive it.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import difflib
+import fcntl
+import hashlib
+import uuid
+from contextlib import contextmanager
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+import tomllib
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).resolve().parent.parent
+USER_CONFIG = Path(os.environ.get("FLEET_CONFIG", "~/.config/agent-fleet/config.toml")).expanduser()
+HARNESS_SKILL_DIRS = {
+    "claude": "~/.claude/skills",
+    "claude-co": "~/.claude-co/skills",
+    "codex": "~/.agents/skills",
+    "cursor": "~/.cursor/skills",
+}
+DEFAULTS = {
+    "workspace": None,
+    "routing": "auto",
+    "prefer": ["claude", "codex", "cursor"],
+    "max_parallel": 6,
+    "review": "cross-heavy",
+}
+STATUS_RE = re.compile(r"^\s*[*_`]*\s*status\s*[*_`]*\s*:\s*[*_`]*\s*(.+?)\s*[*_`]*\s*$", re.I)
+SURFACE_RE = re.compile(r"surface:\d+")
+
+
+class FleetError(Exception):
+    pass
+
+
+# ---------- config ----------
+
+def deep_merge(base: dict, over: dict) -> dict:
+    out = dict(base)
+    for key, value in over.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = deep_merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def load_config(user_path: Path = USER_CONFIG) -> dict:
+    with open(SKILL_DIR / "providers.toml", "rb") as fh:
+        cfg = tomllib.load(fh)
+    if user_path.exists():
+        with open(user_path, "rb") as fh:
+            cfg = deep_merge(cfg, tomllib.load(fh))
+    cfg["defaults"] = deep_merge(DEFAULTS, cfg.get("defaults", {}))
+    if not isinstance(cfg["defaults"]["max_parallel"], int) or cfg["defaults"]["max_parallel"] < 1:
+        raise FleetError("defaults.max_parallel must be a positive integer")
+    if cfg["defaults"]["review"] not in ("off", "cross-heavy", "cross-all"):
+        raise FleetError("invalid defaults.review")
+    for name, adapter in cfg["providers"].items():
+        if not isinstance(adapter.get("max", 2), int) or adapter.get("max", 2) < 1:
+            raise FleetError(f"{name}.max must be a positive integer")
+    return cfg
+
+
+def provider(cfg: dict, name: str) -> dict:
+    p = cfg.get("providers", {}).get(name)
+    if p is None:
+        raise FleetError(f"unknown provider '{name}'. Known: {', '.join(cfg.get('providers', {}))}")
+    return p
+
+
+# ---------- pure helpers ----------
+
+def resolve_model(pcfg: dict, tier: str | None, model: str | None, effort: str | None) -> tuple[str, str | None]:
+    tier_cfg = pcfg.get("tiers", {}).get(tier or "standard", {})
+    model = model or tier_cfg.get("model")
+    if not model:
+        raise FleetError(f"no model: pass --model or define tiers.{tier or 'standard'} for this provider")
+    return model, effort or tier_cfg.get("effort")
+
+
+def build_launch(pcfg: dict, model: str, effort: str | None, prompt: str) -> str:
+    template = pcfg["launch"]
+    if "{effort}" in template and not effort:
+        raise FleetError("this provider's launch needs an effort: pass --effort or set it on the tier")
+    return template.format(bin=pcfg["bin"], model=shlex.quote(model), effort=shlex.quote(effort or ""), prompt=shlex.quote(prompt))
+
+
+def worker_prompt_line(prompt_path: Path, ticket_id: str) -> str:
+    return (f"Read {prompt_path} and follow it exactly. You are fleet worker {ticket_id}. "
+            f"Your report path and hard rules are in that file.")
+
+
+def parse_status(text: str) -> str | None:
+    for line in text.splitlines():
+        m = STATUS_RE.match(line)
+        if m:
+            return m.group(1).strip("*_` ").strip()
+    return None
+
+
+def compare_snapshots(before: dict, after: dict) -> list[str]:
+    problems = []
+    for path, sha in before["heads"].items():
+        now = after["heads"].get(path)
+        if now != sha:
+            problems.append(f"HEAD moved in {path}: {sha[:10]} -> {(now or 'missing')[:10]}")
+    for path in before["staged"].keys() | after["staged"].keys():
+        old, new = before["staged"].get(path, []), after["staged"].get(path, [])
+        if old != new:
+            problems.append(f"index changed in {path}: " + ", ".join(sorted(set(new) ^ set(old))[:10]))
+    return problems
+
+
+# ---------- shell ----------
+
+def sh(args: list[str] | str, *, cwd: Path | None = None, timeout: int = 60, check: bool = True) -> str:
+    res = subprocess.run(args, cwd=cwd, capture_output=True, text=True, timeout=timeout,
+                         shell=isinstance(args, str))
+    if check and res.returncode != 0:
+        cmd = args if isinstance(args, str) else " ".join(args)
+        raise FleetError(f"`{cmd}` failed ({res.returncode}): {(res.stderr or res.stdout).strip()}")
+    return res.stdout
+
+
+def cmux(*args: str, timeout: int = 30) -> str:
+    return sh(["cmux", *args], timeout=timeout)
+
+
+def repo_root(start: Path | None = None) -> Path:
+    return Path(sh(["git", "rev-parse", "--show-toplevel"], cwd=start or Path.cwd()).strip())
+
+
+def git_snapshot(repo: Path) -> dict:
+    paths = ["."]
+    out = sh(["git", "submodule", "foreach", "--quiet", "--recursive", "echo $displaypath"], cwd=repo, check=False)
+    paths += [p for p in out.splitlines() if p.strip()]
+    heads, staged = {}, {}
+    for p in paths:
+        d = repo / p
+        heads[p] = sh(["git", "rev-parse", "HEAD"], cwd=d, check=False).strip()
+        staged[p] = sorted(x for x in sh(["git", "ls-files", "--stage", "-z"], cwd=d).split("\0") if x)
+    return {"heads": heads, "staged": staged}
+
+
+# ---------- run state ----------
+
+def run_dir(repo: Path, run: str) -> Path:
+    valid_id(run)
+    root = contained(repo.resolve(), repo.resolve() / ".fleet" / "runs")
+    return contained(root, root / run)
+
+
+def load_run(repo: Path, run: str) -> dict:
+    f = run_dir(repo, run) / "run.json"
+    if not f.exists():
+        raise FleetError(f"no run '{run}' in {repo}. Start one with: fleet init {run}")
+    state = json.loads(f.read_text())
+    if state.get("schema") != 2:
+        raise FleetError("legacy run: stop and inspect its workers before starting a new run; baseline cannot be upgraded safely")
+    if Path(state["repo"]).resolve() != repo.resolve():
+        raise FleetError("run belongs to a different checkout")
+    return state
+
+
+def save_run(repo: Path, run: str, state: dict) -> None:
+    atomic_json(run_dir(repo, run) / "run.json", state)
+
+
+def worker(state: dict, ticket_id: str) -> dict:
+    valid_id(ticket_id)
+    w = state["workers"].get(ticket_id)
+    if not w:
+        raise FleetError(f"no worker '{ticket_id}' in this run")
+    return w
+
+
+def active(state: dict) -> list[dict]:
+    return [w for w in state["workers"].values() if w.get("state") in ACTIVE_STATES]
+
+
+# ---------- durable orchestration helpers ----------
+
+ACTIVE_STATES = {"launching", "running", "stop-failed", "unknown"}
+ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}\Z")
+
+
+def valid_id(value: str) -> str:
+    if not isinstance(value, str) or not ID_RE.fullmatch(value):
+        raise FleetError("run/worker IDs must be 1–64 letters, numbers, underscores or hyphens; start with a letter or number")
+    return value
+
+
+def contained(root: Path, path: Path) -> Path:
+    # Reject symlinks as well as lexical traversal; run state must remain in the checkout.
+    root = Path(root)
+    if not path.resolve().is_relative_to(root.resolve()):
+        raise FleetError(f"path escapes its allowed directory: {path}")
+    cursor = path
+    while cursor != cursor.parent:
+        if cursor.is_symlink():
+            raise FleetError(f"symlink path is not supported: {cursor}")
+        if cursor.resolve() == root.resolve():
+            break
+        cursor = cursor.parent
+    return path
+
+
+def safe_file(repo: Path, value: str) -> str:
+    path = Path(value)
+    if path.is_absolute() or not path.parts or ".." in path.parts or any(c in value for c in "*?\n\r"):
+        raise FleetError(f"scope must name an exact relative file: {value}")
+    if any(part in (".git", ".fleet") or part.startswith(".env") for part in path.parts):
+        raise FleetError(f"protected file cannot be a worker scope: {value}")
+    full = contained(repo.resolve(), repo / path)
+    if full.is_dir():
+        raise FleetError(f"scope must name files, not directories: {value}")
+    return path.as_posix()
+
+
+def atomic_json(path: Path, data: dict) -> None:
+    contained(path.parent, path)
+    temp = path.with_name(path.name + "." + uuid.uuid4().hex + ".tmp")
+    try:
+        temp.write_text(json.dumps(data, indent=2) + "\n")
+        temp.replace(path)
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+@contextmanager
+def mutation_lock(a):
+    if not hasattr(a, "run") or a.cmd == "wait":
+        yield
+        return
+    repo = repo_root()
+    root = contained(repo.resolve(), repo / ".fleet" / "runs")
+    root.mkdir(parents=True, exist_ok=True)
+    lock_path = contained(root, root / ".lock")
+    with lock_path.open("a") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise FleetError("another Fleet command is changing this checkout; retry when it finishes")
+        try:
+            yield
+        finally:
+            fcntl.flock(lock, fcntl.LOCK_UN)
+
+
+def routing_pool(routing: str, cfg: dict) -> dict | None:
+    if routing == "auto":
+        return None
+    if routing.startswith("single:"):
+        name = routing.removeprefix("single:")
+        provider(cfg, name)
+        return {name: None}
+    if routing.startswith("agents="):
+        pool = {}
+        for item in routing.removeprefix("agents=").split(","):
+            name, sep, model = item.partition(":")
+            provider(cfg, name)
+            pool[name] = model if sep else None
+        return pool
+    raise FleetError("routing must be auto, single:<provider> or agents=<provider>[:<model>],...")
+
+
+def model_family(pcfg: dict, tier: str, model: str, explicit: str | None = None) -> str | None:
+    if explicit:
+        return explicit
+    mapped = pcfg.get("model_families", {}).get(model)
+    if mapped:
+        return mapped
+    t = pcfg.get("tiers", {}).get(tier, {})
+    if t.get("model") == model and t.get("family"):
+        return t["family"]
+    family = pcfg.get("family")
+    return family if family and family not in ("mixed", "unknown") else None
+
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def scopes_overlap(left, right) -> bool:
+    return any(a == b or a.startswith(b + "/") or b.startswith(a + "/") for a in left for b in right)
+
+
+def capture_files(repo: Path, files: list[str]) -> dict:
+    result = {}
+    for filename in files:
+        safe_file(repo, filename)
+        path = repo / filename
+        result[filename] = {"data": base64.b64encode(path.read_bytes()).decode(),
+                            "mode": path.stat().st_mode & 0o777} if path.exists() else None
+    return result
+
+
+def scoped_diff(repo: Path, state: dict, ticket_id: str) -> str:
+    valid_id(ticket_id)
+    t = state["tickets"][ticket_id]
+    path = run_dir(repo, state["run"]) / "snapshots" / f"{ticket_id}.json"
+    before = json.loads(path.read_text())
+    after = capture_files(repo, t["files"])
+    result = []
+    for filename in t["files"]:
+        old, new = before[filename], after[filename]
+        if old == new:
+            continue
+        old_bytes = base64.b64decode(old["data"]) if old else b""
+        new_bytes = base64.b64decode(new["data"]) if new else b""
+        result.append(f"diff --fleet {filename}\n")
+        result.append(f"before: {digest(old_bytes) if old else 'absent'} mode={old['mode'] if old else '-'}\n")
+        result.append(f"after: {digest(new_bytes) if new else 'absent'} mode={new['mode'] if new else '-'}\n")
+        try:
+            old_text, new_text = old_bytes.decode("utf-8"), new_bytes.decode("utf-8")
+            result.extend(difflib.unified_diff(old_text.splitlines(keepends=True), new_text.splitlines(keepends=True),
+                fromfile=f"a/{filename}" if old else "/dev/null", tofile=f"b/{filename}" if new else "/dev/null"))
+            result.append("\n")
+        except UnicodeDecodeError:
+            result.append("Binary content changed; inspect artifact separately.\n")
+    return "".join(result)
+
+
+def reconcile(repo: Path, state: dict) -> None:
+    for w in state["workers"].values():
+        if w["state"] not in ACTIVE_STATES or not w.get("exit_file"):
+            continue
+        receipt = contained(run_dir(repo, state["run"]), Path(w["exit_file"]))
+        started = receipt.with_suffix(".started.json")
+        if started.exists():
+            info = json.loads(started.read_text())
+            if info.get("token") == w.get("token"):
+                w["process"] = info
+        if receipt.exists():
+            data = json.loads(receipt.read_text())
+            if data.get("token") == w.get("token"):
+                w["state"] = "exited"
+                w["returncode"] = data["returncode"]
+
+
+def assert_scope_idle(state: dict, files: list[str]) -> None:
+    for w in active(state):
+        owner = w.get("review_of") or w["id"]
+        if scopes_overlap(files, state["tickets"][owner]["files"]):
+            raise FleetError("scope overlaps a worker whose exit is unconfirmed")
+
+
+def ensure_other_runs_idle(repo: Path, current: str) -> None:
+    root = contained(repo.resolve(), repo.resolve() / ".fleet" / "runs")
+    for file in root.glob("*/run.json"):
+        contained(root, file)
+        if file.parent.name == current:
+            continue
+        state = json.loads(file.read_text())
+        if state.get("schema") == 2:
+            reconcile(repo, state)
+        if active(state):
+            raise FleetError(f"run {file.parent.name} has workers with unconfirmed exits; use one active run per checkout")
+
+
+def read_evidence(filename: str) -> str:
+    text = Path(filename).read_text().strip()
+    if not text:
+        raise FleetError("evidence file must describe the checks and their results")
+    return text
+
+
+def run_child(args: list[str]) -> int:
+    """Runs inside the worker terminal. Reports exit, never writes the shared run state."""
+    if len(args) != 3:
+        raise FleetError("internal runner expects receipt, token, command")
+    path, token, command = args
+    child = subprocess.Popen(command, shell=True, executable="/bin/sh")
+    atomic_json(Path(path).with_suffix(".started.json"),
+                {"token": token, "wrapper_pid": os.getpid(), "child_pid": child.pid})
+    while True:
+        try:
+            code = child.wait()
+            break
+        except KeyboardInterrupt:
+            # Ctrl-C also reaches the child; keep watching until it actually exits.
+            continue
+    atomic_json(Path(path), {"token": token, "returncode": code})
+    return code
+
+
+# ---------- commands ----------
+
+def cmd_init(a, cfg):
+    repo = repo_root()
+    ensure_other_runs_idle(repo, a.run)
+    d = run_dir(repo, a.run)
+    if (d / "run.json").exists():
+        raise FleetError(f"run already exists; use fleet resume {a.run}")
+    workspace = a.workspace or cfg["defaults"]["workspace"] or os.environ.get("CMUX_WORKSPACE_ID")
+    if not workspace:
+        raise FleetError("no cmux workspace: pass --workspace or run inside cmux")
+    cmux("list-panes", "--workspace", workspace)  # Fail before creating state for an invalid workspace.
+    options = dict(cfg["defaults"], routing=a.routing or cfg["defaults"]["routing"],
+                   review=a.review or cfg["defaults"]["review"])
+    routing_pool(options["routing"], cfg)
+    for sub in ("prompts", "reports", ".seen", "exits", "snapshots", "evidence"):
+        (d / sub).mkdir(parents=True, exist_ok=True)
+    gi = repo / ".fleet" / ".gitignore"
+    previous = gi.read_text() if gi.exists() else ""
+    if "runs/" not in previous.splitlines():
+        gi.write_text(previous + ("\n" if previous and not previous.endswith("\n") else "") + "runs/\n")
+    state = {"schema": 2, "run": a.run, "repo": str(repo), "workspace": workspace,
+             "created": time.strftime("%Y-%m-%dT%H:%M:%S"), "baseline": git_snapshot(repo),
+             "options": options, "tickets": {}, "workers": {}, "prompts": {}, "decisions": []}
+    save_run(repo, a.run, state)
+    print(f"run dir: {d}\nworkspace: {workspace}\nNext: fleet plan {a.run} --file <plan.json>")
+
+
+def cmd_plan(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    if state["workers"]:
+        raise FleetError("plan is frozen after the first launch; record decisions in run notes, or start another run after stopping workers")
+    data = json.loads(Path(a.file).read_text())
+    tickets = {}
+    pool = routing_pool(state["options"]["routing"], cfg)
+    for raw in data["tickets"]:
+        t = dict(raw)
+        i = valid_id(t["id"])
+        if i in tickets:
+            raise FleetError(f"duplicate ticket {i}")
+        if t.get("tier", "standard") not in ("heavy", "standard", "light"):
+            raise FleetError(f"invalid tier for {i}")
+        t["tier"] = t.get("tier", "standard")
+        pcfg = provider(cfg, t["provider"])
+        if not pcfg.get("enabled", True):
+            raise FleetError(f"disabled provider for {i}")
+        if pool is not None:
+            if t["provider"] not in pool:
+                raise FleetError(f"{i}: provider outside selected routing pool")
+            if pool[t["provider"]]:
+                if t.get("model") and t["model"] != pool[t["provider"]]:
+                    raise FleetError(f"{i}: model conflicts with pinned routing")
+                t["model"] = pool[t["provider"]]
+        t["model"], t["effort"] = resolve_model(pcfg, t["tier"], t.get("model"), t.get("effort"))
+        t["family"] = model_family(pcfg, t["tier"], t["model"], t.get("family"))
+        ticket = Path(t["ticket"])
+        if not ticket.is_absolute():
+            ticket = repo / ticket
+        if not ticket.is_file():
+            raise FleetError(f"missing local ticket: {ticket}; export remote issues first")
+        t["ticket"] = str(ticket.resolve())
+        if not t.get("files") or not isinstance(t["files"], list):
+            raise FleetError(f"{i}: files must be a nonempty list of exact repo-relative paths")
+        t["files"] = sorted(set(safe_file(repo, f) for f in t["files"]))
+        t["blockers"] = t.get("blockers", [])
+        if not isinstance(t["blockers"], list):
+            raise FleetError(f"{i}: blockers must be a list")
+        t["status"] = "pending"
+        t["review_required"] = state["options"]["review"] == "cross-all" or (state["options"]["review"] == "cross-heavy" and t["tier"] == "heavy")
+        tickets[i] = t
+    if not tickets:
+        raise FleetError("plan must contain at least one ticket")
+    visited, visiting = set(), set()
+    def visit(i):
+        if i not in tickets:
+            raise FleetError(f"unknown blocker {i}")
+        if i in visiting:
+            raise FleetError(f"dependency cycle at {i}")
+        if i in visited:
+            return
+        visiting.add(i)
+        for dep in tickets[i]["blockers"]:
+            visit(dep)
+        visiting.remove(i)
+        visited.add(i)
+    for i in tickets:
+        visit(i)
+    state["tickets"] = tickets
+    state["decisions"] = data.get("decisions", [])
+    save_run(repo, a.run, state)
+    print(f"saved {len(tickets)} tickets; routing, dependencies and assignments persist across sessions")
+
+
+def cmd_prompt(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    valid_id(a.id)
+    d = run_dir(repo, a.run)
+    out = contained(d, d / "prompts" / f"{a.id}.md")
+    if out.exists() and not a.force:
+        raise FleetError(f"{out} exists (use --force to overwrite)")
+    if a.id in state["workers"] and state["workers"][a.id]["state"] in ACTIVE_STATES:
+        raise FleetError("cannot replace a live worker prompt")
+    review_of = a.review_of
+    if review_of:
+        writer = worker(state, review_of)
+        if writer.get("role") != "implementation" or writer["state"] in ACTIVE_STATES:
+            raise FleetError("stop the implementation worker before preparing review")
+        if a.id in state["tickets"]:
+            raise FleetError("reviewer must have a separate ID")
+        t = state["tickets"][review_of]
+        assert_scope_idle(state, t["files"])
+        if not a.diff:
+            raise FleetError("review prompt needs --diff from fleet diff")
+        diff = Path(a.diff).read_text()
+        if diff != scoped_diff(repo, state, review_of):
+            raise FleetError("review diff differs from current scoped changes; regenerate it")
+        snapshot = d / "snapshots" / f"{a.id}.diff"
+        snapshot.write_text(diff)
+        meta = {"role": "review", "review_of": review_of, "diff_sha": digest(diff.encode())}
+        template = "review-prompt.md"
+    else:
+        if a.id not in state["tickets"]:
+            raise FleetError("save the ticket in fleet plan first")
+        t = state["tickets"][a.id]
+        meta = {"role": "implementation"}
+        template = "ticket-prompt.md"
+    ticket = a.ticket or t["ticket"]
+    if str(Path(ticket).resolve()) != t["ticket"]:
+        raise FleetError("ticket differs from saved plan")
+    fields = {"id": a.id, "ticket": t["ticket"], "report": str(d / "reports" / f"{a.id}.md"),
+              "repo": str(repo), "files": ", ".join(t["files"]),
+              "diff": str(d / "snapshots" / f"{a.id}.diff") if review_of else "",
+              "review_of": review_of or ""}
+    parts = [] if review_of else [(SKILL_DIR / "templates" / "preamble.md").read_text()]
+    rules = repo / ".fleet" / "rules.md"
+    if rules.exists():
+        parts.append("## Repo rules\n\n" + rules.read_text())
+    parts.append((SKILL_DIR / "templates" / template).read_text())
+    parts.append("## Report format\n\n" + (SKILL_DIR / "templates" / "report.md").read_text())
+    text = "\n\n".join(p.strip() for p in parts) + "\n"
+    for k, v in fields.items():
+        text = text.replace("{{" + k + "}}", v)
+    out.write_text(text)
+    state["prompts"][a.id] = meta
+    save_run(repo, a.run, state)
+    print(out)
+
+
+def cmd_launch(a, cfg):
+    repo = repo_root()
+    ensure_other_runs_idle(repo, a.run)
+    state = load_run(repo, a.run)
+    valid_id(a.id)
+    reconcile(repo, state)
+    save_run(repo, a.run, state)
+    pcfg = provider(cfg, a.provider)
+    if not pcfg.get("enabled", True):
+        raise FleetError(f"provider '{a.provider}' is turned off in config")
+    prompt_path = contained(run_dir(repo, a.run), run_dir(repo, a.run) / "prompts" / f"{a.id}.md")
+    if not prompt_path.exists() or a.id not in state["prompts"]:
+        raise FleetError("write the prompt first with fleet prompt")
+    if "<!-- LEAD:" in prompt_path.read_text() or "{{" in prompt_path.read_text():
+        raise FleetError("fill all LEAD fields/placeholders in the prompt before launch")
+    w = state["workers"].get(a.id)
+    if w and w.get("state") in ACTIVE_STATES:
+        raise FleetError(f"worker {a.id} may still be running on {w['surface']}; stop or recover it first")
+    running = active(state)
+    if len(running) >= state["options"]["max_parallel"]:
+        raise FleetError("max_parallel reached; stop and confirm an existing worker's exit first")
+    if sum(x["provider"] == a.provider for x in running) >= pcfg.get("max", 2):
+        raise FleetError(f"{a.provider} is at capacity; stop and confirm a worker's exit first")
+    meta = state["prompts"][a.id]
+    if meta["role"] == "implementation":
+        t = state["tickets"][a.id]
+        if t["status"] == "verified":
+            raise FleetError("ticket already verified; create a follow-up ticket")
+        if any(state["tickets"][b]["status"] != "verified" for b in t["blockers"]):
+            raise FleetError("ticket has unverified blockers")
+        model, effort = resolve_model(pcfg, a.tier, a.model, a.effort)
+        if (a.provider, a.tier, model, effort) != (t["provider"], t["tier"], t["model"], t["effort"]):
+            raise FleetError("launch provider/tier/model/effort must match saved plan")
+        family = model_family(pcfg, a.tier, model, a.family)
+        if family != t["family"]:
+            raise FleetError("launch family must match saved plan")
+        for other in running:
+            owned = state["tickets"][other.get("review_of") or other["id"]]["files"]
+            if scopes_overlap(t["files"], owned):
+                raise FleetError("files overlap an active implementation/review; wait for its exit")
+    else:
+        if a.tier != "review":
+            raise FleetError("review prompt requires --tier review")
+        t = state["tickets"][meta["review_of"]]
+        if worker(state, meta["review_of"])["state"] in ACTIVE_STATES:
+            raise FleetError("stop writer before review")
+        model, effort = resolve_model(pcfg, "review", a.model, a.effort)
+        family = model_family(pcfg, "review", model, a.family)
+        if not family or not t["family"] or family == t["family"]:
+            raise FleetError("review requires known different model families; configure family or pass --family")
+        pool = routing_pool(state["options"]["routing"], cfg)
+        if pool is not None and (a.provider not in pool or (pool[a.provider] and model != pool[a.provider])):
+            raise FleetError("reviewer outside pinned routing pool; cross-family review cannot proceed")
+        assert_scope_idle(state, t["files"])
+        if digest(scoped_diff(repo, state, meta["review_of"]).encode()) != meta["diff_sha"]:
+            raise FleetError("review snapshot is stale; regenerate diff and prompt")
+    d = run_dir(repo, a.run)
+    baseline = d / "snapshots" / f"{a.id}.json"
+    if meta["role"] == "implementation" and not baseline.exists():
+        atomic_json(baseline, capture_files(repo, t["files"]))
+    report = d / "reports" / f"{a.id}.md"
+    if report.exists():
+        report.replace(d / "reports" / f"{a.id}.{uuid.uuid4().hex}.previous")
+    token = uuid.uuid4().hex
+    command = build_launch(pcfg, model, effort, worker_prompt_line(prompt_path, a.id))
+    exit_file = d / "exits" / f"{a.id}.{token}.json"
+    wrapped = shlex.join([sys.executable, str(Path(__file__).resolve()), "_run", str(exit_file), token, command])
+    # Persist before launch: an uncertain cmux result must not silently free capacity.
+    state["workers"][a.id] = dict(meta, id=a.id, provider=a.provider, model=model, effort=effort,
+        family=family, tier=a.tier, surface="unknown", state="launching", command=command,
+        token=token, exit_file=str(exit_file), launched=time.strftime("%Y-%m-%dT%H:%M:%S"))
+    save_run(repo, a.run, state)
+    args = ["new-surface", "--workspace", state["workspace"], "--working-directory", str(repo),
+            "--command", wrapped, "--focus", "false"]
+    if a.pane:
+        args += ["--pane", a.pane]
+    out = cmux(*args)
+    m = SURFACE_RE.search(out)
+    if not m:
+        raise FleetError(f"uncertain launch; inspect cmux before recovery: {out.strip()}")
+    w = state["workers"][a.id]
+    w["surface"], w["state"] = m.group(0), "running"
+    save_run(repo, a.run, state)
+    label = f"{a.id} · {a.provider}:{model}" + (f"@{effort}" if effort else "")
+    sh(["cmux", "rename-tab", "--workspace", state["workspace"], "--surface", w["surface"], label], check=False)
+    print(f"{a.id}: {label} on {w['surface']}")
+
+
+def send_keys(workspace: str, surface: str, items: list[str]) -> None:
+    for item in items:
+        if item in ("enter", "ctrl+c", "escape", "tab"):
+            cmux("send-key", "--workspace", workspace, "--surface", surface, item)
+        else:
+            cmux("send", "--workspace", workspace, "--surface", surface, "--", item)
+        time.sleep(0.4)
+
+
+def cmd_send(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    w = worker(state, a.id)
+    send_keys(state["workspace"], w["surface"], [" ".join(a.text), "enter"])
+    print(f"sent to {a.id} ({w['surface']})")
+
+
+def cmd_peek(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    w = worker(state, a.id)
+    print(cmux("read-screen", "--workspace", state["workspace"], "--surface", w["surface"], "--lines", str(a.lines)))
+
+
+def report_rows(repo: Path, state: dict) -> list[dict]:
+    d = run_dir(repo, state["run"]) / "reports"
+    ids = set(state["workers"]) | {p.stem for p in d.glob("*.md")}
+    rows = []
+    for i in sorted(ids):
+        w = state["workers"].get(i, {})
+        f = d / f"{i}.md"
+        status = parse_status(f.read_text()) if f.exists() else None
+        age = int(time.time() - f.stat().st_mtime) if f.exists() else None
+        rows.append({"id": i, "worker": f"{w.get('provider', '?')}:{w.get('model', '?')}",
+                     "surface": w.get("surface", "-"), "state": w.get("state", "-"),
+                     "report": status or ("-" if not f.exists() else "no status line"),
+                     "report_age_s": age, "process": w.get("process")})
+    return rows
+
+
+def cmd_status(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    reconcile(repo, state)
+    save_run(repo, a.run, state)
+    rows = report_rows(repo, state)
+    if a.json:
+        print(json.dumps(rows, indent=2))
+        return
+    print(f"run {state['run']}  workspace {state['workspace']}  running {len(active(state))}/{cfg['defaults']['max_parallel']}")
+    for r in rows:
+        age = f"{r['report_age_s'] // 60}m ago" if r["report_age_s"] is not None else ""
+        print(f"  {r['id']:<10} {r['worker']:<34} {r['surface']:<12} {r['state']:<9} {r['report']} {age}")
+
+
+WAKE_STATUSES = ("needs-verification", "blocked")
+
+
+def scan_reports(reports: Path, seen: Path, statuses: tuple[str, ...] | None) -> list[tuple[str, str, Path]]:
+    """Reports that reached a wake status since last seen. statuses=None wakes on any change.
+
+    The lead parks a report by rewriting its Status (verified, changes-requested); a worker
+    flipping it back to needs-verification wakes the lead again.
+    """
+    fresh = []
+    for f in sorted(reports.glob("*.md")):
+        status = parse_status(f.read_text()) or "no status line"
+        if statuses is not None and status.lower() not in statuses:
+            continue
+        key = f"{status}|{f.stat().st_mtime_ns}"
+        marker = seen / f.stem
+        if not marker.exists() or marker.read_text() != key:
+            marker.write_text(key)
+            fresh.append((f.stem, status, f))
+    return fresh
+
+
+def cmd_wait(a, cfg):
+    repo = repo_root()
+    load_run(repo, a.run)
+    d = run_dir(repo, a.run)
+    seen = d / ".seen"
+    seen.mkdir(exist_ok=True)
+    statuses = None if a.any_change else WAKE_STATUSES
+    deadline = time.time() + a.timeout
+    while True:
+        fresh = scan_reports(d / "reports", seen, statuses)
+        if fresh:
+            for i, status, f in fresh:
+                print(f"REPORT {i} [{status}] {f}")
+            return 0
+        if time.time() >= deadline:
+            print(f"TIMEOUT no new report in {a.timeout}s; check panes: fleet status {a.run}")
+            return 2
+        time.sleep(min(a.interval, max(0, deadline - time.time())))
+
+
+def cmd_stop(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    reconcile(repo, state)
+    ids = list(state["workers"]) if a.all else a.ids
+    if not ids and not a.all:
+        raise FleetError("name workers to stop, or pass --all")
+    failed = False
+    for i in ids:
+        w = worker(state, i)
+        try:
+            if w["state"] in ACTIVE_STATES:
+                send_keys(state["workspace"], w["surface"], provider(cfg, w["provider"]).get("quit", ["/exit", "enter"]))
+                deadline = time.monotonic() + a.timeout
+                while w["state"] in ACTIVE_STATES and time.monotonic() < deadline:
+                    reconcile(repo, state)
+                    if w["state"] in ACTIVE_STATES:
+                        time.sleep(0.2)
+                if w["state"] in ACTIVE_STATES:
+                    raise FleetError("quit sent but process exit unconfirmed; slot retained")
+            if a.close and w["state"] != "closed":
+                cmux("close-surface", "--workspace", state["workspace"], "--surface", w["surface"])
+                w["state"] = "closed"
+        except (FleetError, OSError, subprocess.TimeoutExpired) as e:
+            failed = True
+            if w["state"] in ACTIVE_STATES:
+                w["state"] = "stop-failed"
+            print(f"{i}: {e}", file=sys.stderr)
+        save_run(repo, a.run, state)
+        print(f"{i}: {w['state']} ({w['surface']})")
+    return 1 if failed else 0
+
+
+def cmd_resume(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    reconcile(repo, state)
+    save_run(repo, a.run, state)
+    print(json.dumps({"run": state["run"], "workspace": state["workspace"], "options": state["options"],
+                      "tickets": state["tickets"], "decisions": state["decisions"],
+                      "workers": report_rows(repo, state)}, indent=2))
+    print("Unconfirmed workers retain their slots. Inspect panes/processes before stop or recover.")
+
+
+def cmd_recover(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    w = worker(state, a.id)
+    evidence = read_evidence(a.evidence)
+    # Deliberate lead attestation for externally stopped/legacy/crashed processes.
+    w["state"] = "recovered"
+    w["recovery_evidence"] = evidence
+    save_run(repo, a.run, state)
+    print("Recorded lead-confirmed process exit; ticket acceptance is unchanged.")
+
+
+def cmd_diff(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    reconcile(repo, state)
+    save_run(repo, a.run, state)
+    w = worker(state, a.id)
+    if w["state"] in ACTIVE_STATES:
+        raise FleetError("stop writer before capturing a review diff")
+    if w.get("role") != "implementation":
+        raise FleetError("diff expects an implementation ID")
+    assert_scope_idle(state, state["tickets"][a.id]["files"])
+    result = scoped_diff(repo, state, a.id)
+    if a.output:
+        Path(a.output).write_text(result)
+    else:
+        print(result, end="")
+
+
+def cmd_verify(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    reconcile(repo, state)
+    save_run(repo, a.run, state)
+    w = worker(state, a.id)
+    if w["state"] in ACTIVE_STATES:
+        raise FleetError("stop worker and confirm exit before accepting its result")
+    owner = w.get("review_of") or a.id
+    assert_scope_idle(state, state["tickets"][owner]["files"])
+    evidence = read_evidence(a.evidence)
+    report = run_dir(repo, a.run) / "reports" / f"{a.id}.md"
+    if not report.exists() or parse_status(report.read_text()) != "needs-verification":
+        raise FleetError("report must have Status: needs-verification")
+    if w["role"] == "implementation":
+        t = state["tickets"][a.id]
+        if t["review_required"]:
+            sha = digest(scoped_diff(repo, state, a.id).encode())
+            if not any(r.get("review_of") == a.id and r.get("verified") and r.get("diff_sha") == sha for r in state["workers"].values()):
+                raise FleetError("required cross-family review is missing, unverified or stale")
+        t["status"] = "verified"
+    else:
+        sha = digest(scoped_diff(repo, state, w["review_of"]).encode())
+        if sha != w["diff_sha"]:
+            raise FleetError("review is stale; regenerate diff and review")
+    w["verified"] = True
+    w["verification_evidence"] = evidence
+    text = report.read_text()
+    lines = text.splitlines()
+    for n, line in enumerate(lines):
+        if STATUS_RE.match(line):
+            lines[n] = "Status: verified"
+            break
+    report.write_text("\n".join(lines) + "\n\n## Lead verification\n" + evidence + "\n")
+    save_run(repo, a.run, state)
+    print(f"{a.id}: verified; update the source ticket only after implementation acceptance")
+
+
+def cmd_check(a, cfg):
+    repo = repo_root()
+    state = load_run(repo, a.run)
+    problems = compare_snapshots(state["baseline"], git_snapshot(repo))
+    if problems:
+        print("CHANGED since the run started (fleet never commits or stages; find out who did):")
+        for p in problems:
+            print(f"  - {p}")
+        return 1
+    print("OK: captured HEAD and index states match the run baseline")
+    return 0
+
+
+def first_binary(bin_field: str) -> str:
+    tokens = [t for t in shlex.split(bin_field) if "=" not in t or t.startswith("-")]
+    return tokens[0] if tokens else bin_field
+
+
+def cmd_doctor(a, cfg):
+    ok = True
+    try:
+        cmux("ping", timeout=5)
+        print("cmux          ready")
+    except (FleetError, FileNotFoundError, subprocess.TimeoutExpired) as e:
+        ok = False
+        print(f"cmux          NOT REACHABLE: {e}")
+        if os.environ.get("CODEX_SANDBOX") or os.environ.get("CODEX_SANDBOX_NETWORK_DISABLED"):
+            print("              Check host socket permissions; do not bypass a denied permission through another harness.")
+    print(f"config        {USER_CONFIG if USER_CONFIG.exists() else 'none (built-in defaults)'}")
+    names = a.providers or list(cfg["providers"])
+    for name in names:
+        p = provider(cfg, name)
+        if not p.get("enabled", True):
+            print(f"{name:<13} off")
+            continue
+        binary = first_binary(p["bin"])
+        if not shutil.which(binary):
+            ok = False
+            print(f"{name:<13} MISSING binary '{binary}'")
+            continue
+        if "login" not in p:
+            print(f"{name:<13} installed (no login check defined)")
+            continue
+        try:
+            res = subprocess.run(p["login"], shell=True, capture_output=True, text=True, timeout=60)
+            ready = res.returncode == 0 and bool(p.get("login_ok")) and p["login_ok"] in res.stdout + res.stderr  # codex prints its status to stderr
+        except subprocess.TimeoutExpired:
+            ready = False
+        ok &= ready
+        tiers = ", ".join(f"{t}={v.get('model')}" for t, v in p.get("tiers", {}).items())
+        print(f"{name:<13} {'authenticated (models unverified)' if ready else 'LOGIN CHECK FAILED'}  max={p.get('max', 2)}  {tiers}")
+    for harness, d in HARNESS_SKILL_DIRS.items():
+        target = Path(d).expanduser() / "fleet"
+        print(f"skill@{harness:<7} {'installed' if (target / 'SKILL.md').exists() else 'not installed'}")
+    return 0 if ok else 1
+
+
+def cmd_providers(a, cfg):
+    print(json.dumps({"defaults": cfg["defaults"], "providers": cfg["providers"]}, indent=2))
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] == "_run":
+        return run_child(argv[1:])
+    ap = argparse.ArgumentParser(prog="fleet", description=__doc__.splitlines()[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("doctor", help="check cmux, provider logins and skill installs")
+    s.add_argument("providers", nargs="*")
+    s.set_defaults(fn=cmd_doctor)
+
+    s = sub.add_parser("providers", help="print the merged provider config")
+    s.set_defaults(fn=cmd_providers)
+
+    s = sub.add_parser("init", help="start a run: dirs + git baseline")
+    s.add_argument("run")
+    s.add_argument("--workspace")
+    s.add_argument("--routing")
+    s.add_argument("--review", choices=["off", "cross-heavy", "cross-all"])
+    s.set_defaults(fn=cmd_init)
+
+    s = sub.add_parser("plan", help="persist a ticket graph and routing assignments")
+    s.add_argument("run")
+    s.add_argument("--file", required=True)
+    s.set_defaults(fn=cmd_plan)
+
+    s = sub.add_parser("resume", help="reconcile exits and show saved plan and decisions")
+    s.add_argument("run")
+    s.set_defaults(fn=cmd_resume)
+
+    for name, fn in (("verify", cmd_verify), ("recover", cmd_recover)):
+        s = sub.add_parser(name, help="record lead verification" if name == "verify" else "attest worker process has exited after manual inspection")
+        s.add_argument("run")
+        s.add_argument("id")
+        s.add_argument("--evidence", required=True)
+        s.set_defaults(fn=fn)
+
+    s = sub.add_parser("diff", help="diff owned files against their launch baseline")
+    s.add_argument("run")
+    s.add_argument("id")
+    s.add_argument("--output")
+    s.set_defaults(fn=cmd_diff)
+
+    s = sub.add_parser("prompt", help="scaffold a worker prompt from the templates")
+    s.add_argument("run")
+    s.add_argument("id")
+    s.add_argument("--ticket")
+    s.add_argument("--review-of")
+    s.add_argument("--diff")
+    s.add_argument("--force", action="store_true")
+    s.set_defaults(fn=cmd_prompt)
+
+    s = sub.add_parser("launch", help="launch a worker in a new cmux tab")
+    s.add_argument("run")
+    s.add_argument("id")
+    s.add_argument("provider")
+    s.add_argument("--tier", choices=["heavy", "standard", "light", "review"], default="standard")
+    s.add_argument("--model")
+    s.add_argument("--effort")
+    s.add_argument("--family", help="known family for an account-specific model override")
+    s.add_argument("--pane")
+    s.set_defaults(fn=cmd_launch)
+
+    s = sub.add_parser("send", help="type a message into a worker's pane and press enter")
+    s.add_argument("run")
+    s.add_argument("id")
+    s.add_argument("text", nargs="+")
+    s.set_defaults(fn=cmd_send)
+
+    s = sub.add_parser("peek", help="read the bottom of a worker's screen")
+    s.add_argument("run")
+    s.add_argument("id")
+    s.add_argument("--lines", type=int, default=40)
+    s.set_defaults(fn=cmd_peek)
+
+    s = sub.add_parser("status", help="workers and their report status")
+    s.add_argument("run")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_status)
+
+    s = sub.add_parser("wait", help="block until a report reaches needs-verification or blocked (exit 0), "
+                                    "or timeout (exit 2)")
+    s.add_argument("run")
+    s.add_argument("--timeout", type=int, default=45)
+    s.add_argument("--interval", type=int, default=10)
+    s.add_argument("--any-change", action="store_true", help="wake on any report change, whatever its status")
+    s.set_defaults(fn=cmd_wait)
+
+    s = sub.add_parser("stop", help="send each worker its quit sequence")
+    s.add_argument("run")
+    s.add_argument("ids", nargs="*")
+    s.add_argument("--all", action="store_true")
+    s.add_argument("--close", action="store_true", help="close tab only after confirmed process exit")
+    s.add_argument("--timeout", type=float, default=10)
+    s.set_defaults(fn=cmd_stop)
+
+    s = sub.add_parser("check", help="compare HEAD and index with the captured baseline")
+    s.add_argument("run")
+    s.set_defaults(fn=cmd_check)
+
+    a = ap.parse_args(argv)
+    try:
+        if hasattr(a, "id"):
+            valid_id(a.id)
+        if hasattr(a, "run"):
+            valid_id(a.run)
+        if hasattr(a, "timeout") and not 0 <= a.timeout <= 60:
+            raise FleetError("timeout must be between 0 and 60 seconds")
+        if hasattr(a, "interval") and not 0 < a.interval <= 60:
+            raise FleetError("interval must be between 0 and 60 seconds")
+        with mutation_lock(a):
+            return a.fn(a, load_config()) or 0
+    except (FleetError, OSError, ValueError, KeyError, TypeError, subprocess.TimeoutExpired) as e:
+        print(f"fleet: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())