taskops-cli 0.2.0__py3-none-any.whl

taskops/usecases/_mirroring.py

@@ -0,0 +1,57 @@
+"""Bringing the local board level with a write that happened on the server.
+
+The pull that follows a remote write carries the EVENTS, and events are enough for most of
+what a board shows — but not for a claim. `engine.replay` deliberately does not materialise
+leases: importing one would mean claiming a task on behalf of an agent running on another
+machine, which is the opposite of what this whole feature is for. So a pull alone leaves the
+winner's own board saying `ready`, and the commit guard reads that board — it refuses a commit
+from an actor with no live lease HERE. The agent would have won the race and then been told it
+had never claimed anything.
+
+What is safe is narrower than what replay refuses, and this module is exactly that narrow: the
+only lease written here is the one the server just GRANTED TO THIS CALLER, handed back in the
+answer. It is not inferred from somebody else's event; it is the receipt for a claim this
+machine made a moment ago. Everything else about other agents' claims still stays out.
+
+The result is also applied verbatim rather than recomputed: the timestamps are the server's, so
+a later status event from that same server is still newer than what is written here and replays
+normally. Stamping `now()` instead would silently make the local row look newer than the server
+it came from, and every subsequent pull would decline to update it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..contracts import Claim, Task
+from ._project import project
+
+__all__ = ["mirror_claim", "mirror_update"]
+
+_LEASE_ENDS = ("ready", "done", "cancelled")
+
+
+def mirror_claim(start: Path | str, claim: Claim) -> None:
+    """Record the lease the server granted, and put the card in `claimed` here too."""
+    lease = claim["lease"]
+    with project(start) as store:
+        if store.tasks.get(lease["task"]) is None:
+            return
+        store.leases.release(lease["task"])
+        store.leases.acquire(lease)
+        store.tasks.set_status(lease["task"], "claimed", when=lease["acquired"])
+
+
+def mirror_update(start: Path | str, task: Task) -> None:
+    """Take the task exactly as the server returned it, and drop the lease if it ended.
+
+    The status is copied rather than replayed because this caller has the authoritative row
+    in its hands; the lease has to be dropped here because releasing one is local state and
+    `replay` has no business writing it, so nothing else would ever clear it.
+    """
+    with project(start) as store:
+        if store.tasks.get(task["id"]) is None:
+            return
+        store.tasks.set_status(task["id"], task["status"], when=task["updated"])
+        if task["status"] in _LEASE_ENDS:
+            store.leases.release(task["id"])

taskops/usecases/_narrating.py

@@ -0,0 +1,77 @@
+"""The narration reaching the FILE while it is still being written.
+
+The first version wrote the prose once, at the end. On a day that is one reading that is
+thirty seconds of `_pendiente_`; on `report all`, which narrates in several passes, it is a
+quarter of an hour during which the file on disk is indistinguishable from one nobody ever
+narrated — and if the process dies at minute fourteen, that is exactly what it becomes.
+
+So the text is flushed as it arrives: every `FLUSH_CHARS` of prose, and at every pass
+boundary. A flush is a whole-file rewrite through `render.narrated`, which is the same call
+the final write makes, so a partial file is never a different SHAPE of file — only a shorter
+one. Nothing here decides anything; it is the writing half of `dossier.digest`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..engine import OnPass, OnText
+from ..render import narrated
+
+__all__ = ["Progressive", "FLUSH_CHARS"]
+
+FLUSH_CHARS = 400
+"""Prose written since the last flush before the file is rewritten. Roughly a paragraph.
+
+A report is tens of kilobytes and a narration arrives over minutes, so this is a handful of
+rewrites per pass — cheap enough to ignore, frequent enough that a person watching the file
+sees it grow rather than jump.
+"""
+
+
+class Progressive:
+    """Wraps a caller's callbacks so the same deltas also land on disk as they arrive."""
+
+    def __init__(self, path: Path, report: str, *,
+                 on_pass: OnPass = None, on_text: OnText = None) -> None:
+        self._path = path
+        self._report = report
+        self._on_pass = on_pass
+        self._on_text = on_text
+        self._written: list[str] = []
+        self._chars = 0
+        self._flushed = 0
+
+    def text(self, delta: str) -> None:
+        """A fragment: keep it, pass it on, and flush once enough has piled up."""
+        self._written.append(delta)
+        self._chars += len(delta)
+        if self._on_text:
+            self._on_text(delta)
+        if self._chars - self._flushed >= FLUSH_CHARS:
+            self.flush()
+
+    def passed(self, n: int, total: int) -> None:
+        """A pass is starting, so the previous one is complete — the natural moment to flush."""
+        self.flush()
+        if self._on_pass:
+            self._on_pass(n, total)
+
+    def finish(self, prose: str) -> Path:
+        """The FINAL write, from the text `narrate` returned rather than from the fragments.
+
+        Not the same string as the last flush, and that is why this exists: a multi-pass
+        narration returns the STITCHED reading, not the concatenation of the slices somebody
+        watched go by. The partial file is a live view; this is the document.
+        """
+        self._path.write_text(narrated(self._report, prose), encoding="utf-8")
+        return self._path
+
+    def flush(self) -> None:
+        """The report as it stands, narrated with the prose so far. A no-op before the first
+        delta, because a file whose narration section is empty reads as a taskops bug."""
+        prose = "".join(self._written)
+        if not prose.strip():
+            return
+        self._path.write_text(narrated(self._report, prose), encoding="utf-8")
+        self._flushed = self._chars

taskops/usecases/_project.py

@@ -0,0 +1,67 @@
+"""Opening the project, and the heartbeat every call pays for.
+
+Two things every use case needs and none of them should re-derive:
+
+**The root.** Callers pass whatever path they happen to be in — an agent its cwd, a
+git hook wherever git ran it — so resolution walks up for `.taskops/` exactly once,
+here.
+
+**The heartbeat.** Any taskops call an agent makes is proof it is alive, so every
+call renews that agent's leases. This is what makes the TTL bound a CRASH rather
+than a slow task: an agent working for an hour keeps its claim without doing anything
+special, and one whose process died stops renewing within a single call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from .._clock import LEASE_TTL, now
+from ..contracts import Actor
+from ..engine import identity, sweep_dead
+from ..storage import Store, resolve_root
+
+__all__ = ["project", "caller", "heartbeat", "locate"]
+
+
+def locate(start: Path | str) -> Path:
+    """Which project a path belongs to. Raises `NotInitialized` naming the fix.
+
+    Exported because the studio needs the root BEFORE it opens a port — it serves one repository,
+    and binding to a directory with no project would be a server that answers every request with
+    the same error. A transport may not call `storage.resolve_root` itself (an invariant test says
+    so, and it caught exactly this), so the resolution is a use case like any other.
+    """
+    return resolve_root(start)
+
+
+@contextmanager
+def project(start: Path | str) -> Generator[Store]:
+    """An open Store on the project containing `start`. Commits on a clean exit."""
+    with Store(resolve_root(start)) as store:
+        yield store
+
+
+def caller(store: Store, asked: str = "") -> Actor:
+    """Who is calling. Resolved from the argument, the environment, then git."""
+    return identity.resolve(store.root, asked)
+
+
+def heartbeat(store: Store, actor: str, *, at: float | None = None) -> None:
+    """Push this actor's LIVE lease deadlines out, and expire every dead one.
+
+    Both halves belong together: the sweep is what makes another agent's crash
+    visible, and running it on every call means no daemon has to exist to notice one.
+
+    An already-expired lease is NOT revived, and that is the important case. By the
+    time it lapsed another agent may have claimed the task, so quietly handing it
+    back would produce two holders and no error. The late agent instead finds out at
+    its next write, where the lease guard names the fix — which is the one path that
+    cannot end with two agents editing the same files believing they own them.
+    """
+    when = now() if at is None else at
+    for lease in store.leases.of_actor(actor, when):
+        store.leases.renew(task_id=lease["task"], actor=actor, expires=when + LEASE_TTL)
+    sweep_dead(store, at=when)

taskops/usecases/_range.py

@@ -0,0 +1,102 @@
+"""Which days a report covers — the selector a human types, resolved to two dates.
+
+Four ways of saying the same thing (one day, the last N, an explicit span, everything) and
+ONE place that turns any of them into `from_date, to_date`. That is deliberate: the dossier
+writer needs the same answer as the reader, and a second resolution is how a file named
+`2026-07-22..2026-07-28.md` ends up holding a different week.
+
+Strict, like `parse_window` and `parse_date`. A selector nobody can read is REFUSED and never
+widened to something plausible: a report quietly covering the wrong month looks exactly like
+a correct one, and it is the shape somebody pastes into a review.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from .._clock import now
+from .._errors import BadRequest
+from ..engine import date_of, first_date, shift
+from ..storage import Store
+
+__all__ = ["is_day", "Selector", "resolve", "parse_date"]
+
+_UNITS = {"d": 1, "w": 7}
+
+
+class Selector(NamedTuple):
+    """What the caller asked for, before a store is open. Defaults to today."""
+
+    date: str = ""
+    """The START of the window, or the whole of it when nothing else is set: `today`,
+    `yesterday`, or `YYYY-MM-DD` — whatever `parse_date` accepts."""
+
+    to: str = ""
+    """The last day, INCLUSIVE. Empty means today for a range, and `date` for a single day."""
+
+    last: str = ""
+    """`7d`, `2w`, `1m` — a span ending at `to`."""
+
+    whole: bool = False
+    """`report all`: from the log's first event to today."""
+
+
+def resolve(store: Store, sel: Selector) -> tuple[str, str, str]:
+    """`Selector` -> the two dates a `period_report` runs between, and what to call them.
+
+    Order matters: `whole` wins, then `last`, then an explicit pair, then the single day.
+    They are not combinable, and letting one silently override another inside a report would
+    be worse than the argument parser refusing the combination up front.
+
+    `all` is labelled `all` and not by its dates on purpose: it is a standing name for "the
+    whole project", so `report all --digest` keeps updating ONE file instead of leaving a
+    trail of near-identical ones whose end date happens to differ.
+    """
+    if sel.whole:
+        return first_date(store), parse_date(sel.to), "all"
+    if sel.last:
+        end = parse_date(sel.to)
+        return _back(end, sel.last), end, ""
+    if sel.to:
+        return parse_date(sel.date), parse_date(sel.to), ""
+    return parse_date(sel.date), parse_date(sel.date), ""
+
+
+def _back(end: str, last: str) -> str:
+    """`2026-07-28`, `7d` -> `2026-07-22`. INCLUSIVE of both ends: `7d` is seven days of
+    work, not seven days ago plus today, which would be eight."""
+    raw = last.strip().lower()
+    number, unit = raw[:-1], raw[-1:]
+    if not number.isdigit() or int(number) <= 0 or unit not in (*_UNITS, "m"):
+        raise BadRequest(f"`{last}` is not a span — use a positive number then d, w or m, "
+                         f"e.g. 7d, 2w or 1m")
+    if unit == "m":
+        return shift(shift(end, months=-int(number)), days=1)
+    return shift(end, days=1 - int(number) * _UNITS[unit])
+
+
+def parse_date(text: str) -> str:
+    """`yesterday` -> `2026-07-27`. Strict, for the same reason `parse_window` is.
+
+    `yesterday` is 24 hours back read as a LOCAL date rather than "today minus one" in
+    arithmetic on a date, which would have to know how long a month is. The calendar is
+    libc's problem, and libc is the only one that knows about the two days a year that are
+    not 24 hours long.
+    """
+    raw = text.strip().lower()
+    if raw in ("", "today"):
+        return date_of(now())
+    if raw == "yesterday":
+        return date_of(now() - 86400.0)
+    if len(raw) == 10 and raw[4] == "-" and raw[7] == "-" and raw.replace("-", "").isdigit():
+        return raw
+    raise BadRequest(f"`{text}` is not a day — use `today`, `yesterday`, or a date "
+                     f"like 2026-07-28")
+
+
+def is_day(label: str) -> bool:
+    """Whether a report label names one calendar day. The ONE place this shape is read:
+    the index and the report reader both branch on it, and two copies is how one of them
+    keeps accepting a shape the other started refusing."""
+    return (len(label) == 10 and label[4] == "-" and label[7] == "-"
+            and label.replace("-", "").isdigit())

taskops/usecases/_reasons.py

@@ -0,0 +1,54 @@
+"""Why there is nothing to claim. Prose with branches in it, kept out of the claim path.
+
+Split from `claim` because the two answer different questions: that module decides what an agent GETS,
+this one explains what it did not get. Every branch here exists because a specific unhelpful answer
+sent an agent to ask a human when it could have acted:
+
+- "nothing ready" → it asks a human. "waiting on tk-abc" → it goes and does tk-abc.
+- "cannot claim" → it retries the same call. "assigned to agent:ana/w2" → it asks for its own.
+"""
+
+from __future__ import annotations
+
+from ..engine import counts
+from ..storage import Store
+
+__all__ = ["why_nothing", "why_not_this"]
+
+
+def why_nothing(store: Store, labels: tuple[str, ...], wanted: str, asker: str = "") -> str:
+    """Why there is nothing to do. "Nothing ready" alone sends the agent to ask a
+    human; told WHICH — all blocked, all taken, or genuinely finished — it can act."""
+    if wanted:
+        return why_not_this(store, wanted, asker)
+    numbers = counts(store)
+    if numbers["open"] == 0:
+        return "nothing open — the project is finished, or nothing has been planned"
+    if labels:
+        return (f"no ready task carries {', '.join(labels)}. Drop the label filter, "
+                f"or plan the work that is missing")
+    if numbers["ready"] == 0 and numbers["blocked"]:
+        return (f"{numbers['blocked']} task(s) are waiting on a dependency and "
+                f"{numbers['working']} are in flight — unblocking one of those is "
+                f"the useful move")
+    return (f"every ready task was claimed by another agent in the last moment "
+            f"({numbers['working']} in flight) — ask again")
+
+
+def why_not_this(store: Store, wanted: str, asker: str = "") -> str:
+    """Why THIS task cannot be claimed. Each status has a different useful answer.
+
+    A blocked task names its blockers, because "not ready" alone sends the agent to a human when
+    the actionable move is usually to go work on the blocker instead.
+    """
+    task = store.tasks.need(wanted)
+    if task["status"] == "backlog":
+        blockers = ", ".join(store.deps.open_blockers_of(wanted)) or "unresolved deps"
+        return (f"{wanted} is waiting on {blockers} — finish those first, or claim one "
+                f"of them with taskops_next")
+    if task["status"] in ("done", "cancelled"):
+        return f"{wanted} is already {task['status']} — nothing to do there"
+    if task["assignee"] and task["assignee"] != asker:
+        return (f"{wanted} is assigned to {task['assignee']} — ask taskops_next with no task "
+                f"and it will give you something that is yours")
+    return f"{wanted} is {task['status']}, held by someone else — read it with taskops_ask"

taskops/usecases/_remotefile.py

@@ -0,0 +1,62 @@
+"""Reading and writing `.taskops/remote.json` — the file mechanics, nothing else.
+
+Split from `remote` by what each half is: that module decides WHAT a remote is (one per
+project, a URL and a secret, two cursors that never compare), this one knows how to put it
+on disk without leaking it. The file is written through `os.open` with mode 0600 rather than
+`write_text` followed by a `chmod`, because the two-step version publishes the token to every
+user on the machine for the width of one syscall.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, cast
+
+from ..contracts import Remote
+from ..storage import PROJECT_DIR, resolve_root
+
+__all__ = ["REMOTE_FILE", "remote_path", "load", "write"]
+
+REMOTE_FILE = f"{PROJECT_DIR}/remote.json"
+
+
+def remote_path(root: Path) -> Path:
+    return root / REMOTE_FILE
+
+
+def load(start: Path | str) -> Remote | None:
+    """The configured remote, or None. Never raises on a corrupt file.
+
+    A hand-edited `remote.json` with a trailing comma should read as "no remote configured",
+    which `remote add` can then fix — refusing to run and refusing to be repaired is a state
+    with no way out of it.
+    """
+    path = remote_path(resolve_root(start))
+    if not path.is_file():
+        return None
+    try:
+        parsed: Any = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    fields = cast("dict[str, Any]", parsed)
+    if not fields.get("url"):
+        return None
+    return Remote(url=str(fields["url"]), token=str(fields.get("token", "")),
+                  pushed=int(fields.get("pushed", 0) or 0),
+                  cursor=int(fields.get("cursor", 0) or 0))
+
+
+def write(root: Path, remote: Remote) -> Remote:
+    path = remote_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(handle, "w", encoding="utf-8") as out:
+        json.dump(remote, out, indent=2, sort_keys=True)
+        out.write("\n")
+    # A file that already existed keeps its old mode through O_CREAT, so say it again.
+    os.chmod(path, 0o600)
+    return remote

taskops/usecases/_reportsync.py

@@ -0,0 +1,108 @@
+"""Reports across the wire — the half of sync that can destroy something irrecoverable.
+
+Events are safe to move in bulk: they are facts with content-hash ids, so the union of two
+logs is the correct log. A report is not. Its dossier regenerates from the log any time, but
+the NARRATION under it was written once — by a model somebody paid for, or by a person — and
+nothing in the system can reconstruct it. So the rule here is the opposite of the one for
+events: never overwrite, ever, unless a human said `--force` after reading what they would
+lose.
+
+The comparison is `stamped_seq`: line one of every generated report carries the log's
+`max_seq` at the moment it was rendered, so a larger stamp means "this copy saw more of the
+history". It is a HEURISTIC and worth saying so — two machines number their own sqlite rows,
+so the stamps are strictly comparable only once both have synced. The pathological case (two
+independent narrations of the same day, neither machine having seen the other) falls to the
+server's equal-seq-different-content 409, which is the honest answer: nobody can decide that
+one for you.
+
+This module never regenerates a dossier. Owning the store is what earns the right to render,
+and a client that "helpfully" re-rendered what it downloaded would be uploading a report the
+server has never seen the events for.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..engine import stamped_seq
+from ..storage import REPORTS_DIR
+from ._wireclient import Wire
+from .dossier import report_path
+
+__all__ = ["ReportSwap", "exchange"]
+
+
+class ReportSwap:
+    """Which reports moved, and which ones refused to."""
+
+    def __init__(self) -> None:
+        self.uploaded: list[str] = []
+        self.downloaded: list[str] = []
+        self.conflicts: list[str] = []
+        """One sentence per stand-off, naming BOTH seqs and the two ways out. A count would
+        be useless: the answer is per report, and it is `pull` for one and `--force` for the
+        next."""
+
+
+def exchange(wire: Wire, root: Path, *, upload: bool, force: bool = False) -> ReportSwap:
+    """Reconcile every report both sides know about. `upload` is False on a plain `pull`."""
+    swap = ReportSwap()
+    for label in _labels(wire, root):
+        _reconcile(wire, root, label, swap, upload=upload, force=force)
+    return swap
+
+
+def _reconcile(wire: Wire, root: Path, label: str, swap: ReportSwap, *,
+               upload: bool, force: bool) -> None:
+    path = report_path(root, label)
+    ours = path.read_text(encoding="utf-8") if path.is_file() else ""
+    theirs = wire.get_report(label)
+    if not _served(theirs):
+        if upload and ours:
+            _send(wire, label, ours, swap, force=force)
+        return
+    content = str(theirs.get("content", ""))
+    if not ours or int(theirs.get("max_seq", 0) or 0) > stamped_seq(ours):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        swap.downloaded.append(label)
+    elif upload and content != ours:
+        _send(wire, label, ours, swap, force=force)
+
+
+def _send(wire: Wire, label: str, text: str, swap: ReportSwap, *, force: bool) -> None:
+    answer = wire.put_report(label, text, force=force)
+    if answer.get("status") == 409:
+        swap.conflicts.append(_clash(label, answer, stamped_seq(text)))
+    else:
+        swap.uploaded.append(label)
+
+
+def _clash(label: str, answer: dict[str, Any], mine: int) -> str:
+    """The 409 in a sentence. Note the INVERSION: the body's `ours` is the SERVER's copy and
+    its `theirs` is what we just offered, because the server wrote it from where it stands."""
+    server = int(answer.get("ours", 0) or 0)
+    ours = int(answer.get("theirs", mine) or mine)
+    return (f"{label}: the server's copy is stamped at seq {server}, yours at {ours} — "
+            f"nothing was overwritten. Run `taskops pull` to take the server's, or "
+            f"`taskops push --force` to replace it (any narration there is lost).")
+
+
+def _served(answer: dict[str, Any]) -> bool:
+    return answer.get("status") is None and "content" in answer
+
+
+def _labels(wire: Wire, root: Path) -> list[str]:
+    """Every label either side has, sorted so the output is stable.
+
+    The server's list is best-effort (`Wire.list_reports` explains why): on a server without
+    that route this degrades to the labels on this disk, which still reconciles everything
+    this machine has ever written — only a report that exists SOLELY on the server stays out
+    of reach, and it arrives the moment anyone here generates that window.
+    """
+    directory = root / REPORTS_DIR
+    local: set[str] = set()
+    if directory.is_dir():
+        local = {path.stem for path in directory.glob("*.md")}
+    return sorted(local | set(wire.list_reports()))

taskops/usecases/_routing.py

@@ -0,0 +1,91 @@
+"""Where a WRITE happens: here, or in the server that other machines also write to.
+
+Push and pull make two boards converge; they do not make a claim safe. Between two syncs,
+two agents on two machines can both find the same card `ready` and both take it — each
+sqlite grants its own lease because neither knows about the other. The engine already solves
+this *within* one database (two INSERTs on one primary key, one winner, pinned by a
+fifty-thread test); the fix is therefore not a new algorithm but a new PLACE: when a project
+has a remote, `next` and `update` are executed in the server's sqlite, where the race is the
+same race the engine already wins.
+
+**The decision lives here, in the use cases, and not in a transport.** The CLI, the MCP tools
+and the local HTTP board all call `next_task` and `update`; putting the routing in any one of
+them would mean an agent that claims safely through MCP and unsafely through `taskops claim`.
+
+**The server must never route to itself.** It runs these very use cases, so a `remote.json`
+that happened to sit in the store it serves would make it POST to itself, forever. That is
+why every server endpoint passes `local=True`: a flag the caller must opt into is checkable,
+and `tests/e2e/test_agentwire.py` plants exactly that file and asserts the server answers.
+
+**Offline never falls back to a local claim.** A remote-configured project whose server is
+unreachable raises, naming the URL. Quietly claiming locally instead would be the collision
+this module exists to prevent, delivered by the very code meant to prevent it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, cast
+
+from .._errors import Unreachable
+from ..contracts import NextResult, Remote, UpdateResult
+from ..engine import identity
+from ._mirroring import mirror_claim, mirror_update
+from ._project import locate
+from ._wireclient import Wire
+from .remote import read_remote
+
+__all__ = ["routed", "whoami", "claim_remotely", "update_remotely"]
+
+
+def routed(start: Path | str, local: bool) -> Remote | None:
+    """The remote this write belongs to, or None when it belongs to this disk."""
+    return None if local else read_remote(start)
+
+
+def whoami(start: Path | str, actor: str) -> str:
+    """Resolve the actor HERE, before it crosses the wire.
+
+    The server cannot do it: it has neither this machine's `$TASKOPS_ACTOR` nor its git
+    config, so an empty actor would arrive and resolve to the server's own identity — every
+    remote agent filed as one `dev:` on the box.
+    """
+    return identity.resolve(locate(start), actor)["id"]
+
+
+def claim_remotely(start: Path | str, remote: Remote, body: dict[str, Any]) -> NextResult:
+    answer = cast("NextResult", _relay(start, remote, lambda wire: wire.claim(body)))
+    if answer["claim"] is not None:
+        mirror_claim(start, answer["claim"])
+    return answer
+
+
+def update_remotely(start: Path | str, remote: Remote, body: dict[str, Any]) -> UpdateResult:
+    answer = cast("UpdateResult", _relay(start, remote, lambda wire: wire.change(body)))
+    mirror_update(start, answer["task"])
+    return answer
+
+
+def _relay(start: Path | str, remote: Remote,
+           send: Callable[[Wire], dict[str, Any]]) -> dict[str, Any]:
+    """Do it there, then pull. The pull is NOT best effort — see below.
+
+    Without it the agent holds a lease the server knows about and its own board does not, and
+    the board is what the commit guard, `taskops brief` and every render read. So a failed
+    pull fails the whole call: a half-success that reports a claim the local tooling will then
+    deny is worse than an error naming the network.
+
+    The pull carries everybody's events; `_mirroring` then writes the one thing an event cannot
+    carry — the lease this caller was just granted.
+    """
+    from .pushpull import pull
+
+    try:
+        answer = send(Wire(remote["url"], remote["token"]))
+    except Unreachable as gone:
+        raise Unreachable(
+            f"this project's writes go to {remote['url']}, which did not answer "
+            f"({gone}) — taskops will NOT claim locally instead, because a local claim "
+            f"could collide with another machine's; retry, or check the network") from gone
+    pull(start)
+    return answer