taskops-cli 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

taskops/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
 __title__ = "taskops"
-__version__ = "0.3.0"  # single source of truth; pyproject reads it dynamically
+__version__ = "0.3.2"  # single source of truth; pyproject reads it dynamically

taskops/_wire.py

@@ -1,4 +1,6 @@
 """One POST, one envelope, one place that turns an HTTP failure into OUR error.
+And, since the host learned to ask a forge, one GET that deliberately does NOT
+wear that envelope — `get()` at the bottom says why.
 
     {"ok": true,  "seq": 41, "data": {...}}     ->  the data, with `seq` in it
     {"ok": false, "error": {"code", "message"}} ->  raised, in the SERVER's words
@@ -53,6 +55,49 @@ def post(
     return _unwrap(envelope, url)
 
 
+def get(url: str, headers: dict[str, str], timeout: float) -> tuple[int, dict[str, Any]]:
+    """GET JSON from a server that is NOT a taskops one — the status comes back.
+
+    `post` unwraps `{"ok", "data"}` because both of its callers speak to a
+    taskops door. A forge does not: it answers its own shape and says what it
+    MEANS in the status — 401 is a bad token, 404 is "no repo you can see" —
+    so flattening those into one error would throw away the only thing the
+    caller can turn into a sentence somebody can act on.
+
+    What stays shared is the failure with no status at all: a refused
+    connection, a DNS miss, a timeout. That is `Unreachable` here exactly as it
+    is above, because the one caller of this function GRANTS on its answer and
+    must never be able to read silence as a yes.
+    """
+    request = Request(url, headers=headers, method="GET")  # noqa: S310 — https, from our config
+    try:
+        with urlopen(request, timeout=timeout) as answer:  # noqa: S310
+            return int(answer.status), _decode(answer.read())
+    except HTTPError as err:
+        return int(err.code), _decode(_body_of(err))
+    except (URLError, TimeoutError, ValueError) as err:
+        raise Unreachable(
+            f"{url} did not answer ({err}). Nothing was granted and nothing was written — "
+            "a host that cannot ask does not guess."
+        ) from err
+
+
+def _body_of(err: HTTPError) -> bytes:
+    try:
+        return err.read()
+    except OSError:  # pragma: no cover — a body that dies mid-read
+        return b""
+
+
+def _decode(raw: bytes) -> dict[str, Any]:
+    """A foreign answer that is not an object is not an error here: the STATUS
+    already carried the meaning, and the caller reads a field or finds none."""
+    try:
+        return as_object(json.loads(raw or b"{}"))
+    except ValueError:
+        return {}
+
+
 def _unwrap(body: dict[str, Any], url: str) -> dict[str, Any]:
     """v1 let three verbs answer with a bare array, which the client decoder turned
     into `{}` with no error anywhere. Here a missing envelope is loud."""

taskops/cli/commands.py

@@ -1,7 +1,9 @@
-"""The two commands that CONNECT a repo to a board, and the git hooks.
+"""The two commands that CONNECT a repo to a board: `init` and `join`.
 
-`serve`, `invite` and `ui` — the ones that run a server — live in `serving.py`.
-`main.py` only parses and dispatches.
+`serve`, `invite` and `ui` — the ones that run a server — live in `serving.py`,
+and what the git hooks call is `hooks.py`. Both were split off this file rather
+than growing it: these two WRITE a checkout's configuration once, and neither
+runs a server nor fires on every commit. `main.py` only parses and dispatches.
 """
 
 from __future__ import annotations
@@ -16,7 +18,7 @@ from .._json import query
 from ..board import DIR, find_root, open_board
 from ..store import log
 from .._errors import TaskopsError
-from ..gitwork import run, bind, remote, install, trailer, claudefiles
+from ..gitwork import remote, install, claudefiles
 
 # ── the commands ────────────────────────────────────────────────────────────
 
@@ -24,7 +26,7 @@ from ..gitwork import run, bind, remote, install, trailer, claudefiles
 def init(here: Path) -> int:
     root = find_root(here)
     (root / DIR / "board").mkdir(parents=True, exist_ok=True)
-    (root / DIR / "board.json").write_text("{}\n", encoding="utf-8")
+    install.write_local(root)
     _wire(root, actor())
     print(f"local board in {root / DIR / 'board'} — the MCP tools are the way in")
     return 0
@@ -40,8 +42,21 @@ ORPHAN = (
 )
 
 
-def join(
-    here: Path, target: str, given: str, key: str = "", discard: bool = False, invite: str = ""
+BOTH = (
+    "--invite and --github are two ways to be introduced to the same host, and running "
+    "both would burn the invite for nothing. Pick one: --invite <id> if somebody minted "
+    "you a link, --github if you have push on the repo the board declared."
+)
+
+
+def join(  # noqa: PLR0913 — one command, one config; each flag is a way IN
+    here: Path,
+    target: str,
+    given: str,
+    key: str = "",
+    discard: bool = False,
+    invite: str = "",
+    github: bool = False,
 ) -> int:
     """Connect this repo to a board. Bare like every other verb since the host is
     recorded and the key is discovered:
@@ -49,6 +64,7 @@ def join(
         taskops remote add https://host:8787        once per checkout
         taskops join my-project                     registered key: signs in, done
         taskops join my-project --invite <id>       first time: enrols the key too
+        taskops join my-project --github            first time, no invite: GitHub vouches
         taskops join my-project                     no key anywhere + public board: read-only
 
     The name defaults exactly as `board create`'s does (recorded name, else the
@@ -64,9 +80,13 @@ def join(
     archives (never deletes) before proceeding.
 
     With an invite, the invite and the PUBKEY travel in the same call: the server
-    burns the invite and enrols the key in one act. Either way the key then signs
-    in ON THE SPOT and what lands in remote.json is a SESSION with an expiry —
-    never a standing token to copy around. Keys exist so tokens do not travel.
+    burns the invite and enrols the key in one act. `--github` is the same shape
+    with a different proof — a token the CLI already has instead of a link
+    somebody minted (`enrol.by_github`), and it takes no value on purpose. Either
+    way the key then signs in ON THE SPOT and what lands in remote.json is a
+    SESSION with an expiry — never a standing token to copy around, and never the
+    GitHub one, which this process has already forgotten by the time it writes.
+    Keys exist so tokens do not travel.
     """
     from . import remote as remote_cli
 
@@ -76,9 +96,14 @@ def join(
         host, name = remote_cli.named(target)
         target = f"{host}/{name}"
     base = target.partition("?")[0]
-    _keep_or_archive(root, base, discard)
     params = query(target)
     invite = invite or params.get("invite", "")
+    # Before `_keep_or_archive`, which is the first thing here that MOVES anything:
+    # a refusal that had already renamed the local board would be the worse order,
+    # and the invite in a pasted `?invite=` link counts exactly as the flag does.
+    if invite and github:
+        raise TaskopsError(BOTH)
+    _keep_or_archive(root, base, discard)
     who = given or actor()
     name = who.partition(":")[2] or "me"
     found = Path(key).expanduser() if key else identity.discover_key()
@@ -87,6 +112,13 @@ def join(
         token, who = enrol.redeem(base, invite, name, enrol.pubkey(str(found) if found else ""))
         if found:
             door = {"host": enrol.host_of(base), "principal": name, "key": str(found)}
+    elif github:
+        # The door mints NOTHING (`http/github.py`), so there is no token to keep
+        # here: the enrolled key is the credential from the next line onwards.
+        vouched = enrol.by_github(base, name, enrol.pubkey(str(found) if found else ""))
+        who = vouched["actor"]
+        door = {"host": enrol.host_of(base), "principal": name, "key": str(found)}
+        print(f"  GitHub: you have {vouched['need']} on {vouched['repo']} — key enrolled")
     elif bare and found:
         # No invite and no token: the KEY is the whole credential. Proved against
         # the host BEFORE anything is written — a refused sign-in must not leave
@@ -123,29 +155,6 @@ def _keep_or_archive(root: Path, url: str, discard: bool) -> None:
     print(f"  the local board ({len(events)} events) is archived at {archive(local)}")
 
 
-def hook(here: Path, which: str, rest: list[str]) -> int:
-    """The two GIT hooks; `hook claude` is routed in `main` and never prints.
-
-    Neither of these may block a commit. Failures print and return 0.
-    """
-    root = find_root(here)
-    if which == "trailer":
-        if rest:
-            trailer.stamp_file(Path(rest[0]), run.branch_at(here))
-        return 0
-    facts = bind.commit_facts(here)
-    if facts is None:
-        return 0
-    try:
-        board = open_board(root, actor())
-        bind.record(board, root, facts)
-        bind.drain(board, root)
-    except TaskopsError as err:
-        print(f"taskops: {err}", file=sys.stderr)  # visible, never swallowed
-    bind.push_card(here, str(facts["branch"]))
-    return 0
-
-
 # ── plumbing ────────────────────────────────────────────────────────────────
 
 

taskops/cli/enrol.py

@@ -4,10 +4,19 @@ Split out of `commands.py` at its own seam — `join` and `board push` both need
 exactly this and only this: a repo with a local board has never joined
 anything, so its first push may also be its first introduction to the host,
 and there must not be two redemptions to keep in step.
+
+There are two introductions now and they end in the SAME place: a pubkey this
+host knows, and a session minted from it moments later. `redeem` burns an
+invite somebody minted for you; `by_github` (`http/github.py` is the door)
+lets a repo's membership stand in for that invite. Neither leaves a standing
+credential behind, and the GitHub token in particular is a LOCAL — read here,
+put in one request body, and gone with the frame.
 """
 
 from __future__ import annotations
 
+import os
+import getpass
 from pathlib import Path
 
 from .._wire import post as post_json
@@ -40,6 +49,79 @@ def pubkey(key: str) -> str:
         ) from err
 
 
+NO_KEY = (
+    "--github enrols an ssh KEY, and there is none to enrol — GitHub introduces you once "
+    "and the key is what signs you in from then on. Make one and try again:\n"
+    "  ssh-keygen -t ed25519\n"
+    "or point at an existing one: taskops join <board> --github --key <path>"
+)
+
+NO_TOKEN = (
+    "no GitHub token, and nothing was sent. Any ONE of these gives me one:\n"
+    "  gh auth login              the CLI's token is read automatically\n"
+    "  export GITHUB_TOKEN=…      an environment variable\n"
+    "  (or paste it at the hidden prompt)\n"
+    "There is deliberately no --github <token>: a token in a flag lands in your shell "
+    "history forever, and this one is only ever used for a single call."
+)
+
+
+def by_github(base: str, who: str, public: str) -> dict[str, str]:
+    """GitHub vouches for you ONCE, and what stays behind is your pubkey.
+
+    The token is fetched here, travels in this one request body, and is never
+    returned, printed, cached or written: what comes back names the principal
+    this host now knows and the repo that proved it, and the caller's very next
+    act is the ordinary `/login` challenge with the key just enrolled. That is
+    why nothing in this function can put a GitHub token in `remote.json` — it
+    has none to put there by the time `join` writes the file.
+    """
+    if not public:
+        raise TaskopsError(NO_KEY)
+    data = post_json(
+        f"{base.rstrip('/')}/join/github",
+        {"github_token": github_token(), "principal": who, "pubkey": public},
+        {},
+        20.0,
+    )
+    return {
+        "actor": str(data.get("actor", f"dev:{who}")),
+        "repo": str(data.get("repo", "")),
+        "need": str(data.get("need", "")),
+    }
+
+
+def github_token() -> str:
+    """WHERE the token comes from, in order — and never from a flag value.
+
+    `gh auth token` first, because the CLI is already installed and already
+    authenticated on the machine of anybody who has push on a repo, so the
+    common case asks the human nothing. Then `$GITHUB_TOKEN`, which is how CI
+    and a shell that never installed `gh` say it. Then a HIDDEN prompt.
+
+    **A flag is not one of the sources and must never become one.** `--github`
+    takes no value: a secret passed as an argument is written to
+    `~/.zsh_history` by the shell before the process starts, survives every
+    rotation of the token, and is visible in `ps` to every user on the box
+    while the command runs. The prompt is the fallback precisely because it is
+    the one input that leaves no trace.
+    """
+    from ..gitwork import run
+
+    try:
+        asked = run.tool("gh", "auth", "token", timeout=20.0)
+    except TaskopsError:
+        asked = None  # no `gh` on PATH, or it hung — the next source answers
+    if asked is not None and asked.ok and asked.out.strip():
+        return asked.out.strip()
+    if os.environ.get("GITHUB_TOKEN", "").strip():
+        return os.environ["GITHUB_TOKEN"].strip()
+    typed = getpass.getpass("GitHub token (input hidden, used once, stored nowhere): ").strip()
+    if not typed:
+        raise TaskopsError(NO_TOKEN)
+    return typed
+
+
 def host_of(base: str) -> str:
     """The SERVER, out of a board address: `/login` is server scope, not a board's."""
     return base.rstrip("/").rpartition("/")[0]

taskops/cli/grants.py

@@ -0,0 +1,59 @@
+"""`taskops invite` · `taskops revoke` — handing a credential out, and taking it back.
+
+    taskops invite <who> --board <name>    owner only — prints the join line
+    taskops revoke --key <SHA256:…> | --invite <id>
+
+The laptop half of `http/grants.py`, and the split is that seam and not a line
+count: `operate.py` is about a BOARD (create it, list them, say who may read it,
+name the forge that opens it) and this is about a CREDENTIAL — the two never
+share an argument. They do share the transport, which stays in `operate.py`
+where `push.py` already reaches for it; a third module holding three lines of
+`_wire.post` would be one more file to find and nothing to decide in it.
+
+**THE BREAK-GLASS PATH SURVIVES** on both verbs: `--root <dir>` runs the same
+act against the files directly, on the machine that holds them, and it is what
+you use when the server is down or the owner's key is lost. Not deprecated,
+never to be removed — a system whose only door is its own API cannot be
+repaired when that API is what broke. Those two acts live in `cli/admin.py`,
+beside `server init`: that module runs ON the box, this one is the laptop.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from . import admin
+from .remote import address
+from .operate import call, signed_in
+from .._errors import TaskopsError
+
+
+def invite(args: argparse.Namespace) -> int:
+    """A one-time join line, minted by the server that will honour it."""
+    who, name = str(args.who), str(args.board)
+    if not who:
+        raise TaskopsError("taskops invite <who> --board <name>")
+    if args.root:  # break-glass: the files, on the box
+        return admin.on_box_invite(Path(str(args.root)).expanduser(), who, name)
+    if not name:
+        raise TaskopsError("which board? taskops invite <who> --board <name>")
+    host, _ = address(str(args.host))
+    made = call(host, "invite.mint", {"who": who, "board": name}, signed_in(host, args))
+    print(f"one-time invite for {who} (id {made['id']}, 7 days):")
+    print(f"  taskops join \"{host}/{made['board']}?invite={made['token']}\" --key ~/.ssh/id_ed25519")
+    return 0
+
+
+def revoke(args: argparse.Namespace) -> int:
+    """A key stops signing anybody in; an invite stops being redeemable."""
+    key, ident = str(args.key), str(args.invite)
+    if bool(key) == bool(ident):
+        raise TaskopsError("taskops revoke --key <SHA256:…> | --invite <id> — exactly one")
+    if args.root:  # break-glass: the files, on the box
+        return admin.on_box_revoke(Path(str(args.root)).expanduser(), key, ident)
+    host, _ = address(str(args.host))
+    verb = "key.revoke" if key else "invite.revoke"
+    gone = call(host, verb, {"key": key} if key else {"invite": ident}, signed_in(host, args, "sign_key"))
+    print(f"revoked {key or ident} ({gone.get('principal') or gone.get('subject')}) on {host}")
+    return 0

taskops/cli/hooks.py

@@ -0,0 +1,50 @@
+"""What the two GIT hooks call — the other half of what `join` installed.
+
+Split off `commands.py` at the seam that file's own docstring named ("the two
+commands that CONNECT a repo to a board, **and the git hooks**), the same way
+`serving.py` and `watch.py` were: `init` and `join` WRITE a checkout's
+configuration once, and these two run on every single commit somebody makes in
+it. Nothing here is reachable from a human's fingers — `gitwork/install.py`
+writes the shell scripts that call it, and `main.py` routes them.
+
+**Neither of these may ever block a commit.** A failure prints and returns 0.
+The hook is a courtesy that binds a commit to its card; a board that is down,
+a network that is out or a card that was closed a minute ago must cost somebody
+their commit exactly never. That is why the `TaskopsError` below is caught and
+written to stderr instead of raised — visible, and never in the way.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ..board import find_root, open_board
+from .._errors import TaskopsError
+from ..gitwork import run, bind, trailer
+from .commands import actor
+
+
+def hook(here: Path, which: str, rest: list[str]) -> int:
+    """`hook trailer` stamps the message, `hook commit` binds the commit.
+
+    `hook claude` is a third one and it is routed in `main` instead, because it
+    prints NOTHING ever — including the `taskops: …` line every other failure
+    here is allowed to write.
+    """
+    root = find_root(here)
+    if which == "trailer":
+        if rest:
+            trailer.stamp_file(Path(rest[0]), run.branch_at(here))
+        return 0
+    facts = bind.commit_facts(here)
+    if facts is None:
+        return 0
+    try:
+        board = open_board(root, actor())
+        bind.record(board, root, facts)
+        bind.drain(board, root)
+    except TaskopsError as err:
+        print(f"taskops: {err}", file=sys.stderr)  # visible, never swallowed
+    bind.push_card(here, str(facts["branch"]))
+    return 0

taskops/cli/main.py

@@ -1,7 +1,7 @@
 """The CLI, which behaves like git: it connects, it never manages.
 
     taskops init            a local board in this repo
-    taskops join <url>      join one (?token= or ?invite=), install the hooks
+    taskops join <url>      join one (?token=, ?invite= or --github), install the hooks
     taskops remote add <url>  the host this checkout operates, like git's origin
     taskops serve           host boards — an events API, no dashboard
     taskops server init     bootstrap THIS host: its owner and their ssh key
@@ -9,7 +9,13 @@
                             with a remote recorded and a key on disk, all of these
                             go BARE: no URL, no --key, no board name
     taskops board push      THIS repo's local board becomes the hosted one
+    taskops board pull      the reverse: a hosted board comes down as a SNAPSHOT
+                            that stops moving — the host keeps everything
+    taskops board rm        take a board OFF a host — refuses to destroy a history
+                            this checkout does not hold (--discard-history says so)
     taskops board visibility <host>/<name> public|private   owner only
+    taskops board forge <owner>/<repo> [--need push|admin]  owner only — GitHub opens it
+    taskops board forge --clear                             invite-only again
     taskops invite <who>    a single-use link  ·  taskops revoke --key|--invite
     taskops tidy            remove worktrees whose work is already in the trunk
     taskops ui              the dashboard — serves it if nothing is, opens the browser
@@ -27,95 +33,29 @@ import argparse
 from typing import Sequence
 from pathlib import Path
 
-from . import push as promote, admin, claude, remote, operate, serving, commands
+from . import (
+    rm,
+    pull as download,
+    push as promote,
+    admin,
+    hooks,
+    claude,
+    grants,
+    parser as flags,
+    remote,
+    operate,
+    serving,
+    commands,
+)
 from ..board import find_root
 from .._errors import TaskopsError
 from ..gitwork import trees
 
-AS_HELP = "the principal that key belongs to (default: $USER)"
-
 
 def main(argv: Sequence[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="taskops", description=__doc__)
-    sub = parser.add_subparsers(dest="command", required=True)
-    sub.add_parser("init", help="a local board in this repo")
-    join = sub.add_parser("join", help="join a board and install the hooks")
-    join.add_argument(
-        "url",
-        nargs="?",
-        default="",
-        help="<name>, <host>/<name>, or nothing (the recorded/directory name) — "
-        "a full https:// URL with ?token= or ?invite= keeps working",
-    )
-    join.add_argument("--as", dest="actor", default="", help="dev:<name> (default: $USER)")
-    join.add_argument(
-        "--invite",
-        default="",
-        help="first join: the single-use id from `taskops invite` — your key is enrolled with it",
-    )
-    join.add_argument(
-        "--discard-local",
-        action="store_true",
-        help="a local board here is archived instead of orphaned by the join",
-    )
-    join.add_argument(
-        "--key",
-        default="",
-        help="overrides the discovered ssh key (its .pub is what gets registered)",
-    )
-    origin = sub.add_parser("remote", help="the host this checkout operates (git's origin)")
-    origin.add_argument("action", nargs="?", default="", choices=["", "add"])
-    origin.add_argument("url", nargs="?", default="", help="https://<host>")
-    origin.add_argument(
-        "--replace", action="store_true", help="this checkout already names another host"
-    )
-    server = sub.add_parser("serve", help="host boards")
-    server.add_argument("--root", default="~/taskops-boards")
-    server.add_argument("--host", default="127.0.0.1")
-    server.add_argument("--port", type=int, default=8787)
-    host = sub.add_parser("server", help="operate this HOST (over ssh, once): its owner")
-    host.add_argument("action", choices=["init"])
-    host.add_argument("--root", default="~/taskops-boards")
-    host.add_argument("--key", default="", help="the owner's pubkey: a path, or - for stdin")
-    host.add_argument("--owner", default="", help="the owner's name (default: $USER)")
-    boards = sub.add_parser("board", help="create or list the boards on a host")
-    boards.add_argument("action", choices=["create", "ls", "push", "visibility"])
-    boards.add_argument("target", nargs="?", default="", help="<host>/<name>, or just <name>")
-    boards.add_argument(
-        "visibility",
-        nargs="?",
-        default="",
-        choices=["", "public", "private"],
-        help="visibility: public means ANONYMOUS READ — writing always needs a key",
-    )
-    boards.add_argument("--key", default="", help="the ssh key that signs you in")
-    boards.add_argument("--invite", default="", help="push: register that key first")
-    boards.add_argument("--as", dest="principal", default="", help=AS_HELP)
-    invite = sub.add_parser("invite", help="a single-use link for a teammate")
-    invite.add_argument("who", nargs="?", default="")
-    invite.add_argument("--board", default="")
-    invite.add_argument("--host", default="", help="the server (default: the one you joined)")
-    invite.add_argument("--key", default="", help="the ssh key that signs you in")
-    invite.add_argument("--as", dest="principal", default="", help=AS_HELP)
-    # `--root` is BREAK-GLASS and so it has no default: passing it is the deliberate
-    # choice to work on the files, on the box, when the API is what broke.
-    invite.add_argument("--root", default="", help="break-glass: the boards dir, ON the host")
-    kill = sub.add_parser("revoke", help="a key or an invite stops working")
-    kill.add_argument("--key", default="", help="a fingerprint: SHA256:…")
-    kill.add_argument("--invite", default="", help="a credential id")
-    kill.add_argument("--host", default="")
-    # NOT `--key`: on this verb that word is already the fingerprint being revoked.
-    kill.add_argument("--sign-key", default="", help="the ssh key that signs YOU in")
-    kill.add_argument("--as", dest="principal", default="", help=AS_HELP)
-    kill.add_argument("--root", default="", help="break-glass: the boards dir, ON the host")
-    tidy = sub.add_parser("tidy", help="remove integrated worktrees and branches")
-    tidy.add_argument("--trunk", default="")
-    sub.add_parser("ui", help="the dashboard: serve if needed, open the browser, token included")
-    hook = sub.add_parser("hook", help="internal: what the installed hooks call")
-    hook.add_argument("which", choices=["trailer", "commit", "claude"])
-    hook.add_argument("rest", nargs="*")
-
-    args = parser.parse_args(argv)
+    """Parse (`parser.py` holds every flag), then dispatch — and turn the one
+    error type the whole program raises into a line and an exit code."""
+    args = flags.build(__doc__ or "").parse_args(argv)
     try:
         return _run(args)
     except TaskopsError as err:
@@ -135,6 +75,7 @@ def _run(args: argparse.Namespace) -> int:
             str(args.key),
             bool(args.discard_local),
             str(args.invite),
+            bool(args.github),
         )
     if args.command == "remote":
         return remote.remote(args)
@@ -143,14 +84,24 @@ def _run(args: argparse.Namespace) -> int:
     if args.command == "server":
         return admin.server(args)
     if args.command == "board":
-        # `push` is its own module — five ordered steps and a config flip, against
-        # `board`'s two one-shot calls — so `main` routes it, and neither imports
-        # the other (`push.py` needs `operate`'s transport and its address parser).
-        return promote.run(args) if str(args.action) == "push" else operate.board(args)
+        # `push` and `pull` are each their own module — five ordered steps and a
+        # config flip, against `board`'s two one-shot calls — so `main` routes
+        # them, and neither imports the other (both need `operate`'s transport
+        # and its address parser, and nothing needs them back). `rm` is separated
+        # for the mirrored reason: one call, and a guardrail around it that is
+        # the whole command.
+        action = str(args.action)
+        if action == "push":
+            return promote.run(args)
+        if action == "pull":
+            return download.run(args)
+        if action == "rm":
+            return rm.run(args)
+        return operate.board(args)
     if args.command == "invite":
-        return operate.invite(args)
+        return grants.invite(args)
     if args.command == "revoke":
-        return operate.revoke(args)
+        return grants.revoke(args)
     if args.command == "tidy":
         removed = trees.tidy(find_root(here), str(args.trunk))
         print("\n".join(removed) if removed else "nothing to tidy — no integrated worktrees")
@@ -162,4 +113,4 @@ def _run(args: argparse.Namespace) -> int:
         # own error policy end to end: it prints NOTHING, ever, including the
         # `taskops: …` line `main()` writes for every other failure.
         return claude.deliver(here)
-    return commands.hook(here, str(args.which), [str(x) for x in args.rest])
+    return hooks.hook(here, str(args.which), [str(x) for x in args.rest])