@ssheleg/agent-sync 1.2.2

package/plugins/agent-sync/skills/agent-sync/scripts/agent_sync.py

@@ -0,0 +1,2454 @@
+#!/usr/bin/env python3
+"""agent-sync — coordination for concurrent agents over a pluggable knowledge cloud.
+
+Stdlib only. Python 3.9+.
+
+Two planes: git is the record plane, the cloud is the coordination plane.
+Leases and id reservations are decided by replaying one append-only log, because
+no supported backend offers compare-and-swap. Document order is authoritative;
+timestamps only expire leases.
+
+Credentials are read from the environment and never appear in argv, a log line,
+a journal entry or a rendered board. HTTP goes through urllib inside this
+process — there is no subprocess and nothing for another process to read.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import re
+import stat
+import subprocess
+import hashlib
+import shutil
+import sys
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+VERSION = "1.2.2"
+
+CONFIG_PATH = Path(".claude/agent-sync.json")
+ENV_FILE = Path(".env.agent-sync")
+STATE_DIR = Path(".agent-sync")
+GENERATED_MARKER = "<!-- agent-sync:generated"
+
+LOGS = {
+    "claims": "30 Claims",
+    "reservations": "40 Reservations",
+    "signals": "50 Signals",
+    "blockers": "60 Blockers",
+    # The as-built record: what agents actually implemented, as they implemented it.
+    # Git documentation says how it SHOULD be — written before the code and often
+    # without it. This says how it IS, derived from what was really written. They are
+    # two source-of-truths answering two different questions, and the gap between them
+    # is the finding, not a defect in either.
+    "asbuilt": "70 As-built",
+}
+
+# Write with "- ", read any bullet. A knowledge base normalises markdown on the way
+# in — Outline rewrites "- " to "* " — so a parser anchored to the character we wrote
+# rejects every line the server gave back, and the caller sees "lost" instead of
+# "unreadable". Be strict in what you emit, liberal in what you accept.
+LINE_RE = re.compile(r"^[-*+] `(?P<ts>[^`]+)`(?P<pairs>(?: `[a-z_]+=[^`]*`)+)$")
+CANDIDATE_RE = re.compile(r"^[-*+] `")
+PAIR_RE = re.compile(r"`([a-z_]+)=([^`]*)`")
+MAX_UNPARSEABLE = 0.02
+
+DEFAULT_SETTLE = 3.0
+DEFAULT_TTL = 2700
+DEFAULT_RENEW = 300
+
+
+# --------------------------------------------------------------------------- utils
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_iso(ts: str) -> float:
+    try:
+        return datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(
+            tzinfo=timezone.utc).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def git(*args: str, cwd: Path | None = None) -> str:
+    try:
+        out = subprocess.run(
+            ["git", *args], cwd=str(cwd) if cwd else None,
+            capture_output=True, text=True, timeout=15)
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def project_root() -> Path:
+    top = git("rev-parse", "--show-toplevel")
+    return Path(top) if top else Path.cwd()
+
+
+def head_sha() -> str:
+    return git("rev-parse", "--short", "HEAD") or "unknown"
+
+
+def repo_name() -> str:
+    url = git("config", "--get", "remote.origin.url")
+    if url:
+        return url.rstrip("/").rsplit("/", 1)[-1].removesuffix(".git")
+    return project_root().name
+
+
+class Fail(Exception):
+    """A failure the caller must see. Never swallowed into a success."""
+
+
+# --------------------------------------------------------------------------- config
+
+def find_env_file(root: Path) -> Path | None:
+    """Locate .env.agent-sync for this checkout, including from inside a submodule.
+
+    Submodules are separate git repositories, so `project_root()` in one of them is the
+    submodule — and the credentials sit in the SUPERPROJECT. Looking only in the local
+    root put every submodule agent into degraded `fs` mode, isolated in local files and
+    unable to see anyone: three agents entered from one umbrella, coordinating with
+    nobody, and each one saying `ungated` while believing it was configured.
+
+    One credential file therefore serves the whole tree: local root first, then the
+    superproject git reports, then plain parent directories.
+    """
+    local = root / ENV_FILE
+    if local.exists():
+        return local
+
+    superproject = git("rev-parse", "--show-superproject-working-tree", cwd=root)
+    if superproject:
+        candidate = Path(superproject) / ENV_FILE
+        if candidate.exists():
+            return candidate
+
+    for parent in root.resolve().parents:
+        candidate = parent / ENV_FILE
+        if candidate.exists():
+            return candidate
+        if (parent / ".git").exists() and (parent / CONFIG_PATH).exists():
+            break   # a configured project that simply has no env file — stop here
+    return None
+
+
+def load_env_file(root: Path) -> None:
+    """Read .env.agent-sync into the environment when it is not already there.
+
+    Load-bearing, and it was missing. A Claude Code hook is spawned with a bare
+    environment: it never sees the `set -a && . ./.env.agent-sync` the operator ran in
+    their own shell. So every hook silently fell back to the `fs` backend while the
+    agent's own commands used the cloud — the guard denied edits whose lease WAS held,
+    and recorded the run `ungated` while the agent had been told `gated`. Two views of
+    one project, and the enforcement half held the wrong one.
+
+    The file's location is deterministic, so the tool loads it rather than depending on
+    how it was invoked. An already-set variable always wins: explicit beats implicit,
+    and an operator overriding a value for one command must not be undone here.
+    """
+    path = find_env_file(root)
+    if path is None:
+        return
+    try:
+        text = path.read_text()
+    except OSError:
+        return
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip().strip('"').strip("'")
+        if key and value and key not in os.environ:
+            os.environ[key] = value
+
+
+def load_config(root: Path) -> dict[str, Any]:
+    path = root / CONFIG_PATH
+    if not path.exists():
+        raise Fail(
+            "no .claude/agent-sync.json in this project.\n"
+            "Run `init` first — it asks which backend to use and writes the config.\n"
+            "  agent_sync.py init --backend outline --url <instance-url>\n"
+            "  agent_sync.py init --backend fs")
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise Fail(f".claude/agent-sync.json is not valid JSON: {exc}") from exc
+
+
+def run_id(root: Path) -> str:
+    """One identity per session, whichever way the tool is invoked.
+
+    This is load-bearing. A hook runs with CLAUDE_SESSION_ID in its environment and a
+    plain shell command usually does not, so deriving the id from that variable gave
+    one session two identities: the agent acquired a lease as one and was then denied
+    by its own guard as the other. The gate blocked the lease holder.
+
+    The marker file is therefore authoritative for the checkout, with the session name
+    recorded beside it. A genuinely different session rotates it; a run that merely
+    *learns* its session name adopts it instead of rotating — otherwise the first shell
+    command in a fresh checkout would fork the identity all over again.
+    """
+    override = os.environ.get("AGENT_SYNC_RUN_ID")
+    if override:
+        return "r-" + re.sub(r"[^a-z0-9]", "", override.lower())[:12]
+
+    session = os.environ.get("CLAUDE_SESSION_ID") or ""
+    marker = root / STATE_DIR / "run-id"
+
+    stored: dict[str, str] = {}
+    if marker.exists():
+        raw = marker.read_text().strip()
+        try:
+            stored = json.loads(raw)
+        except json.JSONDecodeError:
+            stored = {"run": raw, "session": ""}   # legacy plain-text marker
+
+    if stored.get("run"):
+        known = stored.get("session", "")
+        if not session or known == session:
+            return stored["run"]
+        if not known:
+            marker.write_text(json.dumps({"run": stored["run"], "session": session}))
+            return stored["run"]
+
+    rid = ("r-" + re.sub(r"[^a-z0-9]", "", session.lower())[:12]) if session else \
+          "r-%06x%s" % (random.getrandbits(24), format(int(time.time()) & 0xFFF, "03x"))
+    marker.parent.mkdir(parents=True, exist_ok=True)
+    marker.write_text(json.dumps({"run": rid, "session": session}))
+    return rid
+
+
+# --------------------------------------------------------------------------- adapters
+
+class Adapter:
+    name = "none"
+    capabilities = {"atomicAppend": False, "totalOrderRead": False, "search": False,
+                    "exclusiveLease": False}
+
+    def configured(self) -> bool:
+        raise NotImplementedError
+
+    def tree_ensure(self, path: str) -> str:
+        raise NotImplementedError
+
+    def log_append(self, oid: str, line: str) -> None:
+        raise NotImplementedError
+
+    def log_read(self, oid: str) -> str:
+        raise NotImplementedError
+
+    def doc_put(self, oid: str, text: str) -> None:
+        raise NotImplementedError
+
+    def doc_get(self, oid: str) -> str:
+        raise NotImplementedError
+
+    def search(self, query: str, limit: int = 10) -> list[dict[str, Any]]:
+        return []
+
+    def log_shards(self, prefix: str) -> list[str]:
+        """Every object whose title starts with `prefix` — one per writer."""
+        raise NotImplementedError
+
+    @property
+    def is_lease_authority(self) -> bool:
+        return bool(self.capabilities["atomicAppend"]
+                    and self.capabilities["totalOrderRead"])
+
+    @property
+    def is_exclusive(self) -> bool:
+        """Whether a won lease is a guarantee or advice. Never assume the first."""
+        return bool(self.capabilities.get("exclusiveLease"))
+
+
+class OutlineAdapter(Adapter):
+    """Outline knowledge base. Hosted or self-hosted; the URL is configuration.
+
+    No compare-and-swap exists in this API: documents.update has editMode
+    append/replace/prepend/patch and no lastRevision. Coordination state is
+    therefore never a document we rewrite.
+    """
+
+    name = "outline"
+    # exclusiveLease is FALSE and that is not a formality. Outline has no
+    # compare-and-swap, so a decision cannot be made after all contenders have
+    # written — only after a settle window that is long enough in practice. Two runs
+    # starting inside that window can both win. Measured, not assumed.
+    capabilities = {"atomicAppend": True, "totalOrderRead": True, "search": True,
+                    "exclusiveLease": False}
+
+    def __init__(self) -> None:
+        self.url = (os.environ.get("AGENT_SYNC_OUTLINE_URL") or "").rstrip("/")
+        self.token = os.environ.get("AGENT_SYNC_OUTLINE_TOKEN") or ""
+        self.collection = os.environ.get("AGENT_SYNC_OUTLINE_COLLECTION") or ""
+        self._collection_uuid = ""
+        self._ids: dict[str, str] = {}
+
+    def configured(self) -> bool:
+        return bool(self.url and self.token)
+
+    def _call(self, endpoint: str, body: dict[str, Any]) -> dict[str, Any]:
+        if not self.configured():
+            raise Fail("Outline is not configured (URL or token missing from the environment)")
+        payload = json.dumps(body).encode()
+        req = urllib.request.Request(
+            f"{self.url}/api/{endpoint}", data=payload, method="POST")
+        req.add_header("Authorization", f"Bearer {self.token}")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Accept", "application/json")
+
+        delay = 1.0
+        for attempt in range(7):
+            try:
+                with urllib.request.urlopen(req, timeout=20) as resp:
+                    data = json.loads(resp.read().decode())
+                if not data.get("ok", False):
+                    raise Fail(f"outline {endpoint}: {data.get('message') or data.get('error')}")
+                return data.get("data") or {}
+            except urllib.error.HTTPError as exc:
+                # The useful part of an Outline failure is in the body. Dropping it
+                # turns "collectionId: Invalid UUID" into a bare 400 and costs a
+                # debugging round — never swallow the reason.
+                detail = ""
+                try:
+                    payload_err = json.loads(exc.read().decode())
+                    detail = payload_err.get("message") or payload_err.get("error") or ""
+                except (ValueError, OSError):
+                    pass
+                if exc.code in (401, 403):
+                    raise Fail(
+                        f"outline {endpoint}: {exc.code} — the token is rejected"
+                        f"{': ' + detail if detail else ''}. "
+                        "A credential does not become valid on retry.") from exc
+                # 429 and transient 5xx deserve a retry; 401/403 never will.
+                if exc.code in (429, 500, 502, 503, 504) and attempt < 6:
+                    time.sleep(float(exc.headers.get("Retry-After") or delay)
+                               + random.random() * 0.4)
+                    delay *= 2
+                    continue
+                raise Fail(f"outline {endpoint}: HTTP {exc.code}"
+                           f"{' — ' + detail if detail else ''}") from exc
+            except urllib.error.URLError as exc:
+                if attempt < 2:
+                    time.sleep(delay)
+                    delay *= 2
+                    continue
+                raise Fail(f"outline {endpoint}: cannot reach the instance ({exc.reason})") from exc
+        raise Fail(f"outline {endpoint}: gave up after 7 attempts")
+
+    def resolve_collection(self) -> str:
+        """Accept a UUID, a urlId, or the whole `name-urlId` slug from the browser.
+
+        The API takes a UUID, and the value a person copies out of the address bar
+        is a slug. Rejecting that with 'Invalid UUID' is technically correct and
+        useless, so match it instead."""
+        if self._collection_uuid:
+            return self._collection_uuid
+        value = self.collection.strip()
+        if not value:
+            raise Fail("AGENT_SYNC_OUTLINE_COLLECTION is not set — run `bootstrap` to create "
+                       "the container, then put the id it prints into .env.agent-sync")
+        if re.fullmatch(r"[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}", value):
+            self._collection_uuid = value
+            return value
+
+        rows = self._call("collections.list", {"limit": 100})
+        rows = rows if isinstance(rows, list) else []
+        tail = value.rsplit("-", 1)[-1]
+        for c in rows:
+            if value in (c.get("urlId"), c.get("name")) or (tail and tail == c.get("urlId")):
+                self._collection_uuid = c["id"]
+                print(f"note: resolved collection '{c.get('name')}' → {c['id']}\n"
+                      f"      put that UUID in AGENT_SYNC_OUTLINE_COLLECTION to skip this lookup",
+                      file=sys.stderr)
+                return str(c["id"])
+        names = ", ".join(repr(c.get("name")) for c in rows) or "none visible to this token"
+        raise Fail(f"no collection matches '{value}'. Available: {names}")
+
+    def tree_ensure(self, path: str) -> str:
+        if path in self._ids:
+            return self._ids[path]
+        collection = self.resolve_collection()
+        found = self._call("documents.search",
+                           {"query": path, "limit": 5, "collectionId": collection})
+        for row in (found if isinstance(found, list) else []):
+            doc = row.get("document") or {}
+            if doc.get("title") == path:
+                self._ids[path] = doc["id"]
+                return doc["id"]
+        doc = self._call("documents.create", {
+            "collectionId": collection, "title": path,
+            "text": f"{GENERATED_MARKER} container -->\n", "publish": True})
+        self._ids[path] = doc["id"]
+        return doc["id"]
+
+    def log_append(self, oid: str, line: str) -> None:
+        self._call("documents.update",
+                   {"id": oid, "text": line.rstrip("\n") + "\n", "editMode": "append"})
+
+    def log_read(self, oid: str) -> str:
+        return self._call("documents.info", {"id": oid}).get("text", "")
+
+    def doc_put(self, oid: str, text: str) -> None:
+        self._call("documents.update", {"id": oid, "text": text, "editMode": "replace"})
+
+    def doc_get(self, oid: str) -> str:
+        return self._call("documents.info", {"id": oid}).get("text", "")
+
+    def search(self, query: str, limit: int = 10) -> list[dict[str, Any]]:
+        rows = self._call("documents.search", {"query": query, "limit": limit})
+        out = []
+        for row in (rows if isinstance(rows, list) else []):
+            doc = row.get("document") or {}
+            out.append({"id": doc.get("id"), "title": doc.get("title"),
+                        "snippet": row.get("context", "")})
+        return out
+
+    def log_shards(self, prefix: str) -> list[str]:
+        """Enumerate by the collection's structure, never by the search index.
+
+        `documents.search` matches TEXT; a shard's identity is in its TITLE, and a
+        freshly created shard is not reliably returned. Under concurrency that produced
+        the worst possible failure: each process saw only its own shard, replayed it,
+        and concluded it had won — eight processes, eight winners, one key.
+        `documents.list` reads the collection structure and returns a new document at
+        once.
+        """
+        out: list[str] = []
+        offset = 0
+        while True:
+            rows = self._call("documents.list",
+                              {"collectionId": self.resolve_collection(),
+                               "limit": 100, "offset": offset})
+            rows = rows if isinstance(rows, list) else []
+            for doc in rows:
+                title = doc.get("title") or ""
+                if title.startswith(prefix):
+                    out.append(doc["id"])
+                    self._ids[title] = doc["id"]
+            if len(rows) < 100:
+                break
+            offset += 100
+            if offset > 1000:      # a bound, and it is reported rather than silent
+                print("agent-sync: more than 1000 documents in the collection; "
+                      "shard enumeration truncated", file=sys.stderr)
+                break
+        return out
+
+
+class FsAdapter(Adapter):
+    """Degraded mode. Files under .agent-sync/, committed and pushed.
+
+    atomicAppend is FALSE on purpose: agents here are separated by git, not by a
+    filesystem, so ordering is decided by a merge after the fact — which is not
+    when the protocol needs it. This adapter is never the lease authority.
+    """
+
+    name = "fs"
+    # A local lock file IS an exclusive primitive between processes on one machine.
+    capabilities = {"atomicAppend": False, "totalOrderRead": False, "search": False,
+                    "exclusiveLease": True}
+
+    def __init__(self, root: Path) -> None:
+        self.base = root / STATE_DIR
+        self.base.mkdir(parents=True, exist_ok=True)
+
+    def configured(self) -> bool:
+        return True
+
+    def _p(self, path: str) -> Path:
+        safe = re.sub(r"[^A-Za-z0-9._-]+", "-", path).strip("-").lower()
+        return self.base / f"{safe}.md"
+
+    def tree_ensure(self, path: str) -> str:
+        p = self._p(path)
+        if not p.exists():
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text("")
+        return str(p)
+
+    def log_append(self, oid: str, line: str) -> None:
+        with open(oid, "a") as fh:
+            fh.write(line.rstrip("\n") + "\n")
+
+    def log_read(self, oid: str) -> str:
+        p = Path(oid)
+        return p.read_text() if p.exists() else ""
+
+    def doc_put(self, oid: str, text: str) -> None:
+        Path(oid).write_text(text)
+
+    def doc_get(self, oid: str) -> str:
+        p = Path(oid)
+        return p.read_text() if p.exists() else ""
+
+    def log_shards(self, prefix: str) -> list[str]:
+        stem = re.sub(r"[^A-Za-z0-9._-]+", "-", prefix).strip("-").lower()
+        return [str(q) for q in sorted(self.base.glob(f"{stem}*.md"))]
+
+
+def make_adapter(cfg: dict[str, Any], root: Path) -> Adapter:
+    backend = os.environ.get("AGENT_SYNC_BACKEND") or cfg.get("backend") or "fs"
+    if backend == "outline":
+        ad = OutlineAdapter()
+        if not ad.configured():
+            return FsAdapter(root)
+        return ad
+    return FsAdapter(root)
+
+
+# --------------------------------------------------------------------------- log
+
+def fmt_line(op: str, key: str, rid: str, **extra: Any) -> str:
+    pairs = [f"`op={op}`", f"`key={key}`", f"`run={rid}`"]
+    pairs += [f"`{k}={v}`" for k, v in extra.items() if v not in (None, "")]
+    return f"- `{now_iso()}` " + " ".join(pairs)
+
+
+def parse_log(text: str) -> tuple[list[dict[str, str]], int]:
+    events: list[dict[str, str]] = []
+    bad = 0
+    for raw in text.splitlines():
+        raw = raw.rstrip()
+        # Skip only what is plainly not an entry (blank lines, prose, the generated
+        # marker). Anything shaped like an entry must reach LINE_RE, or a silent
+        # pre-filter hides malformed lines from the very counter meant to expose them.
+        if not CANDIDATE_RE.match(raw):
+            continue
+        m = LINE_RE.match(raw)
+        if not m:
+            bad += 1
+            continue
+        ev = dict(PAIR_RE.findall(m.group("pairs")))
+        if not {"op", "key", "run"} <= ev.keys():
+            bad += 1
+            continue
+        ev["ts"] = m.group("ts")
+        events.append(ev)
+    return events, bad
+
+
+def resolve_holding(events: list[dict[str, str]], key: str, at: float) -> dict[str, Any] | None:
+    """Replay: the holder is the earliest acquire for key that is, at this point,
+    neither released nor expired. Pure function of the log text.
+
+    Returns the holding record — run, repo and when it was taken — because a caller
+    that only learns *that* a key is held cannot tell an agent where to look."""
+    live: list[dict[str, Any]] = []
+    for ev in events:
+        if ev["key"] != key:
+            continue
+        if ev["op"] == "acquire":
+            live.append({"run": ev["run"], "ts": parse_iso(ev["ts"]),
+                         "ttl": int(ev.get("ttl") or DEFAULT_TTL),
+                         "repo": ev.get("repo", "")})
+        elif ev["op"] == "release":
+            live = [h for h in live if h["run"] != ev["run"]]
+        elif ev["op"] == "renew":
+            for h in live:
+                if h["run"] == ev["run"]:
+                    h["ts"] = parse_iso(ev["ts"])
+    for h in live:
+        if at <= h["ts"] + h["ttl"]:
+            return h
+    return None
+
+
+def resolve_holder(events: list[dict[str, str]], key: str, at: float) -> str | None:
+    h = resolve_holding(events, key, at)
+    return str(h["run"]) if h else None
+
+
+def resolve_reservations(events: list[dict[str, str]], reg: str) -> tuple[int, list[int], list[tuple[str, int]]]:
+    """Positional allocation over the log. Returns (base, free_list, assignments)."""
+    base = None
+    free: list[int] = []
+    served = 0
+    assignments: list[tuple[str, int]] = []
+    for ev in events:
+        if ev["key"] != reg:
+            continue
+        if ev["op"] == "base":
+            base = int(ev.get("value") or 0)
+            continue
+        if base is None:
+            continue
+        if ev["op"] == "release_id":
+            try:
+                free.append(int(ev.get("value") or 0))
+            except ValueError:
+                pass
+        elif ev["op"] == "reserve":
+            if free:
+                assignments.append((ev["run"], free.pop(0)))
+            else:
+                assignments.append((ev["run"], base + served))
+                served += 1
+    return (base or 0), free, assignments
+
+
+# --------------------------------------------------------------------------- coordinator
+
+class Sync:
+    def __init__(self) -> None:
+        self.root = project_root()
+        os.chdir(self.root)
+        load_env_file(self.root)
+        self.cfg = load_config(self.root)
+        self.adapter = make_adapter(self.cfg, self.root)
+        self.rid = run_id(self.root)
+        self.ttl = int(self.cfg.get("leaseTtlSeconds") or DEFAULT_TTL)
+        self.settle = float(self.cfg.get("settleSeconds") or DEFAULT_SETTLE)
+
+    @property
+    def gated(self) -> bool:
+        return bool(self.cfg.get("gated", True)) and self.adapter.is_lease_authority
+
+    def log_id(self, which: str) -> str:
+        """This run's OWN shard. One writer per document, always.
+
+        Outline's `editMode: append` is not atomic under concurrency: the server reads
+        the text, appends and writes it back, so simultaneous requests clobber each
+        other — and every one of them returns `ok: true`. Measured: twelve concurrent
+        appends, twelve successes reported, three lines present. Nine writes lost
+        silently.
+
+        That breaks mutual exclusion outright. If B's write erases A's acquire, A has
+        already read back and seen itself win, and B reads back and sees itself win —
+        two holders of one lease, each with proof.
+
+        Sharding removes the race rather than fighting it: nobody else writes this
+        document, so nothing can be clobbered. The cost is that a total order can no
+        longer come from one document's line order, so reads merge the shards and sort
+        by (timestamp, run). Every reader computes the SAME order — which is the
+        property the protocol actually needs. Clock skew now affects who wins a tie,
+        not whether readers agree, and an unfair winner is survivable where
+        disagreement is not.
+        """
+        return self.adapter.tree_ensure(f"{LOGS[which]} — {self.rid}")
+
+    def events(self, which: str) -> tuple[list[dict[str, str]], int]:
+        """Merge every shard, plus any pre-sharding single document, into one order."""
+        prefix = LOGS[which]
+        texts: list[str] = []
+        seen: set[str] = set()
+        for oid in self.adapter.log_shards(prefix):
+            if oid in seen:
+                continue
+            seen.add(oid)
+            texts.append(self.adapter.log_read(oid))
+
+        events: list[dict[str, str]] = []
+        bad = 0
+        for seq, text in enumerate(texts):
+            evs, b = parse_log(text)
+            bad += b
+            for i, ev in enumerate(evs):
+                ev["_shard"] = str(seq)
+                ev["_i"] = str(i)
+                events.append(ev)
+
+        # Deterministic for every reader: time, then run, then position within a shard.
+        events.sort(key=lambda e: (e["ts"], e["run"], int(e["_i"])))
+        return events, bad
+
+    # -- leases ------------------------------------------------------------
+
+    # -- git lease: real compare-and-swap, across machines --------------------
+
+    @staticmethod
+    def _ref(key: str) -> str:
+        return "refs/agent-sync/leases/" + re.sub(r"[^A-Za-z0-9._-]+", "-", key).strip("-")
+
+    def _git_remote(self) -> str:
+        return self.cfg.get("leaseRemote") or "origin"
+
+    def _git_read_lease(self, key: str) -> tuple[str | None, dict[str, Any]]:
+        """(sha, payload) currently on the remote for this key, or (None, {})."""
+        out = git("ls-remote", self._git_remote(), self._ref(key))
+        if not out:
+            return None, {}
+        sha = out.split()[0]
+        git("fetch", "-q", self._git_remote(), f"{self._ref(key)}:refs/agent-sync/fetched")
+        body = git("log", "-1", "--format=%B", sha) or git("log", "-1", "--format=%B",
+                                                           "refs/agent-sync/fetched")
+        try:
+            return sha, json.loads(body.strip())
+        except (json.JSONDecodeError, ValueError):
+            return sha, {}
+
+    def _git_acquire(self, key: str) -> tuple[bool, str | None]:
+        """Push a ref that must not already exist. The remote's non-fast-forward rule
+        IS the compare-and-swap — verified against a hosted remote, not assumed."""
+        remote, ref = self._git_remote(), self._ref(key)
+        held_sha, held = self._git_read_lease(key)
+        if held:
+            if held.get("run") == self.rid:
+                self._touch_renew()
+                return True, self.rid
+            alive = time.time() <= parse_iso(held.get("ts", "")) + int(held.get("ttl", self.ttl))
+            if alive:
+                return False, held.get("run")
+
+        payload = json.dumps({"run": self.rid, "ts": now_iso(), "ttl": self.ttl,
+                              "repo": repo_name(), "host": os.uname().nodename})
+        empty_tree = git("hash-object", "-t", "tree", "/dev/null")
+        commit = subprocess.run(["git", "commit-tree", empty_tree], input=payload,
+                                capture_output=True, text=True).stdout.strip()
+        if not commit:
+            raise Fail("could not create the lease object — is this a git repository?")
+
+        args = ["git", "push", remote, f"{commit}:{ref}"]
+        if held_sha:                       # stealing an expired lease, and only that
+            args.insert(2, f"--force-with-lease={ref}:{held_sha}")
+        r = subprocess.run(args, capture_output=True, text=True)
+        if r.returncode != 0:
+            # Rejected: somebody won between our read and our push. Ask who.
+            _s, now_held = self._git_read_lease(key)
+            return False, now_held.get("run") or "another run"
+        self._touch_renew()
+        return True, self.rid
+
+    def _git_release(self, key: str) -> None:
+        sha, held = self._git_read_lease(key)
+        if not sha:
+            return
+        if held.get("run") not in (self.rid, None):
+            print(f"note: {key} is held by {held.get('run')}, not this run — not released",
+                  file=sys.stderr)
+            return
+        r = subprocess.run(["git", "push", self._git_remote(),
+                            f"--force-with-lease={self._ref(key)}:{sha}",
+                            f":{self._ref(key)}"], capture_output=True, text=True)
+        if r.returncode != 0:
+            print(f"note: could not release {key} on the remote: {r.stderr.strip()[:160]}",
+                  file=sys.stderr)
+
+    @property
+    def lease_mode(self) -> str:
+        return self.cfg.get("leaseBackend") or "local"
+
+    @property
+    def lease_is_cross_machine(self) -> bool:
+        return self.lease_mode == "git"
+
+    def _local_lock(self, key: str) -> Path:
+        d = self.root / STATE_DIR / "leases"
+        d.mkdir(parents=True, exist_ok=True)
+        return d / f"{re.sub(r'[^A-Za-z0-9_-]', '-', key)}.lock"
+
+    def acquire(self, key: str) -> tuple[bool, str | None]:
+        """Exclusion comes from an atomic file create; the cloud carries the record.
+
+        This is the third design, and the first that is true. A single shared document
+        lost writes (twelve concurrent appends, twelve reported successes, three lines
+        present). Sharding fixed the loss and broke the decision: with no way to know a
+        contender is still writing, eight processes each read only their own shard and
+        eight of them won. No settle window closes that — the store has no
+        compare-and-swap, so the question "has everyone written yet?" has no answer.
+
+        `O_EXCL` does have one. It is a genuine mutex between processes on one machine,
+        which is how these agents actually run. Across machines it is not, and the tool
+        says so rather than implying a guarantee it cannot keep.
+        """
+        if self.lease_mode == "git":
+            won, holder = self._git_acquire(key)
+            if won:
+                for n in self.write_claim(key, self.rid):
+                    print(f"  {n}")
+                try:
+                    self.adapter.log_append(self.log_id("claims"), fmt_line(
+                        "acquire", key, self.rid, ttl=self.ttl,
+                        repo=repo_name(), sha=head_sha()))
+                except Fail:
+                    pass
+            return won, holder
+
+        lock = self._local_lock(key)
+
+        # Reap an expired lock first: it is a crashed run, not a live holder.
+        if lock.exists():
+            try:
+                held = json.loads(lock.read_text())
+            except (json.JSONDecodeError, OSError):
+                held = {}
+            expired = time.time() > parse_iso(held.get("ts", "")) + int(held.get("ttl", self.ttl))
+            if held.get("run") == self.rid:
+                self._touch_renew()
+                return True, self.rid
+            if not expired:
+                return False, held.get("run")
+            lock.unlink(missing_ok=True)
+
+        payload = json.dumps({"run": self.rid, "ts": now_iso(), "ttl": self.ttl,
+                              "repo": repo_name()})
+        try:
+            fd = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except FileExistsError:
+            try:
+                other = json.loads(lock.read_text()).get("run")
+            except (json.JSONDecodeError, OSError):
+                other = None
+            return False, other
+        with os.fdopen(fd, "w") as fh:
+            fh.write(payload)
+
+        self._touch_renew()
+        for n in self.write_claim(key, self.rid):
+            print(f"  {n}")
+        # Record it for everyone else to see. A failure here costs visibility, never
+        # correctness — the lock is already held — so it must not fail the acquire.
+        if self.adapter.is_lease_authority:
+            try:
+                self.adapter.log_append(self.log_id("claims"), fmt_line(
+                    "acquire", key, self.rid, ttl=self.ttl,
+                    repo=repo_name(), sha=head_sha()))
+            except Fail as exc:
+                print(f"note: lease held, but not published to the plane ({exc})",
+                      file=sys.stderr)
+        return True, self.rid
+
+    def renew(self, key: str | None = None) -> bool:
+        marker = self.root / STATE_DIR / "last-renew"
+        interval = int(self.cfg.get("renewIntervalSeconds") or DEFAULT_RENEW)
+        if marker.exists() and time.time() - marker.stat().st_mtime < interval:
+            return False
+        keys = [key] if key else self.held()
+        if not keys:
+            self._touch_renew()
+            return False
+        if self.adapter.is_lease_authority:
+            oid = self.log_id("claims")
+            for k in keys:
+                self.adapter.log_append(oid, fmt_line("renew", k, self.rid))
+        self._touch_renew()
+        return True
+
+    def _touch_renew(self) -> None:
+        marker = self.root / STATE_DIR / "last-renew"
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text(now_iso())
+
+    def release(self, key: str) -> None:
+        for n in self.write_claim(key, None):
+            print(f"  {n}")
+        if self.lease_mode == "git":
+            self._git_release(key)
+        lock = self._local_lock(key)
+        if lock.exists():
+            try:
+                if json.loads(lock.read_text()).get("run") in (self.rid, None):
+                    lock.unlink(missing_ok=True)
+            except (json.JSONDecodeError, OSError):
+                lock.unlink(missing_ok=True)
+        if self.adapter.is_lease_authority:
+            try:
+                self.adapter.log_append(self.log_id("claims"),
+                                        fmt_line("release", key, self.rid))
+            except Fail as exc:
+                print(f"note: released locally, not published ({exc})", file=sys.stderr)
+
+    def held(self) -> list[str]:
+        d = self.root / STATE_DIR / "leases"
+        mine = []
+        for q in sorted(d.glob("*.lock") if d.exists() else []):
+            try:
+                h = json.loads(q.read_text())
+            except (json.JSONDecodeError, OSError):
+                continue
+            if h.get("run") == self.rid and \
+                    time.time() <= parse_iso(h.get("ts", "")) + int(h.get("ttl", self.ttl)):
+                mine.append(q.stem)
+        return sorted(mine)
+
+    def _held_legacy(self) -> list[str]:
+        if not self.adapter.is_lease_authority:
+            d = self.root / STATE_DIR / "leases"
+            out = []
+            for p in (d.glob("*.lock") if d.exists() else []):
+                try:
+                    if json.loads(p.read_text()).get("run") == self.rid:
+                        out.append(p.stem)
+                except json.JSONDecodeError:
+                    continue
+            return out
+        events, _ = self.events("claims")
+        now = time.time()
+        keys = {e["key"] for e in events}
+        return sorted(k for k in keys if resolve_holder(events, k, now) == self.rid)
+
+    # -- ids ---------------------------------------------------------------
+
+    def reserve(self, reg: str) -> int:
+        if not self.adapter.is_lease_authority:
+            raise Fail(
+                f"backend '{self.adapter.name}' cannot reserve ids safely "
+                "(atomicAppend is false). Allocate by hand and record it, or configure a "
+                "cloud backend. Pretending would hand two agents the same id.")
+        oid = self.log_id("reservations")
+        events, _ = parse_log(self.adapter.log_read(oid))
+        base, _free, _assign = resolve_reservations(events, reg)
+        if not base:
+            base = self._seed_base(reg)
+            self.adapter.log_append(oid, fmt_line("base", reg, self.rid, value=f"{base:04d}"))
+            events, _ = parse_log(self.adapter.log_read(oid))
+        self.adapter.log_append(oid, fmt_line("reserve", reg, self.rid))
+        time.sleep(0.25 + random.random() * 0.15)
+        events, _ = parse_log(self.adapter.log_read(oid))
+        _b, _f, assignments = resolve_reservations(events, reg)
+        mine = [v for r, v in assignments if r == self.rid]
+        if not mine:
+            raise Fail(f"reserve {reg}: the append did not read back — retry")
+        return mine[-1]
+
+    def _seed_base(self, reg: str) -> int:
+        spec = (self.cfg.get("idRegisters") or {}).get(reg)
+        if not spec:
+            raise Fail(f"register '{reg}' is not declared in .claude/agent-sync.json")
+        path = self.root / spec["file"]
+        if not path.exists():
+            raise Fail(f"register file {spec['file']} does not exist")
+        m = re.search(spec["nextFreeIdPattern"], path.read_text())
+        if not m:
+            raise Fail(f"could not read the next free id out of {spec['file']}")
+        return int(m.group(1))
+
+    def release_id(self, reg: str, value: str) -> None:
+        if self.adapter.is_lease_authority:
+            self.adapter.log_append(self.log_id("reservations"),
+                                    fmt_line("release_id", reg, self.rid, value=value))
+
+    # -- journal / signals -------------------------------------------------
+
+    def _publish(self, which: str, line: str) -> bool:
+        """Write to the plane, and never let that failure destroy the caller's work.
+
+        The plane carries visibility, not correctness. A rate limit or an outage must
+        surface loudly and leave the run able to continue — swallowing it would hide a
+        gap in the record, and raising would make a knowledge base an availability
+        dependency of doing any work at all.
+        """
+        try:
+            self.adapter.log_append(self.log_id(which), line)
+            return True
+        except Fail as exc:
+            print(f"agent-sync: NOT published to the plane ({exc}). The work stands; "
+                  "the record has a gap — re-run this step when the store is reachable.",
+                  file=sys.stderr)
+            return False
+
+    def journal(self, text: str) -> None:
+        try:
+            oid = self.adapter.tree_ensure(f"20 Runs — {self.rid}")
+            self.adapter.log_append(oid, fmt_line(
+                "journal", self.rid, self.rid, sha=head_sha(),
+                note=text.replace("`", "'")[:400]))
+        except Fail as exc:
+            print(f"agent-sync: journal NOT published ({exc})", file=sys.stderr)
+
+    def signal(self, dep: str, state: str) -> None:
+        allowed = {"filed", "accepted", "delivered", "closed", "refused"}
+        if state not in allowed:
+            raise Fail(f"state must be one of {sorted(allowed)}")
+        self._publish("signals", fmt_line(
+            "signal", dep, self.rid, state=state, repo=repo_name(), sha=head_sha()))
+
+    # -- awareness ---------------------------------------------------------
+
+    def _watermark(self, which: str) -> int:
+        p = self.root / STATE_DIR / "seen.json"
+        try:
+            return int(json.loads(p.read_text()).get(which, 0))
+        except (OSError, ValueError, AttributeError):
+            return 0
+
+    def _set_watermark(self, which: str, value: int) -> None:
+        p = self.root / STATE_DIR / "seen.json"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            data = json.loads(p.read_text())
+        except (OSError, ValueError):
+            data = {}
+        data[which] = value
+        p.write_text(json.dumps(data))
+
+    def activity(self, limit: int = 6, mark_read: bool = True) -> dict[str, Any]:
+        """What OTHER runs are doing, and what changed since this run last looked.
+
+        Coordination is not only mutual exclusion. An agent that cannot see the
+        others is merely blocked by them: it learns a task is taken and nothing
+        about who has it, what they are touching, or what landed while it was away.
+        """
+        others = {k: v for k, v in self.all_holdings().items() if v["run"] != self.rid}
+
+        signals, _ = self.events("signals")
+        seen = self._watermark("signals")
+        fresh = signals[seen:] if len(signals) > seen else []
+        if mark_read:
+            self._set_watermark("signals", len(signals))
+
+        return {"others": others, "signals": signals[-limit:], "new_signals": fresh}
+
+    # -- claim tags ---------------------------------------------------------
+
+    def _claim_targets(self, key: str) -> list[tuple[Path, dict[str, Any]]]:
+        out = []
+        for pattern, spec in (self.cfg.get("claimTags") or {}).items():
+            for path in sorted(self.root.glob(pattern)):
+                if path.is_file():
+                    out.append((path, spec))
+        return out
+
+    @staticmethod
+    def _row_cells(line: str) -> list[str] | None:
+        """Split a markdown table row, or None if this is not one."""
+        if not line.lstrip().startswith("|"):
+            return None
+        raw = line.strip()
+        if raw.endswith("|"):
+            raw = raw[:-1]
+        return raw[1:].split("|")
+
+    def write_claim(self, key: str, holder: str | None) -> list[str]:
+        """Write the claim through to git, or restore it. Surgical and reversible.
+
+        One row, one cell, one substitution. Ambiguity is refused rather than guessed:
+        this edits a shared registry, so a wrong line is exactly the collision the lease
+        exists to prevent. The previous cell text is stored in the lock file, so release
+        restores what was there rather than an assumed default.
+        """
+        notes: list[str] = []
+        for path, spec in self._claim_targets(key):
+            if spec.get("mode") != "cell":
+                continue
+            idx = int(spec.get("cell", -1))
+            lines = path.read_text().splitlines(keepends=True)
+            hits = [i for i, l in enumerate(lines)
+                    if re.search(rf"(?<![A-Za-z0-9-]){re.escape(key)}(?![A-Za-z0-9-])", l)
+                    and self._row_cells(l) is not None]
+            rel = path.relative_to(self.root)
+            if not hits:
+                continue
+            if len(hits) > 1:
+                notes.append(f"{rel}: `{key}` appears in {len(hits)} table rows — refusing "
+                             "to guess which one is the claim. Narrow the pattern or edit by hand")
+                continue
+
+            i = hits[0]
+            cells = self._row_cells(lines[i])
+            assert cells is not None
+            if idx < 0:
+                idx = len(cells) + idx
+            if not 0 <= idx < len(cells):
+                notes.append(f"{rel}: cell {spec.get('cell')} is out of range for `{key}`'s row")
+                continue
+
+            # Kept beside the run state, not in the lock file: the git lease mode has no
+            # lock file, and a release that cannot find what it replaced leaves the claim
+            # written through forever — which is worse than never writing it.
+            store = self.root / STATE_DIR / "claims.json"
+            try:
+                state = json.loads(store.read_text())
+            except (json.JSONDecodeError, OSError):
+                state = {}
+            saved = (state.get(key) or {}).get(str(rel))
+
+            current = cells[idx]
+            if holder is not None:
+                if saved is not None:
+                    continue                      # already written through
+                template = spec.get("held") or "{prev} (claimed: {holder})"
+                new = template.replace("{prev}", current.strip()).replace("{holder}", holder)
+                cells[idx] = f" {new.strip()} "
+                state.setdefault(key, {})[str(rel)] = current
+            else:
+                if saved is None:
+                    continue                      # nothing of ours to undo
+                cells[idx] = saved
+                state.get(key, {}).pop(str(rel), None)
+                if not state.get(key):
+                    state.pop(key, None)
+
+            lines[i] = "|" + "|".join(cells) + "|\n"
+            tmp = path.with_suffix(path.suffix + ".agent-sync.tmp")
+            tmp.write_text("".join(lines))
+            tmp.replace(path)
+            store.parent.mkdir(parents=True, exist_ok=True)
+            store.write_text(json.dumps(state, indent=2))
+            notes.append(f"{rel}: `{key}` claim "
+                         + ("written through" if holder else "restored"))
+        return notes
+
+    # -- claim divergence ---------------------------------------------------------
+
+    def claim_divergence(self) -> list[str]:
+        """Where a held lease and the durable git claim tag disagree.
+
+        DEC-0216 makes the git tag the durable record and the lease the live one, with
+        the run writing the tag through. The tool verifies rather than edits: a process
+        that rewrites a shared registry file on its own is the exact mechanism that
+        clobbers another agent's work, and it would do it from a hook, unattended.
+        So this reports, and the agent writes.
+        """
+        out: list[str] = []
+        tags = self.cfg.get("claimTags") or {}
+        if not tags:
+            return out
+        held = set(self.held())
+        if not held:
+            return out
+        for pattern, spec in tags.items():
+            for path in sorted(self.root.glob(pattern)):
+                if not path.is_file():
+                    continue
+                try:
+                    text = path.read_text()
+                except OSError:
+                    continue
+                rel = path.relative_to(self.root)
+                marker = (spec.get("held") or "").replace("{holder}", self.rid)
+                for key in sorted(held):
+                    if key not in text:
+                        continue
+                    line = next((l for l in text.splitlines() if key in l), "")
+                    if marker and marker in line:
+                        continue
+                    if spec.get("open") and spec["open"] in line:
+                        out.append(f"{rel}: `{key}` still reads `{spec['open']}` while "
+                                   "this run holds the lease — write the claim through")
+                    elif spec.get("open") and spec["open"] in text:
+                        # The tag exists in the file but not on the id's line. The
+                        # configured mapping cannot be verified for this key, and saying
+                        # so beats passing silently — an unverifiable check that reports
+                        # clean is indistinguishable from one that works.
+                        out.append(f"{rel}: cannot verify the claim tag for `{key}` — "
+                                   f"`{spec['open']}` appears in the file but not on that "
+                                   "id's line. Fix claimTags, or write the tag by hand")
+        return out
+
+    # -- as-built record and reconciliation ---------------------------------
+
+    def record(self, text: str, decision: str = "", files: str = "") -> None:
+        """Append what was ACTUALLY built. Not a plan, not an intention."""
+        self._publish("asbuilt", fmt_line(
+            "asbuilt", decision or "-", self.rid, repo=repo_name(), sha=head_sha(),
+            files=files.replace("`", "'")[:200],
+            note=text.replace("`", "'")[:400]))
+
+
+    def _allocated_ids(self, reg: str, spec: dict[str, Any]) -> set[str]:
+        """Ids that actually exist, excluding the register's "next free" pointer.
+
+        That line names the id nobody has taken yet. Scraping it as an allocated id
+        makes every reconcile demand an as-built record for a decision that has not
+        been written — and poisons the baseline with a number one higher than reality.
+        """
+        path = self.root / spec["file"]
+        if not path.exists():
+            return set()
+        text = path.read_text()
+        ids = set(re.findall(rf"\b{reg}-\d+\b", text))
+        pattern = spec.get("nextFreeIdPattern")
+        if pattern:
+            m = re.search(pattern, text)
+            if m:
+                ids.discard(f"{reg}-{m.group(1)}")
+        return ids
+
+    def set_baseline(self) -> dict[str, int]:
+        """Stamp today's highest id per register as the line before which nothing is
+        expected to carry an as-built record. Idempotent-ish: re-stamping moves the
+        line forward, which is why it prints what it did."""
+        out = {}
+        oid = self.log_id("asbuilt")
+        for reg, spec in (self.cfg.get("idRegisters") or {}).items():
+            path = self.root / spec["file"]
+            if not path.exists():
+                continue
+            nums = [int(i.rsplit("-", 1)[1]) for i in self._allocated_ids(reg, spec)]
+            top = max(nums) if nums else 0
+            self.adapter.log_append(oid, fmt_line(
+                "baseline", reg, self.rid, value=f"{top:04d}", repo=repo_name()))
+            out[reg] = top
+        return out
+
+    def reconcile(self) -> list[dict[str, str]]:
+        """Compare intent (git) against the as-built record (cloud).
+
+        Only mechanical divergence is decided here. Whether a built thing actually
+        matches what the document describes is a reading, not a diff — this reports
+        where to look and refuses to pretend it judged the substance.
+        """
+        findings: list[dict[str, str]] = []
+        notes_backlog: list[str] = []
+        events, _ = self.events("asbuilt")
+
+        # 1. Recorded as built, but the commit is not in this history: recorded from a
+        #    branch that never landed, or from a different repository.
+        for ev in events:
+            sha = ev.get("sha", "")
+            repo = ev.get("repo", "")
+            if not sha or sha == "unknown" or repo != repo_name():
+                continue
+            # `git cat-file -e` prints nothing on success, so the exit code is the
+            # only signal — a stdout-returning helper cannot answer this.
+            if subprocess.run(["git", "cat-file", "-e", f"{sha}^{{commit}}"],
+                              capture_output=True).returncode != 0:
+                findings.append({
+                    "kind": "as-built commit missing from git",
+                    "detail": f"{sha} recorded by {ev['run']}: {ev.get('note', '')[:90]}",
+                    "means": "recorded as built, but that commit is not in this history"})
+
+        # 2. Intent with no as-built record — as a RATCHET, not a flood.
+        #    A project adopting this on day one has every prior decision unrecorded, and
+        #    a check that reports all of them reports nothing: it is noise, and noise is
+        #    what gets a gate switched off. Ids at or below the baseline are counted as a
+        #    backlog that may only shrink; ids after it fail.
+        recorded_ids = {ev["key"] for ev in events if ev["key"] != "-"}
+        baselines = {ev["key"]: int(ev.get("value") or 0)
+                     for ev in events if ev["op"] == "baseline"}
+        for reg, spec in (self.cfg.get("idRegisters") or {}).items():
+            path = self.root / spec["file"]
+            if not path.exists():
+                continue
+            ids = self._allocated_ids(reg, spec)
+            base = baselines.get(reg)
+            if base is None:
+                findings.append({
+                    "kind": f"{reg} has no as-built baseline",
+                    "detail": f"{len(ids)} ids exist and none is evaluated",
+                    "means": "run `reconcile --set-baseline` once, then only new ids are checked"})
+                continue
+            missing_new, backlog = [], 0
+            for i in sorted(ids - recorded_ids):
+                num = int(i.rsplit("-", 1)[1])
+                if num > base:
+                    missing_new.append(i)
+                else:
+                    backlog += 1
+            if missing_new:
+                findings.append({
+                    "kind": f"{reg} written after the baseline with no as-built record",
+                    "detail": ", ".join(missing_new[:8]) +
+                              (f" (+{len(missing_new)-8} more)" if len(missing_new) > 8 else ""),
+                    "means": "decided since adoption; nothing reports it was built"})
+            if backlog:
+                notes_backlog.append(f"{reg}: {backlog} pre-baseline ids unevaluated (backlog)")
+
+        # 3. As-built citing an id that does not exist in git: built against something
+        #    that was never recorded as a decision.
+        # Only judge what this checkout can actually judge. The as-built log is shared by
+        # every repository on the plane, while id registers are per-repository — a service
+        # repo declares none, because decisions live in the umbrella. Comparing the shared
+        # log against a local register reported every umbrella decision as an orphan when
+        # run from a submodule: a false finding produced by scope, and the loudest possible
+        # way to teach people to ignore the check.
+        registers = self.cfg.get("idRegisters") or {}
+        if registers:
+            known: set[str] = set()
+            for reg, spec in registers.items():
+                known |= self._allocated_ids(reg, spec)
+            prefixes = tuple(f"{reg}-" for reg in registers)
+            orphan = sorted({ev["key"] for ev in events
+                             if ev.get("repo") == repo_name()
+                             and ev["key"].startswith(prefixes)
+                             and ev["key"] not in known})
+            if orphan:
+                findings.append({
+                    "kind": "as-built cites an unknown id",
+                    "detail": ", ".join(orphan[:8]),
+                    "means": "built against a decision that is not in the git register"})
+        else:
+            notes_backlog.append(
+                "no id registers declared here, so register checks are not evaluated in "
+                "this repository — run reconcile in the umbrella for those")
+
+        self.backlog = notes_backlog
+        return findings
+
+    # -- guard -------------------------------------------------------------
+
+    def guard(self, path: str) -> tuple[bool, str]:
+        rel = os.path.relpath(os.path.abspath(path), str(self.root))
+        patterns = self.cfg.get("guardedFiles") or []
+        if not any(Path(rel).match(p) for p in patterns):
+            return True, "not a guarded file"
+
+        # A lease is required in every mode. What differs between backends is how
+        # strongly it is arbitrated, and that is what `gated` reports — not whether
+        # the check runs. A local lock file is genuine mutual exclusion between
+        # agents on one machine; it is only across machines that fs cannot arbitrate.
+        held = self.held()
+        if held:
+            note = "" if self.gated else " (advisory: arbitrated locally only)"
+            return True, f"held by this run ({', '.join(held)}){note}"
+
+        other = self._any_other_holder()
+        who = f" — {other} holds a lease right now" if other else ""
+        return False, (f"{rel} is a guarded registry file and this run holds no lease{who}. "
+                       f"Acquire one first: agent_sync.py acquire <TASK-ID>")
+
+    def _any_other_holder(self) -> str | None:
+        if self.adapter.is_lease_authority:
+            events, _ = self.events("claims")
+            now = time.time()
+            for key in {e["key"] for e in events}:
+                holder = resolve_holder(events, key, now)
+                if holder and holder != self.rid:
+                    return holder
+            return None
+        d = self.root / STATE_DIR / "leases"
+        for p in (d.glob("*.lock") if d.exists() else []):
+            try:
+                held = json.loads(p.read_text())
+            except (json.JSONDecodeError, OSError):
+                continue
+            if held.get("run") != self.rid and \
+                    time.time() <= parse_iso(held.get("ts", "")) + int(held.get("ttl", self.ttl)):
+                return str(held.get("run"))
+        return None
+
+    # -- board -------------------------------------------------------------
+
+    def all_holdings(self) -> dict[str, dict[str, Any]]:
+        """Every key currently held, with who holds it and in which repository.
+
+        The repository matters: work spans several repos that are entered from one
+        umbrella, so "r-alpha holds ASC-072" is only actionable once you know which
+        checkout r-alpha is in."""
+        now = time.time()
+        if self.adapter.is_lease_authority:
+            events, _ = self.events("claims")
+            out: dict[str, dict[str, Any]] = {}
+            for key in sorted({e["key"] for e in events}):
+                holding = resolve_holding(events, key, now)
+                if holding:
+                    out[key] = holding
+            return out
+        out = {}
+        d = self.root / STATE_DIR / "leases"
+        for p in sorted(d.glob("*.lock") if d.exists() else []):
+            try:
+                held = json.loads(p.read_text())
+            except (json.JSONDecodeError, OSError):
+                continue
+            if now <= parse_iso(held.get("ts", "")) + int(held.get("ttl", self.ttl)):
+                out[p.stem] = {"run": str(held.get("run")), "repo": repo_name(),
+                               "ts": parse_iso(held.get("ts", ""))}
+        return out
+
+    def all_holders(self) -> dict[str, str]:
+        return {k: str(v["run"]) for k, v in self.all_holdings().items()}
+
+    def board(self) -> str:
+        """The cross-repository view — identical whoever generates it.
+
+        Four repositories share one plane and every one of them may regenerate this
+        page, so its content must not depend on who did. It once did: the header named
+        the generating repo and the id-leak section read that repo's registers, so a
+        submodule agent's run replaced the umbrella's board with a narrower one. Repo-
+        local findings now live on their own page (`12 Repo — <name>`); only facts that
+        are true from every checkout belong here.
+        """
+        events, bad = self.events("claims")
+        total = max(len(events) + bad, 1)
+        rows = [f"| `{k}` | {h['run']} | {h.get('repo') or '—'} | held |"
+                for k, h in self.all_holdings().items()]
+
+        lines = [
+            f"{GENERATED_MARKER} source={repo_name()}@{head_sha()} at={now_iso()} "
+            "— edit in git, not here -->",
+            "",
+            "# Board — the coordination plane",
+            "",
+            "Every repository on this plane writes and reads this page. It carries only "
+            "facts that are true from any of them.",
+            "",
+            f"- backend: `{self.adapter.name}` · lease authority: "
+            f"**{'yes' if self.adapter.is_lease_authority else 'no'}**",
+            f"- runs are recorded as **{'gated' if self.gated else 'ungated'}**",
+            f"- unparseable log lines: {bad}/{total}"
+            f"{'  ⚠ over 2% — the log cannot be replayed reliably' if bad / total > 0.02 else ''}",
+            "",
+            "## Live leases",
+            "",
+            "| Key | Holder | Repo | State |",
+            "|---|---|---|---|",
+        ]
+        lines += rows or ["| — | — | — | none held |"]
+
+        sig, _ = self.events("signals")
+        if sig:
+            lines += ["", "## Recent cross-repo signals", "",
+                      "| Dependency | State | By | Repo |", "|---|---|---|---|"]
+            for ev in sig[-10:]:
+                lines.append(f"| `{ev['key']}` | {ev.get('state','?')} | {ev['run']} "
+                             f"| {ev.get('repo','—')} |")
+        return "\n".join(lines) + "\n"
+
+    def config_digest(self) -> str:
+        """Identity of the configuration this snapshot describes.
+
+        Stamping the commit instead made the very first adoption look stale: the config
+        is added in the same commit as the snapshot, so a commit-range diff always found
+        a change. A content hash has no such boundary.
+        """
+        raw = (self.root / CONFIG_PATH).read_bytes()
+        return hashlib.sha256(raw).hexdigest()[:12]
+
+    def setup_snapshot(self) -> str:
+        """A snapshot of how THIS project is actually wired, generated from the config.
+
+        Written into the repository so every agent — and every human — reads the same
+        description of the documentation pipeline before touching it, instead of
+        inferring it from behaviour. Generated, never hand-written: a hand-written
+        description of a configuration drifts from it, which is the failure this whole
+        tool exists to surface.
+        """
+        cfg = self.cfg
+        regs = cfg.get("idRegisters") or {}
+        guarded = cfg.get("guardedFiles") or []
+        gates = cfg.get("gates") or []
+        mirror = cfg.get("mirror") or {}
+        env_path = find_env_file(self.root)
+        L = [
+            f"{GENERATED_MARKER} source={repo_name()}@{head_sha()} "
+            f"cfg={self.config_digest()} at={now_iso()} "
+            "— regenerate with `agent_sync.py setup`, do not hand-edit -->",
+            "",
+            f"# How documentation and coordination work in {repo_name()}",
+            "",
+            "This file is **generated** from the live configuration. If it disagrees with",
+            "what the tool does, the tool is right and this file is stale — regenerate it.",
+            "",
+            "## Two documentation sources",
+            "",
+            "| Source | Answers | Where |",
+            "|---|---|---|",
+            "| Git documents | *how it should be* — intent, decisions, contracts | this repository |",
+            "| As-built record | *how it actually is* — what agents wrote, with commits | the coordination plane |",
+            "",
+            "Neither outranks the other; they answer different questions. **The gap between",
+            "them is the finding.** Reconcile before starting a task and after finishing it.",
+            "",
+            "## This project's wiring",
+            "",
+            f"- backend: **{self.adapter.name}** · lease authority: "
+            f"**{'yes' if self.adapter.is_lease_authority else 'NO — degraded'}** · runs recorded "
+            f"**{'gated' if self.gated else 'ungated'}**",
+            f"- lease TTL {cfg.get('leaseTtlSeconds', DEFAULT_TTL)}s, renewed every "
+            f"{cfg.get('renewIntervalSeconds', DEFAULT_RENEW)}s",
+            f"- credentials read from `{env_path.name if env_path else '(none found)'}`"
+            f"{' in ' + str(env_path.parent.name) if env_path and env_path.parent != self.root else ''}"
+            " — gitignored, never committed",
+            "",
+            "### Id registers — reserve before you write",
+            "",
+        ]
+        if regs:
+            L += ["| Register | File | Reserve with |", "|---|---|---|"]
+            L += [f"| `{r}` | `{s['file']}` | `agent_sync.py reserve {r}` |" for r, s in sorted(regs.items())]
+            L += ["", "Reading a *next free id* line is **not** reserving it — two agents read the same number."]
+        else:
+            L += ["None declared here. Ids live in the parent repository; reserve them there."]
+
+        L += ["", "### Guarded files — a live lease is required to write these", ""]
+        L += ([f"- `{g}`" for g in guarded] or ["- none"])
+        L += ["", "### Gates run before a change is considered done", ""]
+        L += ([f"- `{g}`" for g in gates] or ["- none configured"])
+
+        L += ["", "### Mirrored into the plane (read-only rendering of git)", ""]
+        L += ([f"- `{s}`" for s in (mirror.get("sources") or [])]
+              if mirror.get("enabled") else ["- disabled"])
+
+        L += [
+            "",
+            "## What is written where, and what is never deleted",
+            "",
+            "| Information | Home | Lifetime |",
+            "|---|---|---|",
+            "| Decisions, specs, contracts, user-facing behaviour | git | permanent, append-only register |",
+            "| What was actually built, with its commit | as-built log | permanent, append-only |",
+            "| Cross-repo dependency state | signal log | permanent, append-only |",
+            "| Who holds a task right now | claims log | expires by TTL |",
+            "| Per-run narrative | that run's journal | permanent |",
+            "| The board and these pages | generated | replaced on every regeneration |",
+            "",
+            "**Nothing in a log is edited or deleted.** A mistake is corrected by appending",
+            "the correcting entry, because the logs are replayed in order and a deletion",
+            "would silently rewrite a decision every other agent already read. A lease is",
+            "released, never removed. A reserved id that is not used is returned with",
+            "`release-id`, which appends — it does not erase.",
+            "",
+            "Generated pages are the exception: they are rewritten wholesale, and a page",
+            "whose first line lost its generated marker is **refused**, not overwritten.",
+            "",
+            "## The cycle, per task",
+            "",
+            "```",
+            "status      → who else is working, and what changed while you were away",
+            "reconcile   → resolve every divergence BEFORE writing code",
+            "acquire ID  → take the lease; the claim tag in git is written through",
+            "   … work …",
+            "record      → what you ACTUALLY built, with the decision id and files",
+            "   … update the git documents in the same change …",
+            "reconcile   → check both sides again",
+            "board       → regenerate the shared view",
+            "release ID  → on every path, including failure",
+            "```",
+            "",
+            "Full doctrine ships with the skill: `references/two-sources.md`,",
+            "`references/lease-protocol.md`, `references/pipeline-binding.md`.",
+        ]
+        return "\n".join(L) + "\n"
+
+    def mirror(self, limit: int = 120) -> list[str]:
+        """Render the configured git documents into the plane, one-way and stamped.
+
+        A rendering, never a source: each page carries the commit it was made from, and
+        the drift gate compares that stamp with HEAD. It is not a place to edit — a page
+        whose generated marker is gone is refused rather than overwritten.
+        """
+        cfg = self.cfg.get("mirror") or {}
+        if not cfg.get("enabled"):
+            return ["mirror: disabled in this project's config"]
+
+        files: list[Path] = []
+        for source in cfg.get("sources") or []:
+            q = self.root / source
+            if q.is_file():
+                files.append(q)
+            elif q.is_dir():
+                files += sorted(f for f in q.rglob("*.md") if f.is_file())
+        files = sorted(set(files))
+
+        out: list[str] = []
+        truncated = 0
+        if len(files) > limit:
+            truncated = len(files) - limit
+            files = files[:limit]
+
+        sha = head_sha()
+        for f in files:
+            rel = f.relative_to(self.root)
+            title = f"90 Mirror — {rel}"
+            body = (f"{GENERATED_MARKER} source={repo_name()}:{rel}@{sha} at={now_iso()} "
+                    "— a rendering of git, edit the source there -->\n\n" + f.read_text())
+            out.append(self.put_generated(title, body))
+
+        # A silent cap reads as "everything is mirrored" when it is not.
+        if truncated:
+            out.append(f"NOTE: {truncated} further file(s) not mirrored — raise the limit "
+                       "or narrow mirror.sources; they are absent, not up to date")
+        return out
+
+    def mirror_drift(self) -> list[str]:
+        """Mirror pages whose stamped commit is not this repository's HEAD.
+
+        The docstring beside `mirror` claimed this gate existed before any code did —
+        prose asserting a check that was never written, which is worse than silence
+        because a reader stops looking.
+        """
+        cfg = self.cfg.get("mirror") or {}
+        if not cfg.get("enabled"):
+            return []
+        sha = head_sha()
+        out: list[str] = []
+        for oid in self.adapter.log_shards("90 Mirror — "):
+            text = self.adapter.doc_get(oid)
+            m = re.search(r"source=[^@]+@(\S+)", text.splitlines()[0] if text else "")
+            if m and m.group(1) != sha:
+                out.append(f"mirror page stamped {m.group(1)}, HEAD is {sha} — "
+                           "regenerate with `board --mirror`")
+        return out
+
+    def setup_path(self) -> Path:
+        configured = self.cfg.get("setupFile")
+        if configured:
+            return self.root / configured
+        return self.root / ("docs/AGENT_SYNC.md" if (self.root / "docs").is_dir()
+                            else "AGENT_SYNC.md")
+
+    def repo_page(self) -> str:
+        """Findings only this checkout can produce — registers it owns, its own history."""
+        res_events, _ = self.events("reservations")
+        lines = [
+            f"{GENERATED_MARKER} source={repo_name()}@{head_sha()} at={now_iso()} "
+            "— edit in git, not here -->",
+            "",
+            f"# {repo_name()}",
+            "",
+            f"- registers declared here: "
+            f"{', '.join(sorted(self.cfg.get('idRegisters') or {})) or 'none — they live in the parent repository'}",
+            f"- guarded files: {len(self.cfg.get('guardedFiles') or [])}",
+        ]
+        leaks = self._leaks(res_events)
+        lines += ["", "## Reserved ids not found in git", ""]
+        lines += ([f"- `{r}-{v:04d}` reserved by {run}" for r, v, run in leaks]
+                  or ["- none"])
+
+        findings = self.reconcile()
+        lines += ["", "## Intent vs as-built", ""]
+        lines += ([f"- **{f['kind']}** — {f['detail']}" for f in findings] or
+                  ["- no mechanical divergence found"])
+        for n in getattr(self, "backlog", []):
+            lines.append(f"- {n}")
+        return "\n".join(lines) + "\n"
+
+    def _leaks(self, events: list[dict[str, str]]) -> list[tuple[str, int, str]]:
+        out = []
+        for reg, spec in (self.cfg.get("idRegisters") or {}).items():
+            _b, _f, assignments = resolve_reservations(events, reg)
+            path = self.root / spec["file"]
+            text = path.read_text() if path.exists() else ""
+            for run, value in assignments:
+                if f"{reg}-{value:04d}" not in text:
+                    out.append((reg, value, run))
+        return out
+
+    def put_generated(self, path: str, text: str) -> str:
+        oid = self.adapter.tree_ensure(path)
+        current = self.adapter.doc_get(oid)
+        if current.strip() and not current.lstrip().startswith(GENERATED_MARKER):
+            return (f"REFUSED: '{path}' was not written by agent-sync "
+                    "(no generated marker on line 1). Someone took it over; "
+                    "reporting instead of overwriting.")
+        self.adapter.doc_put(oid, text)
+        return f"wrote '{path}'"
+
+
+# --------------------------------------------------------------------------- init
+
+ENV_TEMPLATE = """# agent-sync — identity lives here, shape lives in .claude/agent-sync.json
+# This file is gitignored on purpose. Never commit it, never paste its contents.
+AGENT_SYNC_BACKEND={backend}
+{extra}"""
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = project_root()
+    os.chdir(root)
+    cfg_path = root / CONFIG_PATH
+    backend = args.backend
+
+    if backend == "outline" and not args.url:
+        raise Fail("--url is required for the outline backend "
+                   "(the instance URL, e.g. https://wiki.example.com)")
+
+    if cfg_path.exists() and not args.force:
+        print(f"• {CONFIG_PATH} already exists — left untouched (use --force to replace)")
+    else:
+        cfg_path.parent.mkdir(parents=True, exist_ok=True)
+        cfg_path.write_text(json.dumps(default_config(backend), indent=2) + "\n")
+        print(f"✓ wrote {CONFIG_PATH}")
+
+    extra = ""
+    if backend == "outline":
+        extra = (f"AGENT_SYNC_OUTLINE_URL={args.url}\n"
+                 "AGENT_SYNC_OUTLINE_TOKEN=\n"
+                 "AGENT_SYNC_OUTLINE_COLLECTION=\n")
+    env_path = root / ENV_FILE
+    if env_path.exists() and not args.force:
+        print(f"• {ENV_FILE} already exists — left untouched")
+    else:
+        env_path.write_text(ENV_TEMPLATE.format(backend=backend, extra=extra))
+        os.chmod(env_path, stat.S_IRUSR | stat.S_IWUSR)
+        print(f"✓ wrote {ENV_FILE} (mode 600)")
+
+    ensure_gitignored(root, str(ENV_FILE))
+    ensure_gitignored(root, f"{STATE_DIR}/")
+
+    print()
+    if backend == "outline":
+        print("NEXT — two things only you can do:")
+        print(f"  1. Create an API token in your Outline instance at {args.url}")
+        print("     (Settings → API and access), then put it in this line of "
+              f"{ENV_FILE}:")
+        print("       AGENT_SYNC_OUTLINE_TOKEN=<paste it here>")
+        print(f"  2. Load the file into your shell before running agents:")
+        print(f"       set -a && . ./{ENV_FILE} && set +a")
+        print()
+        print("  Then run `status` again — it will create the cloud layout and print "
+              "the collection id to paste into AGENT_SYNC_OUTLINE_COLLECTION.")
+        print()
+        print("  The token is yours alone: do not paste it into a chat, a commit, "
+              "or a command line.")
+    else:
+        print("Backend 'fs' needs no credentials. It is DEGRADED: it is not the lease")
+        print("authority, and every run is recorded as `ungated`. See references/backend-fs.md.")
+    return 0
+
+
+def default_config(backend: str) -> dict[str, Any]:
+    return {
+        "backend": backend,
+        "leaseTtlSeconds": DEFAULT_TTL,
+        "renewIntervalSeconds": DEFAULT_RENEW,
+        "gated": True,
+        "idRegisters": {},
+        "guardedFiles": [],
+        "claimTags": {},
+        "gates": [],
+        "mirror": {"enabled": False, "sources": []},
+    }
+
+
+def ensure_gitignored(root: Path, entry: str) -> None:
+    gi = root / ".gitignore"
+    lines = gi.read_text().splitlines() if gi.exists() else []
+    if any(line.strip() == entry for line in lines):
+        print(f"• .gitignore already ignores {entry}")
+        return
+    header = "# agent-sync"
+    with open(gi, "a") as fh:
+        if lines and lines[-1].strip():
+            fh.write("\n")
+        if header not in lines:
+            fh.write(f"{header}\n")
+        fh.write(f"{entry}\n")
+    print(f"✓ added {entry} to .gitignore")
+
+
+# --------------------------------------------------------------------------- status
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    root = project_root()
+    os.chdir(root)
+    load_env_file(root)
+    print(f"agent-sync {VERSION} — {repo_name()}@{head_sha()}")
+
+    if not (root / CONFIG_PATH).exists():
+        print("\n✗ not initialised.")
+        print("\nNEXT: run init. It asks nothing it can guess and writes nothing secret.")
+        print("  agent_sync.py init --backend outline --url <instance-url>")
+        print("  agent_sync.py init --backend fs        # local, degraded, no credentials")
+        return 1
+
+    s = Sync()
+    ad = s.adapter
+    print(f"  backend        : {ad.name}")
+    print(f"  lease authority: {'yes' if ad.is_lease_authority else 'NO — degraded'}")
+    print(f"  runs recorded  : {'gated' if s.gated else 'UNGATED'}")
+    print(f"  run id         : {s.rid}")
+
+    if not ad.is_lease_authority:
+        print("\n⚠ This backend cannot hold leases exclusively, so nothing here is")
+        print("  enforced. Do not describe this project as protected.")
+
+    if ad.name == "outline" and isinstance(ad, OutlineAdapter) and not ad.collection:
+        print("\n✗ AGENT_SYNC_OUTLINE_COLLECTION is empty.")
+        print("\nNEXT: create the container, then paste the id into "
+              f"{ENV_FILE}:")
+        print("  agent_sync.py bootstrap")
+        return 1
+
+    try:
+        held = s.held()
+    except Fail as exc:
+        print(f"\n✗ {exc}")
+        return 1
+    print(f"  leases held    : {', '.join(held) if held else 'none'}")
+
+    # Who else is in here, and what landed while this run was away. Without this a
+    # lease only tells an agent it is blocked, never who by or on what.
+    try:
+        act = s.activity()
+    except Fail as exc:
+        print(f"\n⚠ could not read the coordination plane: {exc}")
+        act = {"others": {}, "signals": [], "new_signals": []}
+
+    if act["others"]:
+        print("\n  Other runs working this project right now:")
+        for key, h in sorted(act["others"].items()):
+            where = h.get("repo") or "unknown repo"
+            mine = " ← this repo" if where == repo_name() else ""
+            print(f"    · {h['run']} holds {key}  in {where}{mine}")
+        print("    Do not take these on. If one looks abandoned, its lease expires on its own.")
+    else:
+        print("  other runs     : none holding anything")
+
+    if act["new_signals"]:
+        print(f"\n  New since you last looked ({len(act['new_signals'])}):")
+        for ev in act["new_signals"][-6:]:
+            print(f"    · {ev['key']} → {ev.get('state', '?')} "
+                  f"(by {ev['run']}, {ev.get('repo', 'unknown repo')})")
+        print("    A dependency that moved may unblock — or invalidate — what you were about to do.")
+    elif act["signals"]:
+        print(f"  signals        : {len(act['signals'])} recent, nothing new since you last looked")
+
+    claim_issues = s.claim_divergence()
+    if claim_issues:
+        print("\n  Claim tags not written through:")
+        for c in claim_issues:
+            print(f"    ! {c}")
+
+    try:
+        drift = s.mirror_drift()
+    except Fail:
+        drift = []
+    if drift:
+        print(f"\n  Mirror drift ({len(drift)} page(s)): regenerate with `board --mirror`")
+
+    if not pipeline_installed():
+        print("\n✗ task-pipeline is not installed. agent-sync binds to its stages and")
+        print("  will not improvise a substitute flow.")
+        print("\nNEXT:\n  npx sshlg-skills install")
+        return 1
+
+    print("\nNEXT: acquire a lease before you touch a guarded file —")
+    print("  agent_sync.py acquire <TASK-ID>")
+    return 0
+
+
+def pipeline_installed() -> bool:
+    home = Path.home()
+    if list(home.glob(".claude/plugins/cache/task-pipeline/**/skills/task-pipeline/SKILL.md")):
+        return True
+    if (home / ".agents/skills/task-pipeline/SKILL.md").exists():
+        return True
+    return (home / ".claude/skills/task-pipeline/SKILL.md").exists()
+
+
+def cmd_bootstrap(_args: argparse.Namespace) -> int:
+    load_env_file(project_root())
+    ad = OutlineAdapter()
+    if not ad.configured():
+        raise Fail("set AGENT_SYNC_OUTLINE_URL and AGENT_SYNC_OUTLINE_TOKEN first")
+    if ad.collection:
+        print(f"collection already set: {ad.collection}")
+        return 0
+    name = f"agent-sync — {repo_name()}"
+    data = ad._call("collections.create", {"name": name, "description":
+                                           "Coordination plane for agent-sync. Generated pages "
+                                           "are stamped; edit sources in git."})
+    print(f"✓ created collection '{name}'")
+    print(f"\nNEXT: put this in {ENV_FILE}:")
+    print(f"  AGENT_SYNC_OUTLINE_COLLECTION={data['id']}")
+    return 0
+
+
+# --------------------------------------------------------------------------- cli
+
+def cmd_acquire(args: argparse.Namespace) -> int:
+    s = Sync()
+    won, holder = s.acquire(args.key)
+    if won:
+        print(f"won {args.key} (run {s.rid}, ttl {s.ttl}s)")
+        if s.lease_is_cross_machine:
+            print("  exclusive across machines — the remote's non-fast-forward rule is a "
+                  "real compare-and-swap")
+        else:
+            print("  exclusive between agents on THIS machine; advisory across machines. "
+                  "Set `leaseBackend: \"git\"` for cross-machine exclusion.")
+        if not s.gated:
+            print("⚠ ungated backend — this lease is advisory, not enforced")
+        print("Remember: release it on every path, including failure.")
+        return 0
+    print(f"lost {args.key} — held by {holder or 'another run'}")
+    return 1
+
+
+def cmd_renew(args: argparse.Namespace) -> int:
+    Sync().renew(args.key)
+    return 0
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    Sync().release(args.key)
+    print(f"released {args.key}")
+    return 0
+
+
+def cmd_reserve(args: argparse.Namespace) -> int:
+    value = Sync().reserve(args.register)
+    print(f"{args.register}-{value:04d}")
+    return 0
+
+
+def cmd_release_id(args: argparse.Namespace) -> int:
+    Sync().release_id(args.register, args.value)
+    print(f"released {args.register}-{args.value}")
+    return 0
+
+
+def cmd_journal(args: argparse.Namespace) -> int:
+    Sync().journal(" ".join(args.text))
+    return 0
+
+
+def cmd_signal(args: argparse.Namespace) -> int:
+    Sync().signal(args.dep, args.state)
+    print(f"{args.dep} → {args.state}")
+    return 0
+
+
+def cmd_guard(args: argparse.Namespace) -> int:
+    """Exit 0 = allowed, 2 = denied. Any other code is non-blocking in Claude Code,
+    so internal failures must also exit 2 rather than fail open."""
+    try:
+        allowed, reason = Sync().guard(args.path)
+    except Fail as exc:
+        print(f"agent-sync guard: {exc}", file=sys.stderr)
+        return 2
+    if allowed:
+        print(reason)
+        return 0
+    print(f"agent-sync: {reason}", file=sys.stderr)
+    return 2
+
+
+def cmd_board(args: argparse.Namespace) -> int:
+    s = Sync()
+    results = [s.put_generated("10 Board", s.board()),
+               s.put_generated(f"12 Repo — {repo_name()}", s.repo_page())]
+    if getattr(args, "mirror", False):
+        results += s.mirror()
+    for r in results:
+        print(r)
+    # A refusal must be visible to a gate, not just to a reader.
+    return 1 if any(r.startswith("REFUSED") for r in results) else 0
+
+
+def cmd_record(args: argparse.Namespace) -> int:
+    Sync().record(" ".join(args.text), decision=args.decision or "", files=args.files or "")
+    print("recorded")
+    return 0
+
+
+def cmd_reconcile(args: argparse.Namespace) -> int:
+    """Mechanical divergence only. The semantic read is the agent's job, and the
+    output says so rather than implying the check was complete."""
+    s = Sync()
+    if getattr(args, "set_baseline", False):
+        stamped = s.set_baseline()
+        for reg, top in stamped.items():
+            print(f"baseline {reg} = {reg}-{top:04d} — ids after this must carry an as-built record")
+        return 0
+    findings = s.reconcile()
+    print("Intent (git) vs as-built (coordination plane)\n")
+    if not findings:
+        print("  no mechanical divergence found")
+    for f in findings:
+        print(f"  ! {f['kind']}\n      {f['detail']}\n      → {f['means']}")
+    for n in getattr(s, "backlog", []):
+        print(f"  · {n}")
+    print("\nThis compares ids, commits and presence. It does NOT judge whether the")
+    print("built thing matches what the document describes — read both and decide.")
+    print("Before starting: resolve divergence or record why it stands.")
+    print("After finishing: update BOTH sides, then run this again.")
+    return 1 if findings else 0
+
+
+REGISTER_HINTS = [
+    (r"\*\*Next free ID:\*\*\s*`([A-Z]{2,4})-(\d+)`", "explicit next-free-id line"),
+    (r"^#{2,4}\s+([A-Z]{2,4})-\d+\s+—", "id-prefixed headings"),
+]
+
+DOC_NAMES = ("DECISIONS", "OPEN_QUESTIONS", "ROADMAP", "WORKSTREAMS", "DEPENDENCIES",
+             "BUILD_ORDER", "INDEX", "ADR", "TESTING")
+
+
+def cmd_adopt(_args: argparse.Namespace) -> int:
+    """Inspect an existing project and PROPOSE a configuration.
+
+    Adoption is where a coordination tool most easily starts lying: guess a register
+    wrong and every later check is confidently about the wrong file. So this reads the
+    repository, shows what it found and what it could not decide, and prints a config
+    for a human to approve. It writes nothing.
+    """
+    root = project_root()
+    os.chdir(root)
+    print(f"agent-sync {VERSION} — adopting {repo_name()}\n")
+
+    docs_dir = "docs" if (root / "docs").is_dir() else ""
+    candidates: list[Path] = []
+    for pattern in ("*.md", "docs/*.md", "docs/**/*.md", "doc/*.md"):
+        candidates += [q for q in root.glob(pattern) if q.is_file()]
+    candidates = sorted({q for q in candidates if ".git" not in q.parts})[:400]
+
+    registers: dict[str, dict[str, str]] = {}
+    guarded: list[str] = []
+    notes: list[str] = []
+
+    for q in candidates:
+        rel = str(q.relative_to(root))
+        try:
+            text = q.read_text(errors="ignore")
+        except OSError:
+            continue
+        m = re.search(REGISTER_HINTS[0][0], text)
+        if m:
+            registers[m.group(1)] = {
+                "file": rel,
+                "nextFreeIdPattern": r"\*\*Next free ID:\*\* `" + m.group(1) + r"-(\d{" + str(len(m.group(2))) + r"})`",
+            }
+            guarded.append(rel)
+            continue
+        if any(n in q.stem.upper() for n in DOC_NAMES):
+            guarded.append(rel)
+            ids = set(re.findall(r"\b([A-Z]{2,4})-\d{3,4}\b", text))
+            if ids:
+                notes.append(f"{rel}: carries ids {', '.join(sorted(ids)[:4])} but no "
+                             "\"Next free ID\" line — allocation cannot be reserved safely "
+                             "until one exists, or a pattern is written by hand")
+
+    gates = []
+    for cmd, probe in (("bash scripts/check-docs.sh", "scripts/check-docs.sh"),
+                       ("python3 docs/ux/lint.py --strict", "docs/ux/lint.py"),
+                       ("npm test", "package.json"),
+                       ("pytest -q", "pyproject.toml")):
+        if (root / probe).exists():
+            gates.append(cmd)
+
+    sub = git("rev-parse", "--show-superproject-working-tree")
+    if sub:
+        notes.append(f"this is a submodule of {Path(sub).name} — declare ONLY this "
+                     "repository's registers; decisions belong to the parent")
+        registers = {}
+
+    print("Found:")
+    print(f"  documents scanned : {len(candidates)}")
+    print(f"  id registers      : {', '.join(registers) or 'none detected'}")
+    print(f"  registry files    : {len(guarded)}")
+    print(f"  gates             : {', '.join(gates) or 'none detected'}")
+    print(f"  setup snapshot    : {'docs/AGENT_SYNC.md' if docs_dir else 'AGENT_SYNC.md'}")
+    if notes:
+        print("\nNeeds a human decision:")
+        for n in notes:
+            print(f"  ! {n}")
+
+    proposed = default_config("outline")
+    proposed["idRegisters"] = registers
+    proposed["guardedFiles"] = sorted(set(guarded))
+    proposed["gates"] = gates
+    proposed["mirror"] = {"enabled": bool(docs_dir), "sources": [docs_dir] if docs_dir else []}
+
+    print("\nProposed .claude/agent-sync.json — review every line, then write it:\n")
+    print(json.dumps(proposed, indent=2))
+    print("\nNothing was written. Confirm the registers and guarded files with the operator")
+    print("first: a register pointed at the wrong file makes every later check confidently")
+    print("wrong. Then run `init`, paste this config, `reconcile --set-baseline`, and `setup`.")
+    return 0
+
+
+DECISIONS_SEED = """# Decisions
+
+Every settled decision about this project, append-only. A decision is any answer that
+shapes the product, architecture, scope, security, data or process — recorded here so it
+is never lost to a chat log.
+
+**Reserve an id before you write one.** Reading the line below is not reserving it: two
+agents read the same number and both use it. Run `agent-sync reserve DEC`.
+
+**Next free ID:** `DEC-0001`
+
+---
+
+## How to write one
+
+```
+### DEC-0001 — a title that states the decision, not the topic
+- **Date:** YYYY-MM-DD · **Status:** Accepted
+- **Context:** what forced the decision, with evidence
+- **Decision:** what we do now, in numbered clauses
+- **Consequences / affects:** every document this changes — each MUST then cite this id
+- **Source:** where this came from
+```
+
+**Never edit a decision to change it.** Add a new one that names what it supersedes, and
+annotate the old entry's status line. The body of the old entry stays as history.
+
+---
+"""
+
+AGENTS_SEED = """# AGENTS.md — working protocol
+
+**Read [`{snapshot}`]({snapshot}) first.** It is generated from the live configuration and
+states how documentation and coordination work here: which registers exist, which files
+need a lease, which gates run, what is written where, and what is never deleted.
+
+## Before you write anything
+
+Several agents may work this repository at once.
+
+1. `agent-sync status` — who else is working, and what changed while you were away.
+2. `agent-sync reconcile` — the git documents say how it *should* be, the as-built record
+   says how it *is*. Resolve every divergence **before** writing code.
+3. `agent-sync acquire <TASK-ID>` — the guarded registers refuse an unleased write.
+4. Reserve any new id with `agent-sync reserve <REGISTER>` before writing it.
+
+## When you finish
+
+1. `agent-sync record` — what you actually built, with the decision id and the files.
+2. Update the git documents in the **same** change.
+3. `agent-sync reconcile` again, then `agent-sync board`.
+4. `agent-sync release <TASK-ID>` — on every path, including failure.
+
+## The one rule that matters most
+
+**No decision lives only in chat.** Record it in the decision register, propagate it to
+every document it affects, and commit referencing the id.
+"""
+
+
+def cmd_scaffold(args: argparse.Namespace) -> int:
+    """Create the documentation architecture a project needs to be coordinated.
+
+    Only what is absent, never a line over anything that exists. A tool that rewrites a
+    project's own conventions on adoption is worse than one that does nothing, so this
+    seeds the minimum — a register with an allocation line, and an agent protocol that
+    points at the generated snapshot — and leaves every existing file alone.
+    """
+    root = project_root()
+    os.chdir(root)
+    docs = root / "docs" if (root / "docs").is_dir() or args.docs_dir else root
+    snapshot = "docs/AGENT_SYNC.md" if docs != root else "AGENT_SYNC.md"
+
+    created, skipped = [], []
+
+    def seed(path: Path, body: str) -> None:
+        if path.exists():
+            skipped.append(str(path.relative_to(root)))
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body)
+        created.append(str(path.relative_to(root)))
+
+    seed(docs / "DECISIONS.md", DECISIONS_SEED)
+    seed(root / "AGENTS.md", AGENTS_SEED.format(snapshot=snapshot))
+
+    for c in created:
+        print(f"  + {c}")
+    for s in skipped:
+        print(f"  · {s} already exists — untouched")
+
+    print()
+    if created:
+        print("Scaffolded. Now: `adopt` to see the config it implies, `init` to write it,")
+        print("`reconcile --set-baseline` once, `setup` to generate the snapshot, `check`.")
+    else:
+        print("Nothing to scaffold — this project already has the files. Run `adopt`.")
+    return 0
+
+
+def cmd_check(_args: argparse.Namespace) -> int:
+    """Validate the whole setup, end to end, and refuse to call a broken one healthy.
+
+    Every item here failed for real at some point in this tool's own adoption. A glob
+    that matches nothing, a register pattern that matches nothing, a gate command that
+    does not exist, a snapshot nobody links — each looks like a working install and
+    protects nothing.
+    """
+    root = project_root()
+    os.chdir(root)
+    load_env_file(root)
+    problems: list[str] = []
+    warn: list[str] = []
+    ok: list[str] = []
+
+    cfg_path = root / CONFIG_PATH
+    if not cfg_path.exists():
+        print("✗ not initialised — run `adopt`, then `init`")
+        return 1
+    try:
+        cfg = json.loads(cfg_path.read_text())
+    except json.JSONDecodeError as exc:
+        print(f"✗ {CONFIG_PATH} is not valid JSON: {exc}")
+        return 1
+    ok.append(f"config parses ({CONFIG_PATH})")
+
+    if cfg.get("backend") not in ("outline", "fs"):
+        problems.append(f"backend '{cfg.get('backend')}' is not a known adapter")
+    unknown = set(cfg) - {"$schema", "backend", "leaseTtlSeconds", "renewIntervalSeconds",
+                          "gated", "idRegisters", "guardedFiles", "claimTags", "gates",
+                          "mirror", "setupFile", "leaseBackend", "leaseRemote",
+                          "settleSeconds"}
+    for k in sorted(unknown):
+        problems.append(f"config key '{k}' is not in the schema — it will be ignored")
+
+    # Registers must exist AND their allocation pattern must actually match.
+    regs = cfg.get("idRegisters") or {}
+    for reg, spec in sorted(regs.items()):
+        f = root / spec.get("file", "")
+        if not f.exists():
+            problems.append(f"register {reg}: file '{spec.get('file')}' does not exist")
+            continue
+        text = f.read_text()
+        try:
+            m = re.search(spec.get("nextFreeIdPattern", ""), text)
+        except re.error as exc:
+            problems.append(f"register {reg}: nextFreeIdPattern is not valid regex ({exc})")
+            continue
+        if not m:
+            problems.append(f"register {reg}: nextFreeIdPattern matches nothing in "
+                            f"{spec['file']} — ids cannot be reserved, only guessed")
+        else:
+            ok.append(f"register {reg} allocates from {spec['file']} ({reg}-{m.group(1)})")
+
+    # A guard glob that matches nothing protects nothing.
+    for pattern in (cfg.get("guardedFiles") or []):
+        hits = [q for q in root.glob(pattern) if q.is_file()]
+        if not hits:
+            problems.append(f"guarded pattern '{pattern}' matches no file — it guards nothing")
+    if cfg.get("guardedFiles"):
+        ok.append(f"{len(cfg['guardedFiles'])} guarded pattern(s) declared")
+    else:
+        warn.append("no guarded files — nothing requires a lease in this repository")
+
+    for pattern, spec in (cfg.get("claimTags") or {}).items():
+        files = [q for q in root.glob(pattern) if q.is_file()]
+        if not files:
+            problems.append(f"claimTags pattern '{pattern}' matches no file")
+            continue
+        if spec.get("mode") != "cell":
+            problems.append(f"claimTags '{pattern}': mode must be 'cell'")
+            continue
+        if "cell" not in spec:
+            problems.append(f"claimTags '{pattern}': no `cell` index — nothing to write")
+        if "{holder}" not in (spec.get("held") or ""):
+            problems.append(f"claimTags '{pattern}': `held` must contain {{holder}}, "
+                            "or the claim names nobody")
+    if cfg.get("claimTags"):
+        ok.append(f"{len(cfg['claimTags'])} claim-tag mapping(s) declared")
+
+    mode = cfg.get("leaseBackend") or "local"
+    if mode not in ("local", "git"):
+        problems.append(f"leaseBackend '{mode}' is not a known mode")
+    elif mode == "git":
+        remote = cfg.get("leaseRemote") or "origin"
+        if not git("remote", "get-url", remote):
+            problems.append(f"leaseBackend is 'git' but remote '{remote}' does not exist — "
+                            "the lease cannot be decided at all")
+        else:
+            ok.append(f"lease decided by git refs on '{remote}' — exclusive across machines")
+    else:
+        warn.append("lease is a local file lock: exclusive on this machine, advisory "
+                    "across machines. Set leaseBackend to 'git' if agents run on more than one")
+
+    for cmd in (cfg.get("gates") or []):
+        exe = cmd.split()[0]
+        target = cmd.split()[1] if len(cmd.split()) > 1 else ""
+        if target and not target.startswith("-") and "/" in target and not (root / target).exists():
+            problems.append(f"gate '{cmd}': {target} does not exist")
+        elif not shutil.which(exe):
+            warn.append(f"gate '{cmd}': {exe} is not on PATH here")
+    if cfg.get("gates"):
+        ok.append(f"{len(cfg['gates'])} gate command(s) declared")
+
+    mirror = cfg.get("mirror") or {}
+    if mirror.get("enabled"):
+        for src in mirror.get("sources") or []:
+            if not (root / src).exists():
+                problems.append(f"mirror source '{src}' does not exist")
+        if not mirror.get("sources"):
+            problems.append("mirror is enabled with no sources — it renders nothing")
+
+    # Identity and reachability.
+    env = find_env_file(root)
+    if cfg.get("backend") == "outline":
+        if env is None:
+            problems.append(f"no {ENV_FILE} found here or in any parent — the backend "
+                            "cannot be reached, and every run silently degrades")
+        else:
+            ok.append(f"credentials file found at {env}")
+            missing = [k for k in ("AGENT_SYNC_OUTLINE_URL", "AGENT_SYNC_OUTLINE_TOKEN")
+                       if not os.environ.get(k)]
+            if missing:
+                problems.append(f"{', '.join(missing)} is empty — runs will degrade to `fs`")
+            else:
+                try:
+                    OutlineAdapter().resolve_collection()
+                    ok.append("knowledge base reachable and the collection resolves")
+                except Fail as exc:
+                    problems.append(f"knowledge base unreachable: {exc}")
+
+    # Ignore rules — a committed token is the one unrecoverable mistake here.
+    gi = (root / ".gitignore").read_text() if (root / ".gitignore").exists() else ""
+    for entry in (str(ENV_FILE), f"{STATE_DIR}/"):
+        if entry not in gi:
+            problems.append(f".gitignore does not cover '{entry}'")
+    tracked = git("ls-files", str(ENV_FILE))
+    if tracked:
+        problems.append(f"{ENV_FILE} IS TRACKED BY GIT — it holds a token; remove it now")
+
+    # The snapshot, and whether anything points at it.
+    snap = root / (cfg.get("setupFile") or
+                   ("docs/AGENT_SYNC.md" if (root / "docs").is_dir() else "AGENT_SYNC.md"))
+    if not snap.exists():
+        problems.append(f"no setup snapshot at {snap.relative_to(root)} — run `setup`")
+    else:
+        head = snap.read_text().splitlines()[0] if snap.read_text() else ""
+        if GENERATED_MARKER not in head:
+            problems.append(f"{snap.relative_to(root)} lost its generated marker — "
+                            "someone hand-edited it; regenerate or keep it out of the way")
+        else:
+            # Stale means "the configuration moved on". Comparing commits was wrong at
+            # both boundaries: a snapshot is generated before the commit that carries it,
+            # and the config is often added in that same commit. A content hash is exact.
+            stamped = re.search(r"cfg=(\w+)", head)
+            actual = hashlib.sha256((root / CONFIG_PATH).read_bytes()).hexdigest()[:12]
+            if not stamped:
+                warn.append("snapshot predates configuration stamping — regenerate with `setup`")
+            elif stamped.group(1) != actual:
+                problems.append("the configuration changed since the snapshot was "
+                                "generated — regenerate with `setup`")
+            else:
+                ok.append("setup snapshot present and describes the current configuration")
+        linked = [f for f in ("AGENTS.md", "CLAUDE.md", "README.md", "CONTRIBUTING.md")
+                  if (root / f).exists() and snap.name in (root / f).read_text()]
+        if linked:
+            ok.append(f"snapshot linked from {', '.join(linked)}")
+        else:
+            problems.append("no agent instruction file links the snapshot — agents will "
+                            "not find it, and will infer the pipeline instead")
+
+    # Baselines: without one, reconcile cannot separate history from new work.
+    if regs:
+        try:
+            s = Sync()
+            ev, _ = s.events("asbuilt")
+            based = {e["key"] for e in ev if e["op"] == "baseline"}
+            for reg in regs:
+                if reg not in based:
+                    warn.append(f"register {reg} has no as-built baseline — "
+                                "run `reconcile --set-baseline` once")
+        except Fail:
+            pass
+
+    for line in ok:
+        print(f"  ✓ {line}")
+    for line in warn:
+        print(f"  ! {line}")
+    for line in problems:
+        print(f"  ✗ {line}")
+    print()
+    if problems:
+        print(f"{len(problems)} problem(s) — this setup is NOT healthy. Fix them before "
+              "telling anyone the project is coordinated.")
+        return 1
+    print(f"setup healthy ({len(ok)} checks passed"
+          + (f", {len(warn)} warning(s)" if warn else "") + ")")
+    return 0
+
+
+def cmd_setup(_args: argparse.Namespace) -> int:
+    s = Sync()
+    path = s.setup_path()
+    if path.exists():
+        current = path.read_text()
+        if current.strip() and not current.lstrip().startswith(GENERATED_MARKER):
+            print(f"REFUSED: {path} exists and was not generated by agent-sync — "
+                  "reporting instead of overwriting", file=sys.stderr)
+            return 1
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(s.setup_snapshot())
+    print(f"wrote {path.relative_to(s.root)}")
+    print("Commit it, and link it from the project's agent instructions so every agent "
+          "reads the same description of the pipeline before touching it.")
+    return 0
+
+
+def cmd_whoami(_args: argparse.Namespace) -> int:
+    s = Sync()
+    print(f"run {s.rid} · backend {s.adapter.name} · "
+          f"{'gated' if s.gated else 'ungated'}")
+    print(f"holds: {', '.join(s.held()) or 'nothing'}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agent_sync.py", description=__doc__.splitlines()[0])
+    p.add_argument("--version", action="version", version=VERSION)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    i = sub.add_parser("init", help="ask where to store, write config and env file")
+    i.add_argument("--backend", required=True, choices=["outline", "fs"])
+    i.add_argument("--url", help="instance URL (required for outline)")
+    i.add_argument("--force", action="store_true")
+    i.set_defaults(fn=cmd_init)
+
+    sub.add_parser("status", help="inspect, repair, report, one next action").set_defaults(fn=cmd_status)
+    sub.add_parser("bootstrap", help="create the cloud container").set_defaults(fn=cmd_bootstrap)
+    sub.add_parser("whoami", help="this run and its leases").set_defaults(fn=cmd_whoami)
+    sub.add_parser("setup", help="write the generated snapshot of how this project is wired").set_defaults(fn=cmd_setup)
+    sub.add_parser("adopt", help="inspect an existing project and propose a config (writes nothing)").set_defaults(fn=cmd_adopt)
+    sub.add_parser("check", help="validate the whole setup; non-zero if it is not healthy").set_defaults(fn=cmd_check)
+    sc = sub.add_parser("scaffold", help="create the missing documentation architecture (never overwrites)")
+    sc.add_argument("--docs-dir", action="store_true", help="put the register under docs/ even if it does not exist yet")
+    sc.set_defaults(fn=cmd_scaffold)
+    bd = sub.add_parser("board", help="regenerate the read-only board")
+    bd.add_argument("--mirror", action="store_true",
+                    help="also render the configured git documents into the plane")
+    bd.set_defaults(fn=cmd_board)
+
+    for name, fn, arg in (("acquire", cmd_acquire, "key"), ("release", cmd_release, "key")):
+        q = sub.add_parser(name)
+        q.add_argument(arg)
+        q.set_defaults(fn=fn)
+
+    r = sub.add_parser("renew")
+    r.add_argument("key", nargs="?")
+    r.set_defaults(fn=cmd_renew)
+
+    rv = sub.add_parser("reserve", help="reserve the next id in a register")
+    rv.add_argument("register")
+    rv.set_defaults(fn=cmd_reserve)
+
+    ri = sub.add_parser("release-id", help="return an id you did not write to git")
+    ri.add_argument("register")
+    ri.add_argument("value")
+    ri.set_defaults(fn=cmd_release_id)
+
+    rec = sub.add_parser("record", help="append what was ACTUALLY built")
+    rec.add_argument("text", nargs="+")
+    rec.add_argument("--decision", help="the id it implements, e.g. DEC-0216")
+    rec.add_argument("--files", help="comma-separated paths actually changed")
+    rec.set_defaults(fn=cmd_record)
+
+    rc = sub.add_parser("reconcile", help="intent (git) vs as-built (cloud)")
+    rc.add_argument("--set-baseline", action="store_true",
+                    help="stamp today's ids as the pre-adoption backlog, once")
+    rc.set_defaults(fn=cmd_reconcile)
+
+    j = sub.add_parser("journal")
+    j.add_argument("text", nargs="+")
+    j.set_defaults(fn=cmd_journal)
+
+    sg = sub.add_parser("signal")
+    sg.add_argument("dep")
+    sg.add_argument("state")
+    sg.set_defaults(fn=cmd_signal)
+
+    g = sub.add_parser("guard", help="may this run write that path? exit 2 = no")
+    g.add_argument("path")
+    g.set_defaults(fn=cmd_guard)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.fn(args))
+    except Fail as exc:
+        print(f"agent-sync: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())