@caddis/cli 0.4.34 → 0.4.35

package/bundles/antigravity-plugin/agents/code-reviewer.md

@@ -21,6 +21,10 @@ You are a principal engineer doing a focused code review. You read the change an
    - **Conventions** — per the project's `AGENTS.md` (typed boundaries, no absolute paths, no silent
      failures/logging, layering, framework idioms).
    - **Simplicity** — dead code, duplication, needless abstraction (YAGNI), clearer alternative.
+   - **Reuse** — flag new code that repeats an existing function, and a fix made at one caller
+     instead of the shared point. The rules:
+     Before writing new code, search for an existing function to reuse. Prefer the standard library or an installed package over new code or a new dependency.
+     Before changing a function, find all its callers. Fix the shared point, unless the callers need different behaviour.
 
 ## Severity
 - **blocking** — must fix before merge (bug, security hole, missing test for behavior change, broken

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.121",
+  "version": "1.3.122",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/caddis_file_lock.py

@@ -0,0 +1,121 @@
+"""Portable advisory locks and atomic UTF-8 document writes.
+
+Callers that have an artifact root should pass ``root=``. The resolved target
+must stay within that root, including when a path component is a symlink.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import errno
+import math
+import os
+from pathlib import Path
+import stat
+import tempfile
+import time
+from typing import BinaryIO, Iterator
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+def _destination(path: Path, root: Path | None) -> Path:
+    path = Path(path)
+    if ".." in path.parts:
+        raise ValueError("destination may not contain parent traversal")
+    resolved = path.resolve()
+    if root is not None and not resolved.is_relative_to(Path(root).resolve()):
+        raise ValueError("destination escapes artifact root")
+    if path.is_symlink():
+        raise ValueError("destination may not be a symlink")
+    return resolved
+
+
+def _document_mode(target: Path) -> int:
+    """Mode the replaced document should keep: the existing one, else what ``open()`` would give."""
+    try:
+        return stat.S_IMODE(target.stat().st_mode)
+    except FileNotFoundError:
+        # os.umask has no read-only form; the probe is process-wide for one line, so a file
+        # another thread creates in that window gets 0o666. caddis writers are single-threaded.
+        umask = os.umask(0)
+        os.umask(umask)
+        return 0o666 & ~umask
+
+
+def _try_lock(handle: BinaryIO) -> bool:
+    try:
+        if os.name == "nt":
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+        else:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return True
+    except OSError as exc:
+        if exc.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+            raise
+        return False
+
+
+def _unlock(handle: BinaryIO) -> None:
+    if os.name == "nt":
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+    else:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+@contextlib.contextmanager
+def locked_path(
+    path: Path, timeout_s: float = 5.0, *, root: Path | None = None
+) -> Iterator[Path]:
+    """Hold a stable adjacent lock for ``path``; never remove its inode."""
+    if not math.isfinite(timeout_s) or timeout_s < 0:
+        raise ValueError("timeout_s must be a finite nonnegative number")
+    target = _destination(path, root)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = target.with_name(target.name + ".lock")
+    if lock_path.is_symlink():
+        raise ValueError("lock file may not be a symlink")
+    # O_NOFOLLOW closes the gap between the check above and the open on POSIX.
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    deadline = time.monotonic() + timeout_s
+    with os.fdopen(os.open(lock_path, flags, 0o666), "r+b") as handle:
+        while not _try_lock(handle):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"timed out waiting for lock: {lock_path}")
+            time.sleep(min(0.05, remaining))
+        try:
+            yield target
+        finally:
+            _unlock(handle)
+
+
+def atomic_write(path: Path, text: str, *, root: Path | None = None) -> None:
+    """Atomically replace one document; hold ``locked_path`` for read/modify/write.
+
+    A failed write or replace removes only this call's temporary file.
+    """
+    target = _destination(path, root)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", newline="", dir=target.parent,
+            prefix=f".{target.name}.", suffix=".tmp", delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        # NamedTemporaryFile creates 0o600; without this every write would narrow the document.
+        os.chmod(temporary, _document_mode(target))
+        os.replace(temporary, target)
+        temporary = None  # replaced: that name may now belong to another writer
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)

package/bundles/antigravity-plugin/scripts/caddis_frontmatter.py

@@ -108,6 +108,18 @@ def parse(text: str) -> dict:
     return out
 
 
+def split_document(text: str) -> tuple[dict, str]:
+    """Return parsed metadata and the untouched body after a complete leading header."""
+    source = text.lstrip("\ufeff")
+    lines = source.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+    for index, line in enumerate(lines[1:], 1):
+        if line.strip() == "---":
+            return parse(source), "".join(lines[index + 1:])
+    return {}, text
+
+
 def validate(text: str, allowed_types: set[str]) -> str | None:
     """Report the first missing or unsupported required header field."""
     if _header_lines(text) is None:

package/bundles/antigravity-plugin/scripts/caddis_gate.py

@@ -21,6 +21,9 @@ that hard-fails when it cannot read its inputs breaks every consumer the day it
 first thing anyone does with a gate that cries wolf is switch it off. Only a genuine, positively
 identified violation is non-zero.
 
+One exception: `deploy-boundary` guards the production boundary and FAILS CLOSED. When it
+cannot tell, it exits 3 ("could not run" on the caddis scale), never 0.
+
 EXIT CODES
   0  proceed
   1  blocked           — a real violation; the caller must stop
@@ -440,7 +443,7 @@ def gate_vendor_drift(repo_root: Path) -> int:
 _DOC_PATH = re.compile(r"`([^`\s<>{}*?]+?\.(?:md|py|ts|tsx|json|ya?ml|sh|ps1|html|toml|sql))`")
 
 
-def gate_handover_check(doc: Path, repo_root: Path) -> int:
+def gate_handover_check(doc: Path, repo_root: Path, max_chars: int | None = None) -> int:
     """Every file a handover names must exist. Nothing else in a handover is machine-checkable.
 
     A succession prompt is written from memory, so it names files the writer BELIEVES are there.
@@ -454,8 +457,10 @@ def gate_handover_check(doc: Path, repo_root: Path) -> int:
     later withdrawal" — need conventions that do not exist yet, and a gate that pretends to check
     them would be worse than one that says it does not.
 
-    Degrades open on a missing/unreadable doc. Blocks only on a path the doc claims and the repo
-    does not have.
+    Degrades open on a missing/unreadable doc. Blocks on a path the doc claims and the repo does
+    not have, and -- only when the caller passes ``max_chars`` -- on a doc longer than that. The
+    cap is opt-in: /handoff caps a workstream relay at 4,000 characters, but a /spawn-hub prompt
+    must embed the full inventory verbatim and would never fit.
     """
     if not doc.is_file():
         return _degrade(f"no handover doc at {doc}")
@@ -464,6 +469,12 @@ def gate_handover_check(doc: Path, repo_root: Path) -> int:
     except OSError as exc:
         return _degrade(f"cannot read {doc}: {type(exc).__name__}")
 
+    if max_chars is not None and len(text) > max_chars:
+        sys.stderr.write(
+            f"[caddis-gate] handover doc {doc.name} exceeds {max_chars:,} characters ({len(text)} chars)\n"
+        )
+        return EXIT_BLOCKED
+
     missing: list[str] = []
     for raw in sorted(set(_DOC_PATH.findall(text))):
         # A backtick often wraps a whole command; the path is the token that looks like one.
@@ -617,6 +628,166 @@ def gate_docs_check(root: Path) -> int:
     return EXIT_BLOCKED if failures else EXIT_OK
 
 
+# ── gate: deploy-boundary ───────────────────────────────────────────────────
+# The owner's production boundary: an agent never merges into a repo whose default branch deploys
+# on every push. /ship, /ship-merge and /pr-merge run this before any merge or push to the default
+# branch, and hand the merge to the owner on anything but exit 0.
+#
+# FAILS CLOSED — the one deliberate exception to DEGRADE OPEN above. "Cannot tell" is exit 3,
+# never 0, because a false "clean" here is a production deploy nobody approved. Any positive
+# signal wins over every negative one: config cannot switch the check off.
+EXIT_CANNOT_TELL = 3
+
+_WORKFLOW_DIRS = (".github/workflows", ".gitea/workflows", ".forgejo/workflows")
+
+# An inherited GIT_DIR (from a hook or wrapper) would make `git -C <repo>` read another repository.
+_GIT_REPO_ENV = ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY",
+                 "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE")
+
+
+def _git_out(repo: Path, *args: str) -> str | None:
+    """stdout of a git command in `repo`, or None when it fails."""
+    env = {k: v for k, v in os.environ.items() if k not in _GIT_REPO_ENV}
+    try:
+        r = subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True,
+                           encoding="utf-8", errors="replace", timeout=30, env=env)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return r.stdout if r.returncode == 0 else None
+
+
+def _ref_exists(repo: Path, ref: str) -> bool:
+    return _git_out(repo, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}") is not None
+
+
+def _default_branch_refs(repo: Path) -> list[str]:
+    """Every copy of the default branch: each remote's and the local branch of that name.
+
+    The name comes from any remote's recorded HEAD; with none recorded, `main` and `master` stand
+    in. Reading every copy is deliberate: a positive signal on any of them blocks.
+    """
+    remotes = (_git_out(repo, "remote") or "").split()
+    names: set[str] = set()
+    for remote in remotes:
+        target = (_git_out(repo, "symbolic-ref", "--quiet", f"refs/remotes/{remote}/HEAD") or "").strip()
+        if target.startswith(f"refs/remotes/{remote}/"):
+            names.add(target[len(f"refs/remotes/{remote}/"):])
+    names = names or {"main", "master"}
+    refs = [f"refs/remotes/{r}/{n}" for r in remotes for n in sorted(names)]
+    refs += [f"refs/heads/{n}" for n in sorted(names)]
+    return [r for r in refs if _ref_exists(repo, r)]
+
+
+def _config_production_on_main(text: str) -> bool | None:
+    """True/False from `[deploy] production_on_main`; None when absent. Raises on a bad file."""
+    import tomllib
+    deploy = tomllib.loads(text).get("deploy", {})
+    if not isinstance(deploy, dict):
+        raise ValueError("[deploy] is not a table")
+    value = deploy.get("production_on_main")
+    if value is not None and not isinstance(value, bool):
+        raise ValueError(f"production_on_main is {value!r}, not true or false")
+    return value
+
+
+# A deploy is often not named "deploy". Letters-only boundaries on prod, so `deploy_prod` matches
+# and `product` or `reproduce` do not.
+_DEPLOY_WORD = re.compile(r"deploy|release|publish|(?<![a-z])prod(?:uction)?(?![a-z])", re.I)
+
+
+def _workflow_deploys(text: str) -> bool:
+    """True when the workflow's name, a job id or a job name looks like a deploy, or a job sets a
+    GitHub `environment:` (the forge's own marker for a deployment). Raises on a bad file.
+
+    The caller also checks the file name: a forge shows the file path as the workflow's name when
+    `name:` is unset.
+    """
+    import yaml
+    doc = yaml.safe_load(text)
+    if not isinstance(doc, dict) or not isinstance(doc.get("jobs"), dict):
+        raise ValueError("not a workflow (no jobs mapping)")
+    labels = [doc.get("name")]
+    for job_id, job in doc["jobs"].items():
+        labels.append(job_id)
+        if isinstance(job, dict):
+            if job.get("environment"):
+                return True
+            labels.append(job.get("name"))
+    return any(_DEPLOY_WORD.search(str(label)) for label in labels if label is not None)
+
+
+def gate_deploy_boundary(repo: Path) -> int:
+    """EXIT_BLOCKED when a push to the default branch deploys to production, EXIT_OK when it
+    positively does not, EXIT_CANNOT_TELL otherwise."""
+    blocked: list[str] = []
+    unknown: list[str] = []
+
+    top = _git_out(repo, "rev-parse", "--show-toplevel") if repo.is_dir() else None
+    root = Path(top.strip()) if top else repo
+    refs = _default_branch_refs(root) if top else []
+    if not repo.is_dir():
+        unknown.append(f"{repo} is not a directory")
+    elif not top:
+        unknown.append(f"{repo} is not a git repository")
+    elif not refs:
+        unknown.append("cannot find the default branch (no remote HEAD, no main or master)")
+    # HEAD is what is about to be merged or pushed: a deploy it adds lands on the default branch.
+    # It only ever adds signals; the default branch is still read, so deleting there hides nothing.
+    sources = refs + (["HEAD"] if top and _ref_exists(root, "HEAD") else [])
+
+    # Config: the working tree and every source. Only `true` counts; config cannot switch it off.
+    configs: list[tuple[str, str | None]] = []
+    cfg = root / ".caddis" / "config.toml"
+    if cfg.is_file():
+        configs.append(("working tree", None))
+    for ref in sources:
+        text = _git_out(root, "show", f"{ref}:.caddis/config.toml")
+        if text is not None:
+            configs.append((ref, text))
+    for where, text in configs:
+        try:
+            if _config_production_on_main(cfg.read_text(encoding="utf-8") if text is None else text):
+                blocked.append(f".caddis/config.toml ({where}) sets production_on_main = true")
+        except Exception as exc:
+            unknown.append(f".caddis/config.toml ({where}) unreadable: {exc}")
+
+    # Workflows: read from committed trees, never the working tree.
+    for ref in sources:
+        listing = _git_out(root, "ls-tree", "-r", "-z", "--name-only", ref, "--", *_WORKFLOW_DIRS)
+        if listing is None:
+            unknown.append(f"cannot list workflows on {ref}")
+            continue
+        for path in listing.split("\0"):
+            # Forges run only the files directly inside the workflows directory.
+            if path.rsplit("/", 1)[0] not in _WORKFLOW_DIRS:
+                continue
+            if not path.lower().endswith((".yml", ".yaml")):
+                continue
+            text = _git_out(root, "show", f"{ref}:{path}")
+            try:
+                if text is None:
+                    raise OSError("git show failed")
+                if _DEPLOY_WORD.search(path.rsplit("/", 1)[1]) or _workflow_deploys(text):
+                    blocked.append(f"{path} on {ref} deploys")
+            except Exception as exc:
+                unknown.append(f"{path} on {ref} unreadable: {type(exc).__name__}: {exc}")
+
+    if blocked:
+        print("[gate] deploy-boundary: BLOCKED — a push to the default branch deploys to production")
+        for reason in dict.fromkeys(blocked):
+            print(f"    {reason}")
+        print("    Do not merge. Hand the merge to the owner with the PR link.")
+        return EXIT_BLOCKED
+    if unknown:
+        print("[gate] deploy-boundary: CANNOT TELL — treat as production")
+        for reason in dict.fromkeys(unknown):
+            print(f"    {reason}")
+        print("    Do not merge. Hand the merge to the owner with the PR link.")
+        return EXIT_CANNOT_TELL
+    print(f"[gate] deploy-boundary: clean — no deploy signal found on {', '.join(sources)}")
+    return EXIT_OK
+
+
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description="caddis machine gates")
     sub = ap.add_subparsers(dest="cmd", required=True)
@@ -640,11 +811,21 @@ def main(argv: list[str] | None = None) -> int:
     hc = sub.add_parser("handover-check")
     hc.add_argument("--doc", required=True)
     hc.add_argument("--repo-root", default=".")
+    hc.add_argument("--max-chars", type=int, default=None,
+                    help="block a doc longer than this (relays: 4000); default: no cap")
     dc = sub.add_parser("docs-check")
     dc.add_argument("--root", default=".")
+    db = sub.add_parser("deploy-boundary")
+    db.add_argument("--repo", default=".")
     a = ap.parse_args(argv)
 
     plan = Path(getattr(a, "plan", "") or ".")
+    if a.cmd == "deploy-boundary":
+        try:
+            return gate_deploy_boundary(Path(a.repo).resolve())
+        except Exception as exc:
+            sys.stderr.write(f"[caddis-gate] deploy-boundary cannot evaluate: {type(exc).__name__}: {exc}\n")
+            return EXIT_CANNOT_TELL  # never degrade open across the production boundary
     if a.cmd == "docs-check":
         try:
             return gate_docs_check(Path(a.root).resolve())
@@ -665,7 +846,7 @@ def main(argv: list[str] | None = None) -> int:
         if a.cmd == "vendor-drift":
             return gate_vendor_drift(Path(a.repo_root).resolve())
         if a.cmd == "handover-check":
-            return gate_handover_check(Path(a.doc), Path(a.repo_root).resolve())
+            return gate_handover_check(Path(a.doc), Path(a.repo_root).resolve(), a.max_chars)
         return gate_tracker(plan)
     except Exception as exc:  # pragma: no cover — a gate must never crash the caller
         return _degrade(f"{type(exc).__name__}: {exc}")

package/bundles/antigravity-plugin/scripts/caddis_inventory.py

@@ -47,6 +47,14 @@ import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
+try:
+    import caddis_frontmatter
+except ModuleNotFoundError as exc:
+    if exc.name != "caddis_frontmatter":
+        raise
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
+    import caddis_frontmatter
+
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
@@ -71,15 +79,7 @@ def frontmatter(path: Path) -> dict[str, str]:
         text = path.read_text(encoding="utf-8", errors="ignore").lstrip("")
     except OSError:
         return {}
-    if not text.startswith("---"):
-        return {}
-    end = text.find("\n---", 3)
-    out: dict[str, str] = {}
-    for line in text[3:end if end > 0 else 800].splitlines():
-        if ":" in line and not line.startswith((" ", "\t")):
-            k, _, v = line.partition(":")
-            out[k.strip()] = v.strip()
-    return out
+    return caddis_frontmatter.parse(text)
 
 
 def title_of(path: Path) -> str:

package/bundles/antigravity-plugin/scripts/caddis_relay_git.py

@@ -0,0 +1,159 @@
+"""Transfer one workstream relay through an isolated, leased Git ref."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    from caddis_workstreams import _name, _validate_relay, read_relay, write_relay
+    import secret_filter
+except ModuleNotFoundError as exc:
+    if exc.name not in {"caddis_workstreams", "secret_filter"}:
+        raise
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / ".github" / "tools"))
+    from caddis_workstreams import _name, _validate_relay, read_relay, write_relay
+    import secret_filter
+
+
+MAX_NOTE_CHARS = 4000
+
+
+def _git(repo: Path, *args: str, input_data: bytes | None = None,
+         env: dict[str, str] | None = None) -> bytes:
+    result = subprocess.run(["git", *args], cwd=repo, env=env, input=input_data,
+                            stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+    if result.returncode:
+        # Name the subcommand, not a leading "-c key=value" option.
+        command = next((arg for i, arg in enumerate(args) if not arg.startswith("-") and (i == 0 or args[i - 1] != "-c")), "?")
+        raise RuntimeError(f"git {command} failed: {result.stderr.decode('utf-8', 'replace').strip()}")
+    return result.stdout
+
+
+def _ref(workstream: str) -> str:
+    return "refs/caddis/relay/" + _name(workstream)
+
+
+def _check_note(workstream: str, note: str) -> None:
+    if len(note) > MAX_NOTE_CHARS:
+        raise ValueError("relay exceeds 4,000 characters")
+    _validate_relay(workstream, note)
+
+
+def _pre_send(note: str) -> None:
+    # A synthetic new-file diff makes the existing filter scan every line, not
+    # only lines changed since a prior relay. No user-configured allowlist is
+    # accepted for this outbound note.
+    lines = note.splitlines()
+    diff = ("diff --git a/relay.md b/relay.md\nnew file mode 100644\n"
+            "--- /dev/null\n+++ b/relay.md\n"
+            f"@@ -0,0 +1,{len(lines)} @@\n" +
+            "".join("+" + line + "\n" for line in lines))
+    result = secret_filter.filter_diff(diff, list(secret_filter.DEFAULT_DENY_GLOBS), [])
+    if result.hits or result.dropped_paths or not result.kept_diff:
+        raise ValueError("relay refused by pre-send filter")
+
+
+def push_relay(repo: Path, workstream: str, *, confirmed: bool, interactive: bool) -> int:
+    """Return 0 on a leased push, 1 on refusal or conflict.
+
+    A Git or network failure before the push (for example an unreachable remote in
+    ``ls-remote``) raises RuntimeError, so the caller reports it instead of a refusal.
+
+    The caller must obtain this invocation's interactive decision. This API
+    never reads an ambient confirmation variable or prompts by itself.
+    """
+    if not confirmed or not interactive:
+        return 1
+    repo = Path(repo)
+    ref = _ref(workstream)
+    note, digest = read_relay(repo, workstream)
+    if digest is None:
+        return 1
+    _check_note(workstream, note)
+    _pre_send(note)
+    with tempfile.TemporaryDirectory(prefix="caddis-relay-index-") as temp:
+        index = Path(temp) / "index"
+        env = os.environ.copy()
+        env["GIT_INDEX_FILE"] = str(index)
+        _git(repo, "read-tree", "--empty", env=env)
+        blob = _git(repo, "hash-object", "-w", "--stdin", input_data=note.encode("utf-8"), env=env).decode().strip()
+        _git(repo, "update-index", "--add", "--cacheinfo", "100644", blob, "relay.md", env=env)
+        tree = _git(repo, "write-tree", env=env).decode().strip()
+        commit = _git(repo, "-c", "user.name=Caddis Relay", "-c", "user.email=relay@localhost",
+                      "commit-tree", tree, input_data=b"Relay note\n", env=env).decode().strip()
+        old = _git(repo, "ls-remote", "origin", ref, env=env).decode().strip()
+        expected = old.split("\t", 1)[0] if old else ""
+        try:
+            _git(repo, "push", f"--force-with-lease={ref}:{expected}", "origin",
+                 f"{commit}:{ref}", env=env)
+        except RuntimeError:
+            return 1
+    return 0
+
+
+def fetch_relay(repo: Path, workstream: str, *, replace: bool = False) -> str:
+    """Fetch one explicit ref, validate its one-file tree, then store by local CAS.
+
+    A local relay that differs from the fetched one is never replaced unless the caller
+    passes ``replace=True``: it may hold newer, never-pushed work.
+    """
+    repo = Path(repo)
+    ref = _ref(workstream)
+    local, expected_hash = read_relay(repo, workstream)
+    _git(repo, "fetch", "--no-tags", "origin", ref)
+    fetched = _git(repo, "rev-parse", "FETCH_HEAD").decode().strip()
+    entries = _git(repo, "ls-tree", "-z", fetched).split(b"\0")
+    if len(entries) != 2 or not entries[0].startswith(b"100644 blob ") or not entries[0].endswith(b"\trelay.md"):
+        raise ValueError("remote relay tree must contain only an ordinary relay.md")
+    size = int(_git(repo, "cat-file", "-s", f"{fetched}:relay.md").decode().strip())
+    if size > MAX_NOTE_CHARS * 4:  # UTF-8 upper bound; read nothing larger into memory
+        raise ValueError("remote relay exceeds 4,000 characters")
+    note = _git(repo, "show", f"{fetched}:relay.md").decode("utf-8")
+    _check_note(workstream, note)
+    if expected_hash is not None and local != note and not replace:
+        raise ValueError("local relay differs from the fetched one; pass replace=True to overwrite it")
+    result = write_relay(repo, workstream, note, expected_hash)
+    if result.status != "written":
+        raise RuntimeError("local relay changed during fetch")
+    return note
+
+
+def _headless() -> bool:
+    """No human is watching: the caddis launchers and the docket runner set these."""
+    return any(os.environ.get(name) for name in ("CADDIS_HEADLESS", "DOCKET_PLAN", "DOCKET_BRANCH"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    parser = argparse.ArgumentParser(description="Move one workstream relay between machines")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--repo", type=Path, default=Path("."))
+    sub = parser.add_subparsers(dest="command", required=True)
+    push_p = sub.add_parser("push", parents=[common], help="publish .caddis/relay/<name>.md to refs/caddis/relay/<name>")
+    push_p.add_argument("name")
+    push_p.add_argument("--user-said-yes", action="store_true",
+                        help="pass only after the user answered y to the push question in this session")
+    fetch_p = sub.add_parser("fetch", parents=[common], help="fetch refs/caddis/relay/<name> into .caddis/relay/<name>.md")
+    fetch_p.add_argument("name")
+    fetch_p.add_argument("--replace", action="store_true",
+                         help="overwrite a different local relay (it may hold never-pushed work)")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "push":
+            code = push_relay(args.repo, args.name, confirmed=args.user_said_yes, interactive=not _headless())
+            print("relay pushed" if code == 0 else "relay not pushed (no consent, headless, missing relay, or remote conflict)")
+            return code
+        print(fetch_relay(args.repo, args.name, replace=args.replace), end="")
+        return 0
+    except (RuntimeError, ValueError, OSError) as exc:
+        print(f"caddis-relay: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())