linear

#!/usr/bin/env python3
"""linear - Task management CLI for AI agent teams.

General-purpose Linear CLI designed for orchestrating work across teams of
AI agents. Each agent can query its work queue, pick up tasks, report progress,
and see the full team board.

Commands:
    setup               Configure Linear connection
    tasks               List/view/board tasks (paginated; --cycle
                        active|next|all|none|<name|id>, --since, --assignee)
    update              Modify one or many issues (status, comment, relations);
                        bulk via multiple ids or --stdin
    create              Create a new issue
    cycles              List / create / update / delete cycles
    projects            List / show / create / archive / delete projects
    milestones          List / create / move / retarget / delete milestones
    labels              List / create / update / delete labels
    users               List assignable users
    agents              List agent members you can --delegate to (auto-detected)
    states              List the team's workflow states

Config: ~/.linear-cli/config.json
"""

from __future__ import annotations

import argparse
import difflib
import json
import mimetypes
import os
import subprocess
import sys
from datetime import date, datetime, timezone
from pathlib import Path
from urllib.request import Request, urlopen
from urllib.error import URLError

__version__ = "0.9.0"

# Sentinel for "flag not supplied" — distinct from None, which means an explicit
# clear (e.g. `--project none`). Lets update pre-resolve a field once and pass
# the result down without re-deriving whether the flag was present.
_UNSET = object()

CONFIG_PATH = Path.home() / ".linear-cli" / "config.json"
LEGACY_CONFIG_PATH = Path.home() / ".agents" / "linear.json"
API_URL = "https://api.linear.app/graphql"

# How long a cached agent roster stays fresh before an auto-refresh. Agent apps
# (Claude, Codex, Kimi, …) are installed/removed rarely, so a periodic refresh
# keeps `--delegate <name>` resolving without a per-call lookup.
AGENTS_TTL_SECONDS = 6 * 3600


# ---------------------------------------------------------------------------
# Config
# ---------------------------------------------------------------------------

def load_config() -> dict:
    if CONFIG_PATH.exists():
        return json.loads(CONFIG_PATH.read_text())
    if LEGACY_CONFIG_PATH.exists():
        cfg = json.loads(LEGACY_CONFIG_PATH.read_text())
        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
        CONFIG_PATH.write_text(json.dumps(cfg, indent=2) + "\n")
        print(f"Migrated config: {LEGACY_CONFIG_PATH} -> {CONFIG_PATH}", file=sys.stderr)
        return cfg
    return {}


def save_config(cfg: dict):
    # Volatile cfg (e.g. --team override) opts out of persistence.
    if cfg.get("__volatile__"):
        return
    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
    CONFIG_PATH.write_text(json.dumps(cfg, indent=2) + "\n")


def get_api_key(cfg: dict) -> str:
    """Resolve API key: config > env > Keychain."""
    key = cfg.get("apiKey") or os.environ.get("LINEAR_API_KEY")
    if key:
        return key
    try:
        result = subprocess.run(
            ["security", "find-generic-password", "-s", "linear-api-key", "-w"],
            capture_output=True, text=True,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except FileNotFoundError:
        pass
    return ""


def get_team_id(cfg: dict) -> str:
    """Resolve team ID: config > env > Keychain."""
    tid = cfg.get("teamId") or os.environ.get("LINEAR_TEAM_ID")
    if tid:
        return tid
    try:
        result = subprocess.run(
            ["security", "find-generic-password", "-s", "linear-team-id", "-w"],
            capture_output=True, text=True,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except FileNotFoundError:
        pass
    return ""


# ---------------------------------------------------------------------------
# GraphQL client
# ---------------------------------------------------------------------------

def gql(api_key: str, query: str, variables: dict | None = None) -> dict:
    payload: dict = {"query": query}
    if variables:
        payload["variables"] = variables
    body = json.dumps(payload).encode()

    req = Request(API_URL, data=body, method="POST")
    req.add_header("Content-Type", "application/json")
    req.add_header("Authorization", api_key)

    try:
        with urlopen(req) as resp:
            return json.loads(resp.read())
    except URLError as e:
        # HTTPError has a response body with actual GraphQL error details
        body = ""
        if hasattr(e, "read"):
            try:
                body = e.read().decode("utf-8", errors="replace")
                parsed = json.loads(body)
                if "errors" in parsed:
                    return parsed
            except (json.JSONDecodeError, Exception):
                pass
        detail = body if body else str(e)
        return {"errors": [{"message": detail}]}


def check_errors(data: dict) -> bool:
    errors = data.get("errors")
    if errors:
        print(f"Error: {errors[0].get('message', 'Unknown error')}", file=sys.stderr)
        return True
    return False


# ---------------------------------------------------------------------------
# State resolution (dynamic, not hardcoded)
# ---------------------------------------------------------------------------

def get_states(api_key: str, team_id: str, cfg: dict) -> dict:
    cached = cfg.get("states")
    if cached:
        return cached

    data = gql(api_key, """
        query($teamId: ID!) {
            workflowStates(filter: { team: { id: { eq: $teamId } } }) {
                nodes { id name type }
            }
        }
    """, {"teamId": team_id})

    if check_errors(data):
        return {}

    states = {}
    for node in data["data"]["workflowStates"]["nodes"]:
        states[node["name"]] = {"id": node["id"], "type": node["type"]}

    cfg["states"] = states
    save_config(cfg)
    return states


def resolve_state_id(states: dict, name: str) -> str | None:
    if name in states:
        return states[name]["id"]
    for k, v in states.items():
        if k.lower() == name.lower():
            return v["id"]
    aliases = {
        "progress": "In Progress",
        "in-progress": "In Progress",
        "wip": "In Progress",
    }
    mapped = aliases.get(name.lower(), "")
    if mapped in states:
        return states[mapped]["id"]
    return None


# ---------------------------------------------------------------------------
# Viewer + user resolution (for auto-assign on create)
# ---------------------------------------------------------------------------

def get_viewer_id(api_key: str, cfg: dict) -> str | None:
    """Return the API-key owner's user ID. Cached in config after first lookup."""
    cached = cfg.get("viewerId")
    if cached:
        return cached

    data = gql(api_key, "{ viewer { id name email } }")
    if check_errors(data):
        return None

    viewer = data.get("data", {}).get("viewer") or {}
    vid = viewer.get("id")
    if vid:
        cfg["viewerId"] = vid
        # Stash email too for setup output; not load-bearing.
        if viewer.get("email"):
            cfg["viewerEmail"] = viewer["email"]
        save_config(cfg)
    return vid


def resolve_team_id_by_key(api_key: str, value: str) -> str | None:
    """Resolve --team to a team ID. Accepts team key (e.g. 'ANT') or UUID."""
    if not value:
        return None
    if len(value) == 36 and value.count("-") == 4:
        return value
    data = gql(api_key, """
        query($key: String!) {
            teams(filter: { key: { eqIgnoreCase: $key } }) {
                nodes { id name key }
            }
        }
    """, {"key": value})
    if check_errors(data):
        return None
    nodes = (data.get("data") or {}).get("teams", {}).get("nodes", [])
    if not nodes:
        print(f"Warning: team '{value}' not found.", file=sys.stderr)
        return None
    return nodes[0]["id"]


def resolve_user_id_by_email(api_key: str, email: str) -> str | None:
    """Look up a user by email address. Returns user ID or None."""
    data = gql(api_key, """
        query($email: String!) {
            users(filter: { email: { eq: $email } }) {
                nodes { id name email }
            }
        }
    """, {"email": email})
    if check_errors(data):
        return None
    nodes = data.get("data", {}).get("users", {}).get("nodes", [])
    if not nodes:
        return None
    return nodes[0]["id"]


def list_workspace_users(api_key: str) -> list[dict]:
    """All active workspace members, carrying the `app` flag so callers can split
    humans (assignable) from agents (delegatable). Fully paginated."""
    query = """query($cursor: String) {
        users(filter: { active: { eq: true } }, first: 100, after: $cursor) {
            pageInfo { hasNextPage endCursor }
            nodes { id name email displayName app }
        }
    }"""
    return paginate_connection(api_key, query, ["users"]) or []


def resolve_assignee_id(api_key: str, value: str) -> str | None:
    """Resolve --assign to a user ID. Accepts an email, or a human's name /
    displayName (case-insensitive) so `--assign bisma` works like `--delegate
    claude`. Agents (app users) are excluded on purpose — delegate those instead.
    Exact match wins over substring; ambiguous names note the pick to stderr."""
    v = (value or "").strip()
    if not v:
        return None
    if "@" in v:
        return resolve_user_id_by_email(api_key, v)
    humans = [u for u in list_workspace_users(api_key) if not u.get("app")]
    lv = v.lower()
    matches = [u for u in humans
               if lv in (u["name"].lower(), (u.get("displayName") or "").lower())]
    if not matches:
        matches = [u for u in humans
                   if lv in u["name"].lower() or lv in (u.get("displayName") or "").lower()]
    if not matches:
        return None
    if len(matches) > 1:
        print(f"Note: '{value}' matched {len(matches)} people; picked '{matches[0]['name']}'.",
              file=sys.stderr)
    return matches[0]["id"]


# ---------------------------------------------------------------------------
# Agent detection (Linear app users you can delegate to)
# ---------------------------------------------------------------------------

def get_agents(api_key: str, cfg: dict, force: bool = False) -> list[dict]:
    """Return the workspace's agent members — Linear app users (Claude, Codex,
    Kimi, Antigravity, Grok, Droid, …). Detected via the `app` user flag, cached
    in config, and auto-refreshed every AGENTS_TTL_SECONDS so the roster tracks
    apps installed/removed without a manual step. Pass force=True to refresh now.
    """
    cached = cfg.get("agents")
    fetched = cfg.get("agentsFetchedAt")
    if cached is not None and not force and fetched:
        try:
            age = (datetime.now(timezone.utc) - datetime.fromisoformat(fetched)).total_seconds()
            if age < AGENTS_TTL_SECONDS:
                return cached
        except ValueError:
            pass  # unparseable timestamp — fall through and refresh

    data = gql(api_key, """
        query {
            users(filter: { app: { eq: true }, active: { eq: true } }, first: 100) {
                nodes { id name }
            }
        }
    """)
    if check_errors(data):
        return cached or []  # keep serving the stale roster on a transient error

    nodes = (data.get("data") or {}).get("users", {}).get("nodes", []) or []
    agents = sorted(
        [{"id": n["id"], "name": n["name"]} for n in nodes],
        key=lambda a: a["name"].lower(),
    )
    cfg["agents"] = agents
    cfg["agentsFetchedAt"] = datetime.now(timezone.utc).isoformat()
    save_config(cfg)
    return agents


def resolve_agent_id(api_key: str, cfg: dict, name: str) -> str | None:
    """Resolve an agent name (e.g. 'claude') to its Linear user id, case- and
    space-insensitive. On a cache miss, refreshes once — a freshly-installed
    agent shouldn't have to wait out the TTL to be delegatable."""
    want = name.strip().lower()
    for force in (False, True):
        for agent in get_agents(api_key, cfg, force=force):
            if agent["name"].lower() == want:
                return agent["id"]
        # only bother with the forced refresh if the first pass missed
    return None


# ---------------------------------------------------------------------------
# Cycle resolution (for auto-attach on create, move on update, listing)
# ---------------------------------------------------------------------------

def get_cycle_id(api_key: str, team_id: str, which: str) -> str | None:
    """Return the active or next cycle ID for a team. Never cached (cycles rotate)."""
    if which not in ("active", "next"):
        return None
    if which == "active":
        data = gql(api_key, f"""{{
            team(id: "{team_id}") {{ activeCycle {{ id name }} }}
        }}""")
        if check_errors(data):
            return None
        cycle = (data.get("data") or {}).get("team", {}).get("activeCycle")
        return cycle.get("id") if cycle else None

    # "next" — Linear has no team.nextCycle field. Find the first cycle whose
    # startsAt is after the active cycle's endsAt, ordered ascending.
    active_query = gql(api_key, f"""{{
        team(id: "{team_id}") {{
            activeCycle {{ endsAt }}
        }}
    }}""")
    if check_errors(active_query):
        return None
    active_ends = (
        ((active_query.get("data") or {}).get("team", {}) or {})
        .get("activeCycle", {}) or {}
    ).get("endsAt")
    if not active_ends:
        return None

    data = gql(api_key, """
        query($teamId: ID!, $after: DateTimeOrDuration!) {
            cycles(
                filter: {
                    team: { id: { eq: $teamId } }
                    startsAt: { gte: $after }
                }
                orderBy: updatedAt
                first: 20
            ) {
                nodes { id name startsAt }
            }
        }
    """, {"teamId": team_id, "after": active_ends})
    if check_errors(data):
        return None

    nodes = (data.get("data") or {}).get("cycles", {}).get("nodes", []) or []
    nodes = [n for n in nodes if n.get("startsAt") and n["startsAt"] >= active_ends]
    nodes.sort(key=lambda n: n["startsAt"])
    return nodes[0]["id"] if nodes else None


def list_team_projects(api_key: str, team_id: str) -> list[dict]:
    """All projects accessible to a team. Sorted most-recently-updated first.
    Fully paginated — no silent truncation at Linear's default page size."""
    query = """query($teamId: String!, $cursor: String) {
        team(id: $teamId) {
            projects(first: 100, after: $cursor) {
                pageInfo { hasNextPage endCursor }
                nodes {
                    id name state progress scope
                    startDate targetDate updatedAt
                    lead { name }
                }
            }
        }
    }"""
    projects = paginate_connection(api_key, query, ["team", "projects"], {"teamId": team_id})
    if projects is None:
        return []
    projects.sort(key=lambda p: p.get("updatedAt") or "", reverse=True)
    return projects


def _suggest(value: str, names: list[str]) -> str:
    """A ' Did you mean: a, b?' hint for a name that didn't resolve — fuzzy
    close-matches first, then substring, so a typo or partial name is actionable
    instead of a dead end."""
    close = difflib.get_close_matches(value, names, n=3, cutoff=0.5)
    if not close:
        close = [n for n in names if value.lower() in n.lower()][:3]
    return f" Did you mean: {', '.join(close)}?" if close else ""


def resolve_project_id(api_key: str, team_id: str, value: str,
                       strict: bool = False) -> str | None:
    """Resolve --project to a projectId. Accepts UUID or name (exact match
    preferred, then substring). On ambiguity, picks the most-recently-active
    match and notes it to stderr.

    On no match: when strict, raise LookupError with close-match suggestions so
    the caller aborts instead of silently proceeding — a mistyped or not-yet-
    created project must never no-op an issue create/update (RUSH-1496). When
    not strict, warn to stderr and return None."""
    if not value:
        return None
    # Looks like a UUID? Pass through.
    if len(value) == 36 and value.count("-") == 4:
        return value
    projects = list_team_projects(api_key, team_id)
    matches = [p for p in projects if p["name"].lower() == value.lower()]
    if not matches:
        # Substring fallback so 'phoenix' matches 'Phoenix Horizon'.
        matches = [p for p in projects if value.lower() in p["name"].lower()]
    if not matches:
        msg = f"project '{value}' not found.{_suggest(value, [p['name'] for p in projects])}"
        if strict:
            raise LookupError(msg)
        print(f"Warning: {msg} Skipping.", file=sys.stderr)
        return None
    if len(matches) > 1:
        print(f"Note: '{value}' matched {len(matches)} projects; "
              f"picked '{matches[0]['name']}' (most recent).", file=sys.stderr)
    return matches[0]["id"]


def resolve_milestone_id(api_key: str, team_id: str, name: str,
                         project_id: str | None,
                         strict: bool = False) -> str | None:
    """Resolve --milestone to a projectMilestoneId. If project_id is given,
    look only there. Else search all team projects and pick the
    most-recently-updated match.

    On no match: when strict, raise LookupError with suggestions (so a batch
    aborts rather than silently dropping the milestone); else warn and return
    None."""
    if not name:
        return None
    if len(name) == 36 and name.count("-") == 4:
        return name

    if project_id:
        data = gql(api_key, """
            query($id: String!) {
                project(id: $id) {
                    projectMilestones(first: 100) {
                        nodes { id name updatedAt }
                    }
                }
            }
        """, {"id": project_id})
        if check_errors(data):
            return None
        nodes = (
            ((data.get("data") or {}).get("project") or {})
            .get("projectMilestones", {}).get("nodes", [])
        )
    else:
        projects = list_team_projects(api_key, team_id)
        nodes = []
        for p in projects:
            data = gql(api_key, """
                query($id: String!) {
                    project(id: $id) {
                        projectMilestones(first: 100) {
                            nodes { id name updatedAt }
                        }
                    }
                }
            """, {"id": p["id"]})
            if check_errors(data):
                continue
            for m in (((data.get("data") or {}).get("project") or {})
                      .get("projectMilestones", {}).get("nodes", [])):
                m["_projectName"] = p["name"]
                nodes.append(m)

    matches = [m for m in nodes if m["name"].lower() == name.lower()]
    if not matches:
        matches = [m for m in nodes if name.lower() in m["name"].lower()]
    if not matches:
        msg = f"milestone '{name}' not found.{_suggest(name, [m['name'] for m in nodes])}"
        if strict:
            raise LookupError(msg)
        print(f"Warning: {msg} Skipping.", file=sys.stderr)
        return None
    matches.sort(key=lambda m: m.get("updatedAt") or "", reverse=True)
    if len(matches) > 1:
        proj = matches[0].get("_projectName", "")
        suffix = f" in project '{proj}'" if proj else ""
        print(f"Note: '{name}' matched {len(matches)} milestones; "
              f"picked '{matches[0]['name']}'{suffix} (most recent).", file=sys.stderr)
    return matches[0]["id"]


def list_team_cycles(api_key: str, team_id: str) -> list[dict]:
    """Return all cycles for a team, fully paginated (no 50-cycle truncation)."""
    query = """query($teamId: ID!, $cursor: String) {
        cycles(
            filter: { team: { id: { eq: $teamId } } }
            orderBy: updatedAt
            first: 100
            after: $cursor
        ) {
            pageInfo { hasNextPage endCursor }
            nodes {
                id number name startsAt endsAt completedAt
                issueCountHistory
            }
        }
    }"""
    return paginate_connection(api_key, query, ["cycles"], {"teamId": team_id}) or []


# ---------------------------------------------------------------------------
# File upload
# ---------------------------------------------------------------------------

def upload_file(api_key: str, filepath: str) -> str | None:
    """Upload a file to Linear and return the asset URL."""
    path = Path(filepath)
    if not path.exists():
        print(f"File not found: {filepath}", file=sys.stderr)
        return None

    size = path.stat().st_size
    content_type = mimetypes.guess_type(filepath)[0] or "application/octet-stream"

    data = gql(api_key, """
        mutation($filename: String!, $contentType: String!, $size: Int!) {
            fileUpload(filename: $filename, contentType: $contentType, size: $size) {
                success
                uploadFile { uploadUrl assetUrl headers { key value } }
            }
        }
    """, {"filename": path.name, "contentType": content_type, "size": size})

    if check_errors(data):
        return None

    upload = data["data"]["fileUpload"]
    if not upload["success"]:
        print("Failed to get upload URL.", file=sys.stderr)
        return None

    uf = upload["uploadFile"]
    file_bytes = path.read_bytes()

    req = Request(uf["uploadUrl"], data=file_bytes, method="PUT")
    req.add_header("Content-Type", content_type)
    for h in uf.get("headers") or []:
        req.add_header(h["key"], h["value"])

    try:
        with urlopen(req) as resp:
            if resp.status not in (200, 201):
                print(f"Upload failed: HTTP {resp.status}", file=sys.stderr)
                return None
    except URLError as e:
        print(f"Upload failed: {e}", file=sys.stderr)
        return None

    return uf["assetUrl"]


def build_proof_comment(api_key: str, proofs: list[str]) -> str:
    """Build a markdown comment body from proof items.

    Each item is auto-detected:
      - File path (exists on disk) -> upload and embed as image/link
      - URL (starts with http) -> embed as link
      - Plain text -> inline as-is
    """
    parts = []
    for i, proof in enumerate(proofs, 1):
        label = f"**Proof {i}:**" if len(proofs) > 1 else "**Proof:**"
        path = Path(proof)

        if path.exists() and path.is_file():
            asset_url = upload_file(api_key, proof)
            if not asset_url:
                parts.append(f"{label} (upload failed: {path.name})")
                continue
            ct = mimetypes.guess_type(proof)[0] or ""
            if ct.startswith("image/"):
                parts.append(f"{label}\n![{path.name}]({asset_url})")
            else:
                parts.append(f"{label} [{path.name}]({asset_url})")
        elif proof.startswith("http://") or proof.startswith("https://"):
            parts.append(f"{label} {proof}")
        else:
            parts.append(f"{label} {proof}")

    return "\n\n".join(parts)


# ---------------------------------------------------------------------------
# Issue resolution
# ---------------------------------------------------------------------------

def resolve_issue(api_key: str, team_id: str, identifier: str) -> dict | None:
    number = identifier.split("-")[-1]
    try:
        number = int(number)
    except ValueError:
        print(f"Invalid identifier: {identifier}", file=sys.stderr)
        return None

    data = gql(api_key, f"""{{
        issues(filter: {{
            team: {{ id: {{ eq: "{team_id}" }} }}
            number: {{ eq: {number} }}
        }}) {{
            nodes {{ id identifier title }}
        }}
    }}""")

    if check_errors(data):
        return None

    nodes = data.get("data", {}).get("issues", {}).get("nodes", [])
    return nodes[0] if nodes else None


def _warn_sub_issue(child: str, parent_ident: str):
    """Non-blocking nudge when an issue is nested under a parent. Sub-issues add
    hierarchy that's easy to lose track of; a flat issue under a project/milestone
    is usually clearer. A stderr tip (not a prompt) keeps bulk/agent runs
    unblocked while still discouraging casual nesting."""
    print(f"Tip: making '{child}' a sub-issue of {parent_ident}. "
          f"Sub-issues add nesting — prefer a top-level issue under a "
          f"project/milestone unless you truly need it.", file=sys.stderr)


# ---------------------------------------------------------------------------
# Formatters
# ---------------------------------------------------------------------------

PRIORITY_MAP = {0: "-", 1: "Urgent", 2: "High", 3: "Medium", 4: "Low"}

PRIORITY_NAMES = {
    "urgent": 1, "high": 2, "medium": 3, "med": 3, "low": 4,
    "none": 0, "no": 0, "no-priority": 0,
}


def parse_priority(value: str) -> int:
    """Accept named priorities: urgent, high, medium, low, none."""
    v = str(value).strip().lower()
    if v in PRIORITY_NAMES:
        return PRIORITY_NAMES[v]
    raise SystemExit(
        f"Invalid --priority '{value}'. Use: urgent, high, medium, low, or none."
    )


def derive_title(description: str) -> str:
    """Pull a sensible title out of a description body. First sentence or first
    line, stripped of markdown bullets/headers, capped at 80 chars."""
    text = description.strip()
    # First newline-bounded line
    first_line = text.split("\n", 1)[0].strip()
    # Strip leading markdown noise: headers, bullets, blockquotes
    while first_line and first_line[0] in "#*->":
        first_line = first_line[1:].lstrip()
    # First sentence within that line
    for sep in (". ", "! ", "? "):
        idx = first_line.find(sep)
        if 0 < idx < 80:
            first_line = first_line[: idx + 1]
            break
    if len(first_line) > 80:
        first_line = first_line[:79].rstrip() + "…"
    return first_line or "Untitled"


def read_description(inline: str | None, path: str | None) -> str | None:
    """Resolve description from --description (inline), --description-file PATH,
    or stdin via --description-file -. Inline wins if both are given."""
    if inline is not None:
        return inline
    if path is None:
        return None
    if path == "-":
        return sys.stdin.read()
    p = Path(path)
    if not p.exists():
        raise SystemExit(f"--description-file: {path} not found")
    return p.read_text()


def parse_due_date(value: str) -> str | None:
    """Accept YYYY-MM-DD, or 'none' to clear. Returns the validated string,
    or None when clearing. Linear's dueDate is a TimelessDate (date-only)."""
    v = str(value).strip()
    if v.lower() in ("none", ""):
        return None
    try:
        date.fromisoformat(v)
    except ValueError:
        raise SystemExit(
            f"Invalid --due-date '{value}'. Use YYYY-MM-DD (e.g. 2026-04-28) or 'none'."
        )
    return v

ISSUE_FIELDS = """
    identifier title description state { name type }
    priority labels { nodes { name } }
    assignee { name }
    delegate { name }
    project { name id }
    dueDate createdAt url
"""


# Sort sentinel for missing due dates — push them to the end of their tier.
_NO_DUE = "9999-99-99"


def issue_sort_key(node: dict) -> tuple:
    """Primary: priority (Urgent=1 first, No-priority=4 last).
    Secondary: due date ascending (earliest first, nulls last).
    Tertiary: identifier so ties are deterministic."""
    priority = node.get("priority") or 4
    due = node.get("dueDate") or _NO_DUE
    ident = node.get("identifier") or ""
    return (priority, due, ident)


def format_due(due: str | None) -> str:
    """Compact due date display: '--' if missing, 'today' / 'tomorrow' / relative
    within a week, otherwise MM-DD."""
    if not due:
        return "    --    "
    try:
        from datetime import date, datetime
        today = date.today()
        d = datetime.fromisoformat(due.replace("Z", "+00:00")).date() if "T" in due else date.fromisoformat(due)
        delta = (d - today).days
        if delta < 0:
            return f"{-delta}d overdue".ljust(10)
        if delta == 0:
            return "today     "
        if delta == 1:
            return "tomorrow  "
        if delta <= 7:
            return f"in {delta}d    "[:10]
        return d.strftime("%b %d   ")[:10]
    except Exception:
        return (due[:10] + "  ")[:10]


def format_issue_row(node: dict) -> str:
    ident = node["identifier"]
    title = node["title"]
    state = node["state"]["name"]
    pri = PRIORITY_MAP.get(node.get("priority", 0), "-")
    due = format_due(node.get("dueDate"))
    labels = [l["name"] for l in node.get("labels", {}).get("nodes", [])]
    label_str = f"  [{', '.join(labels)}]" if labels else ""
    assignee = (node.get("assignee") or {}).get("name") or "unassigned"
    # Delegate (the agent handed the issue) rides alongside the human assignee:
    # "Muqsit → claude". Both are distinct Linear fields; showing only assignee
    # hid every delegation, so the column now carries whoever is actually on it.
    delegate = (node.get("delegate") or {}).get("name")
    who = f"{assignee} → {delegate}" if delegate else assignee
    return f"  {ident:<8} {pri:<7}  {state:<12}  {due}  {who:<22}  {title}{label_str}"


# ---------------------------------------------------------------------------
# Paginated issue fetch
# ---------------------------------------------------------------------------

# Linear caps a connection at 50 nodes by default and 250 max per page. Without
# following pageInfo, any list silently truncates — which breaks "search before
# you create" and produces duplicate tickets. paginate_issues walks every page.
_PAGE_SIZE = 100
_MAX_PAGES = 100  # 10k-issue safety rail; warns if ever hit (no silent caps).


def paginate_issues(api_key: str, filter_str: str) -> list[dict] | None:
    """Fetch every issue matching a root-level filter, following pagination.

    `filter_str` is the inner body of the GraphQL `filter:` object (no braces).
    The opaque cursor is passed as a variable; only the static filter is
    interpolated. Returns None on API error (caller already printed it).
    """
    nodes: list[dict] = []
    cursor: str | None = None
    pages = 0
    query = f"""query($cursor: String) {{
        issues(first: {_PAGE_SIZE}, after: $cursor, filter: {{ {filter_str} }}) {{
            pageInfo {{ hasNextPage endCursor }}
            nodes {{ {ISSUE_FIELDS} }}
        }}
    }}"""
    while True:
        data = gql(api_key, query, {"cursor": cursor})
        if check_errors(data):
            return None
        conn = (data.get("data") or {}).get("issues") or {}
        nodes.extend(conn.get("nodes", []))
        pages += 1
        page_info = conn.get("pageInfo") or {}
        cursor = page_info.get("endCursor")
        if not page_info.get("hasNextPage"):
            break
        if pages >= _MAX_PAGES:
            print(
                f"Warning: stopped after {pages * _PAGE_SIZE} issues "
                f"(pagination safety rail). Narrow your filter to see the rest.",
                file=sys.stderr,
            )
            break
    return nodes


def resolve_cycle_meta(api_key: str, team_id: str, which: str) -> dict | None:
    """Resolve 'active'/'next' to {id, name, startsAt, endsAt}. None when none."""
    cid = get_cycle_id(api_key, team_id, which)
    if not cid:
        return None
    data = gql(
        api_key,
        "query($id: String!) { cycle(id: $id) { id name startsAt endsAt } }",
        {"id": cid},
    )
    fallback = f"{which.capitalize()} cycle"
    if check_errors(data):
        return {"id": cid, "name": fallback, "startsAt": None, "endsAt": None}
    c = (data.get("data") or {}).get("cycle") or {}
    return {
        "id": cid,
        "name": c.get("name") or fallback,
        "startsAt": c.get("startsAt"),
        "endsAt": c.get("endsAt"),
    }


def paginate_connection(api_key: str, query: str, path: list[str],
                        variables: dict | None = None) -> list[dict] | None:
    """Generic relay-cursor paginator for any connection (cycles, users,
    projects, labels, ...). Companion to paginate_issues for the issue path.

    `query` must declare `$cursor: String`, pass `after: $cursor` to the target
    connection, and select `pageInfo { hasNextPage endCursor }` next to `nodes`.
    `path` is the key sequence from the `data` root to the connection object
    (e.g. ["team", "projects"] or ["cycles"]). Returns every node across all
    pages, or None on API error (caller already printed it).
    """
    nodes: list[dict] = []
    cursor: str | None = None
    pages = 0
    base_vars = dict(variables or {})
    while True:
        v = dict(base_vars)
        v["cursor"] = cursor
        data = gql(api_key, query, v)
        if check_errors(data):
            return None
        conn: dict | None = data.get("data") or {}
        for key in path:
            conn = (conn or {}).get(key)
        conn = conn or {}
        nodes.extend(conn.get("nodes", []))
        pages += 1
        info = conn.get("pageInfo") or {}
        cursor = info.get("endCursor")
        if not info.get("hasNextPage"):
            break
        if pages >= _MAX_PAGES:
            print(
                f"Warning: stopped after {pages * _PAGE_SIZE} rows "
                f"(pagination safety rail).",
                file=sys.stderr,
            )
            break
    return nodes


def list_team_labels(api_key: str, team_id: str) -> list[dict]:
    """All labels visible to a team (team-scoped + workspace-wide), paginated.
    The single source of truth for label lookups across list/create/update and
    the label-resolution used by `update --label`."""
    query = """query($teamId: ID!, $cursor: String) {
        issueLabels(
            filter: {
                or: [
                    { team: { id: { eq: $teamId } } }
                    { team: { null: true } }
                ]
            }
            first: 100
            after: $cursor
        ) {
            pageInfo { hasNextPage endCursor }
            nodes { id name description color }
        }
    }"""
    return paginate_connection(api_key, query, ["issueLabels"], {"teamId": team_id}) or []


def resolve_cycle_by_value(api_key: str, team_id: str, value: str) -> dict | None:
    """Resolve a non-keyword --cycle value to a cycle node {id, name, ...}.
    Accepts a UUID (passthrough), a cycle number, or a fuzzy name match.
    Warns and returns None when nothing matches."""
    if not value:
        return None
    if len(value) == 36 and value.count("-") == 4:
        return {"id": value, "name": None, "startsAt": None, "endsAt": None}
    cycles = list_team_cycles(api_key, team_id)
    matches = [c for c in cycles if (c.get("name") or "").lower() == value.lower()]
    if not matches and value.isdigit():
        matches = [c for c in cycles if str(c.get("number")) == value]
    if not matches:
        matches = [c for c in cycles if value.lower() in (c.get("name") or "").lower()]
    if not matches:
        print(f"Warning: cycle '{value}' not found.", file=sys.stderr)
        return None
    if len(matches) > 1:
        matches.sort(key=lambda c: c.get("startsAt") or "", reverse=True)
        print(f"Note: '{value}' matched {len(matches)} cycles; "
              f"picked '{matches[0].get('name')}' (most recent).", file=sys.stderr)
    return matches[0]


def resolve_label_by_value(api_key: str, team_id: str, value: str) -> dict | None:
    """Resolve a label id-or-name to a label node {id, name, ...}. UUID passes
    through; otherwise exact (case-insensitive) name wins, then a unique
    substring match. Ambiguous or missing -> warn and return None."""
    if not value:
        return None
    if len(value) == 36 and value.count("-") == 4:
        return {"id": value, "name": value}
    labels = list_team_labels(api_key, team_id)
    exact = [l for l in labels if l["name"].lower() == value.lower()]
    if exact:
        return exact[0]
    subs = [l for l in labels if value.lower() in l["name"].lower()]
    if len(subs) == 1:
        return subs[0]
    if len(subs) > 1:
        names = ", ".join(l["name"] for l in subs[:5])
        print(f"Warning: label '{value}' is ambiguous ({names}). "
              f"Use the exact name or ID.", file=sys.stderr)
        return None
    print(f"Warning: label '{value}' not found.", file=sys.stderr)
    return None


def build_cycle_scope(api_key: str, team_id: str,
                      scope: str | None) -> tuple[str | None, str | None, dict | None]:
    """Translate a --cycle value into an issues() filter fragment + display label.

    Returns (fragment, label, cycle_meta):
      - active/next  -> concrete cycle id filter, cycle name, meta dict
      - none/backlog -> `cycle: { null: true }`, "Backlog (no cycle)", None
      - all          -> "" (no cycle constraint), "All issues", None
      - <name>/<id>  -> concrete cycle id filter, matched name, node
    On an unresolvable active/next/named cycle, returns (None, None, None).
    """
    s = (scope or "active").lower()
    if s in ("active", "next"):
        meta = resolve_cycle_meta(api_key, team_id, s)
        if not meta:
            return None, None, None
        return f'cycle: {{ id: {{ eq: "{meta["id"]}" }} }}', meta["name"], meta
    if s in ("none", "backlog"):
        return "cycle: { null: true }", "Backlog (no cycle)", None
    if s == "all":
        return "", "All issues", None
    node = resolve_cycle_by_value(api_key, team_id, scope)
    if not node:
        return None, None, None
    return f'cycle: {{ id: {{ eq: "{node["id"]}" }} }}', node.get("name") or scope, node


def cycle_date_to_iso(value: str, flag: str) -> str:
    """Cycle startsAt/endsAt are DateTimes. Accept a YYYY-MM-DD and anchor it to
    start-of-day UTC; pass an explicit ISO timestamp through untouched."""
    v = str(value).strip()
    if "T" in v:
        return v
    try:
        date.fromisoformat(v)
    except ValueError:
        raise SystemExit(f"Invalid {flag} '{value}'. Use YYYY-MM-DD (e.g. 2026-07-01).")
    return f"{v}T00:00:00.000Z"


def parse_timeless_date(value: str, flag: str) -> str | None:
    """Project/milestone start/target dates are Linear TimelessDate — a bare
    YYYY-MM-DD, no time or zone. 'none'/'' clears (returns None). Exits on a
    malformed date so a typo can't be sent as-is."""
    v = str(value or "").strip()
    if v.lower() in ("", "none"):
        return None
    try:
        date.fromisoformat(v[:10])
    except ValueError:
        raise SystemExit(f"Invalid {flag} '{value}'. Use YYYY-MM-DD (e.g. 2026-06-10).")
    return v[:10]


# ---------------------------------------------------------------------------
# setup
# ---------------------------------------------------------------------------

def cmd_setup(args, cfg):
    api_key = args.api_key or input("Linear API key: ").strip()
    if not api_key:
        print("API key required.")
        sys.exit(1)

    cfg["apiKey"] = api_key

    data = gql(api_key, "{ teams { nodes { id name key } } }")
    if check_errors(data):
        sys.exit(1)

    teams = data["data"]["teams"]["nodes"]
    if not teams:
        print("No teams found.")
        sys.exit(1)

    if len(teams) == 1:
        team = teams[0]
        print(f"Found team: {team['name']} ({team['key']})")
    else:
        print("Teams:")
        for i, t in enumerate(teams):
            print(f"  {i + 1}. {t['name']} ({t['key']})")
        choice = input(f"Select team [1-{len(teams)}]: ").strip()
        try:
            team = teams[int(choice) - 1]
        except (ValueError, IndexError):
            print("Invalid selection.")
            sys.exit(1)

    cfg["teamId"] = team["id"]
    cfg["teamKey"] = team["key"]

    agent = args.agent or input("Default agent identity (e.g. claude, codex) [skip]: ").strip()
    if agent:
        cfg["agent"] = agent

    cfg.pop("states", None)
    states = get_states(api_key, team["id"], cfg)

    save_config(cfg)
    print(f"\nConfigured: team={team['name']}, states={len(states)}")
    if agent:
        print(f"Agent identity: {agent}")
    print(f"Config: {CONFIG_PATH}")


# ---------------------------------------------------------------------------
# tasks - list, view, board
# ---------------------------------------------------------------------------

def cmd_tasks(args, cfg, api_key, team_id):
    # If an identifier is given, show detail view
    if args.identifier:
        return show_issue_detail(args, api_key, team_id)

    # If --board, show team board
    if args.board:
        return show_board(args, api_key, team_id, cfg)

    # Otherwise, list tasks
    return list_tasks(args, cfg, api_key, team_id)


def list_tasks(args, cfg, api_key, team_id):
    """Default view: my agent's tasks + tasks with no agent:* label (unowned).
    `--agent X` narrows to a specific agent. `--all` shows literally every task.
    `--cycle` scopes to the active cycle (default), next cycle, the whole team
    (`all`, cross-cycle + backlog), or the backlog only (`none`).
    `--assignee EMAIL|me|none` filters by who the issue is assigned to.
    Tasks are sorted by priority, then due date (earliest first), then id.
    Results are fully paginated — no silent truncation at Linear's 50-issue cap.
    """
    filters = [f'team: {{ id: {{ eq: "{team_id}" }} }}']

    # Cycle scope. active/next resolve to a concrete cycle id (and a header
    # name); `all` drops the cycle filter; `none`/`backlog` lists the backlog;
    # any other value is treated as a cycle name or id and resolved.
    scope = args.cycle
    fragment, scope_label, cycle_meta = build_cycle_scope(api_key, team_id, scope)
    if fragment is None:
        print(f"Could not resolve --cycle '{scope}'.")
        return
    if fragment:
        filters.append(fragment)

    # Optional date floor: only issues created on/after --since (YYYY-MM-DD).
    since = getattr(args, "since", None)
    if since:
        try:
            date.fromisoformat(since)
        except ValueError:
            print(f"Invalid --since '{since}'. Use YYYY-MM-DD.", file=sys.stderr)
            return
        filters.append(f'createdAt: {{ gte: "{since}T00:00:00.000Z" }}')

    # Resolve which agent filter to apply (if any). `--all` overrides config default.
    if args.all:
        explicit_agent = None
        include_unowned = False  # --all means show everything including other agents
    elif args.agent:
        explicit_agent = args.agent
        include_unowned = False  # explicit agent request — just show their queue
    elif cfg.get("agent"):
        explicit_agent = cfg.get("agent")
        include_unowned = True   # default view = my queue + unowned
    else:
        explicit_agent = None
        include_unowned = False

    if args.label and not explicit_agent:
        filters.append(f'labels: {{ name: {{ eq: "{args.label}" }} }}')

    # Assignee filter: 'me' = API-key owner, 'none' = unassigned, else email.
    assignee = getattr(args, "assignee", None)
    if assignee:
        if assignee.lower() == "none":
            filters.append("assignee: { null: true }")
        else:
            if assignee.lower() == "me":
                uid = get_viewer_id(api_key, cfg)
            else:
                uid = resolve_user_id_by_email(api_key, assignee)
            if not uid:
                print(f"Could not resolve assignee '{assignee}'.", file=sys.stderr)
                return
            filters.append(f'assignee: {{ id: {{ eq: "{uid}" }} }}')

    if getattr(args, "query", None):
        q = args.query.replace('"', '\\"')
        filters.append(
            f'or: [ {{ title: {{ containsIgnoreCase: "{q}" }} }}, '
            f'{{ description: {{ containsIgnoreCase: "{q}" }} }} ]'
        )

    if args.status:
        status = args.status.lower()
        if status == "open":
            filters.append('state: { type: { nin: ["completed", "canceled"] } }')
        elif status == "done":
            filters.append('state: { type: { eq: "completed" } }')
        else:
            states = get_states(api_key, team_id, cfg)
            sid = resolve_state_id(states, status)
            if sid:
                filters.append(f'state: {{ id: {{ eq: "{sid}" }} }}')
            else:
                filters.append(f'state: {{ name: {{ eqi: "{status}" }} }}')
    else:
        filters.append('state: { type: { nin: ["completed", "canceled"] } }')

    filter_str = ", ".join(filters)

    nodes = paginate_issues(api_key, filter_str)
    if nodes is None:
        return

    # Apply agent ownership filter client-side so "my tasks + unowned" is expressible.
    if explicit_agent:
        target_label = f"agent:{explicit_agent}"

        def match(n):
            names = [l["name"] for l in n.get("labels", {}).get("nodes", [])]
            has_target = target_label in names
            has_any_agent = any(x.startswith("agent:") for x in names)
            if has_target:
                return True
            if include_unowned and not has_any_agent:
                return True
            return False

        nodes = [n for n in nodes if match(n)]

    nodes.sort(key=issue_sort_key)

    if args.json:
        print(json.dumps({
            "scope": scope,
            "cycle": cycle_meta,
            "count": len(nodes),
            "issues": nodes,
        }, indent=2))
        return

    if not nodes:
        print(f"No matching tasks in {scope_label}.")
        return

    header_note = ""
    if explicit_agent and include_unowned:
        owned = sum(1 for n in nodes if any(l["name"] == f"agent:{explicit_agent}" for l in n.get("labels", {}).get("nodes", [])))
        unowned = len(nodes) - owned
        header_note = f"  ({owned} yours, {unowned} unowned)"
    print(f"{scope_label} -- {len(nodes)} task(s){header_note}")
    print()
    for n in nodes:
        print(format_issue_row(n))


def show_board(args, api_key, team_id, cfg):
    # Same cycle scoping as list_tasks (active/next/all/none/name/id), so the
    # board no longer hits the non-existent team.nextCycle field, and it
    # paginates instead of silently capping at 50 open issues.
    fragment, scope_label, cycle_meta = build_cycle_scope(api_key, team_id, args.cycle)
    if fragment is None:
        print(f"Could not resolve --cycle '{args.cycle}'.")
        return

    filters = [
        f'team: {{ id: {{ eq: "{team_id}" }} }}',
        'state: { type: { nin: ["completed", "canceled"] } }',
    ]
    if fragment:
        filters.append(fragment)

    nodes = paginate_issues(api_key, ", ".join(filters))
    if nodes is None:
        return

    cycle_name = scope_label

    if args.json:
        print(json.dumps({
            "scope": args.cycle,
            "cycle": cycle_meta,
            "count": len(nodes),
            "issues": nodes,
        }, indent=2))
        return

    if not nodes:
        print(f"No open tasks in {cycle_name}.")
        return

    agents: dict[str, list] = {}
    unassigned: list = []

    for n in nodes:
        labels = [l["name"] for l in n.get("labels", {}).get("nodes", [])]
        agent_labels = [l for l in labels if l.startswith("agent:")]
        if agent_labels:
            for al in agent_labels:
                agent_name = al.split(":", 1)[1]
                agents.setdefault(agent_name, []).append(n)
        else:
            unassigned.append(n)

    print(f"{cycle_name} -- {len(nodes)} task(s)")
    print()

    for agent_name in sorted(agents.keys()):
        issues = agents[agent_name]
        issues.sort(key=issue_sort_key)
        print(f"  @{agent_name} ({len(issues)})")
        for n in issues:
            pri = PRIORITY_MAP.get(n.get("priority", 0), "-")
            state = n["state"]["name"]
            due = format_due(n.get("dueDate"))
            print(f"    {n['identifier']:<8} {pri:<7}  {state:<12}  {due}  {n['title']}")
        print()

    if unassigned:
        unassigned.sort(key=issue_sort_key)
        print(f"  unassigned ({len(unassigned)})")
        for n in unassigned:
            pri = PRIORITY_MAP.get(n.get("priority", 0), "-")
            state = n["state"]["name"]
            due = format_due(n.get("dueDate"))
            labels = [l["name"] for l in n.get("labels", {}).get("nodes", [])]
            label_str = f"  [{', '.join(labels)}]" if labels else ""
            print(f"    {n['identifier']:<8} {pri:<7}  {state:<12}  {due}  {n['title']}{label_str}")
        print()


def show_issue_detail(args, api_key, team_id):
    identifier = args.identifier
    number = identifier.split("-")[-1]
    try:
        number = int(number)
    except ValueError:
        print(f"Invalid identifier: {identifier}", file=sys.stderr)
        sys.exit(1)

    data = gql(api_key, f"""{{
        issues(filter: {{
            team: {{ id: {{ eq: "{team_id}" }} }}
            number: {{ eq: {number} }}
        }}) {{
            nodes {{
                id identifier title description url
                state {{ name }}
                priority dueDate
                labels {{ nodes {{ name }} }}
                assignee {{ name }}
                delegate {{ name }}
                project {{ name }}
                cycle {{ name }}
                parent {{ identifier title }}
                createdAt updatedAt
                relations {{ nodes {{ type relatedIssue {{ identifier title }} }} }}
                inverseRelations {{ nodes {{ type issue {{ identifier title }} }} }}
                comments {{ nodes {{ body createdAt user {{ name }} }} }}
            }}
        }}
    }}""")

    if check_errors(data):
        return

    nodes = data.get("data", {}).get("issues", {}).get("nodes", [])
    if not nodes:
        print(f"Issue {identifier} not found.")
        return

    n = nodes[0]

    if args.json:
        print(json.dumps(n, indent=2))
        return

    pri = PRIORITY_MAP.get(n.get("priority", 0), "-")
    labels = ", ".join(l["name"] for l in n.get("labels", {}).get("nodes", []))
    assignee = n.get("assignee")
    assignee_name = assignee.get("name", "Unassigned") if assignee else "Unassigned"
    delegate = n.get("delegate")
    delegate_name = delegate.get("name") if delegate else None

    print(f"{n['identifier']}  {n['title']}")
    print(f"  Status:   {n['state']['name']}")
    print(f"  Priority: {pri}")
    print(f"  Labels:   {labels or '-'}")
    print(f"  Assignee: {assignee_name}")
    if delegate_name:
        print(f"  Delegate: {delegate_name}")
    if n.get("dueDate"):
        print(f"  Due:      {n['dueDate']}")
    if n.get("project"):
        print(f"  Project:  {n['project']['name']}")
    if n.get("cycle"):
        print(f"  Cycle:    {n['cycle']['name']}")
    if n.get("parent"):
        print(f"  Parent:   {n['parent']['identifier']}  {n['parent']['title']}")
    if n.get("url"):
        print(f"  URL:      {n['url']}")

    # Relations: forward edges (this blocks / relates to X) + inverse (X blocks this).
    rel_lines = []
    for r in (n.get("relations") or {}).get("nodes", []):
        other = r.get("relatedIssue") or {}
        verb = {"blocks": "Blocks", "related": "Related to", "duplicate": "Duplicate of"}.get(r.get("type"), r.get("type"))
        rel_lines.append(f"  {verb}: {other.get('identifier', '?')}  {other.get('title', '')}")
    for r in (n.get("inverseRelations") or {}).get("nodes", []):
        other = r.get("issue") or {}
        # "related"/"duplicate" are symmetric, so they must render from the
        # inverse side too; "blocks" inverts to "blocked by".
        verb = {"blocks": "Blocked by", "related": "Related to", "duplicate": "Duplicate of"}.get(r.get("type"), r.get("type"))
        rel_lines.append(f"  {verb}: {other.get('identifier', '?')}  {other.get('title', '')}")
    if rel_lines:
        print("  Relations:")
        for line in rel_lines:
            print(f"  {line}")
    print()

    desc = n.get("description", "")
    if desc:
        print("Description:")
        for line in desc.split("\n"):
            print(f"  {line}")
        print()

    comments = n.get("comments", {}).get("nodes", [])
    if comments:
        print(f"Comments ({len(comments)}):")
        for c in comments:
            user = c.get("user", {}).get("name", "Unknown")
            body = c.get("body", "").strip().replace("\n", "\n    ")
            print(f"  [{user}] {body}")
        print()


# ---------------------------------------------------------------------------
# update - all mutations on an existing issue
# ---------------------------------------------------------------------------

def cmd_update(args, cfg, api_key, team_id):
    """Dispatcher: apply the same set of changes to one or many issues.

    Identifiers come from positional args and/or --stdin (whitespace-separated,
    xargs-friendly). A single identifier keeps the original detailed output; two
    or more switch to compact per-issue progress with an error roll-up at the
    end so one bad ticket never aborts the batch.
    """
    # Require proof when marking done — checked once up front for the whole batch.
    if args.done and not args.proof:
        print("Cannot mark done without proof. Provide at least one --proof:", file=sys.stderr)
        print("  --proof /path/to/screenshot.png   (file upload)", file=sys.stderr)
        print("  --proof https://example.com/result (URL)", file=sys.stderr)
        print('  --proof "Sent 15/30 emails"        (text)', file=sys.stderr)
        sys.exit(1)

    identifiers = list(args.identifier or [])
    if getattr(args, "stdin", False):
        for line in sys.stdin:
            identifiers.extend(line.split())
    # De-dupe while preserving order.
    identifiers = list(dict.fromkeys(identifiers))
    if not identifiers:
        print("No issue identifier given.", file=sys.stderr)
        sys.exit(1)

    # Resolve --project / --milestone ONCE, up front and strictly. An unknown
    # name aborts the whole run with a non-zero exit instead of silently no-op'ing
    # every issue in a batch while reporting success (RUSH-1496); resolving once
    # also avoids a per-issue project lookup on bulk updates.
    project_id = _UNSET
    milestone_id = _UNSET
    try:
        # Truthy (not `is not None`) so an empty `--project ""` is a no-op, not a
        # clear — only an explicit `--project none` clears the field.
        if args.project:
            project_id = (None if args.project.lower() == "none"
                          else resolve_project_id(api_key, team_id, args.project, strict=True))
        if args.milestone:
            scope = project_id if project_id not in (_UNSET, None) else None
            milestone_id = (None if args.milestone.lower() == "none"
                            else resolve_milestone_id(api_key, team_id, args.milestone, scope, strict=True))
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

    if len(identifiers) == 1:
        issue = resolve_issue(api_key, team_id, identifiers[0])
        if not issue:
            print(f"Issue {identifiers[0]} not found.")
            sys.exit(1)
        ok = _apply_update(args, cfg, api_key, team_id, issue, single=True,
                           project_id=project_id, milestone_id=milestone_id)
        if not ok:
            sys.exit(1)
        return

    total = len(identifiers)
    succeeded = 0
    failed: list[str] = []
    for i, ident in enumerate(identifiers, 1):
        issue = resolve_issue(api_key, team_id, ident)
        if not issue:
            print(f"[{i}/{total}] {ident} -> not found")
            failed.append(ident)
            continue
        print(f"[{i}/{total}] {issue['identifier']}")
        try:
            if _apply_update(args, cfg, api_key, team_id, issue, single=False,
                             project_id=project_id, milestone_id=milestone_id):
                succeeded += 1
            else:
                failed.append(ident)
        except Exception as e:  # never let one ticket abort the batch
            print(f"  error: {e}", file=sys.stderr)
            failed.append(ident)

    summary = f"\n{succeeded}/{total} updated."
    if failed:
        summary += f" Failed: {', '.join(failed)}"
    sys.stdout.flush()  # keep per-issue progress ahead of the summary when piped
    print(summary, file=sys.stderr)
    if failed:
        sys.exit(1)


def _apply_update(args, cfg, api_key, team_id, issue, single=True,
                  project_id=_UNSET, milestone_id=_UNSET) -> bool:
    """Apply every requested change to one resolved issue. Returns True if at
    least one change was made. Never mutates `args` (so it is safe to call in a
    loop) and never calls sys.exit (so a failure on one issue can be rolled up
    by the bulk caller). Hard per-issue failures return False.

    project_id / milestone_id are pre-resolved once by cmd_update: _UNSET means
    the flag was absent (leave the field alone), None means clear it, a string
    means set it."""
    identifier = issue.get("identifier") or args.identifier
    did_something = False

    # A local copy so the bulk loop doesn't see comment cleared after issue #1.
    comment = args.comment

    # Post proof as a comment before status change
    if args.proof:
        proof_body = build_proof_comment(api_key, args.proof)
        if comment:
            proof_body = f"{comment}\n\n{proof_body}"

        data = gql(api_key, """
            mutation($input: CommentCreateInput!) {
                commentCreate(input: $input) { success }
            }
        """, {"input": {"issueId": issue["id"], "body": proof_body}})

        if check_errors(data):
            return False
        if data["data"]["commentCreate"]["success"]:
            print(f"Proof posted to {identifier}.")
        else:
            print("Proof comment failed.", file=sys.stderr)
            return False
        did_something = True
        # Comment already included in proof, don't post separately
        comment = None

    # Status change
    target_state = None
    if args.done:
        target_state = "Done"
    elif args.pickup:
        target_state = "In Progress"
    elif args.todo:
        target_state = "Todo"
    elif args.status:
        target_state = args.status

    if target_state:
        states = get_states(api_key, team_id, cfg)
        state_id = resolve_state_id(states, target_state)
        if not state_id:
            print(f"State '{target_state}' not found. Available: {', '.join(states.keys())}", file=sys.stderr)
            return False

        data = gql(api_key, """
            mutation($id: String!, $stateId: String!) {
                issueUpdate(id: $id, input: { stateId: $stateId }) {
                    success
                    issue { identifier title state { name } }
                }
            }
        """, {"id": issue["id"], "stateId": state_id})

        if check_errors(data):
            return False

        result = data["data"]["issueUpdate"]
        if result["success"]:
            i = result["issue"]
            print(f"{i['identifier']} -> {i['state']['name']}")
        else:
            print("Status update failed.")
        did_something = True

    # Issue relations. Linear models all of these as one relation with a
    # direction: "A blocks B" is the same edge as "B blocked-by A", so
    # --blocked-by just flips which side is the issueId. type is blocks|related.
    rel_specs = []
    for ident in (args.blocks or []):
        rel_specs.append(("blocks", ident, "forward", "blocks"))
    for ident in (args.blocked_by or []):
        rel_specs.append(("blocked by", ident, "inverse", "blocks"))
    for ident in (args.relates or []):
        rel_specs.append(("related to", ident, "forward", "related"))
    for verb, ident, direction, rel_type in rel_specs:
        other = resolve_issue(api_key, team_id, ident)
        if not other:
            print(f"Related issue {ident} not found, skipping.", file=sys.stderr)
            continue
        if direction == "forward":
            issue_id, related_id = issue["id"], other["id"]
        else:
            issue_id, related_id = other["id"], issue["id"]
        rel_data = gql(api_key, """
            mutation($input: IssueRelationCreateInput!) {
                issueRelationCreate(input: $input) { success }
            }
        """, {"input": {"issueId": issue_id, "relatedIssueId": related_id, "type": rel_type}})
        if check_errors(rel_data):
            continue
        if (rel_data.get("data") or {}).get("issueRelationCreate", {}).get("success"):
            print(f"{identifier} {verb} {other['identifier']}")
            did_something = True
        else:
            print(f"Failed to link {identifier} {verb} {ident}.", file=sys.stderr)

    # Labels (add via --label, remove via --unlabel)
    if args.label or args.unlabel:
        all_labels = list_team_labels(api_key, team_id)
        if all_labels is not None:
            label_map = {l["name"]: l["id"] for l in all_labels}

            # Also get current labels on the issue
            issue_data = gql(api_key, f"""{{
                issue(id: "{issue['id']}") {{
                    labels {{ nodes {{ id name }} }}
                }}
            }}""")
            current_ids = []
            current_names_by_id = {}
            if not check_errors(issue_data):
                for l in issue_data["data"]["issue"]["labels"]["nodes"]:
                    current_ids.append(l["id"])
                    current_names_by_id[l["id"]] = l["name"]

            label_ids = list(current_ids)
            added = []
            for lbl in args.label or []:
                if lbl in label_map:
                    if label_map[lbl] not in label_ids:
                        label_ids.append(label_map[lbl])
                        added.append(lbl)
                else:
                    print(f"Warning: label '{lbl}' not found, skipping.", file=sys.stderr)

            removed = []
            for lbl in args.unlabel or []:
                if lbl in label_map and label_map[lbl] in label_ids:
                    label_ids.remove(label_map[lbl])
                    removed.append(lbl)
                else:
                    print(f"Warning: label '{lbl}' not on this issue, skipping.", file=sys.stderr)

            if added or removed:
                data = gql(api_key, """
                    mutation($id: String!, $labelIds: [String!]!) {
                        issueUpdate(id: $id, input: { labelIds: $labelIds }) {
                            success
                        }
                    }
                """, {"id": issue["id"], "labelIds": label_ids})

                if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
                    parts = []
                    if added:
                        parts.append(f"added {', '.join(added)}")
                    if removed:
                        parts.append(f"removed {', '.join(removed)}")
                    print(f"Labels on {identifier}: {'; '.join(parts)}")
                else:
                    print("Label update failed.")
                did_something = True

    # Cycle move: --cycle active | next | none
    if args.cycle:
        choice = args.cycle.lower()
        new_cycle_id: str | None = None
        if choice == "none":
            new_cycle_id = None
        elif choice in ("active", "next"):
            new_cycle_id = get_cycle_id(api_key, team_id, choice)
            if not new_cycle_id:
                print(f"Warning: no {choice} cycle found; skipping cycle move.", file=sys.stderr)
                new_cycle_id = ...  # sentinel — skip mutation below

        if new_cycle_id is not ...:
            data = gql(api_key, """
                mutation($id: String!, $cycleId: String) {
                    issueUpdate(id: $id, input: { cycleId: $cycleId }) {
                        success
                        issue { identifier cycle { name } }
                    }
                }
            """, {"id": issue["id"], "cycleId": new_cycle_id})
            if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
                i = data["data"]["issueUpdate"]["issue"]
                cyc = (i.get("cycle") or {}).get("name") or "no cycle"
                print(f"{i['identifier']} -> cycle: {cyc}")
                did_something = True
            else:
                print("Cycle update failed.")

    # Title / description: batched in one mutation
    title_desc_input: dict = {}
    if args.title is not None:
        title_desc_input["title"] = args.title
    description = read_description(args.description, args.description_file)
    if description is not None:
        title_desc_input["description"] = description
    if args.parent is not None:
        if args.parent.lower() == "none":
            title_desc_input["parentId"] = None
        else:
            parent_issue = resolve_issue(api_key, team_id, args.parent)
            if parent_issue:
                title_desc_input["parentId"] = parent_issue["id"]
                _warn_sub_issue(identifier, parent_issue.get("identifier") or args.parent)
            else:
                print(f"Warning: parent '{args.parent}' not found; skipping.", file=sys.stderr)
    # project_id / milestone_id are pre-resolved (strictly) by cmd_update.
    if project_id is not _UNSET:
        title_desc_input["projectId"] = project_id
    if milestone_id is not _UNSET:
        title_desc_input["projectMilestoneId"] = milestone_id
    if title_desc_input:
        data = gql(api_key, """
            mutation($id: String!, $input: IssueUpdateInput!) {
                issueUpdate(id: $id, input: $input) {
                    success
                    issue { identifier title }
                }
            }
        """, {"id": issue["id"], "input": title_desc_input})
        if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
            i = data["data"]["issueUpdate"]["issue"]
            changed = ", ".join(title_desc_input.keys())
            print(f"{i['identifier']} -> updated: {changed}")
            did_something = True
        else:
            print("Title/description update failed.")

    # Priority: --priority urgent|high|medium|low|none
    if args.priority is not None:
        pri = parse_priority(args.priority)
        data = gql(api_key, """
            mutation($id: String!, $priority: Int!) {
                issueUpdate(id: $id, input: { priority: $priority }) {
                    success
                    issue { identifier priority }
                }
            }
        """, {"id": issue["id"], "priority": pri})
        if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
            i = data["data"]["issueUpdate"]["issue"]
            name = PRIORITY_MAP.get(i.get("priority", 0), "-")
            print(f"{i['identifier']} -> priority: {name}")
            did_something = True
        else:
            print("Priority update failed.")

    # Assign: --assign email | none
    if args.assign is not None:
        if args.assign.lower() == "none":
            assignee_id = None
        else:
            assignee_id = resolve_assignee_id(api_key, args.assign)
            if not assignee_id:
                print(f"Warning: --assign '{args.assign}' matched no human "
                      f"(try an email, a name, or 'linear users'); skipping reassign.", file=sys.stderr)
                assignee_id = ...

        if assignee_id is not ...:
            data = gql(api_key, """
                mutation($id: String!, $assigneeId: String) {
                    issueUpdate(id: $id, input: { assigneeId: $assigneeId }) {
                        success
                        issue { identifier assignee { name } }
                    }
                }
            """, {"id": issue["id"], "assigneeId": assignee_id})
            if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
                i = data["data"]["issueUpdate"]["issue"]
                asg = (i.get("assignee") or {}).get("name") or "unassigned"
                print(f"{i['identifier']} -> assignee: {asg}")
                did_something = True
            else:
                print("Assign update failed.")

    # Delegate: --delegate <agent-name> | none. Agents can't be plain assignees
    # (Linear silently ignores an app user in assigneeId); delegation is the
    # supported path — the human stays assignee, the agent becomes delegate.
    if getattr(args, "delegate", None) is not None:
        if args.delegate.lower() == "none":
            delegate_id = None
        else:
            delegate_id = resolve_agent_id(api_key, cfg, args.delegate)
            if not delegate_id:
                names = ", ".join(a["name"] for a in get_agents(api_key, cfg)) or "none installed"
                print(f"Warning: agent '{args.delegate}' not found. Available agents: {names}", file=sys.stderr)
                delegate_id = ...

        if delegate_id is not ...:
            data = gql(api_key, """
                mutation($id: String!, $delegateId: String) {
                    issueUpdate(id: $id, input: { delegateId: $delegateId }) {
                        success
                        issue { identifier delegate { name } }
                    }
                }
            """, {"id": issue["id"], "delegateId": delegate_id})
            if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
                i = data["data"]["issueUpdate"]["issue"]
                dg = (i.get("delegate") or {}).get("name") or "no agent"
                print(f"{i['identifier']} -> delegate: {dg}")
                did_something = True
            else:
                print("Delegate update failed.")

    # Due date: --due-date YYYY-MM-DD | none
    if args.due_date is not None:
        due = parse_due_date(args.due_date)
        data = gql(api_key, """
            mutation($id: String!, $due: TimelessDate) {
                issueUpdate(id: $id, input: { dueDate: $due }) {
                    success
                    issue { identifier dueDate }
                }
            }
        """, {"id": issue["id"], "due": due})
        if not check_errors(data) and data["data"]["issueUpdate"]["success"]:
            i = data["data"]["issueUpdate"]["issue"]
            print(f"{i['identifier']} -> due: {i['dueDate'] or 'cleared'}")
            did_something = True
        else:
            print("Due date update failed.")

    # Comment (a proof already folds its comment in above, clearing `comment`)
    if comment:
        data = gql(api_key, """
            mutation($input: CommentCreateInput!) {
                commentCreate(input: $input) { success }
            }
        """, {"input": {"issueId": issue["id"], "body": comment}})

        if check_errors(data):
            return False

        if data["data"]["commentCreate"]["success"]:
            print(f"Comment added to {identifier}.")
        else:
            print("Comment failed.")
        did_something = True

    if not did_something and single:
        print("Nothing to do. Use --done, --pickup, --todo, --status, --cycle, --label, --priority, --assign, --delegate, --title, --description, --due-date, or --comment.")
    return did_something


# ---------------------------------------------------------------------------
# create
# ---------------------------------------------------------------------------

def _build_create_input(api_key: str, team_id: str, cfg: dict, fields: dict,
                        verbose: bool = True) -> tuple[dict | None, str | None]:
    """Build an IssueCreateInput from a flat fields dict (keys match flag names:
    title, description, description_file, priority, parent, project,
    milestone, status, cycle, assign, due_date, label).

    Returns (input_obj, None) on success or (None, error) on hard failure.
    Smart defaults applied silently. Warnings go to stderr when verbose=True.
    """
    def warn(msg):
        if verbose:
            print(f"Warning: {msg}", file=sys.stderr)

    description = read_description(fields.get("description"), fields.get("description_file"))

    title = fields.get("title")
    if not title:
        if not description:
            return None, "no title or description"
        title = derive_title(description)

    input_obj: dict = {"teamId": team_id, "title": title}
    if description:
        input_obj["description"] = description

    if fields.get("due_date"):
        try:
            due = parse_due_date(fields["due_date"])
            if due is not None:
                input_obj["dueDate"] = due
        except SystemExit as e:
            return None, str(e)

    try:
        priority = parse_priority(fields["priority"]) if fields.get("priority") is not None else 3
    except SystemExit as e:
        return None, str(e)
    input_obj["priority"] = priority

    if fields.get("parent"):
        parent_issue = resolve_issue(api_key, team_id, fields["parent"])
        if parent_issue:
            input_obj["parentId"] = parent_issue["id"]
            if verbose:
                _warn_sub_issue(title, parent_issue.get("identifier") or fields["parent"])
        else:
            warn(f"parent '{fields['parent']}' not found; creating without parent.")

    # A named --project/--milestone that doesn't resolve is a hard error: creating
    # the issue without it would silently ignore what the user asked for (RUSH-1496).
    project_id = None
    if fields.get("project"):
        try:
            project_id = resolve_project_id(api_key, team_id, fields["project"], strict=True)
        except LookupError as e:
            return None, str(e)
        input_obj["projectId"] = project_id

    if fields.get("milestone"):
        try:
            mid = resolve_milestone_id(api_key, team_id, fields["milestone"], project_id, strict=True)
        except LookupError as e:
            return None, str(e)
        input_obj["projectMilestoneId"] = mid

    desired_status = fields.get("status")
    if not desired_status:
        desired_status = "Backlog" if priority == 4 else "Todo"
    states = get_states(api_key, team_id, cfg)
    sid = resolve_state_id(states, desired_status)
    if sid:
        input_obj["stateId"] = sid
    else:
        warn(f"state '{desired_status}' not found; letting Linear pick the default.")

    cycle_choice = (fields.get("cycle") or "active").lower()
    if cycle_choice in ("active", "next"):
        cid = get_cycle_id(api_key, team_id, cycle_choice)
        if cid:
            input_obj["cycleId"] = cid
        else:
            warn(f"no {cycle_choice} cycle found; creating without cycle.")

    assign_arg = fields.get("assign")
    if assign_arg is None:
        vid = get_viewer_id(api_key, cfg)
        if vid:
            input_obj["assigneeId"] = vid
    elif assign_arg.lower() == "none":
        pass
    else:
        uid = resolve_assignee_id(api_key, assign_arg)
        if uid:
            input_obj["assigneeId"] = uid
        else:
            warn(f"--assign '{assign_arg}' matched no human "
                 f"(try an email, a name, or 'linear users'); leaving unassigned.")

    delegate_arg = fields.get("delegate")
    if delegate_arg and delegate_arg.lower() != "none":
        did = resolve_agent_id(api_key, cfg, delegate_arg)
        if did:
            input_obj["delegateId"] = did
        else:
            names = ", ".join(a["name"] for a in get_agents(api_key, cfg)) or "none installed"
            warn(f"agent '{delegate_arg}' not found; creating without delegate. Available: {names}")

    label_names = fields.get("label") or []
    if isinstance(label_names, str):
        label_names = [label_names]
    if label_names:
        label_map = {l["name"]: l["id"] for l in list_team_labels(api_key, team_id)}
        label_ids = []
        for lbl in label_names:
            if lbl in label_map:
                label_ids.append(label_map[lbl])
            else:
                warn(f"label '{lbl}' not found, skipping.")
        if label_ids:
            input_obj["labelIds"] = label_ids

    return input_obj, None


def _send_issue_create(api_key: str, input_obj: dict) -> tuple[dict | None, str | None]:
    data = gql(api_key, """
        mutation($input: IssueCreateInput!) {
            issueCreate(input: $input) {
                success
                issue { identifier title state { name } cycle { name } assignee { name } delegate { name } }
            }
        }
    """, {"input": input_obj})
    if data.get("errors"):
        return None, data["errors"][0].get("message", "unknown error")
    result = data["data"]["issueCreate"]
    if not result["success"]:
        return None, "create failed"
    return result["issue"], None


def cmd_create(args, cfg, api_key, team_id):
    if args.from_file:
        return _bulk_create(args.from_file, cfg, api_key, team_id)

    fields = {
        "title": args.title,
        "description": args.description,
        "description_file": args.description_file,
        "priority": args.priority,
        "parent": args.parent,
        "project": args.project,
        "milestone": args.milestone,
        "status": args.status,
        "cycle": args.cycle,
        "assign": args.assign,
        "delegate": args.delegate,
        "due_date": args.due_date,
        "label": args.label or [],
    }
    input_obj, err = _build_create_input(api_key, team_id, cfg, fields, verbose=True)
    if err:
        print(err, file=sys.stderr)
        sys.exit(1)
    issue, err = _send_issue_create(api_key, input_obj)
    if err:
        print(f"Error: {err}", file=sys.stderr)
        return
    cyc = (issue.get("cycle") or {}).get("name") or "no cycle"
    asg = (issue.get("assignee") or {}).get("name") or "unassigned"
    dg = (issue.get("delegate") or {}).get("name")
    meta = f"{cyc} | {asg}" + (f" | delegate: {dg}" if dg else "")
    print(f"Created {issue['identifier']}: {issue['title']}  [{meta}]")


def _bulk_create(path: str, cfg, api_key, team_id):
    """Bulk create from JSONL. Each line is a JSON object with field names
    matching the single-create flags. Continue-on-error; tab-separated output:
    OK<TAB>IDENT<TAB>TITLE  or  ERROR<TAB>-<TAB>TITLE<TAB>REASON."""
    if path == "-":
        stream = sys.stdin
    else:
        if not Path(path).exists():
            print(f"--from-file: {path} not found", file=sys.stderr)
            sys.exit(1)
        stream = open(path)

    ok_count = 0
    err_count = 0
    for raw in stream:
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        try:
            fields = json.loads(line)
        except json.JSONDecodeError as e:
            print(f"ERROR\t-\t<unparseable>\t{e}")
            err_count += 1
            continue

        title_hint = fields.get("title") or (fields.get("description", "")[:60] if fields.get("description") else "<no title>")
        input_obj, err = _build_create_input(api_key, team_id, cfg, fields, verbose=False)
        if err:
            print(f"ERROR\t-\t{title_hint}\t{err}")
            err_count += 1
            continue
        issue, err = _send_issue_create(api_key, input_obj)
        if err:
            print(f"ERROR\t-\t{title_hint}\t{err}")
            err_count += 1
            continue
        print(f"OK\t{issue['identifier']}\t{issue['title']}")
        ok_count += 1

    if path != "-":
        stream.close()
    print(f"\n{ok_count} created, {err_count} failed.", file=sys.stderr)


# ---------------------------------------------------------------------------
# cycles (list)
# ---------------------------------------------------------------------------

def cmd_cycles(args, cfg, api_key, team_id):
    """List cycles (default) or create / update / delete one."""
    action = getattr(args, "cycles_action", None)
    if action == "create":
        return _cycle_create(args, api_key, team_id)
    if action == "update":
        return _cycle_update(args, api_key, team_id)
    if action == "delete":
        return _cycle_delete(args, api_key, team_id)

    cycles = list_team_cycles(api_key, team_id)
    if not cycles:
        print("No cycles found.")
        return

    if args.json:
        print(json.dumps(cycles, indent=2))
        return

    # Sort by startsAt descending (most recent first)
    cycles.sort(key=lambda c: c.get("startsAt") or "", reverse=True)

    # Find the currently-active cycle id so we can mark it in output.
    active_id = get_cycle_id(api_key, team_id, "active")
    next_id = get_cycle_id(api_key, team_id, "next")

    show_ids = getattr(args, "ids", False)

    # Format: status marker | name (number) | startsAt -> endsAt | issue count
    for c in cycles:
        cid = c.get("id")
        name = c.get("name") or f"Cycle {c.get('number')}"
        starts = (c.get("startsAt") or "")[:10]
        ends = (c.get("endsAt") or "")[:10]
        history = c.get("issueCountHistory") or []
        count = history[-1] if history else 0

        marker = "  "
        if cid == active_id:
            marker = "* "
        elif cid == next_id:
            marker = "> "
        elif c.get("completedAt"):
            marker = "- "

        id_str = f"  {cid}" if show_ids else ""
        print(f"{marker}{name:40s}  {starts} → {ends}  {count} issue(s){id_str}")

    print("\n(* = active, > = next, - = completed)")


def _cycle_create(args, api_key, team_id):
    """Create a cycle. Linear assigns the cycle number automatically."""
    input_obj = {
        "teamId": team_id,
        "name": args.name,
        "startsAt": cycle_date_to_iso(args.starts, "--starts"),
        "endsAt": cycle_date_to_iso(args.ends, "--ends"),
    }
    data = gql(api_key, """
        mutation($input: CycleCreateInput!) {
            cycleCreate(input: $input) {
                success
                cycle { id number name startsAt endsAt }
            }
        }
    """, {"input": input_obj})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("cycleCreate") or {}
    if not result.get("success"):
        print("Cycle create failed.", file=sys.stderr)
        sys.exit(1)
    c = result["cycle"]
    print(f"Created cycle {c.get('name') or c.get('number')}  "
          f"{(c.get('startsAt') or '')[:10]} → {(c.get('endsAt') or '')[:10]}  ({c['id']})")


def _cycle_update(args, api_key, team_id):
    node = resolve_cycle_by_value(api_key, team_id, args.cycle)
    if not node:
        sys.exit(1)
    input_obj = {}
    if args.name is not None:
        input_obj["name"] = args.name
    if args.starts is not None:
        input_obj["startsAt"] = cycle_date_to_iso(args.starts, "--starts")
    if args.ends is not None:
        input_obj["endsAt"] = cycle_date_to_iso(args.ends, "--ends")
    if not input_obj:
        print("Nothing to update. Use --name, --starts, or --ends.", file=sys.stderr)
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!, $input: CycleUpdateInput!) {
            cycleUpdate(id: $id, input: $input) {
                success
                cycle { id name startsAt endsAt }
            }
        }
    """, {"id": node["id"], "input": input_obj})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("cycleUpdate") or {}
    if not result.get("success"):
        print("Cycle update failed.", file=sys.stderr)
        sys.exit(1)
    c = result["cycle"]
    print(f"Updated cycle {c.get('name')}  "
          f"{(c.get('startsAt') or '')[:10]} → {(c.get('endsAt') or '')[:10]}  ({c['id']})")


def _cycle_delete(args, api_key, team_id):
    """Archive a cycle (Linear has no hard delete; cycleArchive is the removal)."""
    node = resolve_cycle_by_value(api_key, team_id, args.cycle)
    if not node:
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!) {
            cycleArchive(id: $id) { success }
        }
    """, {"id": node["id"]})
    if check_errors(data):
        sys.exit(1)
    if (data.get("data") or {}).get("cycleArchive", {}).get("success"):
        print(f"Archived cycle {node.get('name') or node['id']}.")
    else:
        print("Cycle delete failed.", file=sys.stderr)
        sys.exit(1)


# ---------------------------------------------------------------------------
# projects, labels, users (discovery)
# ---------------------------------------------------------------------------

def cmd_projects(args, cfg, api_key, team_id):
    """List projects (default), show one's detail + milestones, or create /
    archive / delete a project."""
    action = getattr(args, "projects_action", None)
    if action == "create":
        return _project_create(args, api_key, team_id)
    if action in ("archive", "delete"):
        return _project_delete(args, api_key, team_id)
    if action == "show":
        return _project_show(args, api_key, team_id)

    projects = list_team_projects(api_key, team_id)
    if not projects:
        print("No projects found.")
        return
    if args.json:
        print(json.dumps(projects, indent=2))
        return
    print(f"{len(projects)} project(s):")
    for p in projects:
        progress = int((p.get("progress") or 0) * 100)
        state = p.get("state") or "-"
        lead = (p.get("lead") or {}).get("name") or "-"
        count = int(p.get("scope") or 0)
        print(f"  {p['name']:40s}  {state:12s}  {progress:>3}%  "
              f"{count:>4} issue(s)  lead: {lead}")


def _project_show(args, api_key, team_id):
    """Detail view for one project. Accepts a UUID (queried directly) or a name
    with exact match preferred over substring, so 'Rush' stays addressable once
    'Rush App' / 'Rush CLI' also exist (RUSH-1497)."""
    value = args.name
    if len(value) == 36 and value.count("-") == 4:
        proj_id = value
    else:
        projects = list_team_projects(api_key, team_id)
        matches = [p for p in projects if p["name"].lower() == value.lower()]
        if not matches:
            matches = [p for p in projects if value.lower() in p["name"].lower()]
        if not matches:
            print(f"No project matching '{value}'.{_suggest(value, [p['name'] for p in projects])}")
            return
        if len(matches) > 1:
            print(f"Note: '{value}' matched {len(matches)} projects; "
                  f"showing '{matches[0]['name']}'. Use the exact name or id to disambiguate.",
                  file=sys.stderr)
        proj_id = matches[0]["id"]

    data = gql(api_key, """
        query($id: String!) {
            project(id: $id) {
                id name state progress scope
                description
                startDate targetDate
                lead { name email }
                projectMilestones(first: 50) {
                    nodes { id name description targetDate sortOrder }
                }
            }
        }
    """, {"id": proj_id})
    if check_errors(data):
        return
    proj = (data.get("data") or {}).get("project") or {}
    if not proj:
        print(f"No project with id '{proj_id}'.")
        return
    if args.json:
        print(json.dumps(proj, indent=2))
        return
    lead = (proj.get("lead") or {}).get("name") or "-"
    count = int(proj.get("scope") or 0)
    print(f"{proj['name']}")
    print(f"  State:    {proj.get('state', '-')}")
    print(f"  Progress: {int((proj.get('progress') or 0) * 100)}%")
    print(f"  Issues:   {count}")
    print(f"  Lead:     {lead}")
    print(f"  Start:    {proj.get('startDate') or '-'}")
    print(f"  Target:   {proj.get('targetDate') or '-'}")
    print(f"  ID:       {proj.get('id')}")
    milestones = (proj.get("projectMilestones") or {}).get("nodes", [])
    if milestones:
        milestones.sort(key=lambda m: m.get("sortOrder") or 0)
        print(f"\nMilestones ({len(milestones)}):")
        for m in milestones:
            tgt = m.get("targetDate") or "-"
            print(f"  - {m['name']:30s}  target: {tgt}")


def _project_create(args, api_key, team_id):
    """Create a project on the current team. Lead is resolved by email; start /
    target are TimelessDates (YYYY-MM-DD)."""
    input_obj = {"teamIds": [team_id], "name": args.name}
    if args.description is not None:
        input_obj["description"] = args.description
    if args.lead is not None:
        lead_id = resolve_user_id_by_email(api_key, args.lead.strip())
        if not lead_id:
            print(f"Lead '{args.lead}' not found (pass an email).", file=sys.stderr)
            sys.exit(1)
        input_obj["leadId"] = lead_id
    start = parse_timeless_date(args.start, "--start")
    if start:
        input_obj["startDate"] = start
    target = parse_timeless_date(args.target, "--target")
    if target:
        input_obj["targetDate"] = target
    data = gql(api_key, """
        mutation($input: ProjectCreateInput!) {
            projectCreate(input: $input) {
                success
                project { id name url }
            }
        }
    """, {"input": input_obj})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("projectCreate") or {}
    if not result.get("success"):
        print("Project create failed.", file=sys.stderr)
        sys.exit(1)
    p = result["project"]
    print(f"Created project '{p['name']}'  ({p['id']})")
    if p.get("url"):
        print(f"  {p['url']}")


def _project_delete(args, api_key, team_id):
    """Remove a project via projectDelete, which moves it to the workspace trash
    (recoverable in Linear's UI for ~30 days). Linear exposes no distinct
    'archive' mutation for projects, so `archive` and `delete` are the same
    operation — both trash the project."""
    try:
        pid = resolve_project_id(api_key, team_id, args.project, strict=True)
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!) { projectDelete(id: $id) { success } }
    """, {"id": pid})
    if check_errors(data) or not (data.get("data") or {}).get("projectDelete", {}).get("success"):
        print("Project remove failed.", file=sys.stderr)
        sys.exit(1)
    print(f"Removed project '{args.project}' (moved to trash; recoverable in Linear's UI).")


def cmd_milestones(args, cfg, api_key, team_id):
    """Manage project milestones: list, create, move, set-target-date, delete."""
    action = getattr(args, "milestones_action", None)
    if action == "create":
        return _milestone_create(args, api_key, team_id)
    if action == "move":
        return _milestone_move(args, api_key, team_id)
    if action == "set-target-date":
        return _milestone_set_target(args, api_key, team_id)
    if action == "delete":
        return _milestone_delete(args, api_key, team_id)
    if action == "list":
        return _milestone_list(args, api_key, team_id)
    print("Specify a subcommand: list <project> | create | move | "
          "set-target-date | delete.  See `linear milestones --help`.",
          file=sys.stderr)
    sys.exit(1)


def _milestone_list(args, api_key, team_id):
    """List a project's milestones (sorted by sortOrder)."""
    try:
        pid = resolve_project_id(api_key, team_id, args.project, strict=True)
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    data = gql(api_key, """
        query($id: String!) {
            project(id: $id) {
                name
                projectMilestones(first: 100) {
                    nodes { id name description targetDate sortOrder }
                }
            }
        }
    """, {"id": pid})
    if check_errors(data):
        return
    proj = (data.get("data") or {}).get("project") or {}
    nodes = (proj.get("projectMilestones") or {}).get("nodes", [])
    nodes.sort(key=lambda m: m.get("sortOrder") or 0)
    if args.json:
        print(json.dumps(nodes, indent=2))
        return
    if not nodes:
        print(f"No milestones in '{proj.get('name', args.project)}'.")
        return
    print(f"{len(nodes)} milestone(s) in '{proj.get('name', args.project)}':")
    for m in nodes:
        tgt = m.get("targetDate") or "-"
        print(f"  {m['name']:30s}  target: {tgt:12s}  {m['id']}")


def _milestone_create(args, api_key, team_id):
    try:
        pid = resolve_project_id(api_key, team_id, args.project, strict=True)
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    input_obj = {"projectId": pid, "name": args.name}
    target = parse_timeless_date(args.target, "--target")
    if target:
        input_obj["targetDate"] = target
    if args.description is not None:
        input_obj["description"] = args.description
    data = gql(api_key, """
        mutation($input: ProjectMilestoneCreateInput!) {
            projectMilestoneCreate(input: $input) {
                success
                projectMilestone { id name targetDate }
            }
        }
    """, {"input": input_obj})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("projectMilestoneCreate") or {}
    if not result.get("success"):
        print("Milestone create failed.", file=sys.stderr)
        sys.exit(1)
    m = result["projectMilestone"]
    tgt = m.get("targetDate") or "no target"
    print(f"Created milestone '{m['name']}'  (target: {tgt})  ({m['id']})")


def _milestone_move(args, api_key, team_id):
    """Move a milestone to another project via projectMilestoneUpdate(projectId)."""
    src = None
    if getattr(args, "from_project", None):
        try:
            src = resolve_project_id(api_key, team_id, args.from_project, strict=True)
        except LookupError as e:
            print(f"Error: {e}", file=sys.stderr)
            sys.exit(1)
    try:
        mid = resolve_milestone_id(api_key, team_id, args.milestone, src, strict=True)
        dest = resolve_project_id(api_key, team_id, args.to, strict=True)
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!, $input: ProjectMilestoneUpdateInput!) {
            projectMilestoneUpdate(id: $id, input: $input) {
                success
                projectMilestone { id name project { name } }
            }
        }
    """, {"id": mid, "input": {"projectId": dest}})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("projectMilestoneUpdate") or {}
    if not result.get("success"):
        print("Milestone move failed.", file=sys.stderr)
        sys.exit(1)
    m = result["projectMilestone"]
    proj = (m.get("project") or {}).get("name") or args.to
    print(f"Moved milestone '{m['name']}' -> project '{proj}'.")


def _milestone_set_target(args, api_key, team_id):
    """Set (or clear, with 'none') a milestone's target date — the reliable path
    that the web date-picker fought during the reorg (RUSH-1495)."""
    scope = None
    if getattr(args, "project", None):
        try:
            scope = resolve_project_id(api_key, team_id, args.project, strict=True)
        except LookupError as e:
            print(f"Error: {e}", file=sys.stderr)
            sys.exit(1)
    try:
        mid = resolve_milestone_id(api_key, team_id, args.milestone, scope, strict=True)
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    target = parse_timeless_date(args.date, "target date")  # None when 'none'
    data = gql(api_key, """
        mutation($id: String!, $input: ProjectMilestoneUpdateInput!) {
            projectMilestoneUpdate(id: $id, input: $input) {
                success
                projectMilestone { id name targetDate }
            }
        }
    """, {"id": mid, "input": {"targetDate": target}})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("projectMilestoneUpdate") or {}
    if not result.get("success"):
        print("Set target date failed.", file=sys.stderr)
        sys.exit(1)
    m = result["projectMilestone"]
    print(f"Set '{m['name']}' target date -> {m.get('targetDate') or 'cleared'}.")


def _milestone_delete(args, api_key, team_id):
    scope = None
    if getattr(args, "project", None):
        try:
            scope = resolve_project_id(api_key, team_id, args.project, strict=True)
        except LookupError as e:
            print(f"Error: {e}", file=sys.stderr)
            sys.exit(1)
    try:
        mid = resolve_milestone_id(api_key, team_id, args.milestone, scope, strict=True)
    except LookupError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!) { projectMilestoneDelete(id: $id) { success } }
    """, {"id": mid})
    if check_errors(data):
        sys.exit(1)
    if (data.get("data") or {}).get("projectMilestoneDelete", {}).get("success"):
        print(f"Deleted milestone '{args.milestone}'.")
    else:
        print("Milestone delete failed.", file=sys.stderr)
        sys.exit(1)


def cmd_labels(args, cfg, api_key, team_id):
    """List labels (default) or create / update / delete one."""
    action = getattr(args, "labels_action", None)
    if action == "create":
        return _label_create(args, api_key, team_id)
    if action == "update":
        return _label_update(args, api_key, team_id)
    if action == "delete":
        return _label_delete(args, api_key, team_id)

    labels = list_team_labels(api_key, team_id)
    labels.sort(key=lambda l: l["name"].lower())
    if args.json:
        print(json.dumps(labels, indent=2))
        return
    print(f"{len(labels)} label(s):")
    for l in labels:
        desc = l.get("description") or ""
        print(f"  {l['name']:30s}  {desc}")


def _label_create(args, api_key, team_id):
    input_obj = {"teamId": team_id, "name": args.name}
    if args.color is not None:
        input_obj["color"] = args.color
    if args.description is not None:
        input_obj["description"] = args.description
    data = gql(api_key, """
        mutation($input: IssueLabelCreateInput!) {
            issueLabelCreate(input: $input) {
                success
                issueLabel { id name color }
            }
        }
    """, {"input": input_obj})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("issueLabelCreate") or {}
    if not result.get("success"):
        print("Label create failed.", file=sys.stderr)
        sys.exit(1)
    l = result["issueLabel"]
    print(f"Created label '{l['name']}'  ({l['id']})")


def _label_update(args, api_key, team_id):
    node = resolve_label_by_value(api_key, team_id, args.label)
    if not node:
        sys.exit(1)
    input_obj = {}
    if args.name is not None:
        input_obj["name"] = args.name
    if args.color is not None:
        input_obj["color"] = args.color
    if args.description is not None:
        input_obj["description"] = args.description
    if not input_obj:
        print("Nothing to update. Use --name, --color, or --description.", file=sys.stderr)
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!, $input: IssueLabelUpdateInput!) {
            issueLabelUpdate(id: $id, input: $input) {
                success
                issueLabel { id name }
            }
        }
    """, {"id": node["id"], "input": input_obj})
    if check_errors(data):
        sys.exit(1)
    result = (data.get("data") or {}).get("issueLabelUpdate") or {}
    if not result.get("success"):
        print("Label update failed.", file=sys.stderr)
        sys.exit(1)
    print(f"Updated label '{node.get('name')}' -> '{result['issueLabel']['name']}'")


def _label_delete(args, api_key, team_id):
    node = resolve_label_by_value(api_key, team_id, args.label)
    if not node:
        sys.exit(1)
    data = gql(api_key, """
        mutation($id: String!) {
            issueLabelDelete(id: $id) { success }
        }
    """, {"id": node["id"]})
    if check_errors(data):
        sys.exit(1)
    if (data.get("data") or {}).get("issueLabelDelete", {}).get("success"):
        print(f"Deleted label '{node.get('name') or node['id']}'.")
    else:
        print("Label delete failed.", file=sys.stderr)
        sys.exit(1)


def cmd_users(args, cfg, api_key, team_id):
    """List workspace members, grouped into humans (assign with --assign) and
    agents (delegate with --delegate) — the two are distinct in Linear."""
    users = list_workspace_users(api_key)
    if args.json:
        users.sort(key=lambda u: u["name"].lower())
        print(json.dumps(users, indent=2))
        return
    humans = sorted((u for u in users if not u.get("app")), key=lambda u: u["name"].lower())
    agents = sorted((u for u in users if u.get("app")), key=lambda u: u["name"].lower())
    print(f"Humans ({len(humans)})  — assign with --assign <email or name>:")
    for u in humans:
        print(f"  {u['name']:25s}  {u.get('email') or '-'}")
    print(f"\nAgents ({len(agents)})  — delegate with --delegate <name>:")
    for u in agents:
        print(f"  {u['name']:25s}  (app user)")


def cmd_states(args, cfg, api_key, team_id):
    """List the team's workflow states — the valid values for --status / --done.

    Without this, agents guess state names and only learn they were wrong when a
    mutation fails. Bypasses the cfg cache so the list is always current.
    """
    fresh = {**cfg, "states": None}
    states = get_states(api_key, team_id, fresh)
    if not states:
        return
    # Order by workflow type, then name, so the progression reads top-to-bottom.
    type_order = {"backlog": 0, "unstarted": 1, "started": 2, "completed": 3, "canceled": 4}
    items = sorted(states.items(), key=lambda kv: (type_order.get(kv[1]["type"], 9), kv[0]))
    if args.json:
        print(json.dumps(
            [{"name": name, "type": meta["type"], "id": meta["id"]} for name, meta in items],
            indent=2,
        ))
        return
    print(f"{len(items)} workflow state(s):")
    for name, meta in items:
        print(f"  {name:20s}  {meta['type']}")


def cmd_agents(args, cfg, api_key, team_id):
    """List the workspace's agent members — the app users you can `--delegate` to.

    Auto-detected from Linear (the `app` user flag), cached, and refreshed every
    6h. `--refresh` forces an immediate re-fetch — run it after installing or
    removing an agent app so the roster (and `--delegate <name>`) stays current.
    """
    agents = get_agents(api_key, cfg, force=args.refresh)
    if args.json:
        print(json.dumps(agents, indent=2))
        return
    if not agents:
        print("No agent members found. Install agent apps in Linear "
              "(Settings -> API -> Applications), then: linear agents --refresh")
        return
    print(f"{len(agents)} agent(s)  (auto-refreshes every 6h; --refresh to force):")
    for a in agents:
        print(f"  {a['name']:20s}  delegate: linear update <ID> --delegate {a['name'].lower()}")


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------

def main():
    parser = argparse.ArgumentParser(
        prog="linear",
        description="Task management CLI for AI agent teams",
    )
    parser.add_argument("--version", action="version", version=f"linear-cli {__version__}")
    parser.add_argument("--team", default=None,
                        help="Override team for this invocation (key like 'ANT' or UUID)")
    sub = parser.add_subparsers(dest="command")

    # setup
    p_setup = sub.add_parser("setup", help="Configure Linear connection and agent identity")
    p_setup.add_argument("--api-key", help="Linear API key")
    p_setup.add_argument("--agent", help="Default agent identity")

    # tasks (list + view + board)
    p_tasks = sub.add_parser("tasks", help="List tasks, view details, or show team board")
    p_tasks.add_argument("identifier", nargs="?", help="Issue identifier for detail view (e.g. ANT-42)")
    p_tasks.add_argument("--agent", help="Filter by agent label (e.g. --agent claude)")
    p_tasks.add_argument("--all", action="store_true", help="Ignore default agent filter, show all")
    p_tasks.add_argument("--board", action="store_true", help="Team board grouped by agent")
    p_tasks.add_argument("--label", help="Filter by any label")
    p_tasks.add_argument("--status", help="Filter: backlog, todo, progress, done, open")
    p_tasks.add_argument("--cycle", default="active", metavar="SCOPE",
                         help="Scope: active (default), next, all (whole team, "
                              "cross-cycle + backlog), none/backlog (no cycle), "
                              "or a specific cycle by name or id")
    p_tasks.add_argument("--since", metavar="YYYY-MM-DD",
                         help="Only issues created on or after this date")
    p_tasks.add_argument("--assignee",
                         help="Filter by assignee: email, 'me', or 'none' (unassigned)")
    p_tasks.add_argument("--query", help="Search title + description (case-insensitive)")
    p_tasks.add_argument("--json", action="store_true", help="JSON output")

    # update (all mutations on one or many issues)
    p_update = sub.add_parser("update", help="Update one or many issues (status, comment, ...)")
    p_update.add_argument("identifier", nargs="*",
                          help="Issue identifier(s), e.g. ANT-42 ANT-43. "
                               "Omit and use --stdin to pipe ids.")
    p_update.add_argument("--stdin", action="store_true",
                          help="Read additional identifiers (whitespace-separated) from stdin")
    status_group = p_update.add_mutually_exclusive_group()
    status_group.add_argument("--done", action="store_true", help="Mark Done")
    status_group.add_argument("--pickup", action="store_true", help="Mark In Progress")
    status_group.add_argument("--todo", action="store_true", help="Mark Todo")
    status_group.add_argument("--status", help="Move to any state by name")
    p_update.add_argument("--comment", help="Add a comment")
    p_update.add_argument("--proof", action="append",
                          help="Proof of completion (repeatable). File path, URL, or text.")
    p_update.add_argument("--label", action="append", help="Add label(s) (repeatable)")
    p_update.add_argument("--unlabel", action="append",
                          help="Remove label(s) (repeatable)")
    p_update.add_argument("--priority", type=str, default=None,
                          help="urgent, high, medium, low, or none")
    p_update.add_argument("--assign", default=None,
                          help="Reassign to a human by email or name, or 'none' to unassign")
    p_update.add_argument("--delegate", default=None,
                          help="Delegate to an agent by name (e.g. --delegate claude); "
                               "'none' to clear. See: linear agents")
    p_update.add_argument("--parent", default=None,
                          help="Set parent issue (e.g. ANT-42), or 'none' to detach")
    p_update.add_argument("--project", default=None,
                          help="Move to project (name or ID), or 'none' to detach")
    p_update.add_argument("--milestone", default=None,
                          help="Set milestone (name), or 'none' to detach")
    p_update.add_argument("--title", default=None, help="Rename the issue")
    p_update.add_argument("--description", default=None,
                          help="Replace the issue description")
    p_update.add_argument("--description-file", dest="description_file", default=None,
                          help="Read description from a file path, or '-' for stdin")
    p_update.add_argument("--due-date", dest="due_date",
                          help="Set due date (YYYY-MM-DD), or 'none' to clear")
    p_update.add_argument("--cycle", choices=["active", "next", "none"],
                          help="Move issue: active cycle, next cycle, or remove from cycle")
    p_update.add_argument("--blocks", action="append",
                          help="Mark this issue as blocking another (e.g. ANT-42). Repeatable.")
    p_update.add_argument("--blocked-by", dest="blocked_by", action="append",
                          help="Mark this issue as blocked by another (e.g. ANT-42). Repeatable.")
    p_update.add_argument("--relates", action="append",
                          help="Mark a non-blocking 'related' link to another issue. Repeatable.")

    # create
    p_create = sub.add_parser("create", help="Create a new issue")
    p_create.add_argument("title", nargs="?", default=None,
                          help="Issue title (optional if --description provided)")
    p_create.add_argument("--label", action="append", help="Label(s) to add (repeatable)")
    p_create.add_argument("--priority", type=str, default=None,
                          help="urgent, high, medium (default), low, or none")
    p_create.add_argument("--description", help="Issue description")
    p_create.add_argument("--description-file", dest="description_file", default=None,
                          help="Read description from a file path, or '-' for stdin")
    p_create.add_argument("--status", help="Initial status (default: Todo)")
    p_create.add_argument("--cycle", default="active",
                          choices=["active", "next", "none"],
                          help="Cycle assignment (default: active)")
    p_create.add_argument("--due-date", dest="due_date",
                          help="Due date (YYYY-MM-DD)")
    p_create.add_argument("--assign", default=None,
                          help="Assign to a human by email or name, or 'none' (default: API key owner)")
    p_create.add_argument("--delegate", default=None,
                          help="Delegate the new issue to an agent by name (e.g. --delegate claude)")
    p_create.add_argument("--from-file", dest="from_file", default=None,
                          help="Bulk create from JSONL (one issue per line). '-' for stdin.")
    p_create.add_argument("--parent", default=None,
                          help="Parent issue identifier for sub-issues (e.g. ANT-42)")
    p_create.add_argument("--project", default=None,
                          help="Project name or ID")
    p_create.add_argument("--milestone", default=None,
                          help="Project milestone name (resolved within --project if set)")

    # cycles (list / create / update / delete)
    p_cycles = sub.add_parser("cycles", help="List, create, update, or delete cycles")
    p_cycles.add_argument("--json", action="store_true", help="JSON output")
    p_cycles.add_argument("--ids", action="store_true", help="Show cycle IDs in the plain list")
    cyc_sub = p_cycles.add_subparsers(dest="cycles_action")
    c_create = cyc_sub.add_parser("create", help="Create a cycle")
    c_create.add_argument("--name", required=True, help="Cycle name")
    c_create.add_argument("--starts", required=True, metavar="YYYY-MM-DD", help="Start date")
    c_create.add_argument("--ends", required=True, metavar="YYYY-MM-DD", help="End date")
    c_update = cyc_sub.add_parser("update", help="Update a cycle (by id or name)")
    c_update.add_argument("cycle", help="Cycle id, number, or name")
    c_update.add_argument("--name", default=None, help="New name")
    c_update.add_argument("--starts", default=None, metavar="YYYY-MM-DD", help="New start date")
    c_update.add_argument("--ends", default=None, metavar="YYYY-MM-DD", help="New end date")
    c_delete = cyc_sub.add_parser("delete", help="Archive a cycle (by id or name)")
    c_delete.add_argument("cycle", help="Cycle id, number, or name")

    # projects (list / show / create / archive / delete)
    p_projects = sub.add_parser("projects",
                                help="List, show, create, archive, or delete projects")
    p_projects.add_argument("--json", action="store_true", help="JSON output (list)")
    proj_sub = p_projects.add_subparsers(dest="projects_action")
    ps_show = proj_sub.add_parser("show", help="Show a project's detail + milestones")
    ps_show.add_argument("name", help="Project name (exact match preferred) or id")
    # SUPPRESS: when absent, don't overwrite a parent `projects --json` (the shim
    # can place --json before the injected `show`); when present, still sets json.
    ps_show.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
                         help="JSON output")
    ps_create = proj_sub.add_parser("create", help="Create a project")
    ps_create.add_argument("--name", required=True, help="Project name")
    ps_create.add_argument("--description", default=None, help="Project description")
    ps_create.add_argument("--lead", default=None, metavar="EMAIL", help="Lead by email")
    ps_create.add_argument("--start", default=None, metavar="YYYY-MM-DD", help="Start date")
    ps_create.add_argument("--target", default=None, metavar="YYYY-MM-DD", help="Target date")
    ps_archive = proj_sub.add_parser("archive", aliases=["delete"],
                                     help="Remove a project (moves to trash; recoverable in Linear's UI)")
    ps_archive.add_argument("project", help="Project name or id")

    # milestones (list / create / move / set-target-date / delete)
    p_ms = sub.add_parser("milestones",
                          help="List, create, move, retarget, or delete project milestones")
    p_ms.add_argument("--json", action="store_true", help="JSON output")
    ms_sub = p_ms.add_subparsers(dest="milestones_action")
    ms_list = ms_sub.add_parser("list", help="List a project's milestones")
    ms_list.add_argument("project", help="Project name or id")
    ms_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
                         help="JSON output")
    ms_create = ms_sub.add_parser("create", help="Create a milestone in a project")
    ms_create.add_argument("--project", required=True, help="Project name or id")
    ms_create.add_argument("--name", required=True, help="Milestone name")
    ms_create.add_argument("--target", default=None, metavar="YYYY-MM-DD", help="Target date")
    ms_create.add_argument("--description", default=None, help="Milestone description")
    ms_move = ms_sub.add_parser("move", help="Move a milestone to another project")
    ms_move.add_argument("milestone", help="Milestone name or id")
    ms_move.add_argument("--to", required=True, dest="to", help="Destination project name or id")
    ms_move.add_argument("--from", default=None, dest="from_project",
                         help="Source project to disambiguate a same-named milestone")
    ms_target = ms_sub.add_parser("set-target-date", help="Set or clear a milestone's target date")
    ms_target.add_argument("milestone", help="Milestone name or id")
    ms_target.add_argument("date", help="YYYY-MM-DD, or 'none' to clear")
    ms_target.add_argument("--project", default=None, help="Project to disambiguate the milestone")
    ms_delete = ms_sub.add_parser("delete", help="Delete a milestone")
    ms_delete.add_argument("milestone", help="Milestone name or id")
    ms_delete.add_argument("--project", default=None, help="Project to disambiguate the milestone")

    # labels (list / create / update / delete)
    p_labels = sub.add_parser("labels", help="List, create, update, or delete labels")
    p_labels.add_argument("--json", action="store_true", help="JSON output")
    lbl_sub = p_labels.add_subparsers(dest="labels_action")
    l_create = lbl_sub.add_parser("create", help="Create a label")
    l_create.add_argument("name", help="Label name")
    l_create.add_argument("--color", default=None, metavar="#RRGGBB", help="Hex color")
    l_create.add_argument("--description", default=None, help="Label description")
    l_update = lbl_sub.add_parser("update", help="Update a label (by id or name)")
    l_update.add_argument("label", help="Label id or name")
    l_update.add_argument("--name", default=None, help="New name")
    l_update.add_argument("--color", default=None, metavar="#RRGGBB", help="New hex color")
    l_update.add_argument("--description", default=None, help="New description")
    l_delete = lbl_sub.add_parser("delete", help="Delete a label (by id or name)")
    l_delete.add_argument("label", help="Label id or name")

    # users
    p_users = sub.add_parser("users", help="List assignable users")
    p_users.add_argument("--json", action="store_true", help="JSON output")

    # agents (app users you can delegate to; auto-detected + cached)
    p_agents = sub.add_parser("agents", help="List agent members you can --delegate to")
    p_agents.add_argument("--refresh", action="store_true",
                          help="Force an immediate re-fetch (after installing/removing an agent app)")
    p_agents.add_argument("--json", action="store_true", help="JSON output")

    # states (workflow states for the team)
    p_states = sub.add_parser("states", help="List the team's workflow states")
    p_states.add_argument("--json", action="store_true", help="JSON output")

    # Back-compat + ergonomics: `projects <name>` (a bare name, not a verb) is
    # shorthand for `projects show <name>`. Insert the implicit `show` so the
    # detail view keeps working alongside the create/archive/delete subcommands.
    argv = sys.argv[1:]
    if len(argv) >= 2 and argv[0] == "projects":
        _proj_verbs = {"show", "create", "archive", "delete"}
        for _i in range(1, len(argv)):
            if not argv[_i].startswith("-"):
                if argv[_i] not in _proj_verbs:
                    argv = argv[:_i] + ["show"] + argv[_i:]
                break
    args = parser.parse_args(argv)

    if not args.command:
        parser.print_help()
        sys.exit(0)

    cfg = load_config()

    if args.command == "setup":
        cmd_setup(args, cfg)
        return

    # All other commands need credentials
    api_key = get_api_key(cfg)
    team_id = get_team_id(cfg)

    if not api_key:
        print("No API key configured. Run: linear setup", file=sys.stderr)
        sys.exit(1)

    if args.team:
        override = resolve_team_id_by_key(api_key, args.team)
        if not override:
            sys.exit(1)
        team_id = override
        # Use a volatile cfg copy — don't pollute on-disk config with the
        # other team's states cache.
        cfg = {**cfg, "states": {}, "__volatile__": True}

    if not team_id:
        print("No team configured. Run: linear setup", file=sys.stderr)
        sys.exit(1)

    if args.command == "tasks":
        cmd_tasks(args, cfg, api_key, team_id)
    elif args.command == "update":
        cmd_update(args, cfg, api_key, team_id)
    elif args.command == "create":
        cmd_create(args, cfg, api_key, team_id)
    elif args.command == "cycles":
        cmd_cycles(args, cfg, api_key, team_id)
    elif args.command == "projects":
        cmd_projects(args, cfg, api_key, team_id)
    elif args.command == "milestones":
        cmd_milestones(args, cfg, api_key, team_id)
    elif args.command == "labels":
        cmd_labels(args, cfg, api_key, team_id)
    elif args.command == "users":
        cmd_users(args, cfg, api_key, team_id)
    elif args.command == "agents":
        cmd_agents(args, cfg, api_key, team_id)
    elif args.command == "states":
        cmd_states(args, cfg, api_key, team_id)


if __name__ == "__main__":
    main()