rendez-cli 0.1.0__py3-none-any.whl

rendez/__init__.py

@@ -0,0 +1,1134 @@
+#!/usr/bin/env python3
+"""rendez — put the repository you are already in into a Rendez session.
+
+    $ rendez connect
+    Session  rate limit signups
+    Share    http://localhost:3000/sessions/8f3a...
+    Workspace ~/code/Hive  (main, clean)
+
+    [Priya] the counter should be in Postgres, we run several processes
+    [agent] Reading signup-service/main.py
+    ...
+
+**What it is.** A second client, not a second system. It speaks the same
+websocket protocol as the web app -- same `?user=` identity, same `since=`
+replay -- and adds one capability the browser cannot have: it offers the
+local filesystem as the session's workspace. The agent's `read_file`,
+`write_file` and `list_dir` then run here, against the real repository, with
+the developer's own branch and credentials.
+
+Everything else stays on the server: the agent, the plan, conflict detection,
+permissions, the event log. This process only has hands.
+
+**Why one machine.** The agent can reason about one filesystem. Three people
+have three different trees, so "whose disk?" needs an answer, and the honest
+one is "whoever ran this". Everyone else watches in the browser. See
+`server/app/host.py`.
+
+**Shell asks first** (`DEC-022`). Commands that obviously only read run
+unprompted; anything else is put to you, here, and only you can answer -- it
+is your machine. A redirect kills the command's whole process group, so an
+interrupted `npm test` does not leave its runner behind.
+
+**What it deliberately does not do.**
+
+  * No git operations. It reports the branch for display and never commits,
+    pushes or checks out.
+  * No second host. One machine per session.
+  * No sandbox. Paths are confined to the repository root, which stops `../`
+    and nothing else: a `.env` inside the root is inside the root.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+from http.cookies import SimpleCookie
+import json
+import os
+import signal
+import subprocess
+import sys
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+try:
+    import websockets
+except ImportError:  # pragma: no cover - guidance beats a stack trace
+    sys.exit("rendez needs `websockets`: pip install websockets")
+
+# The deployed product, because this is an installed package: someone who runs
+# `pipx install rendez-cli` and then `rendez login` means the real service, not
+# an empty localhost. Developing against a local stack is the case that sets
+# `RENDEZ_API`/`RENDEZ_WEB`, or passes `--api`/`--web` -- it knows it is the
+# exception. The old defaults were `localhost:8100` and `localhost:3000`, and
+# the API one did not even match the server's own port (`R-102`).
+DEFAULT_API = os.getenv("RENDEZ_API", "https://rendez-server.onrender.com")
+DEFAULT_WEB = os.getenv("RENDEZ_WEB", "https://rendez.space")
+AUTH_FILE = Path(os.environ["RENDEZ_AUTH_FILE"]) if os.environ.get("RENDEZ_AUTH_FILE") else Path.home() / ".config" / "rendez" / "auth.json"
+
+
+def saved_token(api: str) -> str:
+    try:
+        return json.loads(AUTH_FILE.read_text()).get(api, "")
+    except (OSError, ValueError):
+        return ""
+
+
+def save_token(api: str, token: str) -> None:
+    try:
+        data = json.loads(AUTH_FILE.read_text())
+    except (OSError, ValueError):
+        data = {}
+    if token:
+        data[api] = token
+    else:
+        data.pop(api, None)
+    AUTH_FILE.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd = os.open(AUTH_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as out:
+        json.dump(data, out)
+    AUTH_FILE.chmod(0o600)
+
+
+def api_json(url: str, token: str = "", body: dict | None = None) -> dict | list:
+    headers = {"authorization": f"Bearer {token}"} if token else {}
+    if body is not None:
+        headers["content-type"] = "application/json"
+    req = urllib.request.Request(url, json.dumps(body).encode() if body is not None else None,
+                                 headers)
+    with urllib.request.urlopen(req, timeout=15) as response:
+        return json.load(response)
+
+
+# The protocol this client speaks. The server advertises its own range on
+# `/health`; see `DEC-092`. This is not the package version: a release that
+# changes nothing on the wire leaves it alone.
+CLIENT_PROTOCOL = 1
+
+
+def check_protocol(api: str) -> str:
+    """Compare wire versions with the server. Returns a warning, or "".
+
+    Never fatal on its own. A server that predates the handshake answers
+    without the fields, and an unreachable one is the connect path's problem
+    to report -- neither is a reason for this to stop the run.
+    """
+    try:
+        health = api_json(f"{api}/health")
+    except Exception:                                    # noqa: BLE001
+        return ""
+    if not isinstance(health, dict) or "protocol" not in health:
+        return ""                                        # older server
+    try:
+        server_protocol = int(health["protocol"])
+        min_client = int(health.get("min_client", server_protocol))
+    except (TypeError, ValueError):
+        return ""
+    if CLIENT_PROTOCOL < min_client:
+        return (f"This rendez is too old for {api}: it speaks protocol "
+                f"{CLIENT_PROTOCOL}, the server needs {min_client} or newer.\n"
+                "Upgrade with: pipx upgrade rendez-cli")
+    if CLIENT_PROTOCOL > server_protocol:
+        return (f"This rendez speaks protocol {CLIENT_PROTOCOL} and {api} "
+                f"serves {server_protocol}. Newer features may be missing.")
+    return ""
+
+
+def login_cli(api: str) -> int:
+    # Checked here too, so a client that has fallen out of range says so at
+    # the first command rather than signing in and failing at the second.
+    warning = check_protocol(api)
+    if warning:
+        print(warning, file=sys.stderr)
+        if warning.startswith("This rendez is too old"):
+            return 1
+    # The username, not the email (`DEC-067` narrowed sign-in to one
+    # identifier). The request field is still called `email` because that is
+    # what the server's `Credentials` model names it; it carries a username.
+    # Prompting for an address here produced "Invalid username or password"
+    # with nothing to say why.
+    username = input("Username: ").strip()
+    password = getpass.getpass("Password: ")
+    req = urllib.request.Request(f"{api}/auth/login",
+        json.dumps({"email": username, "password": password}).encode(),
+        {"content-type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=15) as response:
+            cookie = SimpleCookie()
+            cookie.load(response.headers.get("Set-Cookie", ""))
+            token = cookie["rendez_session"].value
+    except (urllib.error.URLError, KeyError) as exc:
+        print(f"Sign in failed: {exc}", file=sys.stderr)
+        return 1
+    save_token(api, token)
+    print("Signed in. You can now run rendez connect.")
+    return 0
+
+# Refuse to read or write anything larger than this. A tool result is re-sent
+# to the model on every subsequent request (the text runtime carries its own
+# history), so one large file does not cost once -- it costs every turn for
+# the rest of the session.
+MAX_BYTES = 256 * 1024
+# A diff is for reading. A regenerated lockfile is a legitimate change and
+# thousands of useless lines, so the per-file diff and the number of files
+# diffed are both capped; the file list itself is never truncated.
+MAX_DIFF_BYTES = 64 * 1024
+MAX_DIFF_FILES = 50
+
+
+class Workspace:
+    """The local repository, and the only part of the disk this exposes.
+
+    Every path is resolved and checked against the root. A path that escapes
+    is refused rather than clamped, so the failure is visible in the
+    transcript instead of quietly reading the wrong file.
+
+    This is a confinement check, not a sandbox. It stops the agent walking up
+    out of the repository with `../`; it does not stop anything else running
+    on this machine, and it does not make the repository's own secrets safe
+    -- a `.env` inside the root is inside the root.
+    """
+
+    def __init__(self, root: Path):
+        self.root = root.resolve()
+
+    def _resolve(self, rel: str) -> Path:
+        p = (self.root / rel).resolve()
+        if not p.is_relative_to(self.root):
+            raise ValueError(f"path escapes the workspace: {rel}")
+        return p
+
+    def read_file(self, path: str) -> str:
+        p = self._resolve(path)
+        if not p.is_file():
+            raise FileNotFoundError(f"no such file: {path}")
+        if p.stat().st_size > MAX_BYTES:
+            raise ValueError(
+                f"{path} is {p.stat().st_size // 1024}KB; the limit is "
+                f"{MAX_BYTES // 1024}KB")
+        return p.read_text(errors="replace")
+
+    def write_file(self, path: str, content: str) -> str:
+        if len(content.encode()) > MAX_BYTES:
+            raise ValueError(f"refusing to write more than {MAX_BYTES} bytes")
+        p = self._resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        existed = p.is_file()
+        p.write_text(content)
+        return (f"{'updated' if existed else 'created'} {path} "
+                f"({len(content)} bytes)")
+
+    def list_dir(self, path: str = ".") -> list[str]:
+        p = self._resolve(path or ".")
+        if not p.is_dir():
+            raise NotADirectoryError(f"not a directory: {path}")
+        # Skip the noise that makes a listing useless in a real repository.
+        skip = {".git", "node_modules", "__pycache__", ".next", ".venv"}
+        return sorted(e.name + ("/" if e.is_dir() else "")
+                      for e in p.iterdir() if e.name not in skip)
+
+    def remote(self) -> str:
+        """The origin URL, or "" if there is no remote.
+
+        Used to identify the repository across machines (`DEC-023`), so a
+        teammate's clone of the same project matches this one.
+        """
+        try:
+            out = subprocess.run(("git", "remote", "get-url", "origin"),
+                                 cwd=self.root, capture_output=True,
+                                 text=True, timeout=5)
+            return out.stdout.strip() if out.returncode == 0 else ""
+        except (OSError, subprocess.SubprocessError):
+            return ""
+
+    def root_commit(self) -> str:
+        """The first commit's hash, or "" if there isn't a usable one.
+
+        A repository with no remote has no identity to share, so `DEC-023`
+        files it under its absolute path -- and renaming the directory then
+        hides every session for it. The root commit is computed locally by
+        git, needs no server, and does not change when the checkout moves.
+
+        **Refused for a shallow clone.** `--max-parents=0` returns the commit
+        history was truncated at, which has no visible parents and is not the
+        root: exit code 0 and a plausible hash that changes with every new
+        commit. Measured -- a `--depth 1` clone answers with its own HEAD.
+        That is worse than the path it would replace, and silent, so a
+        shallow repository keeps the path fallback.
+        """
+        def run(*args: str) -> str:
+            try:
+                out = subprocess.run(("git", *args), cwd=self.root,
+                                     capture_output=True, text=True, timeout=5)
+                return out.stdout.strip() if out.returncode == 0 else ""
+            except (OSError, subprocess.SubprocessError):
+                return ""
+
+        if run("rev-parse", "--is-shallow-repository") != "false":
+            return ""
+        # `rev-list` lists every root on a repository with grafted or
+        # unrelated histories. The oldest is the one that does not move.
+        roots = run("rev-list", "--max-parents=0", "HEAD").split()
+        return roots[-1] if roots else ""
+
+    def git_changes(self) -> dict:
+        """What `git status` says, plus a diff per changed file.
+
+        The room reviews the agent's work from the browser; without this they
+        read a transcript saying "wrote app/cart.py" and have to open an IDE
+        to see what that meant. `--porcelain=v1 -z` so paths with spaces or
+        quotes survive, and the diff is capped: a vendored lockfile is a real
+        change and a useless thing to render.
+        """
+        def run(*args: str, ok=(0,)) -> str | None:
+            try:
+                out = subprocess.run(("git", *args), cwd=self.root,
+                                     capture_output=True, text=True,
+                                     timeout=15, errors="replace")
+                return out.stdout if out.returncode in ok else None
+            except (OSError, subprocess.SubprocessError):
+                return None
+
+        status = run("status", "--porcelain=v1", "-z")
+        if status is None:
+            # `git status` failed, which says nothing about whether this
+            # machine is hosting the session -- it is, or this call could not
+            # have arrived. Reporting `attached: False` here made the server
+            # spread it over its own answer and the Files tab tell someone
+            # with a running CLI to go and run `rendez connect`.
+            #
+            # No git installed, or a directory that is not a repository: the
+            # file tools work normally, there is simply no change list to
+            # show. Say which, because "no changes" and "cannot see changes"
+            # look identical in an empty panel.
+            return {"attached": True, "files": [], "branch": "",
+                    "root": str(self.root), "no_git": True}
+        files, parts = [], [p for p in status.split("\0") if p]
+        i = 0
+        while i < len(parts):
+            entry = parts[i]
+            code, path = entry[:2], entry[3:]
+            # A rename's old path is the next NUL-separated field, not part
+            # of this one -- splitting on " -> " instead loses files whose
+            # names contain that sequence.
+            if "R" in code and i + 1 < len(parts):
+                i += 1
+            files.append({"status": code.strip() or "?", "path": path})
+            i += 1
+
+        for f in files[:MAX_DIFF_FILES]:
+            # `--no-index` exits 1 when the files differ, which is the normal
+            # case here and not an error; treating it as one silently dropped
+            # every new file's diff.
+            diff = (run("diff", "--no-color", "--no-index", "/dev/null", f["path"], ok=(0, 1))
+                    if f["status"] == "??" else
+                    run("diff", "--no-color", "--", f["path"]))
+            if diff and len(diff) > MAX_DIFF_BYTES:
+                diff = diff[:MAX_DIFF_BYTES] + "\n... diff truncated ..."
+            f["diff"] = diff or ""
+        branch, _ = self.git()
+        return {"attached": True, "branch": branch, "root": str(self.root),
+                "files": files, "truncated": len(files) > MAX_DIFF_FILES}
+
+    def git(self) -> tuple[str, bool]:
+        """Branch and whether the tree is dirty. For display only."""
+        def run(*args: str) -> str | None:
+            try:
+                out = subprocess.run(("git", *args), cwd=self.root,
+                                     capture_output=True, text=True, timeout=5)
+                return out.stdout.strip() if out.returncode == 0 else None
+            except (OSError, subprocess.SubprocessError):
+                return None
+        branch = run("rev-parse", "--abbrev-ref", "HEAD")
+        status = run("status", "--porcelain")
+        return (branch or "", bool(status))
+
+
+
+class Watcher:
+    """Notice files the developer changed, so the agent can be told.
+
+    Polls mtimes rather than using an OS watch API. The comparison is
+    deliberate: `watchdog` is a dependency, needs a thread, and behaves
+    differently on three platforms, all to improve a resolution that does
+    not matter here. The agent acts between turns, so "changed since we last
+    looked" is the only granularity that can affect anything.
+
+    Only files the session has actually touched are watched. A repository
+    has thousands of files and the agent cares about a handful; polling the
+    whole tree would burn CPU to detect edits nobody is racing.
+    """
+
+    def __init__(self, workspace: "Workspace"):
+        self._ws = workspace
+        self._mtimes: dict[str, float] = {}
+
+    def track(self, rel: str) -> None:
+        """Start watching a path the agent just touched."""
+        try:
+            self._mtimes[rel] = self._ws._resolve(rel).stat().st_mtime
+        except (OSError, ValueError):
+            self._mtimes[rel] = 0.0
+
+    def changed(self) -> list[str]:
+        """Paths modified since we last looked. Updates the baseline."""
+        out = []
+        for rel, was in list(self._mtimes.items()):
+            try:
+                now = self._ws._resolve(rel).stat().st_mtime
+            except (OSError, ValueError):
+                continue
+            if now != was:
+                self._mtimes[rel] = now
+                out.append(rel)
+        return out
+
+
+
+async def do_file(sock, workspace, watcher, msg) -> None:
+    """Run one file operation and answer. Always answers, even on failure:
+    an unanswered request stalls the turn until the server's timeout and the
+    room sees nothing."""
+    op, a = msg.get("op"), msg.get("args") or {}
+    try:
+        fn = OPS.get(op)
+        if fn is None:
+            raise ValueError(f"unsupported operation: {op}")
+        result, err = fn(workspace, a), None
+        print(dim(f"  {op} {a.get('path', '')}"))
+        # Watch what the agent touched, so a developer's edit to the same
+        # file is noticed rather than silently overwritten. A teammate's
+        # private assistant reads with `watch: false`: it is not the agent,
+        # and a watch would turn a private question into a shared
+        # `file.changed` event (`DEC-046`).
+        if a.get("path") and a.get("watch", True):
+            watcher.track(a["path"])
+    except Exception as e:  # noqa: BLE001 -- report, never crash
+        result, err = None, f"{type(e).__name__}: {e}"
+        print(dim(f"  {op} {a.get('path', '')} -> {err}"))
+    await sock.send(json.dumps({"type": "host_result",
+                                "call_id": msg.get("call_id"),
+                                "result": result, "error": err}))
+
+
+async def do_shell(sock, workspace, call_id, command) -> None:
+    """Run an approved command and answer.
+
+    A cancelled run answers nothing: the server is no longer waiting, and
+    `Host.call` has already unwound. Reporting a result here would arrive
+    against a call id nobody holds.
+    """
+    print(f"  $ {command}")
+    try:
+        result = await run_shell(workspace, command)
+        tail = (result["output"] or "").strip().splitlines()
+        for line in tail[-8:]:
+            print(dim(f"    {line[:110]}"))
+        err = None
+    except asyncio.CancelledError:
+        return
+    except Exception as e:  # noqa: BLE001
+        result, err = None, f"{type(e).__name__}: {e}"
+        print(dim(f"    {err}"))
+    await sock.send(json.dumps({"type": "host_result", "call_id": call_id,
+                                "result": result, "error": err}))
+
+
+# ---- the terminal ----------------------------------------------------------
+#
+# Reading a person's answer is where four separate session failures came
+# from, and every one traced to the same root: `input()` on a worker thread
+# cannot be cancelled. A prompt that was answered in the browser, or whose
+# question was cancelled by a barge-in, or whose connection dropped, left a
+# thread blocked on stdin forever. The next prompt then started a *second*
+# reader on the same file descriptor, two threads raced for one line, and
+# output held for the first prompt never flushed. The session looked frozen.
+#
+# The fix is structural rather than another guard: **one** reader thread for
+# the life of the process, pushing lines onto a queue. Nothing ever cancels
+# it, because nothing ever needs to. A prompt takes the next line off the
+# queue and can be abandoned freely -- the reader neither knows nor cares.
+
+_lines: asyncio.Queue[str] | None = None
+
+
+def _start_stdin_reader(loop: asyncio.AbstractEventLoop) -> asyncio.Queue:
+    """One daemon thread, one queue, for the whole process.
+
+    A daemon so it cannot keep the process alive at exit, which a blocked
+    `input()` otherwise does.
+    """
+    queue: asyncio.Queue[str] = asyncio.Queue()
+
+    def pump() -> None:
+        while True:
+            try:
+                line = sys.stdin.readline()
+            except (ValueError, OSError):
+                line = ""
+            if line == "":                      # EOF: stdin closed
+                loop.call_soon_threadsafe(queue.put_nowait, "")
+                return
+            loop.call_soon_threadsafe(queue.put_nowait, line.strip())
+
+    threading.Thread(target=pump, daemon=True, name="stdin").start()
+    return queue
+
+
+# Output is held while a question is on screen, so a reply cannot be printed
+# over a half-typed answer, and released when it is settled -- however it was
+# settled.
+_prompting = asyncio.Event()
+_prompting.set()          # set == nobody is being asked
+_held: list[str] = []
+
+
+def say(line: str) -> None:
+    """Print, unless someone is mid-answer -- then queue it."""
+    if _prompting.is_set():
+        print(line)
+    else:
+        _held.append(line)
+
+
+def _flush() -> None:
+    for line in _held:
+        print(line)
+    _held.clear()
+
+
+# The question currently on screen, so it can be retired from elsewhere.
+_open_request: dict[str, object] = {}
+
+
+def _close_prompt(note: str = "") -> None:
+    """Take the question off screen and let output flow again.
+
+    Called when the question is settled anywhere: answered here, answered in
+    the browser, cancelled by a redirect, or orphaned by a disconnect. The
+    waiting task is cancelled, which is safe now that it is waiting on a
+    queue rather than on stdin.
+    """
+    task = _open_request.pop("task", None)
+    _open_request.pop("id", None)
+    if note:
+        print(dim(f"\n  {note}"))
+    if task is not None and not task.done():
+        task.cancel()
+    _prompting.set()
+    _flush()
+
+
+def resolve_elsewhere(request_id: str, approved: bool) -> None:
+    """Someone answered in the browser. Retire the terminal's prompt."""
+    if _open_request.get("id") != request_id:
+        return
+    _close_prompt(f"answered in the browser: "
+                  f"{'allowed' if approved else 'refused'}")
+
+
+def cancel_prompt(request_id: str = "") -> None:
+    """The question no longer needs an answer: redirected, or disconnected."""
+    if request_id and _open_request.get("id") != request_id:
+        return
+    if _open_request.get("id"):
+        _close_prompt("that question no longer needs an answer")
+
+
+def abandon_prompt(why: str) -> None:
+    """The connection went away while a question was open."""
+    if _open_request.get("id"):
+        _close_prompt(f"{why} — that question is gone")
+
+
+async def ask_human(sock, msg) -> None:
+    """Put the agent's command to the person whose machine this is.
+
+    Waits on the shared stdin queue, never on stdin itself, so this task can
+    be cancelled the moment the question stops mattering. That is the whole
+    difference from the version that caused four failed sessions.
+    """
+    command = msg.get("command", "")
+    request_id = msg.get("request_id")
+    _open_request["id"] = request_id
+    _open_request["task"] = asyncio.current_task()
+    _prompting.clear()
+    print(f"\n  {bold('The agent wants to run:')}  {command}")
+    print(dim("  [y] once   [a] always this command   [n] no"), end="", flush=True)
+    print("  > ", end="", flush=True)
+    try:
+        answer = (await _lines.get()).strip().lower()
+    except asyncio.CancelledError:
+        # Settled elsewhere. `_close_prompt` has already released the gate.
+        raise
+    _open_request.pop("id", None)
+    _open_request.pop("task", None)
+    _prompting.set()
+    _flush()
+    approved = answer in ("y", "yes", "a", "always")
+    remember = answer in ("a", "always")
+    print(dim(f"  {'approved' if approved else 'refused'}"
+              f"{' (remembered)' if remember else ''}\n"))
+    await sock.send(json.dumps({
+        "type": "approve", "request_id": request_id,
+        "approved": approved, "remember": remember}))
+
+
+async def watch_loop(sock, watcher: "Watcher", workspace: "Workspace",
+                     user: str, interval: float = 1.5) -> None:
+    """Report the developer's own edits, and any change of branch.
+
+    Runs alongside the message loop. Without it the agent only discovers a
+    human edit by reading the file again, which it has no reason to do --
+    the silent-overwrite case in `R-023`.
+
+    Branch and dirty state are re-read here rather than only at attach.
+    Otherwise checking out a branch mid-session leaves the agent being told,
+    every turn, about the branch you were on when you started -- a stale
+    fact stated confidently, which is worse than no fact at all.
+    """
+    last_git = workspace.git()
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            for rel in watcher.changed():
+                print(dim(f"  you edited {rel}"))
+                await sock.send(json.dumps({
+                    "type": "file_changed", "path": rel, "actor": user}))
+            now = workspace.git()
+            if now != last_git:
+                last_git = now
+                branch, dirty = now
+                if branch:
+                    print(dim(f"  now on {branch}"
+                              f"{' (dirty)' if dirty else ''}"))
+                await sock.send(json.dumps({
+                    "type": "host_update", "branch": branch, "dirty": dirty}))
+        except Exception:  # noqa: BLE001 -- socket closing; the loop ends
+            return
+
+
+OPS = {
+    "read_file": lambda ws, a: ws.read_file(a["path"]),
+    "write_file": lambda ws, a: ws.write_file(a["path"], a.get("content", "")),
+    "list_dir": lambda ws, a: ws.list_dir(a.get("path") or "."),
+    "git_changes": lambda ws, a: ws.git_changes(),
+}
+
+
+async def run_shell(workspace: "Workspace", command: str) -> dict:
+    """Run a command in the repository, killable as a group.
+
+    `start_new_session=True` puts the child in its own process group, so a
+    cancel kills the whole tree rather than just the shell. Without it,
+    `npm test` leaves the test runner alive: the orphaned-process failure in
+    `R-023`, which happened five times on the server before anyone noticed.
+    """
+    proc = await asyncio.create_subprocess_shell(
+        command, cwd=workspace.root,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+        start_new_session=True)
+    try:
+        out, _ = await proc.communicate()
+        return {"exit_code": proc.returncode,
+                "output": out.decode(errors="replace")[:20000]}
+    except asyncio.CancelledError:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            proc.kill()
+        await proc.wait()
+        raise
+
+
+def create_session(api: str, goal: str, user: str, token: str = "") -> str:
+    return api_json(f"{api}/sessions", token,
+                    {"goal": goal, "created_by": user})["id"]
+
+
+def repo_sessions(api: str, remote: str, root: str, token: str = "",
+                  root_commit: str = "") -> list[dict]:
+    """Sessions already running against this repository (`DEC-023`).
+
+    Best-effort: a server too old to know the route, or unreachable, simply
+    means we offer nothing and start fresh.
+
+    `root_commit` has to be sent here as well as on attach: the two must
+    key the same way, or the picker searches under one identity and the
+    attach files under another.
+    """
+    q = urllib.parse.urlencode({"remote": remote, "root": root,
+                                "root_commit": root_commit})
+    try:
+        return api_json(f"{api}/repo-sessions?{q}", token)
+    except Exception:
+        return []
+
+
+def session_goal(api: str, sid: str, token: str = "") -> str:
+    """What this session is called, for a header a person has to read.
+
+    Joining with `--session` means nobody typed a goal here, and the id is
+    the one thing on screen that identifies nothing: the terminal would say
+    `Session  f5576f29` while the browser called it "add rate limiting".
+
+    Best-effort: a session is perfectly usable without a name, and failing to
+    fetch one must not stop the connection the user asked for.
+    """
+    try:
+        found = api_json(f"{api}/sessions/{sid}", token)
+    except Exception:
+        return ""
+    return str((found or {}).get("goal") or "") if isinstance(found, dict) else ""
+
+
+def delete_session(api: str, sid: str, token: str = "") -> None:
+    """Remove a session for good. Raises HTTPError if the server refuses."""
+    req = urllib.request.Request(f"{api}/sessions/{sid}", method="DELETE")
+    if token:
+        req.add_header("authorization", f"Bearer {token}")
+    urllib.request.urlopen(req, timeout=10).close()
+
+
+class PickerStopped(Exception):
+    """Ctrl-C at the session picker: not a choice, and not a new session."""
+
+
+def _prompt_line() -> str:
+    """Read one answered line, turning Ctrl-C into `PickerStopped`.
+
+    `asyncio.run()` installs its own SIGINT handling, and under it a blocking
+    `sys.stdin.readline()` inside a coroutine is *not* interrupted: no
+    `KeyboardInterrupt` is raised and the process simply stays blocked.
+    Measured -- the same read catches it fine outside asyncio, which is what
+    made this look like it already worked. The picker runs inside
+    `asyncio.run(run(args))`, so it installs a handler of its own for the
+    duration of the read and restores whatever was there afterwards.
+    """
+    def interrupted(_sig, _frame):
+        raise PickerStopped()
+    try:
+        previous = signal.signal(signal.SIGINT, interrupted)
+    except ValueError:      # not the main thread; nothing to install
+        previous = None
+    try:
+        return sys.stdin.readline().strip()
+    except (KeyboardInterrupt, EOFError):
+        raise PickerStopped() from None
+    finally:
+        if previous is not None:
+            signal.signal(signal.SIGINT, previous)
+
+
+def show_sessions(found: list[dict]) -> None:
+    """Print the numbered list the picker is answered against.
+
+    One function rather than two, because there were two: the list printed
+    after a deletion was a second, simpler renderer that lost the grouping,
+    the branch names and the completed markers -- so deleting a session
+    turned "sessions with no repository" into a bare "2 session(s) left"
+    with an unfiled session sitting under a heading that implied otherwise.
+    """
+    # The two groups answer different questions, and the heading counts only
+    # the first: "5 sessions on this repo" was a lie when four of them were
+    # unrelated sessions that merely had no repository of their own.
+    mine = sum(1 for s in found if s.get("repo_key"))
+    spare = len(found) - mine
+    print(bold(f"\n  {mine} recent session(s) on this repo:" if mine
+               else "\n  No sessions on this repo yet."))
+    for i, s in enumerate(found, 1):
+        when = s.get("created_at", "")[:16].replace("T", " ")
+        # Branching leaves the completed source and its children sharing one
+        # goal. Shown as bare goals they are the same line several times over,
+        # and joining the source attaches this machine to a session that
+        # cannot act until someone reopens it.
+        #
+        # A session with no goal has no name to show. The bare id read as one
+        # -- `b1025a6e` looks like a label rather than the absence of one --
+        # so say what it is and keep the id as the thing you type after `d`.
+        label = s.get("goal") or f"(unnamed · {s['id'][:8]})"
+        if s.get("branch_name"):
+            label += f" [{s['branch_name']}]"
+        if s.get("session_status") == "completed":
+            label += " (completed)"
+        # Sessions with no repository are a tail under their own heading, not
+        # peers of this repo's own (`DEC-023`): joining one files it under
+        # this directory for good, and an unseparated list made that
+        # permanent choice look like the reversible one above it.
+        if not s.get("repo_key") and i == mine + 1:
+            print(dim(f"\n  your {spare} most recent session(s) with no "
+                      f"repository — joining one connects it here:"))
+        print(f"    {i}. {label}  "
+              + dim(f"{s.get('created_name') or s.get('created_by','')} · {when}"))
+
+
+def choose_session(api: str, remote: str, root: str, token: str = "",
+                   root_commit: str = "") -> str:
+    """Offer to join a session already open on this repo, or start a new one.
+
+    Without this, running the CLI twice in one repository silently produces two
+    unrelated sessions against the same files -- each unaware of the other's
+    edits, since collision detection is per-session.
+
+    Non-interactive stdin (a script, a pipe) always starts fresh: prompting
+    something that cannot answer would hang.
+    """
+    if not sys.stdin.isatty():
+        return ""
+    found = repo_sessions(api, remote, root, token, root_commit)
+    if not found:
+        return ""
+    show_sessions(found)
+    while True:
+        # "d<number>" invited `d<2c056f8c>` -- the angle brackets read as
+        # "put the thing here", and an id is the thing in front of you. The
+        # example is literal instead, and anything unrecognised says so rather
+        # than quietly starting a new session.
+        print(dim("\n  Number to join (e.g. 1), d then a number to delete "
+                  "(e.g. d1), or Enter for a new session: "), end="")
+        sys.stdout.flush()
+        # Not `return ""` on an interrupt: that is the caller's word for
+        # "start a new session", so Ctrl-C at this prompt created the thing it
+        # was pressed to avoid -- and the next run then offered that session
+        # back as something to clean up.
+        answer = _prompt_line()
+        if answer.isdigit() and 1 <= int(answer) <= len(found):
+            return found[int(answer) - 1]["id"]
+        # Deleting is offered here because this list is where its absence is
+        # felt: every abandoned attempt stays in it forever, and the list is
+        # what someone reads before starting work (`DEC-023`).
+        if answer[:1].lower() == "d":
+            target = answer[1:].strip().strip("<>")
+            if not target.isdigit():
+                print(dim(f"  '{answer}' is not a number. To delete the first "
+                          f"session type d1."))
+                continue
+            index = int(target)
+            if not 1 <= index <= len(found):
+                print(dim("  no such session"))
+                continue
+            victim = found[index - 1]
+            label = victim.get("goal") or victim["id"][:8]
+            print(dim(f"  delete \"{label}\"? this cannot be undone [y/N]: "), end="")
+            sys.stdout.flush()
+            if _prompt_line().lower() not in ("y", "yes"):
+                print(dim("  kept"))
+                continue
+            try:
+                delete_session(api, victim["id"], token)
+            except urllib.error.HTTPError as exc:
+                reason = ("only its owner can delete it" if exc.code == 403
+                          else f"could not delete it: {exc}")
+                print(dim(f"  {reason}"))
+                continue
+            found.pop(index - 1)
+            print(dim(f"  deleted \"{label}\""))
+            if not found:
+                # Deleting the last one used to fall straight through to
+                # `return ""`, which means "start a new session" -- so tidying
+                # up silently created the thing you were tidying. Say the list
+                # is empty and let the next Enter be a decision.
+                print(dim("  no sessions left on this repo."))
+                print(dim("  Enter to start one, or Ctrl-C to stop: "), end="")
+                sys.stdout.flush()
+                try:
+                    _prompt_line()
+                except PickerStopped:
+                    raise
+                return ""
+            show_sessions(found)
+            continue
+        if answer:
+            # Typing something unrecognised is a mistake, not a request for a
+            # new session. Saying so costs one line; starting a session nobody
+            # asked for costs a row in this list and the confusion of not
+            # knowing why.
+            print(dim(f"  '{answer}' is not an option here."))
+            continue
+        return ""
+
+
+def dim(s: str) -> str:
+    return f"\033[2m{s}\033[0m" if sys.stdout.isatty() else s
+
+
+def bold(s: str) -> str:
+    return f"\033[1m{s}\033[0m" if sys.stdout.isatty() else s
+
+
+async def run(args: argparse.Namespace) -> int:
+    root = Path(args.dir).resolve()
+    if not root.is_dir():
+        print(f"not a directory: {root}", file=sys.stderr)
+        return 1
+    workspace = Workspace(root)
+    branch, dirty = workspace.git()
+
+    api = args.api.rstrip("/")
+    # Before anything else, so a client that cannot work with this server says
+    # so in one line rather than failing later with something less legible.
+    warning = check_protocol(api)
+    if warning.startswith("This rendez is too old"):
+        print(warning, file=sys.stderr)
+        return 1
+    if warning:
+        print(dim(warning))
+    try:
+        token = saved_token(api)
+        if not token:
+            print("Sign in first with rendez login.", file=sys.stderr)
+            return 1
+        args.user = api_json(f"{api}/auth/me", token)["name"]
+    except urllib.error.URLError as exc:
+        print(f"Authentication check failed: {exc}", file=sys.stderr)
+        return 1
+    try:
+        sid = args.session
+        # Before the stdin reader exists: `choose_session` reads the fd
+        # directly, and a second reader on one fd is what `_start_stdin_reader`
+        # was introduced to stop (`R-023`). The daemon would win the race and
+        # the prompt would hang forever.
+        if not sid and not args.new:
+            try:
+                sid = choose_session(api, workspace.remote(), str(root),
+                                     token, workspace.root_commit())
+            except PickerStopped:
+                # Ctrl-C at the picker means "none of these, and not a new one
+                # either". It used to fall through to `create_session`, so
+                # abandoning the prompt created a session -- which the next run
+                # then listed as something to clean up.
+                print(dim("\n  stopped. No session was started."))
+                return 130
+        # One stdin reader for the rest of the process, shared by every prompt.
+        global _lines
+        _lines = _start_stdin_reader(asyncio.get_running_loop())
+        sid = sid or create_session(api, args.goal or "", args.user, token)
+    except urllib.error.URLError as e:
+        print(f"cannot reach the server at {api}: {e}", file=sys.stderr)
+        return 1
+
+    ws_url = api.replace("http://", "ws://").replace("https://", "wss://")
+    url = f"{ws_url}/ws/{sid}"
+
+    # `args.goal` is only set when this invocation created the session. Joining
+    # one -- with `--session`, or from the picker -- leaves it empty, and the
+    # id identifies nothing to the person reading it.
+    label = args.goal or session_goal(api, sid, token) or sid[:8]
+    print(bold("Session  ") + label)
+    print(bold("Open    ") +
+          f"{args.web.rstrip('/')}/sessions/{sid}")
+    print(bold("Workspace") + f" {root}" +
+          (f"  ({branch}{', dirty' if dirty else ''})" if branch else ""))
+    # A workspace with no remote and no root commit is filed under its path
+    # (`DEC-023`), and renaming the directory then hides every session for
+    # it. That is a weaker promise than the one above it, and the moment to
+    # say so is before any work depends on it -- the alternative is someone
+    # renaming a folder months later and finding their sessions gone with no
+    # error anywhere. A shallow clone lands here too, deliberately.
+    if not workspace.remote() and not workspace.root_commit():
+        print(dim("Filed under this path: renaming the folder will hide its "
+                  "sessions.\n          `git init` here, or a git remote, "
+                  "makes them survive a rename."))
+    print(dim("The agent reads and writes files here. Ctrl-C to stop.\n"))
+
+    # Reconnect rather than exit. A dropped socket used to end the session's
+    # workspace for good: measured once, the host went away mid-turn and the
+    # agent carried on against a filesystem that was not the repository. The
+    # server now refuses those calls (`tools_for(had_host=...)`), but the
+    # right answer is to come back.
+    attempt = 0
+    while True:
+        try:
+            connect_url = url
+            try:
+                issued = api_json(f"{api}/auth/ws-ticket", token, {})
+            except urllib.error.HTTPError as exc:
+                # The server answered and refused: the token is expired or
+                # revoked, and no amount of retrying will change that.
+                if exc.code in (401, 403):
+                    print(f"Session expired: {exc}. Run rendez login again.",
+                          file=sys.stderr)
+                    return 1
+                raise OSError(f"ticket request failed: {exc}") from exc
+            except urllib.error.URLError as exc:
+                # The server could not be reached. That is the same
+                # condition the reconnect loop below already handles -- a
+                # restart, a dropped network -- so it must not end the
+                # session. Measured: a four-second server restart used to
+                # kill the client for good, telling the user to log in
+                # again when their token was perfectly valid.
+                raise OSError(f"cannot reach {api}: {exc.reason}") from exc
+            connect_url += "?ticket=" + urllib.parse.quote(issued["ticket"])
+            if args.share_token:
+                connect_url += "&share=" + urllib.parse.quote(args.share_token)
+            await _session(connect_url, root, branch, dirty, workspace, args)
+            return 0
+        except (websockets.ConnectionClosed, OSError) as e:
+            # An open approval prompt is waiting on an answer the server can
+            # no longer receive. Retire it, or the message loop never runs
+            # again and the reconnect below is invisible.
+            abandon_prompt("connection lost")
+            attempt += 1
+            if attempt > 6:
+                print(f"\n  lost the connection: {e}")
+                print(dim("  giving up. Re-run to re-attach this workspace."))
+                return 1
+            wait = min(2 ** attempt, 20)
+            print(dim(f"\n  connection lost; reattaching in {wait}s "
+                      f"(attempt {attempt}/6)"))
+            await asyncio.sleep(wait)
+            branch, dirty = workspace.git()
+
+
+async def _session(url, root, branch, dirty, workspace, args) -> None:
+    """One connection's lifetime. Returns when the user stops it.
+
+    Keepalive: the library and uvicorn both default to a 20s ping with a 20s
+    timeout. Too tight here -- an approval prompt waits on a person reading a
+    command, and a 22s pause to answer was followed ten seconds later by a
+    dropped socket. A wider window makes thinking time normal.
+    """
+    async with websockets.connect(url, max_size=2 ** 22,
+                                  ping_interval=30, ping_timeout=90,
+                                  close_timeout=10) as sock:
+        await sock.send(json.dumps({
+            "type": "host_attach", "root": str(root),
+            "remote": workspace.remote(),
+            "root_commit": workspace.root_commit(),
+            "branch": branch, "dirty": dirty}))
+        # Unbuffered, because this client is usually watched in a terminal
+        # beside an editor and a silent reconnect reads as a hang.
+        sys.stdout.flush()
+
+        watcher = Watcher(workspace)
+        watching = asyncio.create_task(
+            watch_loop(sock, watcher, workspace, args.user))
+        # call id -> running shell task, so `host.cancel` can reach it.
+        inflight: dict[str, asyncio.Task] = {}
+        # Our identity as the server knows it, for matching approval
+        # requests addressed to this host. Filled in from `hello`.
+        me = args.user
+
+        async for raw in sock:
+            msg = json.loads(raw)
+            kind = msg.get("type")
+
+            if kind == "host.request":
+                # Shell runs as a task so `host.cancel` can stop it; file
+                # operations are fast enough to run inline.
+                call_id = msg.get("call_id")
+                if msg.get("op") == "run_shell":
+                    inflight[call_id] = asyncio.create_task(
+                        do_shell(sock, workspace, call_id,
+                                 (msg.get("args") or {}).get("command", "")))
+                else:
+                    await do_file(sock, workspace, watcher, msg)
+
+            elif kind == "host.cancel":
+                # The turn was redirected. Kill the work rather than letting
+                # it finish unattended.
+                task = inflight.pop(msg.get("call_id"), None)
+                if task is not None and not task.done():
+                    task.cancel()
+                    print(dim("  cancelled"))
+
+            elif kind in ("tool.cancelled", "agent.interrupted"):
+                # A barge-in cancelled the turn, so any question it raised is
+                # moot. This is the path in the session that reported a host
+                # detaching: the approval was still on screen when the turn
+                # went away, and the prompt outlived its own question.
+                cancel_prompt()
+
+            elif kind == "approval.answered":
+                # Answered somewhere -- possibly in the browser. If a prompt
+                # is still on this terminal it is now dead; say so rather
+                # than leaving a question nobody is waiting on.
+                resolve_elsewhere(str(msg.get("request_id") or ""),
+                                  bool(msg.get("approved")))
+
+            elif kind == "approval.requested" and msg.get("asked_of") == me:
+                # Only asked of the host. Answering blocks the agent, so it
+                # runs as a task and the message loop keeps flowing.
+                asyncio.create_task(ask_human(sock, msg))
+
+            elif kind == "hello":
+                me = msg.get("you_id") or msg.get("you") or args.user
+                if msg.get("role") not in ("owner",):
+                    print(dim(f"  note: you joined as "
+                              f"{msg.get('role')}; only an owner may attach "
+                              f"a workspace"))
+
+            elif kind == "denied":
+                print(f"  refused: {msg.get('detail')}")
+                # A refused *attach* leaves this process connected to a
+                # session whose files it will never serve: every tool call
+                # fails and the room sees a workspace that is not there.
+                # Retrying cannot help -- the session is bound to another
+                # repository -- so stop rather than hold a dead connection.
+                if msg.get("action") == "host_attach":
+                    raise SystemExit(1)
+
+            elif kind == "message.posted":
+                say(f"[{msg.get('actor')}] {msg.get('text', '')}")
+
+            elif kind == "agent.turn.complete":
+                text = (msg.get("text") or "").strip()
+                if text:
+                    say(f"[agent] {text}\n")
+
+            elif kind == "host.attached" and msg.get("user") == args.user:
+                print(dim("  workspace attached\n"))
+
+        watching.cancel()
+
+    return 0
+
+
+def main() -> int:
+    # Line-buffered: this client is watched in a terminal beside an editor,
+    # and Python block-buffers stdout whenever it is not a tty. A piped or
+    # redirected run would otherwise show nothing until it exits.
+    try:
+        sys.stdout.reconfigure(line_buffering=True)
+    except (AttributeError, ValueError):
+        pass
+    p = argparse.ArgumentParser(
+        prog="rendez",
+        description="Share this repository with a Rendez session.")
+    p.add_argument("command", choices=["connect", "login", "logout"])
+    p.add_argument("-d", "--dir", default=".", help="repository root")
+    p.add_argument("-g", "--goal", default="", help="what the session is for")
+    p.add_argument("-s", "--session", default="", help="join an existing id")
+    p.add_argument("-n", "--new", action="store_true",
+                   help="start a new session without offering existing ones")
+    p.add_argument("-u", "--user", default=os.getenv("USER", "dev"))
+    p.add_argument("--api", default=DEFAULT_API)
+    p.add_argument("--web", default=DEFAULT_WEB)
+    p.add_argument("--share-token", default="", help="access token from a shared session link")
+    args = p.parse_args()
+    if args.command == "login":
+        return login_cli(args.api.rstrip("/"))
+    if args.command == "logout":
+        token = saved_token(args.api.rstrip("/"))
+        if token:
+            try:
+                api_json(f"{args.api.rstrip('/')}/auth/logout", token, {})
+            except urllib.error.URLError:
+                pass
+        save_token(args.api.rstrip("/"), "")
+        print("Signed out.")
+        return 0
+    try:
+        return asyncio.run(run(args))
+    except KeyboardInterrupt:
+        print("\ndisconnected")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rendez/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m rendez` — the same entry point as the `rendez` command."""
+import sys
+
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rendez_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: rendez-cli
+Version: 0.1.0
+Summary: Put your repository into a Rendez session, from your terminal
+License-Expression: MIT
+Project-URL: Homepage, https://rendez.space
+Project-URL: Documentation, https://rendez.space
+Keywords: rendez,agent,collaboration,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12
+Dynamic: license-file
+
+# rendez CLI — put your repository into a session
+
+Status: **experimental** (`DEC-021`). Files, plus shell with your
+consent per command (`DEC-022`).
+
+The web app is the control plane: the plan, the transcript, who is steering.
+This puts the *files* somewhere useful — the repository already checked out on
+your machine, instead of an empty directory on the server.
+
+```bash
+pipx install "git+https://github.com/rendez-engine/hive.git#subdirectory=cli"
+
+cd ~/code/your-repo
+rendez connect -g "add rate limiting"
+```
+
+Not on PyPI: the name `rendez` there belongs to an unrelated project, so the
+distribution would be `rendez-cli` (the installed command stays `rendez`).
+Authentication works and the server is deployed; what is still open before
+publishing is a protocol-version handshake, so an installed CLI and a
+redeployed server cannot drift apart silently (`DEPLOYMENT.md` §10).
+Installing from the repository needs read access to it.
+
+**HTTPS rather than `git+ssh`**, which assumes a GitHub SSH key that a
+developer may not have — `gh auth login` covers HTTPS and is already how most
+people here reach this repo. Found by installing on a machine that had no SSH
+key. `pipx reinstall rendez-cli` picks up later commits. From a checkout,
+`PYTHONPATH=cli python3 -m rendez connect` runs the working tree.
+
+**A plain `pipx install` copies the source, so it silently shadows your
+checkout.** Editing `cli/rendez/__init__.py` then changes nothing about what
+`rendez connect` runs, and the symptom is a feature that works in tests and is
+absent in the app -- with no error anywhere, because the installed copy is
+older but perfectly valid. If you are developing the CLI:
+
+```bash
+pipx install --force --editable ./cli    # runs your checkout, not a copy
+```
+
+To tell which one is live:
+
+```bash
+"$(pipx environment --value PIPX_LOCAL_VENVS)/rendez-cli/bin/python" \
+  -c "import rendez, inspect; print(inspect.getfile(rendez))"
+```
+
+```
+  2 recent session(s) on this repo:
+    1. add rate limiting   you · 2026-09-29 14:02
+    2. fix the cart bug    sam · 2026-09-28 11:40
+
+  your 1 most recent session(s) with no repository — joining one connects it here:
+    3. plan the migration   you · 2026-09-27 09:15
+
+  Number to join, or Enter for a new session:
+
+Session  add rate limiting
+Open     http://localhost:3000/sessions/8f3a...
+Workspace /Users/you/code/your-repo  (main, clean)
+```
+
+Sessions are filed under the repository they were attached to, keyed on the
+git remote (`DEC-023`), so a teammate's clone at a different path matches
+yours. A repository with no remote keys on its first commit instead, which
+means renaming or moving the checkout keeps its sessions. A folder that is
+not a git repository has nothing stable to key on and is filed under its
+path -- renaming it hides its sessions, and `rendez connect` says so. Your own sessions that have **no** repository follow underneath, up to
+two of them: a session started in the browser is filed under nothing, and
+joining one from a checkout connects it to that repository for good. They are
+a tail rather than peers — this repository's own sessions come first and are
+never displaced by them, because "what was already going on here?" is the
+question the list answers. To join
+a specific session directly — the app shows this command on its Files tab —
+use `rendez connect --session <id>`. The header then shows the session's
+goal rather than its id -- the id identifies the session, but it is not what
+anyone calls it. A goal is a label, not an identifier: two sessions may share
+one, and `--session` always takes the id. Without this, two people in one repo start parallel sessions that
+cannot see each other's edits. Press Enter to start fresh, or `--new` to skip
+the question. It is skipped automatically when stdin is not a terminal, so
+scripts do not hang.
+
+Authentication is mandatory. First sign up and verify your email in the browser,
+then run `rendez login --api https://YOUR-API`. The CLI prompts for your
+**username** -- not your email address (`DEC-067`) -- and your password, and
+stores a revocable token at `~/.config/rendez/auth.json` with
+mode 0600. `rendez logout` revokes it. `rendez connect` uses the same account
+name as the browser. The terminal's printed session URL identifies a session;
+use the browser Share panel to create a link or invite teammates. For a
+link-only CLI join, supply `--session` and the link's `access` value as
+`--share-token`.
+
+Your teammates open an invited session in a browser — nothing to install,
+nothing to clone. They see the transcript and the plan; the owner can grant
+collaborator access to steer the agent. When the agent reads or writes a file, it
+happens **here**, in your working tree, and your editor updates.
+
+## Options
+
+| | |
+|---|---|
+| `-d, --dir` | repository root (default: current directory) |
+| `-g, --goal` | what the session is for |
+| `-s, --session` | join an existing session instead of creating one |
+| `-n, --new` | start a new session without being offered existing ones |
+| `-u, --user` | your name in the room (default: `$USER`) |
+| `--share-token` | access value from a revocable share URL |
+| `--api` | server (default `http://localhost:8100`, or `RENDEZ_API`) |
+| `--web` | web app, for the share link (or `RENDEZ_WEB`) |
+
+Requires `websockets`. Only the session **owner** may attach a workspace —
+normally the person who created it, which `connect` does for you.
+
+## What it does, exactly
+
+Three operations, forwarded from the server and run against your tree:
+
+- `read_file` · `write_file` · `list_dir`
+
+Paths are resolved and refused if they leave the root. `.git`,
+`node_modules`, `__pycache__`, `.next` and `.venv` are hidden from listings.
+Files over 256KB are refused in both directions — a tool result re-enters the
+model's history on every later request (`DEC-020`), so a large file is paid
+for every turn, not once.
+
+## What it does not do
+
+- **Shell asks first** (`DEC-022`). `ls`, `cat`, `grep` and similar run
+  unprompted; anything else prompts you in this terminal — `y` once, `a`
+  always for that exact command this session, `n` no. Only you can answer:
+  it is your machine. A redirect kills the command's whole process group, so
+  an interrupted `npm test` does not leave its runner behind.
+- **The watcher warns, it does not prevent.** Edit a file the agent is
+  working on and the session notices within ~1.5s and tells the agent on its
+  next turn. It does not stop the write that already happened, and only files
+  the agent has touched are watched.
+- **No git.** Branch and dirty state are shown for context. Nothing commits,
+  pushes or checks out.
+- **No second host.** One machine per session. Close your laptop and the
+  session has no filesystem until you reconnect; in-flight calls fail
+  immediately rather than hanging.
+
+## Be aware
+
+Anyone who can steer the session can make the agent read and write files in
+this directory. Confinement to the root is a path check, not a sandbox: a
+`.env` **inside** the repository is inside the repository. Run this on repos
+you would screen-share, with people you would screen-share to.
+
+For isolated automation, `RENDEZ_AUTH_FILE` overrides the default CLI login
+cache path (`~/.config/rendez/auth.json`). The managed test runner uses a private
+temporary cache so tests cannot replace a developer's saved credentials.

rendez_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+rendez/__init__.py,sha256=vWgkFJIcUvj_K1o3eUuGby06ZRf94PKJ5F7jdm32VFk,49774
+rendez/__main__.py,sha256=fKj6oEuhI4Lj9fEtE3MFWvUH9XIDEjz1zjPyWciL2q4,155
+rendez_cli-0.1.0.dist-info/licenses/LICENSE,sha256=-ghzE3eh3bqZGHr2m0LQh6m1NKs_x4CYzXkYbJvvuB0,1070
+rendez_cli-0.1.0.dist-info/METADATA,sha256=NH6wrWUJbD30WUtj1-TCPZg61ZxtzS6hlDh6Kb6HxgI,8000
+rendez_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+rendez_cli-0.1.0.dist-info/entry_points.txt,sha256=hT1PccrfG_pZUFjyvq6ZktstO0gJT4v6lKslkneZ8Lk,39
+rendez_cli-0.1.0.dist-info/top_level.txt,sha256=JzJl43aXMlN5fi1yoPZbV2X17Bg4Z6fQpOhTvBwohB4,7
+rendez_cli-0.1.0.dist-info/RECORD,,

rendez_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rendez_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rendez = rendez:main

rendez_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rendez Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rendez_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rendez