taskops-cli 0.2.0__py3-none-any.whl

taskops/usecases/log.py

@@ -0,0 +1,134 @@
+"""`taskops log <task>` — what the agent actually said while working on a card.
+
+The card already knows enough to find it without any new bookkeeping: `dispatch` puts every worker in
+`<repo>/.taskops/trees/<id>/`, and Claude Code names a transcript directory after the working directory
+it ran in. So the lookup is a path computation, and it works on transcripts written before taskops knew
+it would ever read them — the axion-v3 workers' conversations were recoverable after the fact.
+
+Two directories are searched, in this order:
+
+1. **the card's worktree** — one directory per card, so everything in it belongs to this card
+2. **the repository itself** — shared by every session anybody ran there, so it needs a filter
+
+For (2) there are two ways to prove an entry belongs, and the path computation alone is not enough. A
+dispatched agent makes a branch, so `gitBranch` identifies it. A person who claimed a card in their own
+terminal usually stays on `main`, and every one of their entries would be discarded — so the card also
+remembers WHICH sessions worked it, and a transcript named by a recorded session id is read whole.
+
+Nothing is copied into the event log. A transcript is 200 KB for 40 turns, `events.jsonl` is committed,
+and the value of that file is that a human can read its diff. The consequence is stated plainly in the
+contract: a transcript is LOCAL, and a teammate who pulls gets the card and the commits but not this.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..contracts import LogEntry, SessionLog
+from ..engine import branch_for
+from ..engine._entries import flatten
+from ..engine.transcript import directories_for, home, read_entries
+from ..engine.worker import worktree_for
+from ..storage import Store
+from ._project import project
+
+__all__ = ["session_log", "MAX_ENTRIES"]
+
+MAX_ENTRIES = 400
+"""Entries kept, newest last. A long session runs to thousands, and a viewer wants the shape of the
+work plus how it ended — so when it truncates, it keeps the END and says so."""
+
+
+def session_log(start: Path | str, task_id: str, *, limit: int = MAX_ENTRIES) -> SessionLog:
+    """The conversation for one card, oldest first."""
+    with project(start) as store:
+        task = store.tasks.need(task_id)
+        branch = branch_for(task)
+        tree = worktree_for(store.root, task)
+        places = directories_for(store.root, tree)
+        if not places:
+            return _empty(task_id, _nowhere(store, tree))
+        entries = _gather(places, tree, branch, _recorded(store, task_id))
+        if not entries:
+            return _empty(task_id, _silent(store, task_id, places))
+        return _bounded(task_id, entries, ", ".join(str(p) for p in places), limit)
+
+
+def _recorded(store: Store, task_id: str) -> tuple[str, ...]:
+    """The session ids known to have worked this card — from its live lease and from its own history.
+
+    The lease is the current holder; the events are every past one, which matters because a card that
+    was released and re-claimed has more than one conversation and both are worth reading.
+    """
+    held = store.leases.get(task_id)
+    found = [held["session"]] if held else []
+    found += [str(event["body"].get("session", ""))
+              for event in store.events.of_task(task_id)]
+    return tuple(dict.fromkeys(name for name in found if name))
+
+
+def _gather(places: list[Path], tree: Path, branch: str,
+            sessions: tuple[str, ...]) -> list[LogEntry]:
+    """Read every place, flatten every line, then order by time.
+
+    Sorted at the END rather than per file: two sessions on one card can overlap, and a viewer showing
+    them concatenated would imply an order that did not happen.
+    """
+    out: list[LogEntry] = []
+    for place in places:
+        # The worktree's directory holds only this card's sessions, so it needs no filter. The
+        # repository's is shared, so an entry has to prove it belongs by naming the card's branch.
+        wanted = "" if place.name.endswith(tree.name) else branch
+        for raw in read_entries(place, branch=wanted, sessions=sessions):
+            out += flatten(raw)
+    return sorted(out, key=lambda entry: entry["ts"])
+
+
+def _bounded(task_id: str, entries: list[LogEntry], source: str,
+             limit: int) -> SessionLog:
+    """Keep the LAST `limit` entries, and say when that happened.
+
+    The end, not the beginning: a person opening a card's log is usually asking how it went, and the
+    answer is in the last few turns. Silence about the truncation would be a lie about the ending.
+    """
+    kept = entries[-limit:] if len(entries) > limit else entries
+    return SessionLog(task=task_id, sessions=_sessions(kept), entries=kept,
+                      source=source, truncated=len(entries) > limit)
+
+
+def _sessions(entries: list[LogEntry]) -> list[str]:
+    """The session ids present, in the order they first appear. More than one is normal — a card can be
+    released and picked up again, and each attempt is its own session."""
+    return list(dict.fromkeys(entry["session"] for entry in entries if entry["session"]))
+
+
+def _empty(task_id: str, why: str) -> SessionLog:
+    return SessionLog(task=task_id, sessions=[], entries=[], source=why, truncated=False)
+
+
+def _silent(store: Store, task_id: str, places: list[Path]) -> str:
+    """The directory exists and holds nothing for this card. Say which of the two reasons it is.
+
+    An empty pane that only prints a path reads as a broken viewer — it was reported as one. The
+    difference that matters to the reader: nobody ever worked this card in a Claude Code session (there
+    is nothing to show, and that is fine), versus somebody did but the entries cannot be attributed,
+    which happens for interactive work done before the card started recording its sessions.
+    """
+    looked = ", ".join(str(place) for place in places)
+    if _recorded(store, task_id):
+        return (f"a session is recorded for this card but none of its entries were found in {looked}. "
+                f"The transcript may have been written under a different Claude Code home.")
+    return ("no Claude Code session is recorded against this card, so there is no conversation to "
+            f"show. Sessions are recorded from the claim onwards; searched {looked}.")
+
+
+def _nowhere(store: Store, tree: Path) -> str:
+    """Why there is nothing, specifically enough to act on.
+
+    A viewer that shows an empty pane cannot distinguish "this agent said nothing" from "taskops looked
+    in the wrong place", and the second has a fix — which is usually `$CLAUDE_CONFIG_DIR`, because a
+    second Claude Code home is exactly how the first version of this found nothing at all.
+    """
+    return (f"no transcript directory for this card. Looked under {home() / 'projects'} for "
+            f"{tree} and {store.root}. If Claude Code stores its config elsewhere, "
+            f"$CLAUDE_CONFIG_DIR is what points here.")

taskops/usecases/narration.py

@@ -0,0 +1,91 @@
+"""Narrating a report IN THE BACKGROUND, with the prose on the wire as it is written.
+
+The user's report was "aprieto Generate y no hace nada". Nothing was broken: the POST was a
+multi-minute call to a model behind a mute spinner, the file said `_pendiente_` for all of it,
+and a browser that gave up on the request took the only feedback there was with it.
+
+So the request stops carrying the work. `start` spawns the digest and returns immediately; what
+happens next arrives on the socket the board already holds, as `WireMessage`s — a pass
+announcement, the prose in fragments, and one terminal frame either way. The engine already
+streamed all of this (`engine.narrate`'s `on_pass`/`on_text`, which the terminal has used since
+`report --digest` learned to show itself); the only thing missing was somewhere to send it.
+
+**A delta is never an event.** It goes on `WIRE`, not on `BUS`, and never near the database —
+`events.jsonl` is committed and its worth is that a human can read its diff.
+
+One at a time per report. Two models rewriting the same file is guaranteed corruption, so a
+second request is refused rather than queued: the first is already streaming to the person who
+asked, and a queued duplicate would only overwrite it later.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+from .._errors import AlreadyNarrating
+from ..contracts import WireMessage
+from ..engine import WIRE
+from ..storage import resolve_root
+from ._range import Selector
+from .dossier import digest
+
+__all__ = ["start", "running"]
+
+_lock = threading.Lock()
+_running: set[str] = set()
+"""Report labels being narrated right now, in THIS process. Process-wide state, like the
+channel it publishes to, and for the same reason: the digest runs inside the studio's own
+server, so the only narrations this can collide with are the ones it started itself."""
+
+
+def start(root: Path | str, label: str, *, force: bool = False, model: str = "") -> str:
+    """Begin narrating `label` and return at once. Raises `AlreadyNarrating` on a duplicate.
+
+    The caller gets no prose from this — that is the point. It arrives on the wire.
+    """
+    # Resolved HERE, on the caller's thread, and carried into every frame the run publishes.
+    # The channel is process-global: without the origin stamped on each message, a server
+    # holding several boards would show this project's prose on all of them. Resolving before
+    # the thread starts also means a bad root is an exception the caller sees, not a traceback
+    # in the server's stderr.
+    origin = str(resolve_root(root))
+    with _lock:
+        if label in _running:
+            raise AlreadyNarrating(f"{label} is being narrated right now — watch it arrive, "
+                                   f"or wait for that one to finish before regenerating")
+        _running.add(label)
+    worker = threading.Thread(target=_run, args=(root, origin, label, force, model),
+                              name=f"narrate-{label}", daemon=True)
+    # Daemon: a narration is a paid-for convenience, never a reason a server refuses to exit.
+    # The dossier is already on disk, and the next run picks up from the file.
+    worker.start()
+    return label
+
+
+def running() -> frozenset[str]:
+    """Which reports are being narrated. Read by tests and by anything wanting to say so."""
+    with _lock:
+        return frozenset(_running)
+
+
+def _run(root: Path | str, origin: str, label: str, force: bool, model: str) -> None:
+    """The digest, with every callback turned into a frame. Never raises: it IS the top of a
+    thread, so an escaping exception would print a traceback into the server's stderr and tell
+    the person watching nothing at all."""
+    try:
+        digest(root, Selector(date=label), model=model, force=force,
+               on_pass=lambda n, total: _say(origin, "narration.pass", label, f"{n}/{total}"),
+               on_text=lambda text: _say(origin, "narration.delta", label, text))
+        _say(origin, "narration.done", label, "")
+    except Exception as err:                     # noqa: BLE001 — the reader is the error's audience
+        # Verbatim. `claude` missing or logged out is a thing the person can fix in a minute,
+        # and only if the sentence reaches the screen instead of becoming "failed".
+        _say(origin, "narration.failed", label, str(err) or err.__class__.__name__)
+    finally:
+        with _lock:
+            _running.discard(label)
+
+
+def _say(origin: str, kind: str, label: str, text: str) -> None:
+    WIRE.publish(WireMessage(kind=kind, label=label, text=text, root=origin))

taskops/usecases/plan.py

@@ -0,0 +1,128 @@
+"""Decomposition: a whole plan — tasks, tree and DAG — created in one call.
+
+One call and not N, because the graph is the point. An agent that creates five tasks
+with five calls has to invent its own scheme for referring to the ones it just made, and
+the dependencies land in a second pass a context limit can cut short. Here `after`
+accepts the INDEX of an earlier entry in the same batch, so the plan arrives whole or not
+at all.
+
+taskops does not decompose anything itself. The session calling this already read the
+code and thought about the work; asking a second model to re-derive that from a title
+would be worse and slower. What this owns is that the result is persistent, ordered, and
+legible to every other agent — including ones on other machines.
+
+Field reading lives in `_entry`: this module builds a graph, that one decides what a
+model meant by a field it spelled its own way.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .._clock import now
+from .._errors import BadRequest
+from .._ids import new_task_id
+from ..contracts import Dep, PlanResult, Task
+from ..engine import record, unblock
+from ..storage import Store
+from . import _entry as field
+from ._project import caller, heartbeat, project
+
+__all__ = ["plan"]
+
+
+def plan(start: Path | str, entries: list[dict[str, Any]], *,
+         actor: str = "") -> PlanResult:
+    """Create every task in `entries`, wire the dependencies, return what unblocked."""
+    if not entries:
+        raise BadRequest("`tasks` is empty — a plan with no tasks is not a plan")
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        created = [_create(store, entry, who) for entry in entries]
+        deps = _wire(store, entries, created)
+        return PlanResult(created=created, deps=deps, unblocked=unblock(store))
+
+
+def _create(store: Store, entry: dict[str, Any], who: str) -> Task:
+    """One entry -> a stored task. Starts in `backlog`; `unblock` promotes it.
+
+    Deliberately never created `ready`: whether a task is pickable is a property of the
+    dependency graph, and letting a creator assert it directly is how the column starts
+    disagreeing with the edges.
+    """
+    title = field.title_of(entry)
+    if not title:
+        raise BadRequest("every task needs a `title`")
+    when = now()
+    task = Task(id=new_task_id(), title=title,
+                spec=str(entry.get("spec", "")).strip(), status="backlog",
+                priority=field.priority_of(entry),
+                parent=field.optional(entry, "parent"),
+                labels=field.strings(entry, "labels"),
+                files=field.strings(entry, "files"),
+                created_by=who, assignee=field.optional(entry, "assignee") or "",
+                created=when, updated=when)
+    store.tasks.insert(task)
+    # The WHOLE task in the body, not just its title. The log is the source of truth another
+    # machine rebuilds from, so an event that omits the spec is an event that cannot reconstruct
+    # the task — which is exactly what happened: a teammate's `git pull` imported the events and
+    # left them with an empty board. `engine.replay` is the reader.
+    record(store, task=task["id"], actor=who, kind="created", body=_snapshot(task), ts=when)
+    return task
+
+
+def _snapshot(task: Task) -> dict[str, Any]:
+    """Everything needed to recreate this task elsewhere. `id` and `created_by` are already on the
+    event, so repeating them would be two places to keep in step."""
+    return {"title": task["title"], "spec": task["spec"], "priority": task["priority"],
+            "parent": task["parent"], "labels": task["labels"], "files": task["files"],
+            "assignee": task["assignee"]}
+
+
+def _wire(store: Store, entries: list[dict[str, Any]],
+          created: list[Task]) -> list[Dep]:
+    """Resolve every `after` into an edge: an index means this batch, a string an id."""
+    out: list[Dep] = []
+    # strict=True asserts the invariant rather than trusting it: `created` is built one
+    # per entry, so a length mismatch means `_create` skipped one — and the symptom
+    # would be a dependency wired to the WRONG task.
+    for entry, task in zip(entries, created, strict=True):
+        for reference in field.references(entry):
+            out.append(_edge(store, _resolve(reference, created), task["id"], task["created_by"]))
+        for waiting in field.blocked_ids(entry):
+            # The INVERSE direction: this new card blocks an existing one. Same edge, other way
+            # round, which is what makes the stuck-agent flow a single call.
+            store.tasks.need(waiting)
+            out.append(_edge(store, task["id"], waiting, task["created_by"]))
+    return out
+
+
+def _edge(store: Store, blocker: str, waiting: str, who: str) -> Dep:
+    """One dependency, stored AND recorded.
+
+    Recorded because a dependency that exists only in this machine's database is one a teammate's
+    scheduler will walk somebody straight into after a `git pull`.
+    """
+    store.deps.add(blocker, waiting)
+    record(store, task=waiting, actor=who, kind="blocked", body={"on": blocker})
+    return Dep(task=blocker, blocks=waiting)
+
+
+def _resolve(reference: object, created: list[Task]) -> str:
+    """An `after` entry -> a task id.
+
+    An out-of-range index is an ERROR, never a skipped edge: a plan whose dependencies
+    silently did not apply looks finished and schedules wrongly, which is the most
+    expensive way for this to fail. `bool` is rejected before `int` because `True == 1`
+    would otherwise resolve to the first task in the batch.
+    """
+    if isinstance(reference, bool):
+        raise BadRequest(f"`after` got {reference!r} — expected an index or a task id")
+    if isinstance(reference, int):
+        if not 0 <= reference < len(created):
+            raise BadRequest(f"`after` index {reference} is outside this batch of "
+                             f"{len(created)} — indexes are 0-based")
+        return created[reference]["id"]
+    return str(reference)

taskops/usecases/pushpull.py

@@ -0,0 +1,119 @@
+"""`taskops push` and `taskops pull` — the same convergence as git, over HTTP.
+
+The order is `usecases/sync.py`'s order and for the same reasons: events in, REPLAY, unblock,
+and only then anything else. Replay is the step whose absence was a real bug — a teammate
+imported every event and looked at an empty board, because events are the source of truth and
+something has to turn them into rows. `pull` that only relayed would reproduce that bug over a
+faster wire, so `tests/e2e/test_remote.py` asserts the imported card is on the BOARD, not that
+its row is in the table.
+
+**Push implies pull.** git does not do this and here it should: the round trip is one more
+request against a server you just proved you can reach, and the alternative is two developers
+whose boards have diverged since this morning, each convinced they are current.
+
+**Marked exported only after a 200.** A push cut halfway through re-sends on the next run and
+the server accepts each event exactly once — ids are content hashes — so the failure mode is
+a duplicate request, not a lost event. The other order loses work to a dropped connection.
+
+`push` keeps its OWN cursor (`pushed`, a local seq in remote.json) and never touches the
+`exported` flag — that one belongs to the git-log export. The first version drained
+`exported` instead, and on any project that had ever run `taskops sync` everything was
+already marked: a 370-event board pushed as `0 event(s) out`, silently. Two sinks, two
+cursors, and a project may use both — the jsonl for teammates on git, the server for the
+live board.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from .._types import LOCAL_ONLY_KINDS
+from ..contracts import Event
+from ..engine import relay, replay, unblock
+from ._project import locate, project
+from ._reportsync import ReportSwap, exchange
+from ._wireclient import PAGE, Wire
+from .remote import require_remote, save_cursor, save_pushed
+
+__all__ = ["push", "pull", "Exchange"]
+
+
+class Exchange:
+    """What crossed the wire, in both directions, plus what the import actually changed."""
+
+    def __init__(self, *, events_in: int = 0, accepted: int = 0, applied: int = 0,
+                 unblocked: list[str] | None = None) -> None:
+        self.events_in = events_in
+        self.accepted = accepted
+        """Events the SERVER had never seen. Zero on a second push of the same work, which is
+        the idempotency showing through rather than a failure."""
+
+        self.applied = applied
+        self.unblocked = unblocked or []
+        self.reports = ReportSwap()
+
+
+def pull(start: Path | str) -> Exchange:
+    """Take the server's events, materialise them, and take any newer reports."""
+    remote = require_remote(start)
+    wire = Wire(remote["url"], remote["token"])
+    done = _receive(start, wire, remote["cursor"])
+    done.reports = exchange(wire, locate(start), upload=False)
+    return done
+
+
+def push(start: Path | str, *, force: bool = False) -> Exchange:
+    """Send what is local, then pull, then reconcile reports in both directions."""
+    remote = require_remote(start)
+    wire = Wire(remote["url"], remote["token"])
+    accepted = _send(start, wire, remote["pushed"])
+    done = _receive(start, wire, remote["cursor"])
+    done.accepted = accepted
+    done.reports = exchange(wire, locate(start), upload=True, force=force)
+    return done
+
+
+def _send(start: Path | str, wire: Wire, pushed: int) -> int:
+    """Page the LOCAL log past the push cursor. Returns how many were new on the server.
+
+    The cursor advances only after the server's 200, so a push cut halfway re-sends and the
+    content-hashed ids make the repeat a no-op. Local-only kinds are filtered out but their
+    seqs still advance the cursor — skipping that would re-scan every activity heartbeat this
+    machine ever wrote, which is most of the log.
+    """
+    accepted = 0
+    while True:
+        with project(start) as store:
+            batch, tail = store.events.page_after(pushed, limit=PAGE)
+            if not batch:
+                return accepted
+            shared = [e for e in batch if e["kind"] not in LOCAL_ONLY_KINDS]
+        if shared:
+            accepted += int(wire.post_events(cast("list[Any]", shared)).get("accepted", 0))
+        save_pushed(start, tail)
+        pushed = tail
+
+
+def _receive(start: Path | str, wire: Wire, cursor: int) -> Exchange:
+    """Page the server's log from the cursor, then REPLAY and unblock. Saves the cursor.
+
+    The cursor is the server's `seq` and is never compared with a local one. A server that
+    forgot it — a store rebuilt from scratch — answers from 0, and re-importing the whole log
+    is a no-op rather than a repair job: `relay` accepts each content-hashed id once.
+    """
+    fresh: list[Event] = []
+    with project(start) as store:
+        while True:
+            page = wire.get_events(cursor, PAGE)
+            arrived = [cast("Event", row) for row in page.get("events", [])
+                       if isinstance(row, dict)]
+            fresh.extend(event for event in arrived if relay(store, event))
+            cursor = max(cursor, int(page.get("max_seq", 0) or 0))
+            if not page.get("more") or not arrived:
+                break
+        # Replay is not optional. Without it the events landed and the board stays empty.
+        done = Exchange(events_in=len(fresh), applied=replay.apply(store, fresh),
+                        unblocked=unblock(store))
+    save_cursor(start, cursor)
+    return done

taskops/usecases/recover.py

@@ -0,0 +1,84 @@
+"""`taskops recover` — unstick a fleet whose workers died.
+
+Written the day it was needed. Six cards in a real project sat `claimed` by six agents that had been
+killed mid-run (an API balance ran out), and getting them back took six hand-written `update
+--status released` calls plus a manual hunt through six worktrees for work that had never been
+committed. That is the wrong shape for something that will happen every time a fleet dies.
+
+**It does not wait for the lease.** A TTL is the right mechanism for a crash nobody noticed, but a
+person looking at a board full of SILENT rows has already noticed — making them wait fifteen minutes
+for a timer to agree with them is a tool arguing with its user.
+
+**It never deletes anything.** A dead worker's worktree keeps whatever it wrote, and the recovery
+records that in the card's thread instead of tidying it away. Uncommitted work in a directory nobody
+mentions is work the next agent redoes from scratch, which was exactly what nearly happened.
+
+**Two kinds of stuck, and the second is easy to miss.** A card can be held by a lease whose worker
+went quiet, OR merely ASSIGNED to a worker that was never started — which is what a `dispatch` whose
+sub-agents nobody spawned leaves behind. The second has no lease at all, so a recovery that only
+swept leases left eight of them assigned to workers that did not exist: invisible to every other
+agent, and unclaimable forever. Found by running it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import HEARTBEAT_GRACE, now
+from ..engine import fleet
+from ..storage import Store
+from ._freeing import Stuck, release_lease, unassign
+from ._project import caller, heartbeat, project
+
+__all__ = ["recover", "Recovered", "Stuck"]
+
+
+class Recovered:
+    def __init__(self, *, released: list[Stuck], alive: list[str]) -> None:
+        self.released = released
+        self.alive = alive
+        """Workers still reporting. Named, not silently skipped: a recovery that quietly left two
+        cards claimed is a recovery somebody has to check by hand anyway."""
+
+
+def recover(start: Path | str, *, actor: str = "", grace: float = HEARTBEAT_GRACE,
+            force: bool = False) -> Recovered:
+    """Release every card whose worker has gone quiet. Returns what was freed and what was not.
+
+    `grace` is the silence a worker is allowed before it counts as gone — the same number the fleet
+    view uses to print SILENT, so what you see is what this acts on. `force` releases even the ones
+    still reporting, which is for the case where a fleet is alive and wrong.
+    """
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        when = now()
+        live = {m["task"]: m for m in fleet(store, at=when)["members"]}
+        released: list[Stuck] = []
+        alive: list[str] = []
+        for lease in store.leases.live(when):
+            member = live.get(lease["task"])
+            quiet = when - (member["last_seen"] if member else lease["acquired"])
+            if not force and quiet < grace:
+                alive.append(f"{lease['actor']} on {lease['task']}")
+                continue
+            released.append(release_lease(store, lease, who, quiet))
+        released += _orphans(store, who)
+        return Recovered(released=released, alive=alive)
+
+
+def _orphans(store: Store, who: str) -> list[Stuck]:
+    """Cards ASSIGNED to a worker that holds no lease — a dispatch nobody spawned.
+
+    Always recovered, with no grace period, because there is nothing to wait for: an assignment with
+    no lease means the worker never started, and the card is meanwhile hidden from every other agent
+    by the very filter that makes assignment useful. Left alone it is unclaimable forever.
+    """
+    out: list[Stuck] = []
+    for task in store.tasks.all():
+        if not task["assignee"] or store.leases.get(task["id"]) is not None:
+            continue
+        if task["status"] in ("done", "cancelled"):
+            continue
+        out.append(unassign(store, task["id"], task["assignee"], who))
+    return out

taskops/usecases/remote.py

@@ -0,0 +1,78 @@
+"""The one remote a project syncs with: a URL, a secret, and two cursors.
+
+ONE remote per project. A second `add` is refused by naming the first: two remotes means two
+cursors over two logs and a report that has to answer "who saw more" three ways, and none of
+that is designed. Federation is a different feature with a different shape.
+
+The token lives inside the block `taskops init` gitignores — that block lists what under
+`.taskops/` is NOT committed and its one hole is `events.jsonl`, so `remote.json` is ignored
+by construction. `tests/e2e/test_remote.py` pins it: a token reaching a commit is
+unrecoverable in the only sense that matters, since rotating it is work somebody has to
+notice they need to do. The file mechanics (0600, atomic-enough writes) live in `_remotefile`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from .._errors import BadRequest, NotInitialized
+from ..contracts import Remote
+from ..storage import resolve_root
+from ._remotefile import REMOTE_FILE, load, remote_path, write
+
+__all__ = ["REMOTE_FILE", "add_remote", "read_remote", "require_remote",
+           "remove_remote", "save_cursor", "save_pushed", "remote_path"]
+
+read_remote = load
+
+
+def add_remote(start: Path | str, url: str, token: str) -> Remote:
+    """Register the one remote. Refuses a second by naming the one already there."""
+    root = resolve_root(start)
+    address = url.strip().rstrip("/")
+    if not address.startswith(("http://", "https://")):
+        raise BadRequest(f"`{url}` is not a server address — pass the base URL, "
+                         f"like https://taskops.example.com")
+    if not token.strip():
+        raise BadRequest("a remote needs a token — the server rejects every call without one")
+    already = read_remote(start)
+    if already is not None:
+        raise BadRequest(f"this project already syncs with {already['url']} — one remote per "
+                         f"project; run `taskops remote remove` first")
+    return write(root, Remote(url=address, token=token.strip(), pushed=0, cursor=0))
+
+
+def require_remote(start: Path | str) -> Remote:
+    """The remote, or the one line that says how to get one."""
+    found = read_remote(start)
+    if found is None:
+        raise NotInitialized("no remote configured — run `taskops remote add <url> "
+                             "--token <token>`, or keep syncing through git with `taskops sync`")
+    return found
+
+
+def remove_remote(start: Path | str) -> str:
+    """Forget the remote AND the token. Returns the url that was dropped."""
+    gone = require_remote(start)
+    remote_path(resolve_root(start)).unlink(missing_ok=True)
+    return gone["url"]
+
+
+def save_cursor(start: Path | str, cursor: int) -> None:
+    """Record how far this machine has read the SERVER's log. Never moves backwards."""
+    _advance(start, "cursor", cursor)
+
+
+def save_pushed(start: Path | str, pushed: int) -> None:
+    """Record how far this machine's OWN log has been sent up. Its own number — the two
+    cursors count different logs and may never be compared (see the contract)."""
+    _advance(start, "pushed", pushed)
+
+
+def _advance(start: Path | str, field: str, value: int) -> None:
+    current = require_remote(start)
+    if value > int(current[field]):                     # type: ignore[literal-required]
+        stored = dict(current)
+        stored[field] = int(value)
+        write(resolve_root(start), cast("Remote", stored))