path: root/wf.py

#!/usr/bin/env python3
"""wf — shared task workflow tool. Run inside a project (folder with workflow.toml).

Look:    next [--brief] · list [filters] · show ID… · ctx ID|PATH#ANCHOR
         search WORDS… · log [-n N] [WORDS] · projects · check
Change:  add "Title. Goal." -p N -e EFFORT · done ID… -m "entry" · prio ID N
         move ID SECTION | --before/--after ID · status ID progress NOTE|blocked A-ID|clear
         set ID --title/--effort/--after/--ref/--model/--sessions/--cloud · note ID "line"
         body ID <stdin (Model:/Sessions:/After:/Ref: kept) · tick ID N|TEXT · setup · merge (in a lane worktree)
Orch:    orch pick LANE [--id ID] [--recovery WHY] · orch post ID LANE [--result LINE] [--agent A] [--duration S] [--no-next]
Other:   report "what happened" · init · migrate [--write] · res … (shared memory/CPU ledger; wf res -h)
         batch N [--lanes L,…] [--prep] | --status (unattended batch orchestrator; wf batch -h)
         prep [N|all] [--lanes L,…] (= batch --prep: sonnet workers write Done for tasks without one; all = every such task)

Every change command takes --dry-run. `wf CMD -h` for details.
Rules: /projects/CLAUDE.md. Design: docs/design.md.
"""
from __future__ import annotations

import argparse
import contextlib
import datetime
import difflib
import glob
import io
import fcntl
import os
import re
import subprocess
import sys
import tempfile
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

from wflib import check as checks  # noqa: E402
from wflib import areas as areas_mod  # noqa: E402
from wflib import config, lanes, ledgers, refs, search, tasks, usage  # noqa: E402
import json  # noqa: E402

WIDTH = 100
SKIP_DIRS = {".worktrees", "node_modules", "lib", "__pycache__"}


class Failure(Exception):
    code = 1


class Usage(Failure):
    code = 2


def old_spelling(old: str, new: str) -> None:
    """One-line notice for an option kept one more release under its old name."""
    print(f"wf: {old} is now {new}", file=sys.stderr)


# ------------------------------------------------------------------ files

def stamp(path: Path) -> tuple[int, int]:
    s = path.stat()
    return (s.st_mtime_ns, s.st_size)


def write_if_unchanged(path: Path, text: str, read_stamp: tuple[int, int]) -> None:
    """Replace `path` by temp file + rename, unless it changed since `read_stamp`."""
    if stamp(path) != read_stamp:
        raise Failure(f"{path.name} changed on disk since it was read: nothing written, run again")
    mode = path.stat().st_mode & 0o777
    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
    try:
        with os.fdopen(fd, "wb") as f:
            f.write(text.encode("utf-8"))
        os.chmod(tmp, mode)
        if stamp(path) != read_stamp:
            raise Failure(f"{path.name} changed on disk since it was read: nothing written, run again")
        os.replace(tmp, path)
    finally:
        if os.path.exists(tmp):
            os.unlink(tmp)


def read(path: Path) -> str:
    return path.read_bytes().decode("utf-8", errors="replace")


class Project:
    def __init__(self, cfg: config.Config):
        self.cfg = cfg
        for name, path in (("tasks", cfg.tasks), ("archive", cfg.archive)):
            if not path.is_file():
                raise Failure(f"workflow.toml: {name} '{cfg.rel(path)}' does not exist")
        self.tasks_stamp, self.archive_stamp = stamp(cfg.tasks), stamp(cfg.archive)
        self.tasks_text, self.archive_text = read(cfg.tasks), read(cfg.archive)
        self.doc = tasks.parse(self.tasks_text)
        self.new_archive: str | None = None

    @property
    def archived(self) -> set[str]:
        return tasks.archive_ids(self.new_archive or self.archive_text)

    def taken(self) -> set[str]:
        return self.doc.ids() | self.archived

    def resolve(self, given: str) -> str:
        """Exact id, or a unique prefix of an open id (read commands)."""
        known = self.doc.ids()
        if given in known:
            return given
        hits = sorted(i for i in known if i.startswith(given))
        if len(hits) == 1:
            return hits[0]
        if hits:
            raise Failure(f"'{given}' matches {', '.join(hits)}")
        raise Failure(tasks.unknown_id(given, known))

    def save(self, dry_run: bool) -> None:
        cfg = self.cfg
        new_tasks = tasks.render(self.doc)
        before = {p.key for p in checks.check(cfg, slow=False)[0]}
        after = checks.check(cfg, tasks_text=new_tasks, archive_text=self.new_archive, slow=False)[0]
        added = [p for p in after if p.key not in before]
        if added:
            raise Failure("refused: nothing written, the change adds problems:\n" + "\n".join(f"  {p}" for p in added))
        changes = [(cfg.tasks, self.tasks_text, new_tasks, self.tasks_stamp)]
        if self.new_archive is not None:
            changes.insert(0, (cfg.archive, self.archive_text, self.new_archive, self.archive_stamp))
        if dry_run:
            for path, old, new, _ in changes:
                name = cfg.rel(path)
                sys.stdout.writelines(difflib.unified_diff(
                    old.replace("\r\n", "\n").splitlines(keepends=True),
                    new.replace("\r\n", "\n").splitlines(keepends=True), name, f"{name} (new)"))
            return
        written = []
        for path, old, new, read_stamp in changes:
            if new == old:
                continue
            try:
                write_if_unchanged(path, new, read_stamp)
            except Failure as e:
                if written:
                    raise Failure(f"{e}; {written[0]} was already written: remove its new top line(s)") from None
                raise
            written.append(cfg.rel(path))


def load_project(args, write: bool = False) -> Project:
    start = Path(args.project) if args.project else Path.cwd()
    if not start.is_dir():
        raise Failure(f"--project {start}: no such folder")
    cfg = config.load_at(start)
    if cfg.format > config.FORMAT:
        raise Failure(f"project format {cfg.format} is newer than this wf ({config.FORMAT}): update /projects/public/workflow")
    if write and cfg.format < config.FORMAT:
        raise Failure(f"TASKS format {cfg.format}, wf needs {config.FORMAT}: "
                      "run wf migrate --write (idle project, one commit)")
    return Project(cfg)


# ------------------------------------------------------------------ output

def show(item: tasks.Item) -> str:
    return "\n".join(item.lines())


def status_word(item: tasks.Item) -> str:
    if not item.status:
        return "-"
    return "blkd" if item.status.startswith("blocked") else "prog"


def row(item: tasks.Item, width: int, cfg: config.Config) -> str:
    prio = "--" if item.prio is None else f"P{item.prio}"
    model = item.model if item.prio is not None else "-"
    lane = lanes.lane_of(item, cfg.lanes, cfg.slice_above) if item.prio is not None else "-"
    lane_w = max(len(l.name) for l in cfg.lanes)
    mark = f"[{item.sessions}] " if item.prio is not None and item.sessions != "parallel" else ""
    line = (f"{item.id:<{width}}  {prio}  {item.effort or '-':<4}  {status_word(item):<4}  {model:<6}  "
            f"{lane:<{lane_w}}  {mark}{item.title}")
    return line if len(line) <= WIDTH else line[:WIDTH - 1] + "…"


def counts(doc: tasks.Doc) -> str:
    def n(key):
        return sum(len(s.items) for s in doc.sections if s.key == key)
    return " · ".join(f"{key} {n(key)}" for key in ("pending", "human", "awaiting", "deferred"))


def resolve_refs(cfg: config.Config, item: tasks.Item) -> list[str]:
    out = []
    for path, anchor in item.refs:
        out.append(refs.resolve(cfg.root, path, anchor))
        if anchor and cfg.anchors_index and cfg.anchors_specs and cfg.anchors_specs.is_dir() \
                and (cfg.root / path).resolve() == cfg.anchors_index.resolve():
            for spec in sorted(cfg.anchors_specs.rglob("*.md")):
                text = read(spec)
                if any(anchor in refs.ANCHOR_RE.findall(l) for l in text.split("\n")):
                    out.append(refs.resolve(cfg.root, cfg.rel(spec), anchor))
    return out


def inbox_path() -> Path:
    return Path(os.environ.get("WF_INBOX") or HERE / "inbox.md")


def inbox_count() -> int:
    path = inbox_path()
    if not path.is_file():
        return 0
    return sum(1 for l in read(path).split("\n") if l.startswith("- "))


# ------------------------------------------------------------------ sessions (lanes)

def sessions_dir(cfg: config.Config) -> Path:
    return cfg.root / ".wf" / "sessions"


def alive(pid, socket) -> bool:
    try:
        os.kill(int(pid), 0)
    except (OSError, ValueError, TypeError):
        return False
    return bool(socket) and Path(socket).exists()


def lane_names(cfg: config.Config) -> list[str]:
    return [l.name for l in cfg.lanes]


def check_lane(cfg: config.Config, lane: str | None) -> None:
    if lane and lane not in lane_names(cfg):
        raise Usage(f"unknown lane '{lane}' ({', '.join(lane_names(cfg))})")


def sessions(cfg: config.Config) -> dict[str, dict]:
    """Registered sessions keyed by lane name or "all" (no lane: every lane)."""
    out = {}
    folder = sessions_dir(cfg)
    for name in [*lane_names(cfg), "all"]:
        try:
            s = json.loads((folder / f"{name}.json").read_text())
        except (OSError, ValueError):
            continue
        if isinstance(s, dict):
            s["alive"] = alive(s.get("pid"), s.get("socket"))
            out[name] = s
    return out


def my_session() -> tuple[str, str] | None:
    """(socket, pid) of this agent session from Claude Code's env; None outside one."""
    socket, pid = os.environ.get("CLAUDE_CODE_MESSAGING_SOCKET"), os.environ.get("CLAUDE_PID")
    return (socket, pid) if socket and pid else None


def wf_folder(cfg: config.Config, name: str) -> Path:
    """.wf/<name> in the project root, created; .wf is git-ignored."""
    folder = cfg.root / ".wf" / name
    folder.mkdir(parents=True, exist_ok=True)
    ignore = folder.parent / ".gitignore"
    if not ignore.exists():
        ignore.write_text("*\n")
    return folder


@contextlib.contextmanager
def project_lock(root: Path):
    """Exclusive project lock (.wf/lock): every wf write and merge-back runs under it. Not reentrant."""
    folder = root / ".wf"
    folder.mkdir(parents=True, exist_ok=True)
    ignore = folder / ".gitignore"
    if not ignore.exists():
        ignore.write_text("*\n")
    with open(folder / "lock", "w") as f:
        fcntl.flock(f, fcntl.LOCK_EX)
        yield


def register(cfg: config.Config, lane: str, model: str) -> str | None:
    """Record this agent session as the lane's session (lane "all" = every lane; env from Claude Code;
    skipped without it). Another live session already holding the lane keeps it; returns a warning line then."""
    me = my_session()
    if not me:
        return None
    socket, pid = me
    other = sessions(cfg).get(lane)
    if other and other["alive"] and str(other.get("pid")) != pid:
        return (f"another live {lane} session holds this lane: uds:{other['socket']} "
                "(claims keep tasks apart; tell the owner if unintended)")
    try:
        record = {"lane": lane, "model": model, "socket": socket, "pid": int(pid) if pid.isdigit() else pid,
                  "session": os.environ.get("CLAUDE_CODE_SESSION_ID", ""),
                  "at": datetime.datetime.now().isoformat(timespec="seconds")}
        (wf_folder(cfg, "sessions") / f"{lane}.json").write_text(json.dumps(record) + "\n")
    except OSError as e:
        print(f"wf: session not registered: {e}", file=sys.stderr)
    return None


def unregister(cfg: config.Config) -> None:
    """Drop session records whose pid is this session (orchestrator holds no lane)."""
    me = my_session()
    if not me:
        return
    for name in [*lane_names(cfg), "all"]:
        f = sessions_dir(cfg) / f"{name}.json"
        try:
            if str(json.loads(f.read_text()).get("pid")) == me[1]:
                f.unlink()
        except (OSError, ValueError, AttributeError):
            pass


# ------------------------------------------------------------------ claims (wf status progress)

def claim(cfg: config.Config, id: str, lane: str = "") -> None:
    """Mark task id as held by this session (skipped outside one). lane: the task's lane."""
    me = my_session()
    if not me:
        return
    socket, pid = me
    model = next((s.get("model", name) for name, s in sessions(cfg).items()
                  if str(s.get("pid")) == pid and s.get("socket") == socket), "")
    try:
        record = {"id": id, "lane": lane, "model": model, "socket": socket, "pid": int(pid) if pid.isdigit() else pid,
                  "session": os.environ.get("CLAUDE_CODE_SESSION_ID", ""),
                  "at": datetime.datetime.now().isoformat(timespec="seconds")}
        (wf_folder(cfg, "claims") / f"{id}.json").write_text(json.dumps(record) + "\n")
    except OSError as e:
        print(f"wf: claim not recorded: {e}", file=sys.stderr)


def unclaim(cfg: config.Config, ids) -> None:
    for id in ids:
        try:
            (cfg.root / ".wf" / "claims" / f"{id}.json").unlink(missing_ok=True)
        except OSError:
            pass


def held(p: "Project") -> dict[str, str]:
    """id → holder, for tasks in progress claimed by another live session."""
    me = my_session()
    pending = {i.id: i for i in p.doc.section("pending").items}
    out = {}
    for path in sorted((p.cfg.root / ".wf" / "claims").glob("*.json")):
        try:
            c = json.loads(path.read_text())
        except (OSError, ValueError):
            continue
        if not isinstance(c, dict) or (me and str(c.get("pid")) == me[1]) or not alive(c.get("pid"), c.get("socket")):
            continue
        item = pending.get(path.stem)
        if item is None or not (item.status or "").startswith("in progress"):
            continue
        out[item.id] = f"{c.get('model') + ' ' if c.get('model') else ''}session uds:{c.get('socket')}"
    return out


def stale(p: "Project") -> list:
    """Items in progress whose claim is missing or held by a dead session."""
    out = []
    for item in p.doc.section("pending").items:
        if not (item.status or "").startswith("in progress"):
            continue
        try:
            c = json.loads((p.cfg.root / ".wf" / "claims" / f"{item.id}.json").read_text())
        except (OSError, ValueError):
            c = None
        if not isinstance(c, dict) or not alive(c.get("pid"), c.get("socket")):
            out.append(item)
    return out


def other_live(cfg: config.Config) -> int:
    """Live sessions in the project other than this one."""
    me = my_session()
    return sum(1 for s in sessions(cfg).values() if s["alive"] and not (me and str(s.get("pid")) == me[1]))


def multi_lines(p: Project, args, lane: str, extra: int) -> list[str]:
    """Worktree mode advice when more than one session is live in the project (git only)."""
    n = sum(1 for s in sessions(p.cfg).values() if s["alive"]) + extra
    main_top = config.git_top(p.cfg.root)
    if n < 2 or not main_top or not (main_top / ".git").is_dir():
        return []
    head = f"{n} live sessions here: "
    wt = config.linked_worktree(Path(args.project or Path.cwd()).resolve())
    if wt:
        return [head + f"you are in worktree {p.cfg.rel(wt[0])} (branch {config.git_branch(wt[1])}); "
                       "wf writes the main tree's TASKS.md"]
    folder, master = p.cfg.root / ".worktrees" / lane, config.git_branch(main_top / ".git") or "master"
    cmd = (f"cd {p.cfg.rel(folder)} && git switch -c {lane}/<task> {master}" if folder.is_dir()
           else f"git worktree add {p.cfg.rel(folder)} -b {lane}/<task> {master}")
    if p.cfg.worktree_setup:
        cmd += " && wf setup" if folder.is_dir() else f" && cd {p.cfg.rel(folder)} && wf setup"
    return [head + f"work in your lane's worktree, never on {master}:", f"  {cmd}  (wf there writes this TASKS.md)"]


def lane_lines(p: Project, me: str | None, runner: bool = False) -> list[str]:
    a = (p.doc, p.archived, p.cfg.lanes, p.cfg.slice_above, held(p))
    return lanes.lanes_block(lanes.counts(*a, runner=runner), sessions(p.cfg), me,
                             lanes.not_ready(*a) if runner else None)


# ------------------------------------------------------------------ read commands

def cmd_next(args) -> int:
    p = load_project(args)
    lane = args.lane
    check_lane(p.cfg, lane)
    model = args.as_ or "haiku"
    out: list[str] = []
    warning = None
    if not args.as_:
        out.append("no --as: treated as haiku; pass --as " + "|".join(tasks.MODELS))
    elif warning := register(p.cfg, lane or "all", model):
        out.append(warning)
    claims = held(p)
    if solo := tasks.solo_running(p.doc, claims):
        if out:
            print("\n".join(out))
        raise Failure(f"solo {solo[0]} in progress by {solo[1]}: wait (its wf done notifies you)")
    item, skipped = lanes.pick(p.doc, p.archived, p.cfg.lanes, p.cfg.slice_above, lane, model, claims,
                               other_live(p.cfg), args.owner)
    multi = multi_lines(p, args, lane or "all", 1 if warning else 0)
    if not args.brief:
        awaiting = p.doc.section("awaiting").items
        if awaiting:
            out += ["===== Awaiting your decision (mention, don't block) =====",
                    *(f"- {i.id}: {i.text}" for i in awaiting), ""]
        human = p.doc.section("human").items
        if human:
            out += ["===== Needs human (not picked) =====", *(f"- {i.id}: {i.title}" for i in human), ""]
        flight = ledgers.in_flight(p.cfg.root, p.cfg.ledgers) if p.cfg.ledgers and p.cfg.ledgers.is_dir() else []
        if flight:
            out += ["===== In-flight plans =====", *flight, ""]
        if skipped:
            out += ["===== Skipped =====", *(f"- {i.id}: {why}" for i, why in skipped), ""]
        if multi:
            out += ["===== Multi-session =====", *multi, ""]
        lines = lane_lines(p, lane)
        if len(lines) > 1:
            out += ["===== Lanes =====", *lines, ""]
        waits = lanes.waiting_block(lanes.cross_waits(p.doc, p.archived, lane, p.cfg.lanes, p.cfg.slice_above),
                                    sessions(p.cfg), p.cfg.lanes, p.cfg.slice_above) if lane else []
        if waits:
            out += ["===== Waiting on other lanes =====", *waits, ""]
    if item:
        if not args.brief:
            out.append("===== Next task =====")
        out.append(show(item))
        if lanes.is_slice_job(item, p.cfg.slice_above):
            out += ["", "===== Slice job (no code) =====",
                    f"effort {item.effort} > slice_above {p.cfg.slice_above}: split it, don't implement.",
                    f'  wf add "<title>. <goal>" -e <1h|1h> --parent {item.id} --model haiku|sonnet|opus'
                    "  (then wf body: Steps/Done/Ref)",
                    f'  wf note {item.id} "sliced into …" · wf status {item.id} clear · not wf done'
                    " (the parent waits on its slices)"]
        if not args.brief:
            for block in resolve_refs(p.cfg, item):
                out += ["", block]
    n = 0 if args.brief else inbox_count()
    if n:
        out += ["", f"workflow inbox: {n} reports (triage: workflow session)"]
    if hint := ctx_hint_line(p.cfg):
        out += ["", hint]
    while out and not out[-1]:
        out.pop()
    if out:
        print("\n".join(out))
    if not item:
        raise Failure(f"nothing pickable for {lane or 'all lanes'} ({model}) in Pending")
    return 0


def cmd_areas(args) -> int:
    p = load_project(args, write=bool(args.mark))
    file = p.cfg.areas_file
    rel = p.cfg.areas_rel
    text = file.read_text(encoding="utf-8", errors="replace") if file.is_file() else ""
    found = areas_mod.parse(text)
    if not found:
        print(f"no areas in {rel}")
        return 0
    names = ", ".join(a.name for a in found)
    wanted = args.name or args.mark
    if wanted and wanted not in [a.name for a in found]:
        hits = [a.name for a in found if a.name.startswith(wanted)]
        if len(hits) == 1:
            if args.name:
                args.name = hits[0]
            else:
                args.mark = hits[0]
            wanted = hits[0]
        elif hits:
            raise Usage(f"ambiguous area '{wanted}' in {rel}: " + ", ".join(hits))
        else:
            raise Usage(f"no area '{wanted}' in {rel} ({names})")
    if args.mark:
        r = git_run(p.cfg.code, "rev-parse", "--short", "HEAD")
        if r.returncode != 0:
            raise Failure("git rev-parse HEAD failed: " + r.stderr.strip())
        text = areas_mod.mark(text, args.mark, r.stdout.strip())
        file.write_text(text, encoding="utf-8")
        found = areas_mod.parse(text)
    for a in found:
        if wanted and a.name != wanted:
            continue
        stale, miss, commits = areas_mod.status(p.cfg.code, a, p.cfg.area_stale_commits)
        line = " · ".join([f"{a.name}: " + ("stale" if stale else "ok")]
                          + ([f"missing: {', '.join(miss)}"] if miss else [])
                          + ([f"{commits} commits since {a.checked}"] if commits is not None else ["no Checked"] if not a.checked else []))
        print(line)
    if not wanted:
        for folder, n in uncovered_areas(p, args):
            print(f"uncovered: {folder} ({n} file{'s' * (n != 1)}): no area's Paths covers it")
    return 0


def cmd_lanes(args) -> int:
    p = load_project(args)
    check_lane(p.cfg, args.lane)
    if args.unregister:
        unregister(p.cfg)
    elif args.lane or args.as_:
        register(p.cfg, args.lane or "all", args.as_ or "haiku")
    if args.wait is not None:
        import time
        poll = float(os.environ.get("WF_LANES_POLL", "30"))
        end = time.monotonic() + args.wait
        while True:
            p = load_project(args)
            if (p.cfg.root / "out" / "wf-batch.stop").exists():
                print("stop requested: out/wf-batch.stop")
                return 2
            if any(c[0] for c in lanes.counts(p.doc, p.archived, p.cfg.lanes, p.cfg.slice_above, held(p), runner=True).values()):
                break
            left = end - time.monotonic()
            if left <= 0:
                print("\n".join(lane_lines(p, args.lane, True)))
                return 1
            time.sleep(min(poll, left))
    print("\n".join(lane_lines(p, args.lane, True)))
    return 0


def runner_ids(p: Project) -> set[str]:
    """Pending ids a headless worker can take: not blocked, After done, runner-ready, no open slices, not sliced out."""
    return {i.id for i in p.doc.section("pending").items
            if not i.error and not (i.status or "").startswith("blocked") and all(a in p.archived for a in i.after)
            and i.runner_ready and not tasks.open_slices(p.doc, i.id) and not lanes.sliced_out(i, p.cfg.slice_above)}


def cmd_list(args) -> int:
    p = load_project(args)
    check_lane(p.cfg, args.lane)
    keys = list(tasks.SECTIONS) if args.section == "all" else [args.section]
    ready = None
    if args.ready:
        ready = {i.id for i in p.doc.section("pending").items
                 if not i.error and not (i.status or "").startswith("blocked")
                 and all(a in p.archived for a in i.after)}
    if args.runner:
        ready = runner_ids(p)
    stale_ids = {i.id for i in stale(p)} if args.stale else None
    want_ref = tuple(args.ref.split("#", 1)) if args.ref else None

    def keep(i: tasks.Item) -> bool:
        if args.prio is not None and (i.prio is None or i.prio > args.prio):
            return False
        if ready is not None and i.id not in ready:
            return False
        if args.blocked and status_word(i) != "blkd":
            return False
        if args.progress and status_word(i) != "prog":
            return False
        if stale_ids is not None and i.id not in stale_ids:
            return False
        if args.model and (i.prio is None or i.model != args.model):
            return False
        if args.lane and (i.prio is None or lanes.lane_of(i, p.cfg.lanes, p.cfg.slice_above) != args.lane):
            return False
        if want_ref and not any(path == want_ref[0] and (len(want_ref) == 1 or anchor == want_ref[1])
                                for path, anchor in i.refs):
            return False
        return True

    groups = [(s, [i for i in s.items if keep(i)]) for k in keys for s in p.doc.sections if s.key == k]
    if args.runner and args.lane:   # pick order of the lane, then its fallback lane's
        order = lanes.ranked(p.doc, p.archived, p.cfg.lanes, p.cfg.slice_above, args.lane)
        keys, groups = ["pending"], [(None, [i for i in order if i.id in ready
                                             and (args.prio is None or i.prio <= args.prio)])]
    if args.n is not None:
        left = args.n
        for n, (s, items) in enumerate(groups):
            groups[n] = (s, items[:left])
            left -= len(groups[n][1])
    width = max((len(i.id) for _, items in groups for i in items), default=0)
    for s, items in groups:
        if len(keys) > 1:
            print(f"== {s.heading}")
        for i in items:
            print(row(i, width, p.cfg))
    print(counts(p.doc))
    return 0


def cmd_show(args) -> int:
    p = load_project(args)
    print("\n\n".join(show(p.doc.item(p.resolve(i))) for i in args.ids))
    return 0


def cmd_ctx(args) -> int:
    p = load_project(args)
    target = args.target
    if "#" in target or "/" in target or (p.cfg.root / target).exists():
        path, _, anchor = target.partition("#")
        users = [i.id for i in p.doc.all_items()
                 if any(r == path and (not anchor or a == anchor) for r, a in i.refs)]
        print(refs.resolve(p.cfg.root, path, anchor or None))
        print("\nTasks: " + (", ".join(users) if users else "none"))
        return 0
    if target not in p.doc.ids() and target in p.archived:
        line = next(l for l in p.archive_text.replace("\r\n", "\n").split("\n")
                    if (m := tasks.ARCHIVE_ID_RE.match(l)) and m.group(1) == target)
        print(f"done: {line}")
        return 0
    id = p.resolve(target)
    section, _ = p.doc.find(id)
    item = p.doc.item(id)
    where = {i.id: s.heading for s in p.doc.sections for i in s.items}
    out = [show(item), "", f"Section: {section.heading}"]
    if item.after:
        out.append("After: " + ", ".join(
            f"{a} ({'open, ' + where[a] if a in where else 'done' if a in p.archived else 'unknown'})"
            for a in item.after))
    needed = [i.id for i in p.doc.all_items() if id in i.after]
    blocks = [i.id for i in p.doc.all_items() if i.blocked_on == id]
    linked = [i.id for i in p.doc.all_items()
              if i.id != id and i.id not in needed and i.id not in blocks
              and id in refs.links("\n".join(i.lines()))]
    for label, ids in (("Needed by", needed), ("Blocks", blocks), ("Linked from", linked)):
        if ids:
            out.append(f"{label}: {', '.join(ids)}")
    if p.cfg.verify and not id.startswith("a-"):
        out.append("Verify (run before wf finish): " + " · ".join(p.cfg.verify))
    for block in resolve_refs(p.cfg, item):
        out += ["", block]
    out += area_blocks(p, "\n".join(item.lines()))
    print("\n".join(out))
    return 0


def area_blocks(p: Project, text: str) -> list[str]:
    """Notes of the areas the task text names (area name, anchor or a path no other area lists) → ctx lines."""
    file = p.cfg.areas_file
    if not file.is_file():
        return []
    notes = file.read_text(encoding="utf-8", errors="replace")
    out = []
    found = areas_mod.parse(notes)
    skip = areas_mod.shared_paths(found)
    for a in found:
        if areas_mod.matches(a, text, skip):
            out += ["", f"Area {a.name} ({p.cfg.areas_rel}):", areas_mod.block(notes, a.name)]
    return out


def cmd_search(args) -> int:
    p = load_project(args)
    kinds = {k for k, on in (("task", args.tasks), ("archive", args.archive), ("doc", args.docs)) if on} or None
    docs = {}
    if kinds is None or "doc" in kinds:
        docs = {p.cfg.rel(f): read(f) for f in checks.doc_files(p.cfg)}
    hits = search.search(args.words, p.doc, p.archive_text, docs, kinds=kinds, limit=args.n,
                         archive_name=p.cfg.rel(p.cfg.archive))
    if not hits:
        raise Failure("no hits")
    for h in hits:
        if h.kind == "task":
            header = p.doc.item(h.where).text if h.where in p.doc.ids() else ""
            text = h.line if h.line == header else f"{h.label} — {h.line}"
        elif h.kind == "archive":
            text = re.sub(r"^\d{4}-\d\d-\d\d \*\*([^*]+)\*\*", r"\1", h.line)
        else:
            text = f"{h.label} — {h.line}" if h.line and h.line != h.label else h.label
        line = f"{h.where}  {text}"
        print(line if len(line) <= 2 * WIDTH else line[:2 * WIDTH - 1] + "…")
    return 0


def cmd_log(args) -> int:
    p = load_project(args)
    lines = [l for l in p.archive_text.replace("\r\n", "\n").split("\n") if l.startswith("- ")]
    words = [w.lower() for w in args.words]
    lines = [l for l in lines if all(w in l.lower() for w in words)]
    print("\n".join(lines[:args.n]))
    return 0


def cmd_check(args) -> int:
    p = load_project(args)
    errors, warnings = checks.check(p.cfg)
    warnings += checks.merged_tool_worktrees(Path(os.environ.get("WF_TOOL_ROOT") or HERE))
    for w in warnings:
        print(f"warn: {w}")
    for e in errors:
        print(f"ERROR: {e}")
    print(("OK: " if not errors else "") + f"{len(errors)} errors · {len(warnings)} warnings")
    return 1 if errors else 0


def find_projects(root: Path, depth: int = 3) -> list[Path]:
    out = []

    def walk(folder: Path, left: int) -> None:
        if (folder / "wf.py").is_file() and (folder / "wflib").is_dir():
            return                                  # a wf checkout (its templates/ is no project)
        if (folder / config.NAME).is_file():
            out.append(folder)
            return
        if left == 0:
            return
        try:
            children = sorted(c for c in folder.iterdir() if c.is_dir() and not c.is_symlink())
        except OSError:
            return
        for c in children:
            if not c.name.startswith(".") and c.name not in SKIP_DIRS:
                walk(c, left - 1)

    walk(root, depth)
    return out


def default_root(tool: Path) -> Path:
    """Folder `wf projects` scans: the tool's parent, else its grandparent (tool under e.g. public/), if it holds projects."""
    return next((d for d in (tool.parent, tool.parent.parent) if find_projects(d)), tool.parent)


def projects_root() -> Path:
    return Path(os.environ.get("WF_ROOT") or default_root(HERE))


def cmd_projects(args) -> int:
    root = projects_root()
    rows = []
    for folder in find_projects(root):
        name = str(folder.relative_to(root))
        try:
            cfg = config.load(folder)
            doc = tasks.parse(read(cfg.tasks))
            archived = tasks.archive_ids(read(cfg.archive)) if cfg.archive.is_file() else set()
            errors = len(checks.check(cfg, slow=False)[0])
            item = lanes.pick(doc, archived, cfg.lanes, cfg.slice_above, owner=True)[0]
            n = {k: sum(len(s.items) for s in doc.sections if s.key == k) for k in tasks.SECTIONS}
            rows.append((name, f"pending {n['pending']}  human {n['human']}  awaiting {n['awaiting']}  "
                               f"errors {errors}  next: " + (f"{item.id} {item.title}" if item else "-")))
        except (config.ConfigError, tasks.TaskError, OSError) as e:
            rows.append((name, f"broken: {e}"))
    width = max((len(n) for n, _ in rows), default=0)
    for name, text in rows:
        line = f"{name:<{width}}  {text}"
        print(line if len(line) <= WIDTH else line[:WIDTH - 1] + "…")
    if not rows:
        raise Failure(f"no projects under {root}")
    return 0


def claude_projects() -> Path:
    return Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude") / "projects"


def since_time(value: str | None) -> str | None:
    """ISO (UTC) as is; 90m / 2h / 1d = that long ago."""
    m = re.fullmatch(r"(\d+)([mhd])", value or "")
    if not m:
        return value
    delta = datetime.timedelta(**{{"m": "minutes", "h": "hours", "d": "days"}[m[2]]: int(m[1])})
    return (datetime.datetime.now(datetime.timezone.utc) - delta).strftime("%Y-%m-%dT%H:%M:%S")


def agent_label(path: Path) -> str:
    id = path.stem.removeprefix("agent-")
    try:
        desc = json.loads(path.with_name(path.stem + ".meta.json").read_text()).get("description") or ""
    except (OSError, ValueError, AttributeError):
        desc = ""
    return f"{id} {desc}".strip()


def usage_transcripts(args) -> list[tuple[str, Path]]:
    """(label, jsonl): one agent, or a session's main transcript + its subagents."""
    base = claude_projects()
    if args.agent:
        id = args.agent.removeprefix("agent-")
        found = sorted(base.glob(f"*/*/subagents/agent-{id}.jsonl"))
        if not found:
            raise Failure(f"no transcript for agent {args.agent}")
        return [(agent_label(found[0]), found[0])]
    sid = args.session or os.environ.get("CLAUDE_CODE_SESSION_ID")
    if sid:
        found = sorted(base.glob(f"*/{sid}*.jsonl"))
        if len(found) != 1:
            raise Failure(f"session {sid}: {len(found)} transcripts match")
        main = found[0]
    else:
        folder = base / re.sub(r"[^A-Za-z0-9]", "-", str(Path.cwd()))
        found = sorted(folder.glob("*.jsonl"), key=lambda p: p.stat().st_mtime)
        if not found:
            raise Failure(f"no transcripts in {folder} (--session ID)")
        main = found[-1]
    agents = sorted((main.parent / main.stem / "subagents").glob("agent-*.jsonl"))
    return [("main", main)] + [(agent_label(p), p) for p in agents]


def cmd_usage(args) -> int:
    since = since_time(args.since)
    if args.report:
        return usage_report(since)
    if args.explore:
        return usage_explore(args, since)
    if args.log and not args.agent:
        raise Usage("--log needs --agent")
    if args.log:
        root = config.find_root(Path(args.project) if args.project else Path.cwd())
        path = usage_transcripts(args)[0][1]
        now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
        line = usage.log_line(now, root.name, args.log[0], args.effort or "-", args.log[1],
                              path.stem.removeprefix("agent-"), usage.parse(read(path), since=since), lane=args.lane, dur=args.duration)
        (root / "out").mkdir(exist_ok=True)
        with open(root / "out" / "wf-cost.log", "a") as f:
            f.write(line + "\n")
        print(line)
        return 0
    rows, total, dollars, unknown = [], usage.Usage(), 0.0, False
    for label, path in usage_transcripts(args):
        for model, u in usage.parse(read(path), since=since).items():
            c = usage.cost(model, u)
            total.add(u)
            dollars += c or 0
            unknown |= c is None
            rows.append((label, usage.short(model), u, "?" if c is None else f"{c:.2f}"))
    width = min(max([len(r[0]) for r in rows] + [5]), 40)

    def nums(u):
        out = ("~" if u.est else "") + usage.fmt(u.out)  # ~ = estimated from content (subagent)
        return " ".join(f"{usage.fmt(n):>7}" for n in (u.inp, u.cw, u.cr)) + f" {out:>7}"

    print(f"{'agent':<{width}}  {'model':<12} {'turns':>6} {'in':>7} {'cw':>7} {'cr':>7} {'out':>7} {'$':>7}")
    for label, model, u, c in rows:
        label = label if len(label) <= width else label[:width - 1] + "…"
        print(f"{label:<{width}}  {model:<12} {u.turns:>6} {nums(u)} {c:>7}")
    print(f"{'total':<{width}}  {'':<12} {total.turns:>6} {nums(total)} {dollars:>7.2f}{'+' if unknown else ''}")
    return 0


def usage_explore(args, since: str | None) -> int:
    root = str(Path.cwd())
    agents = [(label, usage.explore(read(path), since=since, root=root))
              for label, path in usage_transcripts(args) if label != "main"]
    r = usage.explore_report(agents)
    if not r["rows"]:
        print("no subagent with >= 4 calls")
        return 0
    width = min(max([len(x[0]) for x in r["rows"]] + [5]), 40)
    print(f"{'agent':<{width}} {'calls':>5} {'1stEdit':>7} {'explore':>7} {'pre-edit':>8}")
    for label, calls, fe, exp, pre in r["rows"]:
        label = label if len(label) <= width else label[:width - 1] + "…"
        print(f"{label:<{width}} {calls:>5} {fe:>7} {exp:>7.0%} {pre:>8.0%}")
    tot = r["total"] or 1
    print(f"ALL {r['agents']} agents, {usage.fmt(r['total'])} billed input: "
          + ", ".join(f"{k} {100 * v // tot}%" for k, v in sorted(r["cost"].items(), key=lambda kv: -kv[1])))
    if r["pre_n"]:
        print(f"before 1st edit (median, {r['pre_n']} agents): {r['pre_share']:.0%} of input, "
              f"{r['pre_calls']:g} calls, +{usage.fmt(int(r['pre_ctx']))} context")
    rt = sum(r["results"].values()) or 1
    print("result tokens: " + ", ".join(f"{k} {usage.fmt(v)} {100 * v // rt}%"
                                        for k, v in sorted(r["results"].items(), key=lambda kv: -kv[1])))
    if r["files"]:
        print("files read by >= 2 agents (agents, tokens):")
        for f, a, n in r["files"]:
            print(f"{a:>4} {usage.fmt(n):>7}  {f}")
    return 0


def fmt_dur(s) -> str:
    return "-" if s is None else f"{int(s) // 3600}h{int(s) % 3600 // 60:02d}m" if s >= 3600 else f"{int(s) // 60}m{int(s) % 60:02d}s"


def usage_report(since: str | None) -> int:
    root = projects_root()
    entries = []
    for folder in find_projects(root):
        log = folder / "out" / "wf-cost.log"
        if log.is_file():
            entries += usage.parse_log(read(log), since=since)
    if not entries:
        raise Failure(f"no out/wf-cost.log lines in the projects under {root}")
    print(f"{'lane':<8} {'effort':<6} {'n':>4} {'done':>4} {'other':>5} {'med$':>7} {'total$':>8} {'$/done':>7} med_turns  med_dur")
    for lane, effort, n, done, other, med, total, per, turns, dur in usage.report(entries, tasks.EFFORTS):
        per = "-" if per is None else f"{per:.2f}"
        print(f"{lane:<8} {effort:<6} {n:>4} {done:>4} {other:>5} {med:>7.2f} {total:>8.2f} {per:>7} {turns:>9} {fmt_dur(dur):>8}")
    return 0


# ------------------------------------------------------------------ write commands

def split_list(value: str) -> list[str]:
    return tasks.split_refs(value)


def stdin_lines() -> list[str]:
    return sys.stdin.read().replace("\r\n", "\n").split("\n")


def set_slices_line(parent: tasks.Item, id: str) -> None:
    at = parent._line(tasks.SLICES_RE)
    if at is None:
        parent.body.insert(tasks._tail_start(parent), f"{tasks.INDENT}- Slices: [[{id}]]")
    else:
        parent.body[at] = parent.body[at].rstrip() + f", [[{id}]]"


def cmd_add(args) -> int:
    p = load_project(args, write=True)
    doc = p.doc
    if args.title == "-":
        item = tasks.parse_block(sys.stdin.read())
        key = args.section or ("awaiting" if item.id.startswith("a-") else "pending")
    else:
        key = args.section or "pending"
        prio, after = args.prio, split_list(args.after or "")
        text = " ".join(args.title.split())
        leading = tasks.LEADING_ID_RE.match(text)
        if leading and not args.id:
            args.id, text = leading.groups()
        if args.parent:
            parent_section, _ = doc.find(args.parent)
            parent = doc.item(args.parent)
            key = args.section or parent_section.key
            prio = parent.prio if prio is None else prio
            id = args.id or tasks.slice_id(args.parent, p.taken())
            m = re.match(re.escape(args.parent) + r"-(\d+)$", id)
            prev = parent.slices or ([f"{args.parent}-{int(m.group(1)) - 1}"] if m and int(m.group(1)) > 1 else [])
            if not after:
                # a deferred previous slice would block a live one forever: chain to the last live slice
                live = [s for s in prev if s in p.archived or key == "deferred"
                        or (s in doc.ids() and doc.find(s)[0].key != "deferred")]
                after = live[-1:]
        task = key != "awaiting"
        if task and prio is None:
            raise Usage("add: a task needs -p 0-3")
        if task and args.effort is None:
            raise Usage("add: a task needs -e " + "|".join(tasks.EFFORTS))
        if task and args.effort not in tasks.EFFORTS:
            raise Failure(f"effort '{args.effort}' (want {', '.join(tasks.EFFORTS)})")
        if not text:
            raise Usage("add: empty title")
        if not text.endswith((".", "?", "!")):
            text += "."
        if not args.parent:
            title = text.split(". ", 1)[0]
            id = args.id or tasks.make_id(title, p.taken(), "t-" if task else "a-")
        if not tasks.ID_RE.match(id):
            raise Failure(f"bad id '{id}' (want t-… or a-…, lowercase a-z 0-9 -)")
        if id in p.archived:
            raise Failure(f"id '{id}' already used in the archive (ids are never reused)")
        item = tasks.Item(id=id, prio=prio if task else None, effort=args.effort if task else None, text=text)
        if args.body:
            item.body = tasks.indent_body(stdin_lines())
        if args.interactive:
            old_spelling("--interactive", "--sessions owner")
            args.sessions = args.sessions or "owner"
        if args.done and task:
            item.body.append(f"{tasks.INDENT}Done: {args.done}")
        if args.sessions and args.sessions != "parallel" and task:
            item.body.append(f"{tasks.INDENT}Sessions: {args.sessions}")
        if args.model and task:
            item.body.append(f"{tasks.INDENT}Model: {args.model}")
        if args.cloud and task:
            item.body.append(f"{tasks.INDENT}Cloud: {args.cloud}")
        if after:
            item.body.append(f"{tasks.INDENT}- After: " + ", ".join(f"[[{a}]]" for a in after))
        if args.ref:
            item.body.append(f"{tasks.INDENT}Ref: " + ", ".join(split_list(args.ref)))
        if args.parent:
            set_slices_line(parent, id)
    tasks.insert(doc, item, key)
    p.save(args.dry_run)
    if not args.dry_run:
        print(item.header())
        if item.prio is not None and item.done_text is None:
            if item.prio == 0:
                print("wf: warning: P0 without Done line is not runner-pickable; use --done \"<text>\"", file=sys.stderr)
            else:
                print("hint: no Done line; add one (--done) so runners can pick it", file=sys.stderr)
    return 0


RELEARN_LINE = "re-learned anything (>3 greps to find)? one anchor line → that area's code map"


def area_tasks(p: Project) -> list[str]:
    """Add t-map-<area> refresh tasks for stale areas without an open one; returns output lines."""
    file = p.cfg.areas_file
    if not file.is_file():
        return []
    out = []
    for a in areas_mod.parse(file.read_text(encoding="utf-8", errors="replace")):
        if not areas_mod.status(p.cfg.code, a, p.cfg.area_stale_commits)[0]:
            continue
        prefix = f"t-map-{a.slug}"
        if any(i == prefix or i.startswith(prefix + "-") for i in p.doc.ids()):
            continue
        id, n = prefix, 1
        while id in p.archived:
            n += 1
            id = f"{prefix}-{n}"
        item = tasks.Item(id, prio=1, effort="<1h", text=f"Refresh {a.name} area map.")
        item.body = tasks.indent_body([
            f"Steps: wf areas {a.name}; fix missing anchors + test recipe from git log --stat "
            f"<Checked>..HEAD -- <paths>; wf areas --mark {a.name}.",
            f"Done: wf areas {a.name} shows ok.",
            "Model: sonnet"])
        tasks.insert(p.doc, item, "pending")
        out.append(f"added {id} (area map stale)")
    return out


def uncovered_areas(p: Project, args) -> list[tuple[str, int]]:
    """Folders this task's diff (branch since its base + uncommitted) touches outside every area's Paths."""
    file = p.cfg.areas_file
    if not file.is_file() or p.cfg.code_root:      # code in another repo: this diff is not its code
        return []
    start = Path(getattr(args, "project", None) or Path.cwd()).resolve()
    here = _here(start, p.cfg)
    found = [areas_mod.with_anchor_paths(here, a)
             for a in areas_mod.parse(file.read_text(encoding="utf-8", errors="replace"))]
    if not any(a.paths for a in found):
        return []
    wt = config.linked_worktree(start)
    if wt:
        base = config.git_branch(wt[2] / ".git") or "master"
    else:
        base = next((b for b in ("master", "main")
                     if git_run(here, "rev-parse", "-q", "--verify", f"refs/heads/{b}").returncode == 0), None)
    books = {p.cfg.rel(f) for f in (p.cfg.tasks, p.cfg.archive, p.cfg.root / config.NAME)} | {p.cfg.areas_rel}
    files = [f for f in areas_mod.changed_files(here, base) if f not in books]
    return areas_mod.uncovered(files, found, p.cfg.area_ignore)


UNCOVERED_MAX = 3       # map tasks one wf done adds at most


def uncovered_tasks(p: Project, args) -> list[str]:
    """Add t-map-<folder> tasks for folders the diff touches outside every area's Paths (once per id)."""
    out = []
    for folder, n in uncovered_areas(p, args)[:UNCOVERED_MAX]:
        id = f"t-map-{areas_mod.slug(folder)}"
        if any(i == id or i.startswith(id + "-") for i in [*p.doc.ids(), *p.archived]):
            continue
        rel = p.cfg.areas_rel
        item = tasks.Item(id, prio=1, effort="<1h", text=f"Map {folder} area. No area's Paths covers it.")
        item.body = tasks.indent_body([
            f"Steps: git log --stat -- {folder}; new ### section under ## Areas in {rel} (Code map anchors, "
            f"Test recipe, Paths: {folder}/) or add {folder}/ to an existing area's Paths; wf areas --mark <area>.",
            f"Done: wf areas lists the area ok and no longer names {folder} uncovered.",
            "Model: sonnet"])
        tasks.insert(p.doc, item, "pending")
        out.append(f"added {id} (uncovered area: {folder}, {n} file{'s' * (n != 1)})")
    return out


def cmd_done(args) -> int:
    p = load_project(args, write=True)
    doc = p.doc
    task_ids = [i for i in args.ids if not i.startswith("a-")]
    if len(task_ids) == 1 and not args.m:
        raise Usage('done: -m "<entry>" is required for a single task')
    if len(task_ids) > 1 and args.m:
        raise Usage("done: -m goes with one task; several ids use each task's goal")
    out = []
    today = datetime.date.today().isoformat()
    for id in args.ids:
        doc.find(id)
    if not config.linked_worktree(Path(args.project or Path.cwd()).resolve()):
        for id in task_ids:
            if wt := claimed_worktree(p.cfg.root, doc.item(id)):
                raise Failure(f"{id} is in progress in worktree {wt[0]} (branch {wt[1]}): run wf finish/done there "
                              f"(its bookkeeping goes in with wf merge), or wf status {id} clear first")
    before = lanes.pickable_ids(doc, p.archived)
    lane = lambda i: lanes.lane_of(i, p.cfg.lanes, p.cfg.slice_above)
    done_lanes = {lane(doc.item(i)) for i in task_ids}
    solo = [i for i in task_ids if doc.item(i).sessions == "solo"]
    for id in args.ids:
        if id.startswith("a-"):
            item = tasks.remove(doc, id)
            if args.m:
                line = tasks.archive_line(today, item, args.m)
                p.new_archive = tasks.archive_prepend(p.new_archive or p.archive_text, line)
            out.append(f"removed: {id}" + (f" → {p.cfg.rel(p.cfg.archive)}" if args.m else ""))
            freed = tasks.unblock(doc, id)
            if freed:
                out.append("unblocked: " + ", ".join(freed))
            continue
        open_ = [s for s in tasks.open_slices(doc, id) if s not in args.ids]
        if open_:
            raise Failure(f"'{id}' has open slices: {', '.join(open_)}")
        item = tasks.remove(doc, id)
        line = tasks.archive_line(today, item, args.m or item.goal)
        p.new_archive = tasks.archive_prepend(p.new_archive or p.archive_text, line)
        out.append(f"done: {id} → {p.cfg.rel(p.cfg.archive)}")
        parent = tasks.parent_of(doc, id)
        if parent and not tasks.open_slices(doc, parent):
            out.append(f"last slice of {parent}: finish it with wf done {parent} -m \"…\"")
    if task_ids and not args.dry_run:
        out += area_tasks(p)
        out += uncovered_tasks(p, args)
    p.save(args.dry_run)
    if args.dry_run:
        return 0
    unclaim(p.cfg, task_ids)
    after = lanes.pickable_ids(doc, p.archived | set(task_ids))
    freed = [i for s in doc.sections if s.key == "pending" for i in s.items
             if i.id in after - before and lane(i) not in done_lanes]
    if task_ids:
        out += lanes.notify_block(freed, sessions(p.cfg), p.cfg.lanes, p.cfg.slice_above)
        me = my_session()
        out += lanes.solo_done_block(solo, sessions(p.cfg), me[1] if me else None)
    if task_ids:
        if p.cfg.verify:
            out += ["verify:", *(f"  {v}" for v in p.cfg.verify)]
        out += ["checklist:", f"  - {RELEARN_LINE}", *(f"  - {d}" for d in p.cfg.done)]
        if not getattr(args, "finishing", False):
            out += worktree_done_lines(p, args)
        if hint := ctx_hint_line(p.cfg):
            out.append(hint)
    print("\n".join(out))
    return 0


CTX_TAIL = 1 << 20      # bytes of the transcript read for the last request


def ctx_hint_line(cfg) -> str | None:
    """This session's prompt size over cfg.ctx_hint → a /clear hint; no session id / transcript → None."""
    sid = os.environ.get("CLAUDE_CODE_SESSION_ID")
    if not cfg.ctx_hint or not sid:
        return None
    found = sorted(claude_projects().glob(f"*/{glob.escape(sid)}.jsonl"))
    if len(found) != 1:
        return None
    try:
        with open(found[0], "rb") as f:
            f.seek(max(0, f.seek(0, 2) - CTX_TAIL))
            text = f.read().decode("utf-8", "replace")
    except OSError:
        return None
    return usage.ctx_hint(usage.context_tokens(text), cfg.ctx_hint)


def claimed_worktree(root: Path, item: tasks.Item) -> tuple[str, str] | None:
    """(worktree path, branch) of a linked worktree on the branch named by item's 'in progress: <branch>'."""
    status = item.status or ""
    if not status.startswith("in progress: "):
        return None
    words = status.removeprefix("in progress: ").split()
    branch = words[0] if words else ""
    path = None
    for line in git_run(root, "worktree", "list", "--porcelain").stdout.splitlines():
        if line.startswith("worktree "):
            path = line.removeprefix("worktree ")
        elif branch and line == f"branch refs/heads/{branch}" and path and Path(path).resolve() != root.resolve():
            if config.linked_worktree(Path(path)):
                return path, branch
    return None


def worktree_done_lines(p: Project, args) -> list[str]:
    """Merge-back steps when wf done runs in a linked worktree (multi-session mode)."""
    wt = config.linked_worktree(Path(args.project or Path.cwd()).resolve())
    if not wt:
        return []
    branch, main = config.git_branch(wt[1]), wt[2]
    master = config.git_branch(main / ".git") or "master"
    files = " ".join(str(f.relative_to(main)) for f in (p.cfg.tasks, p.cfg.archive))
    warn = []
    if not branch and (n := unmerged_count(wt[0], master)):
        warn = [f"detached HEAD has {n} commit{'s' * (n != 1)} not in {master}: wf merge merges "
                f"{'them' if n != 1 else 'it'} (never leave them unmerged)"]
    return warn + [f"worktree mode (branch {branch or 'none: detached HEAD'}), after verify: commit your code here (explicit paths), then:",
            f"  wf merge   (rebase, ff-merge into {master}, commit {files}, push home; "
            f"conflict → git rebase {master}, resolve, verify, wf merge again)"]


def git_run(cwd: Path, *args: str) -> subprocess.CompletedProcess:
    return subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)


def unmerged_count(top: Path, master: str) -> int:
    """Commits on this worktree's HEAD not in master (0 when git fails)."""
    r = git_run(top, "rev-list", "--count", f"{master}..HEAD")
    return int(r.stdout.strip()) if r.returncode == 0 and r.stdout.strip().isdigit() else 0


def cmd_merge(args) -> int:
    """Merge-back of a lane worktree's branch, under the project lock (main() takes it)."""
    start = Path(args.project or Path.cwd()).resolve()
    wt = config.linked_worktree(start)
    if not wt:
        raise Failure("merge runs inside a linked git worktree (lane worktree)")
    top, gitdir, main = wt
    branch = config.git_branch(gitdir)
    master = config.git_branch(main / ".git") or "master"
    cfg = config.load_at(start)
    files = [str(f.relative_to(main)) for f in (cfg.tasks, cfg.archive)]
    if git_run(top, "status", "--porcelain", "-uall").stdout.strip():
        raise Failure("worktree has uncommitted changes: commit them first")
    if not branch and not unmerged_count(top, master):
        # after a merge: notes / follow-ups written since → bookkeeping commit only
        if not git_run(main, "status", "--porcelain", "--", *files).stdout.strip():
            raise Failure("worktree is on a detached HEAD: nothing to merge")
        r = git_run(main, "commit", "-q", "-m", args.m or "bookkeeping", "--", *files)
        if r.returncode:
            raise Failure(f"bookkeeping commit failed: {(r.stderr.strip() or r.stdout.strip() or 'git error').splitlines()[-1]}")
        print(f"committed {' '.join(files)}")
        return 0
    out = []        # a branch, or a detached HEAD with commits not in master (never left behind)
    if git_run(top, "rebase", master).returncode:
        git_run(top, "rebase", "--abort")
        raise Failure(f"rebase onto {master} conflicts: git rebase {master}, resolve, verify, then wf merge again")
    out.append(f"rebased onto {master}")
    args.merged_sha = git_run(top, "rev-parse", "--short", "HEAD").stdout.strip()
    r = git_run(main, "merge", "--ff-only", branch or git_run(top, "rev-parse", "HEAD").stdout.strip())
    if r.returncode:
        raise Failure(f"ff-merge into {master} failed: {(r.stderr.strip() or 'git error').splitlines()[-1]}")
    out.append(f"fast-forwarded {master}")
    if git_run(main, "status", "--porcelain", "--", *files).stdout.strip():
        msg = args.m or (f"{branch.rsplit('/', 1)[-1]} done" if branch else "bookkeeping")
        r = git_run(main, "commit", "-q", "-m", msg, "--", *files)
        if r.returncode:
            raise Failure(f"bookkeeping commit failed: {(r.stderr.strip() or r.stdout.strip() or 'git error').splitlines()[-1]}")
        out.append(f"committed {' '.join(files)}")
    git_run(top, "switch", "-q", "--detach", master)
    if branch:
        git_run(top, "branch", "-q", "-d", branch)
    if not args.no_push and _push_home(main):
        out.append("pushed home")
    out.append(f"merged {branch or 'detached HEAD'} into {master}")
    print("\n".join(out))
    return 0


def _push_home(main: Path) -> bool:
    """git push home --all/--tags when remote home exists; True if pushed."""
    if "home" not in git_run(main, "remote").stdout.split():
        return False
    for extra in ("--all", "--tags"):
        r = git_run(main, "push", "-q", "home", extra)
        if r.returncode:
            raise Failure(f"push home failed: {(r.stderr.strip() or 'git error').splitlines()[-1]}")
    return True


def _dirty_outside(top: Path, keep: list[Path]) -> list[str]:
    """Uncommitted paths of the repo at `top` not under any of `keep` (absolute paths)."""
    stray = []
    for line in git_run(top, "status", "--porcelain", "-uall").stdout.splitlines():
        rel = line[3:].split(" -> ")[-1].strip('"').rstrip("/")
        path = (top / rel).resolve()
        if not any(path == k or k in path.parents for k in keep):
            stray.append(rel)
    return stray


GATE_RED_HELP = (
    "\ngate red procedure (also for a red gate run after wf finish, on the merged sha):"
    "\n- culprit = your diff (git show --stat <sha>) explains the failure -> fix now (new commit, wf merge) or hand back"
    "\n- not your diff (earlier task broke it; see git log of the failing area) -> wf add -p 0 --model <m> -e <effort>"
    ' --done "gate ALL GREEN" -b "Fix gate red <test>. <goal>" with body line "Steps: <failing test, culprit sha/id>"'
    "\n- then report result: done+gate-red <culprit sha or id> <fix id> (your task is done, the lane goes on with the fix)")


def cmd_finish(args) -> int:
    """gate → done → commit the given paths → merge (lane worktree), in one call; checks first, so a refusal
    leaves the task open."""
    if args.paths and not args.commit:
        raise Usage("finish: paths need --commit MSG")
    start = Path(args.project or Path.cwd()).resolve()
    root = config.find_root(start)
    cfg = config.load(root)
    wt = config.linked_worktree(start)
    top = Path(git_run(start, "rev-parse", "--show-toplevel").stdout.strip() or start)
    paths = [(start / f).resolve() for f in args.paths]
    books = [] if wt else [cfg.tasks.resolve(), cfg.archive.resolve()]
    for f, path in zip(args.paths, paths):
        if path != top and top not in path.parents:
            raise Failure(f"path {f} is outside this repo ({top}): commit it in its own repo first, "
                          "then wf finish without it")
        if wt and path in (top / cfg.tasks.relative_to(wt[2]), top / cfg.archive.relative_to(wt[2])):
            raise Failure(f"path {f} = this worktree's copy of the books: wf finish writes the main tree's "
                          "and wf merge commits them; drop it")
        if not path.exists() and git_run(top, "ls-files", "--error-unmatch", "--", str(path)).returncode:
            raise Failure(f"path {f} does not exist and is not tracked: nothing to commit")
    if wt and paths and not git_run(top, "status", "--porcelain", "--", *map(str, paths)).stdout.strip():
        raise Failure("nothing to commit in the --commit paths: drop them (wf finish without paths) or fix them")
    if stray := _dirty_outside(top, paths + books):
        raise Failure("uncommitted changes outside the --commit paths: " + " ".join(stray))
    if cfg.quick_gate:
        _run_lines(cfg.quick_gate, _here(start, cfg), cfg,
                   "quick_gate '{line}' red (exit {rc}): fix it, then wf finish again; later commands skipped" + GATE_RED_HELP)
        print(f"quick_gate: {len(cfg.quick_gate)} green", flush=True)
    with project_lock(root):
        p = load_project(args)
        if args.id not in p.doc.ids() and args.id in p.archived:
            print(f"{args.id} already done ({cfg.rel(cfg.archive)}): resuming with commit + merge", flush=True)
        else:
            done = argparse.Namespace(project=args.project, ids=[args.id], m=args.m, dry_run=False, finishing=True)
            cmd_done(done)
            sys.stdout.flush()
        resume = f" ({args.id} is done already: fix it, then rerun the same wf finish, it resumes)"
        commit = list(dict.fromkeys(map(str, [*paths, *(books if args.commit or not wt else [])])))
        if commit:
            r = git_run(top, "add", "--", *map(str, paths)) if paths else None
            if r and r.returncode:
                raise Failure(f"git add failed: {(r.stderr.strip() or 'git error').splitlines()[-1]}" + resume)
            msg = args.commit or f"{args.id} done"
            r = git_run(top, "commit", "-q", "-m", msg, "--", *commit)
            if r.returncode:
                raise Failure(f"commit failed: {(r.stderr.strip() or r.stdout.strip() or 'git error').splitlines()[-1]}"
                              + resume)
            print("committed " + " ".join(os.path.relpath(c, top) for c in commit), flush=True)
            if not wt:
                sha = git_run(top, "rev-parse", "--short", "HEAD").stdout.strip()
                tool = getattr(args, "tool_commit", None)
                print(f"report: commit {sha}" + (f" tool {tool}" if tool else ""), flush=True)
        if not wt and not args.no_push and _push_home(top):
            print("pushed home", flush=True)
        if wt:
            ns = argparse.Namespace(project=args.project, m=None, no_push=args.no_push)
            rc = cmd_merge(ns)
            if not rc and getattr(ns, "merged_sha", ""):
                tool = getattr(args, "tool_commit", None)
                print(f"report: commit {ns.merged_sha}" + (f" tool {tool}" if tool else ""), flush=True)
            return rc
    return 0


def cmd_wip(args) -> int:
    """Wrap-up in one call (lane worktree): commit the given paths on the branch, note the state, status clear."""
    start = Path(args.project or Path.cwd()).resolve()
    if not config.linked_worktree(start):
        raise Failure("wip runs inside a lane worktree")
    top = Path(git_run(start, "rev-parse", "--show-toplevel").stdout.strip() or start)
    paths = [str((start / f).resolve()) for f in args.paths]
    if paths:
        r = git_run(top, "add", "--", *paths)
        if r.returncode:
            raise Failure(f"git add failed: {(r.stderr.strip() or 'git error').splitlines()[-1]}")
        r = git_run(top, "commit", "-q", "-m", args.commit or f"{args.id} WIP", "--", *paths)
        if r.returncode:
            raise Failure(f"commit failed: {(r.stderr.strip() or r.stdout.strip() or 'git error').splitlines()[-1]}")
        print("committed " + " ".join(os.path.relpath(c, top) for c in paths), flush=True)
    p = load_project(args)
    id = p.resolve(args.id)
    with project_lock(p.cfg.root):
        cmd_note(argparse.Namespace(project=args.project, id=id, line=args.m, dry_run=False))
        cmd_status(argparse.Namespace(project=args.project, id=id, kind="clear", value=[], dry_run=False,
                                      clear_stale=False))
    return 0


def _here(start: Path, cfg) -> Path:
    """Project folder to run config commands in: the worktree's copy of cfg.root, else cfg.root."""
    wt = config.linked_worktree(start)
    if not wt:
        return cfg.root
    top, _, main = wt
    try:
        return top / cfg.root.relative_to(main)
    except ValueError:
        return top


def _run_lines(lines: list[str], here: Path, cfg, fail: str) -> None:
    """Run shell lines in `here` with env WF_MAIN = main tree project folder; first nonzero → Failure."""
    env = {**os.environ, "WF_MAIN": str(cfg.root)}
    for line in lines:
        print(f"$ {line}", flush=True)
        rc = subprocess.run(line, shell=True, cwd=here, env=env).returncode
        if rc:
            raise Failure(fail.format(line=line, rc=rc))


def cmd_setup(args) -> int:
    """Run workflow.toml worktree_setup in this lane worktree (cwd = its project folder, env WF_MAIN)."""
    start = Path(args.project or Path.cwd()).resolve()
    wt = config.linked_worktree(start)
    if not wt:
        raise Failure("setup runs inside a linked git worktree (lane worktree)")
    cfg = config.load_at(start)
    if not cfg.worktree_setup:
        print(f"no worktree_setup in {config.NAME}: nothing to do")
        return 0
    _run_lines(cfg.worktree_setup, _here(start, cfg), cfg,
               "worktree_setup '{line}' failed (exit {rc}): later commands skipped")
    n = len(cfg.worktree_setup)
    print(f"worktree_setup: {n} command{'s' * (n != 1)} ok in {os.path.relpath(wt[0], cfg.root)}")
    return 0


def cmd_start(args) -> int:
    """Worker setup in one call (main tree): worktree + branch (clean check), worktree_setup, status progress,
    then wf ctx and a ready verify && wf finish line."""
    start = Path(args.project or Path.cwd()).resolve()
    if config.linked_worktree(start):
        raise Failure("start runs in the main tree (it creates the worktree)")
    p = load_project(args)
    id = p.resolve(args.id)
    main = Path(git_run(start, "rev-parse", "--show-toplevel").stdout.strip() or p.cfg.root)
    master = config.git_branch(main / ".git") or "master"
    wt = (Path.cwd() / args.worktree).resolve()
    shown = p.cfg.rel(wt)
    b = args.branch

    def git_ok(cwd, *a):
        r = git_run(cwd, *a)
        if r.returncode:
            raise Failure(f"git {a[0]} failed: {(r.stderr.strip() or r.stdout.strip() or 'git error').splitlines()[-1]}")
        return r.stdout

    has_branch = not git_run(main, "rev-parse", "--verify", "-q", f"refs/heads/{b}").returncode
    extra = []
    if not wt.exists():
        if has_branch:
            git_ok(main, "worktree", "add", "-q", str(wt), b)
            how = f"new, existing branch {b}: earlier WIP, read the notes"
        else:
            git_ok(main, "worktree", "add", "-q", str(wt), "-b", b, master)
            how = f"new, branch {b} from {master}"
    else:
        dirty = git_run(wt, "status", "--porcelain").stdout.rstrip("\n")
        cur = config.git_branch(Path(git_run(wt, "rev-parse", "--absolute-git-dir").stdout.strip()))
        if dirty and not args.recovery:
            raise Failure(f"worktree {shown} has uncommitted changes: "
                          + " ".join(l.strip() for l in dirty.splitlines())
                          + " (hand back, or --recovery when a dead worker left them)")
        if dirty and cur != b:
            raise Failure(f"worktree {shown} has uncommitted changes on another branch ({cur or 'detached'}), "
                          f"not {b}: hand back")
        if cur == b:
            how = f"on {b}"
        elif has_branch:
            git_ok(wt, "switch", "-q", b)
            how = f"switched to existing branch {b}: earlier WIP, read the notes"
        else:
            git_ok(wt, "switch", "-q", "-c", b, master)
            how = f"switched to new branch {b} from {master}"
        if args.recovery:
            log = git_run(wt, "log", "--oneline", f"{master}..HEAD").stdout.strip()
            extra = [f"recovery: uncommitted:\n{dirty}" if dirty else "recovery: uncommitted: none",
                     f"recovery: commits {master}..HEAD:" + (f"\n{log}" if log else " none")]
    print(f"worktree: {shown} ({how})", *extra, sep="\n", flush=True)
    try:
        here = wt / p.cfg.root.relative_to(main)
    except ValueError:
        here = wt
    cmd_setup(argparse.Namespace(project=str(here)))
    sys.stdout.flush()
    with project_lock(p.cfg.root), contextlib.redirect_stdout(io.StringIO()):
        cmd_status(argparse.Namespace(project=args.project, id=id, kind="progress", value=[b], dry_run=False,
                                      clear_stale=False))
    print(flush=True)
    cmd_ctx(argparse.Namespace(project=args.project, target=id))
    steps = [f"cd {here}", *(f"({v})" for v in p.cfg.verify),
             f'python3 {HERE / "wf.py"} finish {id} -m "<entry>" --commit "<msg + footer>" <paths>']
    print("\nFinish (after the work; fill in the quoted parts and the paths):\n  " + " && ".join(steps))
    return 0


def cmd_gate(args) -> int:
    """Run workflow.toml quick_gate (fast regression check) in this tree's project folder, env WF_MAIN."""
    start = Path(args.project or Path.cwd()).resolve()
    cfg = config.load_at(start)
    if not cfg.quick_gate:
        print(f"no quick_gate in {config.NAME}: nothing to do")
        return 0
    _run_lines(cfg.quick_gate, _here(start, cfg), cfg,
               "quick_gate '{line}' red (exit {rc}): fix it before wf done; later commands skipped" + GATE_RED_HELP)
    n = len(cfg.quick_gate)
    print(f"quick_gate: {n} command{'s' * (n != 1)} green")
    return 0


# ------------------------------------------------------------------ orchestrator

GO_ON = ("done", "done+gate-red", "sliced")     # outcomes after which the lane picks its next task


def orch_main(args) -> tuple[Path, Project]:
    """(main tree, project) for wf orch; refuses a linked worktree."""
    start = Path(args.project or Path.cwd()).resolve()
    if config.linked_worktree(start):
        raise Failure("orch runs in the main tree (the orchestrator's)")
    p = load_project(args)
    main = Path(git_run(start, "rev-parse", "--show-toplevel").stdout.strip() or p.cfg.root)
    return main, p


def orch_record(cfg: config.Config, id: str) -> dict:
    try:
        r = json.loads((cfg.root / ".wf" / "orch" / f"{id}.json").read_text())
    except (OSError, ValueError):
        return {}
    return r if isinstance(r, dict) else {}


def live_session_cwds() -> list[Path]:
    """cwd of every live Claude Code session (~/.claude/sessions/*.json)."""
    out = []
    for f in (claude_projects().parent / "sessions").glob("*.json"):
        try:
            s = json.loads(f.read_text())
            os.kill(int(s["pid"]), 0)
            out.append(Path(s["cwd"]).resolve())
        except (OSError, ValueError, KeyError, TypeError):
            continue
    return out


def worktree_free(path: Path, branch: str, busy: set[Path], cwds: list[Path]) -> bool:
    """No live session in it, no other picked worker on it, and clean on a detached HEAD (or on branch = recovery)."""
    if path in busy:
        return False
    if not path.exists():
        return True
    if any(c == path or path in c.parents for c in cwds):
        return False
    cur = config.git_branch(Path(git_run(path, "rev-parse", "--absolute-git-dir").stdout.strip() or path / ".git"))
    if cur == branch:
        return True
    return not cur and not git_run(path, "status", "--porcelain").stdout.strip()


def lane_worktree(main: Path, p: Project, lane: str, id: str) -> Path:
    """First free main/.worktrees/<lane>[-n] for branch <lane>/<id> (worktree_free; other picked workers' trees busy)."""
    cfg, busy = p.cfg, set()
    for f in (cfg.root / ".wf" / "orch").glob("*.json"):
        r = orch_record(cfg, f.stem)
        other = p.doc.item(f.stem) if f.stem in p.doc.ids() else None
        if f.stem != id and r.get("worktree") and other and (other.status or "").startswith("in progress"):
            busy.add(Path(r["worktree"]))
    cwds = live_session_cwds()
    n = 1
    while not worktree_free(wt := main / ".worktrees" / (lane if n == 1 else f"{lane}-{n}"), f"{lane}/{id}", busy, cwds):
        n += 1
    return wt


CLOUD = "cloud"   # virtual lane: wf cloud send instead of a local worker (spec cloud-lane §4.6)


def cloud_pick(main: Path, p: Project, id: str | None) -> int:
    """wf orch pick cloud: ledger check, first fitting task across the lanes (cloud.pick_key) -> wf cloud send."""
    import wf_cloud
    from wflib import cloud
    cfg = p.cfg
    if not cfg.cloud:
        print(f"stop lane {CLOUD}: none fit (project not opted in: workflow.toml cloud = true)")
        return 0
    with wf_cloud.locked(wf_cloud.state_dir()) as led:
        run, cap, bal, res = cloud.running(led), led["max_parallel"], cloud.balance(led), led["reserve_per_task"]
    if run >= cap:
        print(f"stop lane {CLOUD}: max parallel ({run} running >= max_parallel {cap})")
        return 0
    if bal < res:
        print(f"stop lane {CLOUD}: ledger (balance ${bal:.2f} < reserve ${res:.2f})")
        return 0
    if id:
        item = p.doc.item(p.resolve(id))
        if why := cloud.fit(item, cfg):
            print(f"stop lane {CLOUD}: none fit ({item.id}: {why})")
            return 0
    else:
        ready, seen = runner_ids(p), []
        for l in cfg.lanes:
            seen += [i for i in lanes.ranked(p.doc, p.archived, cfg.lanes, cfg.slice_above, l.name)
                     if i not in seen and i.id in ready and not (i.status or "").startswith("in progress")]
        fits = sorted((i for i in seen if cloud.fit(i, cfg) is None), key=cloud.pick_key)
        if not fits:
            print(f"stop lane {CLOUD}: none fit (wf cloud fit rules: wf set ID --cloud yes skips the regex list, opus only)")
            return 0
        item = fits[0]
    buf = io.StringIO()
    with contextlib.redirect_stdout(buf):
        code = wf_cloud.main(["send", item.id, "--project", str(cfg.root)])
    sent = buf.getvalue().strip()
    if code == 3:
        print(f"stop lane {CLOUD}: ledger (send refused, see above)")
        return 0
    if code:
        if sent:
            print(sent)
        raise Failure(f"wf cloud send {item.id} failed (exit {code}): lane {CLOUD} stops, tell the owner")
    rec = json.loads(wf_cloud.record_path(cfg, item.id).read_text())
    (wf_folder(cfg, "orch") / f"{item.id}.json").write_text(json.dumps(
        {"id": item.id, "lane": CLOUD, "task_lane": rec["lane"], "model": item.model, "effort": item.effort,
         "sid": rec["sid"], "branch": f"{rec['lane']}/{item.id}", "at": int(datetime.datetime.now().timestamp())}) + "\n")
    print(f"pick: {item.id} (lane {CLOUD}, model {item.model}, effort {item.effort or '-'}) · {sent.splitlines()[-1]}"
          f" · claimed (in progress: cloud:{rec['sid']})")
    print(f"agent: none (cloud session). On each wake (>= 10 min apart): wf cloud pull --all; per ended task "
          f"'<id>: <state> …' → wf orch post <id> {CLOUD} --result <state> [--commit <sha>]")
    return 0


def orch_pick(main: Path, p: Project, lane: str, id: str | None = None, recovery: str | None = None) -> int:
    cfg = p.cfg
    stop = cfg.root / "out" / "wf-batch.stop"
    if stop.exists() and not recovery:
        print(f"stop: {cfg.rel(stop)} exists: spawn nothing (let running workers finish)")
        return 0
    if lane == CLOUD:
        return cloud_pick(main, p, id)
    if id:
        id = p.resolve(id)
    else:
        ready = runner_ids(p)
        order = [i for i in lanes.ranked(p.doc, p.archived, cfg.lanes, cfg.slice_above, lane)
                 if i.id in ready and not (i.status or "").startswith("in progress")]
        if not order:
            print(f"none: lane {lane} has no runner-ready task (wf list --runner --lane {lane}; wf lanes)")
            return 0
        id = order[0].id
    item = p.doc.item(id)
    branch = f"{lane}/{id}"
    wt = lane_worktree(main, p, lane, id)
    with project_lock(cfg.root), contextlib.redirect_stdout(io.StringIO()):
        cmd_status(argparse.Namespace(project=str(cfg.root), id=id, kind="progress", value=["worker"],
                                      dry_run=False, clear_stale=False))
    model = item.model
    (wf_folder(cfg, "orch") / f"{id}.json").write_text(json.dumps(
        {"id": id, "lane": lane, "model": model, "effort": item.effort, "worktree": str(wt), "branch": branch,
         "at": int(datetime.datetime.now().timestamp())}) + "\n")
    kind = ", slice job: the worker only slices" if lanes.is_slice_job(item, cfg.slice_above) else ""
    print(f"pick: {id} (lane {lane}, model {model}, effort {item.effort or '-'}{kind}) · claimed (in progress: worker)")
    print(f"agent: subagent_type wf-worker, model {model}, no isolation; prompt:")
    print(f"Task: {id}  Lane: {lane}  Model: {model}\nMain tree: {main}  Worktree: {wt}  Branch: {branch}"
          + (f"\nRecovery: {recovery}" if recovery else "") + "\nFinal message: the 4 report lines only.")
    return 0


def cost_line(root: Path, agent: str, task: str, outcome: str, effort: str | None, lane: str, dur: int | None) -> str:
    """Append one usage line for a worker to <root>/out/wf-cost.log; returns it."""
    path = usage_transcripts(argparse.Namespace(agent=agent, session=None))[0][1]
    now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    line = usage.log_line(now, root.name, task, effort or "-", outcome, path.stem.removeprefix("agent-"),
                          usage.parse(read(path)), lane=lane, dur=dur)
    (root / "out").mkdir(exist_ok=True)
    with open(root / "out" / "wf-cost.log", "a") as f:
        f.write(line + "\n")
    return line


def archived_meta(cfg: config.Config, id: str) -> tuple[str | None, str | None]:
    """(model, effort) of a task already archived: its block in TASKS.md just before the commit that removed it."""
    rel = str(cfg.tasks.relative_to(cfg.root))
    r = git_run(cfg.root, "log", "-n1", "--format=%H", f"-S**{id}**", "--", rel)
    if r.returncode or not r.stdout.strip():
        return None, None
    old = git_run(cfg.root, "show", f"{r.stdout.strip()}^:{rel}")
    try:
        it = tasks.parse(old.stdout).item(id) if old.returncode == 0 and id in tasks.parse(old.stdout).ids() else None
    except Exception:
        it = None
    return (it.model, it.effort) if it else (None, None)


def orch_post(main: Path, p: Project, args) -> int:
    cfg, id, lane = p.cfg, args.id, args.lane
    rec = orch_record(cfg, id)
    wt = Path(rec.get("worktree") or main / ".worktrees" / lane)
    item = p.doc.item(id) if id in p.doc.ids() else None
    if item is None and id not in p.archived:
        raise Failure(tasks.unknown_id(id, p.doc.ids()))
    words = (args.result or "").split()
    outcome = words[0] if words else ("done" if id in p.archived else "no-report")
    if outcome == "done" and item is not None and id not in p.archived and tasks.open_slices(p.doc, id):
        outcome = "sliced"      # slice job: worker said done but the task is open with slices
    master = config.git_branch(main / ".git") or "master"
    files = [str(f.relative_to(main)) for f in (cfg.tasks, cfg.archive)]
    problems, out = [], []
    with project_lock(cfg.root):
        if outcome.startswith("done"):
            if id not in p.archived:
                problems.append(f"no archive line for {id}")
            if (wt / ".git").exists():
                dirty = git_run(wt, "status", "--porcelain").stdout.strip()
                if dirty:
                    problems.append(f"worktree {wt} dirty: " + " ".join(l.strip() for l in dirty.splitlines()))
                elif git_run(wt, "merge-base", "--is-ancestor", "HEAD", master).returncode:
                    buf = io.StringIO()
                    try:
                        with contextlib.redirect_stdout(buf):
                            cmd_merge(argparse.Namespace(project=str(wt), m=None, no_push=args.no_push))
                        out.append(f"merged worktree HEAD: {buf.getvalue().strip().splitlines()[-1]}")
                    except Failure as e:
                        problems.append(f"wf merge in {wt}: {e}")
            branch = rec.get("branch") or f"{lane}/{id}"
            if not git_run(main, "rev-parse", "--verify", "-q", f"refs/heads/{branch}").returncode:
                problems.append(f"branch {branch} still there")
            errors = checks.check(config.load(cfg.root))[0]
            if errors:
                problems.append(f"wf check: {len(errors)} errors: {errors[0]}")
        elif git_run(main, "status", "--porcelain", "--", *files).stdout.strip():
            r = git_run(main, "commit", "-q", "-m", f"{id} {outcome} (orchestrator)", "--", *files)
            out.append("committed leftover " + " ".join(files) if not r.returncode
                       else f"leftover commit failed: {(r.stderr.strip() or 'git error').splitlines()[-1]}")
    raised = bool(item and rec.get("model") and not outcome.startswith("done")
                  and tasks.MODELS.index(item.model) > tasks.MODELS.index(rec["model"]))
    final = "post-check-red" if problems else ("model-raised" if raised else outcome)
    am, ae = (None, None) if item or (rec.get("model") and rec.get("effort")) else archived_meta(cfg, id)
    model = rec.get("model") or (item.model if item else am) or "?"
    dur = args.duration if args.duration else (   # None/0 (orchestrator lacked duration_ms) → since the pick
        int(datetime.datetime.now().timestamp()) - rec["at"] if isinstance(rec.get("at"), int) else None)
    commit = args.commit or (git_run(main, "rev-parse", "--short", master).stdout.strip()
                             if outcome.startswith("done") else "-")
    now = datetime.datetime.now().isoformat(timespec="seconds")
    (cfg.root / "out").mkdir(exist_ok=True)
    with open(cfg.root / "out" / "wf-orch.log", "a") as f:
        f.write(f"{now} {lane} {model} {id} {final} {commit} {fmt_dur(dur) if dur is not None else '-'}"
                + (f" ({'; '.join(problems)})" if problems else "") + "\n")
    if args.agent:
        try:
            out.append("cost: " + cost_line(cfg.root, args.agent, id, final, rec.get("effort") or (item and item.effort) or ae,
                                            lane, dur))
        except Failure as e:
            out.append(f"cost: not logged ({e})")
    if final != "post-check-red":   # kept: the re-post after the fix still knows the pick time
        (cfg.root / ".wf" / "orch" / f"{id}.json").unlink(missing_ok=True)
    print(f"post: {id} {final}" + "".join(f"\n  {l}" for l in problems + out))
    if outcome == "done+gate-red" and len(words) >= 3:
        q = load_project(args)
        fix = q.doc.item(words[2]) if words[2] in q.doc.ids() else None
        if fix and not fix.runner_ready:
            print(f"fix {fix.id} not runner-ready: add its Done/Model (wf set {fix.id} --done … --model …), "
                  f"then wf orch pick {lane} --id {fix.id}")
            return 0
    if final not in GO_ON and final != "model-raised":
        print(f"stop lane {lane}: {final} → tell the owner"
              + (f" (crash/no report: one fresh worker: wf orch pick {lane} --id {id} --recovery \"<why>\", then stop)"
                 if final == "no-report" else ""))
        return 0
    if args.no_pick:
        return 0
    print()
    return orch_pick(main, load_project(args), lane)


def cmd_orch(args) -> int:
    main, p = orch_main(args)
    if args.lane != CLOUD or CLOUD in lane_names(p.cfg):
        check_lane(p.cfg, args.lane)
    if args.action == "pick":
        return orch_pick(main, p, args.lane, args.id, args.recovery)
    return orch_post(main, p, args)


def change(args, action) -> int:
    """Run one edit on one item, save, print its new header."""
    p = load_project(args, write=True)
    note = action(p)
    p.save(args.dry_run)
    if not args.dry_run:
        print(note if note else p.doc.item(args.id).header())
    return 0


def cmd_prio(args) -> int:
    return change(args, lambda p: tasks.set_prio(p.doc, args.id, args.prio))


def cmd_move(args) -> int:
    targets = [t for t in (args.section, args.before, args.after) if t]
    if len(targets) != 1:
        raise Usage("move: give a section, or --before ID, or --after ID")
    if args.section:
        return change(args, lambda p: tasks.move_to(p.doc, args.id, args.section))
    return change(args, lambda p: tasks.move_rel(p.doc, args.id, args.before or args.after,
                                                  before=bool(args.before), force=args.force))


def clear_stale(args) -> int:
    p = load_project(args, write=True)
    items = stale(p)
    for i in items:
        tasks.set_status(p.doc, i.id, None)
    p.save(args.dry_run)
    if not args.dry_run:
        unclaim(p.cfg, [i.id for i in items])
    for i in items:
        print(f"cleared {i.id}")
    return 0


def cmd_status(args) -> int:
    if args.clear_stale:
        if args.id or args.kind or args.value:
            raise Usage("status: --clear-stale takes no id/kind/value")
        return clear_stale(args)
    if not args.id or not args.kind:
        raise Usage("status: ID and progress NOTE|blocked A-ID|clear (or --clear-stale)")
    if args.kind == "clear":
        if args.value:
            raise Usage("status: clear takes no value")
        status = None
    elif not args.value:
        raise Usage("status: progress needs a note, blocked needs an a-id")
    elif args.kind == "progress":
        status = "in progress: " + " ".join(args.value)
    else:
        status = f"blocked: [[{args.value[0]}]]"
    code = change(args, lambda p: tasks.set_status(p.doc, args.id, status))
    if not args.dry_run:
        proj = load_project(args)
        cfg = proj.cfg
        if args.kind == "progress":
            claim(cfg, args.id, lanes.lane_of(proj.doc.item(args.id), cfg.lanes, cfg.slice_above))
        else:
            unclaim(cfg, [args.id])
    return code


def cmd_set(args) -> int:
    if args.interactive is not None:
        old_spelling("--interactive", "--sessions owner")
        if args.sessions is None:
            args.sessions = "owner" if args.interactive == "yes" else ""
    fields = dict(
        title=args.title, effort=args.effort,
        after=None if args.after is None else split_list(args.after),
        refs=None if args.ref is None else split_list(args.ref), model=args.model, sessions=args.sessions,
        done=args.done, cloud=args.cloud)
    if args.model not in (None, "", *tasks.MODELS):
        raise Usage(f"set: --model {args.model} (want {', '.join(tasks.MODELS)}, or \"\" to remove)")
    if args.sessions not in (None, "", *tasks.SESSIONS):
        raise Usage(f"set: --sessions {args.sessions} (want {', '.join(tasks.SESSIONS)}, or \"\" to remove)")
    if args.cloud not in (None, "", *tasks.CLOUDS):
        raise Usage(f"set: --cloud {args.cloud} (want {', '.join(tasks.CLOUDS)}, or \"\" to remove)")
    if all(v is None for v in fields.values()):
        raise Usage("set: nothing to set (--title --effort --after --ref --model --sessions --cloud --done)")
    return change(args, lambda p: tasks.set_fields(p.doc, args.id, **fields))


def cmd_rename(args) -> int:
    def action(p):
        n = tasks.rename(p.doc, args.id, args.new, p.archived)
        return f"renamed: {args.id} → {args.new} ({n} link{'' if n == 1 else 's'})"
    return change(args, action)


def cmd_note(args) -> int:
    return change(args, lambda p: tasks.add_note(p.doc, args.id, " ".join(args.line.split())))


def cmd_body(args) -> int:
    if args.text:
        raise Failure("body text goes on stdin (wf body ID <<'EOF' … EOF), not as an argument")
    lines = stdin_lines()
    return change(args, lambda p: tasks.set_body(p.doc, args.id, lines))


def cmd_tick(args) -> int:
    return change(args, lambda p: "ticked: " + tasks.tick(p.doc, args.id, args.which))


# ------------------------------------------------------------------ other commands

def wf_version() -> str:
    try:
        out = subprocess.run(["git", "-C", str(HERE), "rev-parse", "--short=7", "HEAD"],
                             capture_output=True, text=True, timeout=10)
        return out.stdout.strip() if out.returncode == 0 and out.stdout.strip() else "0000000"
    except (OSError, subprocess.SubprocessError):
        return "0000000"


def cmd_report(args) -> int:
    text = " ".join(args.text.split())
    if not text:
        raise Usage("report: say what happened")
    start = Path(args.project) if args.project else Path.cwd()
    try:
        project = config.find_root(start).name
    except config.ConfigError:
        project = start.resolve().name
    cmd = f" (cmd: {' '.join(args.cmd.split())})" if args.cmd else ""
    line = f"- {datetime.date.today().isoformat()} {project} {args.kind}: {text}{cmd} @{wf_version()}\n"
    fd = os.open(inbox_path(), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)
    try:
        os.write(fd, line.encode("utf-8"))
    finally:
        os.close(fd)
    print("reported (workflow inbox); carry on")
    return 0


def cmd_init(args) -> int:
    root = (Path(args.project) if args.project else Path.cwd()).resolve()
    if (root / config.NAME).exists():
        raise Failure(f"{root}/{config.NAME} exists already")
    templates = HERE / "templates"
    for target, source in ((config.NAME, "workflow.toml"), ("TASKS.md", "TASKS.md"),
                           ("tasks/archive.md", "archive.md"), ("CLAUDE.md", "CLAUDE.md")):
        path = root / target
        if path.exists():
            print(f"kept {target} (exists" + ("; old format → wf migrate)" if target == "TASKS.md" else ")"))
            continue
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(read(templates / source).replace("{name}", root.name), encoding="utf-8")
        print(f"wrote {target}")
    return 0


def cmd_migrate(args) -> int:
    from wflib import migrate
    p = load_project(args)
    cfg = p.cfg
    new, report = migrate.migrate(p.tasks_text, taken=p.archived)
    bump = cfg.format < config.FORMAT
    if new == p.tasks_text and not bump:
        print("nothing to migrate")
        return 0
    name = cfg.rel(cfg.tasks)
    sys.stdout.writelines(difflib.unified_diff(
        p.tasks_text.replace("\r\n", "\n").splitlines(keepends=True),
        new.replace("\r\n", "\n").splitlines(keepends=True), name, f"{name} (new)"))
    if report.ids:
        print("\nids:")
        for title, id in report.ids.items():
            print(f"  {id}  {title}")
    if report.notes:
        print("\nnotes:")
        for note in report.notes:
            print(f"  {note}")
    errors = checks.check(cfg, tasks_text=new, slow=False)[0]
    for e in errors:
        print(f"ERROR: {e}")
    print(f"check after migrate: {len(errors)} errors")
    if not args.write:
        print("dry run: nothing written (wf migrate --write)")
        return 0
    wrote = []
    if new != p.tasks_text:
        write_if_unchanged(cfg.tasks, new, p.tasks_stamp)
        wrote.append(name)
    if bump:
        toml = cfg.root / config.NAME
        text = read(toml)
        changed = re.sub(r"(?m)^format(\s*)=(\s*)\d+", rf"format\g<1>=\g<2>{config.FORMAT}", text, count=1)
        write_if_unchanged(toml, changed, stamp(toml))
        wrote.append(f"{config.NAME} (format = {config.FORMAT})")
    print("wrote " + ", ".join(wrote))
    return 0


# ------------------------------------------------------------------ main

def parser() -> argparse.ArgumentParser:
    ap = argparse.ArgumentParser(prog="wf", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", metavar="DIR", help="project folder (default: found from the working directory)")
    sub = ap.add_subparsers(dest="command", metavar="COMMAND")
    sections = list(tasks.SECTIONS)

    def cmd(name, func, help, write=False):
        sp = sub.add_parser(name, help=help, description=help)
        sp.set_defaults(func=func, locks=write)
        if write:
            sp.add_argument("--dry-run", action="store_true", help="print the diff, write nothing")
        return sp

    sp = cmd("next", cmd_next, "cold start: awaiting, needs human, plans in flight, next task with its refs")
    sp.add_argument("--brief", "-b", action="store_true", help="the task only")
    sp.add_argument("--lane", help="lane name (wf lanes); none = all lanes")
    sp.add_argument("--as", dest="as_", choices=tasks.MODELS,
                    help="your model: takes tasks with Model ≤ it (default haiku)")
    sp.add_argument("--owner", action="store_true", help="the owner is present: Sessions: owner tasks pickable")

    sp = cmd("areas", cmd_areas, "area notes: anchors missing, commits since Checked (stale = missing or "
             "≥ area_stale_commits); no NAME → also uncovered: folders the diff since master touches outside "
             "every Paths (area_ignore skipped); --mark NAME stamps HEAD", write=True)
    sp.add_argument("name", nargs="?", help="one area only")
    sp.add_argument("--mark", metavar="NAME", help="set the area's Checked to HEAD (after a refresh)")
    sp = cmd("lanes", cmd_lanes, "lanes: pickable/waiting per lane, the session of each "
             "(--lane/--as registers yours; neither lane = all)")
    sp.add_argument("--lane", help="your lane (wf lanes lists them)")
    sp.add_argument("--as", dest="as_", choices=tasks.MODELS, help="your model (default haiku)")
    sp.add_argument("--unregister", action="store_true", help="drop this session's lane record (orchestrators hold none)")
    sp.add_argument("--wait", type=float, metavar="SECS",
                    help="block until any lane has a pickable task (exit 0, prints the lanes line) or SECS pass "
                         "(exit 1, prints the lanes line); out/wf-batch.stop exists (wf batch --stop) → exit 2 at once; "
                         "polls every 30 s (env WF_LANES_POLL)")
    sp = cmd("list", cmd_list, "one line per item: id, priority, effort, status, model, lane, title")
    sp.add_argument("-s", "--section", choices=[*sections, "all"], default="pending")
    sp.add_argument("-p", "--prio", type=int, choices=range(4), help="this priority or higher")
    sp.add_argument("--ready", action="store_true", help="pickable now")
    sp.add_argument("--runner", action="store_true",
                    help="--ready + Done line, no Sessions: owner, Done not about owner/confirming, no open slices")
    sp.add_argument("--blocked", action="store_true")
    sp.add_argument("--progress", action="store_true")
    sp.add_argument("--stale", action="store_true", help="in progress with no live claim (dead or no holder)")
    sp.add_argument("--model", choices=tasks.MODELS, help="tasks with this Model line (none = opus)")
    sp.add_argument("--lane", help="tasks of this lane (by effort); with --runner: in pick order")
    sp.add_argument("--ref", metavar="PATH[#ANCHOR]")
    sp.add_argument("-n", type=int, metavar="N")

    sp = cmd("show", cmd_show, "the raw item(s)")
    sp.add_argument("ids", nargs="+", metavar="ID")

    sp = cmd("ctx", cmd_ctx, "item with refs resolved, its relations and the areas it names; or a doc section and its tasks")
    sp.add_argument("target", metavar="ID|PATH#ANCHOR")

    sp = cmd("search", cmd_search, "ranked search over tasks, archive and docs")
    sp.add_argument("words", nargs="+")
    sp.add_argument("--tasks", action="store_true")
    sp.add_argument("--archive", action="store_true")
    sp.add_argument("--docs", action="store_true")
    sp.add_argument("-n", type=int, default=15, metavar="N")

    sp = cmd("log", cmd_log, "newest archive lines")
    sp.add_argument("words", nargs="*")
    sp.add_argument("-n", type=int, default=10, metavar="N")

    sp = cmd("usage", cmd_usage, "tokens and API-price $ per agent of a session, from Claude Code transcripts")
    sp.add_argument("--session", metavar="ID", help="session id or prefix (default: this session, else newest here)")
    sp.add_argument("--agent", metavar="ID", help="one subagent only (agent id from its completion notice)")
    sp.add_argument("--since", metavar="TIME", help="ISO UTC time, or 90m / 2h / 1d ago")
    sp.add_argument("--log", nargs=2, metavar=("TASK", "OUTCOME"),
                    help="with --agent: append one line to <project>/out/wf-cost.log (orchestrator, per worker)")
    sp.add_argument("--effort", choices=tasks.EFFORTS, metavar="|".join(tasks.EFFORTS),
                    help="the task's estimate (not reasoning effort), for --log")
    sp.add_argument("--duration", type=int, metavar="S", help="agent wall time in seconds (duration_ms / 1000), for --log")
    sp.add_argument("--lane", metavar="L", help="lane of the logged worker, for --log (default: its model)")
    sp.add_argument("--explore", action="store_true",
                    help="exploring cost per subagent: pct billed input exploring / before the first edit, "
                    "result tokens per tool, files read by >= 2 agents (same --session / --since)")
    sp.add_argument("--report", action="store_true",
                    help="per lane and effort: n, done, $ (median, total, per done), turns, duration, from every project's log")

    cmd("projects", cmd_projects, "every wf project: counts, errors, next task")
    cmd("check", cmd_check, "validate ids, links, refs, order")

    sp = cmd("add", cmd_add, "new item; `add -` reads a whole item block from stdin", write=True)
    sp.add_argument("title", metavar='"Title. Goal."|-')
    sp.add_argument("-p", "--prio", type=int, choices=range(4))
    sp.add_argument("-e", "--effort", metavar="|".join(tasks.EFFORTS))
    sp.add_argument("-s", "--section", choices=sections)
    sp.add_argument("--id", help="the id (default: from the title, or <parent>-N with --parent); "
                    "a leading 'ID: ' in the text works too")
    sp.add_argument("--after", metavar="ID,…")
    sp.add_argument("--ref", metavar="REF,…")
    sp.add_argument("--parent", metavar="ID", help="add as the next slice of ID, After: the previous one")
    sp.add_argument("--interactive", action="store_true", help=argparse.SUPPRESS)
    sp.add_argument("--model", choices=tasks.MODELS, help="Model line (default: none = opus)")
    sp.add_argument("--done", metavar="TEXT", help="Done line (makes the task runner-pickable)")
    sp.add_argument("--cloud", choices=tasks.CLOUDS, help="Cloud line: yes = cloud lane may take it (opus only), no = never")
    sp.add_argument("--sessions", choices=tasks.SESSIONS,
                    help="Sessions line: solo = no other live session, owner = owner present (default parallel)")
    sp.add_argument("-b", "--body", action="store_true", help="read body lines from stdin")

    sp = cmd("done", cmd_done, "finish task(s): remove, archive line, print verify + checklist", write=True)
    sp.add_argument("ids", nargs="+", metavar="ID")
    sp.add_argument("-m", metavar="ENTRY", help="archive entry, ≤2 lines")

    sp = cmd("prio", cmd_prio, "set priority, reposition", write=True)
    sp.add_argument("id")
    sp.add_argument("prio", type=int, choices=range(4))

    sp = cmd("move", cmd_move, "move to a section, or before/after another item", write=True)
    sp.add_argument("id")
    sp.add_argument("section", nargs="?", choices=sections)
    sp.add_argument("--before", metavar="ID")
    sp.add_argument("--after", metavar="ID")
    sp.add_argument("--force", action="store_true", help="allow breaking priority order")

    sp = cmd("status", cmd_status, "progress NOTE | blocked A-ID | clear", write=True)
    sp.add_argument("id", nargs="?")
    sp.add_argument("kind", nargs="?", choices=["progress", "blocked", "clear"])
    sp.add_argument("value", nargs="*")
    sp.add_argument("--clear-stale", action="store_true", help="clear in progress of tasks with no live claim")

    sp = cmd("set", cmd_set, "change header fields, Done:, Model:, After:, Ref:", write=True)
    sp.add_argument("id")
    sp.add_argument("--title", help="new title, goal kept; 'Title. Goal.' or a question replaces the text")
    sp.add_argument("--effort")
    sp.add_argument("--after", metavar="ID,…", help='"" removes the line')
    sp.add_argument("--ref", metavar="REF,…", help='"" removes the line')
    sp.add_argument("--interactive", choices=["yes", "no"], help=argparse.SUPPRESS)
    sp.add_argument("--sessions", metavar="|".join(tasks.SESSIONS), help='Sessions line; "" removes it (= parallel)')
    sp.add_argument("--model", metavar="|".join(tasks.MODELS), help='Model line; "" removes it (= opus)')
    sp.add_argument("--cloud", metavar="|".join(tasks.CLOUDS), help='Cloud line (yes: skip the fit regex list, opus only; no: never cloud); "" removes it')
    sp.add_argument("--done", metavar="TEXT", help='Done line (makes it runner-pickable); "" removes it')

    sp = cmd("rename", cmd_rename, "change an open item's id and every [[link]] to it", write=True)
    sp.add_argument("id")
    sp.add_argument("new", metavar="NEW")

    sp = cmd("note", cmd_note, "append one line to the body", write=True)
    sp.add_argument("id")
    sp.add_argument("line")

    sp = cmd("body", cmd_body, "replace the body with stdin; Model:, Sessions:, After:, Ref: lines kept", write=True)
    sp.formatter_class = argparse.RawDescriptionHelpFormatter
    sp.epilog = "example (body text goes on stdin, not as an argument):\n  wf body ID <<'EOF'\n  - Steps: …\n  - Done: …\n  EOF"
    sp.add_argument("id")
    sp.add_argument("text", nargs="*", help=argparse.SUPPRESS)

    sp = cmd("tick", cmd_tick, "check a `- [ ]` box by number or text", write=True)
    sp.add_argument("id")
    sp.add_argument("which", metavar="N|TEXT")
    sp = cmd("merge", cmd_merge, "in a lane worktree: rebase, ff-merge into master, commit TASKS/archive, "
             "detach, push home (under the project lock)")
    sp.set_defaults(locks=True)
    sp.add_argument("-m", help="bookkeeping commit message (default '<id> done', id from the branch)")
    sp.add_argument("--no-push", action="store_true", help="skip git push home")

    sp = cmd("finish", cmd_finish, "worker's last step in one call: quick_gate → done → commit PATHS (explicit) → "
             "wf merge (lane worktree; main tree: TASKS/archive go into the commit). Run verify first. "
             "Refuses before done if the gate is red, files outside PATHS are uncommitted, or a PATH is outside "
             "this repo / missing / unchanged; an id already archived resumes (commit + merge). "
             "Prints the done output (notify / checklist) and the merge lines, then 'report: commit <sha> [tool <sha>]' "
             "(lane worktree) = the sha for your report")
    sp.add_argument("id")
    sp.add_argument("-m", required=True, metavar="ENTRY", help="archive entry, ≤2 lines")
    sp.add_argument("--commit", metavar="MSG", help="commit message for PATHS (incl. footer lines)")
    sp.add_argument("paths", nargs="*", metavar="PATH", help="files/folders to commit (relative to cwd)")
    sp.add_argument("--no-push", action="store_true", help="skip git push home")
    sp.add_argument("--tool-commit", metavar="SHA", help="tool-repo sha merged by hand; added to the report line")

    sp = cmd("wip", cmd_wip, "wrap-up in one call (lane worktree): commit PATHS on the branch, note MSG "
             "(state + next step), status clear")
    sp.add_argument("id")
    sp.add_argument("-m", required=True, metavar="NOTE", help="state + next step, one line")
    sp.add_argument("--commit", metavar="MSG", help="commit message (default '<id> WIP')")
    sp.add_argument("paths", nargs="*", metavar="PATH", help="files/folders to commit (relative to cwd)")

    cmd("setup", cmd_setup, "in a lane worktree: run workflow.toml worktree_setup (cwd = worktree, env WF_MAIN = "
        "main tree project folder); provides git-ignored inputs, commands must be idempotent")

    sp = cmd("start", cmd_start, "worker setup in one call, in the main tree: worktree at PATH on BRANCH "
             "(new: from master or the existing branch; existing: must be clean, switched to BRANCH), "
             "worktree_setup, status progress BRANCH, then wf ctx and a ready verify && wf finish line")
    sp.add_argument("id")
    sp.add_argument("--worktree", required=True, metavar="PATH", help="worktree folder (relative to cwd)")
    sp.add_argument("--branch", required=True, metavar="BRANCH")
    sp.add_argument("--recovery", action="store_true",
                    help="a dead worker's WIP: uncommitted changes on BRANCH kept, printed with its commits")

    cmd("gate", cmd_gate, "run workflow.toml quick_gate (fast regression check a worker runs before wf done; "
        "cwd = this tree's project folder, env WF_MAIN = main tree project folder); red = exit 1, nothing = exit 0")

    sp = cmd("report", cmd_report, "report a workflow problem or idea to the workflow inbox")
    sp.add_argument("text")
    sp.add_argument("--kind", choices=["bug", "idea", "friction"], default="bug")
    sp.add_argument("--cmd", metavar="COMMAND")

    cmd("init", cmd_init, "make this folder a wf project")

    sp = cmd("migrate", cmd_migrate, "convert a numbered TASKS.md to the id format (dry run unless --write)")
    sp.add_argument("--write", action="store_true")

    sp = cmd("orch", cmd_orch, "orchestrator, main tree: pick LANE (pick + claim + free worktree + agent prompt) · "
             "post ID LANE (post-check, merge if needed, orch log + cost line, next pick)")
    osub = sp.add_subparsers(dest="action", required=True)
    op = osub.add_parser("pick", help="first runner-ready task of LANE: claim it, choose a free worktree "
                         "(.worktrees/LANE, -2, …), print the wf-worker prompt; 'none:'/'stop:' line = spawn nothing. "
                         "LANE cloud: ledger check, first cloud-fitting task of any lane (opus first) -> wf cloud send; "
                         "'stop lane cloud: ledger|none fit|max parallel'")
    op.add_argument("lane")
    op.add_argument("--id", help="this task instead of the pick (a P0 fix, a recovery)")
    op.add_argument("--recovery", metavar="WHY", help="prompt gets 'Recovery: WHY' (crashed worker, one retry)")
    op = osub.add_parser("post", help="after the worker's report: post-check (done: archive line, branch gone, "
                         "worktree clean and in master, else wf merge; wf check), leftover commit otherwise, "
                         "out/wf-orch.log line, out/wf-cost.log line (--agent), then the next pick or 'stop lane'")
    op.add_argument("id")
    op.add_argument("lane")
    op.add_argument("--result", metavar="LINE", help="the report's result line (default: done if archived, else no-report)")
    op.add_argument("--commit", metavar="SHA", help="the report's commit (default: master's sha when done)")
    op.add_argument("--agent", metavar="ID", help="agent id from the completion notice: cost line (wf usage --log)")
    op.add_argument("--duration", type=int, metavar="S", help="agent duration_ms / 1000 (default or 0: since the pick)")
    op.add_argument("--no-pick", "--no-next", dest="no_pick", action="store_true",
                    help="no next pick, claims nothing (batch end, stop file, cross-project rollout)")
    op.add_argument("--no-push", action="store_true", help="the wf merge it may run skips git push home")

    cmd("res", None, "shared memory/CPU ledger for agent jobs (wf res -h)")
    cmd("cloud", None, "cloud-lane ledger (wf cloud -h)")
    cmd("prep", None, "prep tasks without Done: wf prep [N|all] = wf batch --prep (wf batch -h)")
    cmd("batch", None, "start an unattended batch orchestrator (claude -p) under wf res (wf batch -h)")
    return ap


def main(argv: list[str]) -> int:
    if argv[:1] == ["cloud"]:
        import wf_cloud
        return wf_cloud.main(argv[1:])
    if argv[:1] == ["res"]:
        import wf_res
        return wf_res.main(argv[1:])
    if argv[:1] == ["prep"]:
        import wf_res
        return wf_res.prep_main(argv[1:])
    if argv[:1] == ["batch"]:
        import wf_res
        return wf_res.batch_main(argv[1:])
    ap = parser()
    args = ap.parse_args(argv)
    if not args.command:
        ap.print_usage(sys.stderr)
        return 2
    try:
        if getattr(args, "locks", False):
            root = config.find_root(Path(args.project) if args.project else Path.cwd())
            with project_lock(root):
                return args.func(args)
        return args.func(args)
    except Failure as e:
        print(f"wf: {e}", file=sys.stderr)
        return e.code
    except (tasks.TaskError, config.ConfigError) as e:
        print(f"wf: {e}", file=sys.stderr)
        return 1
    except BrokenPipeError:
        return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))