@ssheleg/agent-sync 1.13.0 → 1.15.0

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

@@ -33,7 +33,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.13.0"
+VERSION = "1.15.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -113,12 +113,24 @@ def now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def parse_iso(ts: str) -> float:
+def parse_iso_or_none(ts: str) -> float | None:
+    """The instant this string names, or None when it names none.
+
+    `parse_iso` folds an unreadable timestamp into 0.0, and every expiry test then reads
+    that as "expired in 1970". For exclusion that is the right answer — a lock whose clock
+    cannot be read must not go on holding a key. For residue it is the wrong one: *spent*
+    and *unreadable* are different verdicts, and only the first may be cleared.
+    """
     try:
         return datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(
             tzinfo=timezone.utc).timestamp()
-    except ValueError:
-        return 0.0
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_iso(ts: str) -> float:
+    at = parse_iso_or_none(ts)
+    return 0.0 if at is None else at
 
 
 def git(*args: str, cwd: Path | None = None) -> str:
@@ -827,6 +839,157 @@ def resolve_holder(events: list[dict[str, str]], key: str, at: float) -> str | N
     return str(h["run"]) if h else None
 
 
+# What a lock file turns out to be once the TTL has been applied to it. `live` is not
+# residue; the other three are, and they are not interchangeable — the first may be
+# cleared, the other two may only be reported.
+LIVE = "live"
+REAPABLE = "reapable"
+FOREIGN = "foreign"
+AMBIGUOUS = "ambiguous"
+
+# The same three-way split for the OTHER plane: a claim tag written into a registry file.
+# `held` there means the lease the tag names is still inside its TTL; `orphan` means it is
+# not, and `disputed` means the lease is live under a different run than the tag names.
+TAG_HELD = "held"
+ORPHAN = "orphan"
+DISPUTED = "disputed"
+
+DEFAULT_CLAIM_TEMPLATE = "{prev} (claimed: {holder})"
+
+
+def claim_marker_re(template: str) -> "re.Pattern[str] | None":
+    """A regex for this template's claim marker, capturing the run it names.
+
+    `write_claim` builds the marker by emptying `{prev}` and substituting the run id. Read
+    back, the run id is the one part not known in advance: it is the capture and everything
+    around it is literal, so one function defines the marker in both directions instead of
+    two spellings that can disagree.
+
+    `None` for a template with no `{holder}`. Such a marker names no owner, and a tag whose
+    owner cannot be read must never be cleared on somebody's behalf — the same rule
+    `classify_lock` applies to a lock that records no run.
+    """
+    marker = template.replace("{prev}", "").strip()
+    if "{holder}" not in marker:
+        return None
+    head, _, tail = marker.partition("{holder}")
+    return re.compile(re.escape(head) + r"(?P<holder>[^|\s]+)" + re.escape(tail))
+
+
+def classify_lock(key: str, raw: str, *, rid: str, identity_is_strong: bool,
+                  repo: str, host: str, default_ttl: int, at: float) -> dict[str, Any]:
+    """One lock file, read as a live lease or as one of three kinds of residue.
+
+    Pure — everything it needs is an argument — so each verdict below is a fixture rather
+    than a scenario somebody has to reproduce with two sessions and a clock.
+
+    **Why this function has to exist.** Every reader of lease state in this tool folds the
+    TTL into the read: `held()`, `_lease_holder()` and `all_holdings()` each answer *none*
+    for an expired lock and *none* for a lock that is not there. That is correct for
+    exclusion and it is why seventeen expired locks across nine repositories of one family
+    were reported by nothing — `status` printed `leases held: none` and `finish` printed
+    "no lease left held" standing on top of them. Expiry ends a lease. It does not remove
+    a file, and nothing here could see the difference.
+
+    **The split is the load-bearing part.** `reapable` means state this run can PROVE it
+    owns and has spent, and the proof is deliberately narrow:
+
+    - the lock is past its TTL — a live lease is held, not residue;
+    - it records a `run`, and that run is this one;
+    - **this run's identity is not the shared fallback.** `run_id()` keys its marker by
+      session, and a shell with no session id is served one shared entry whose own
+      docstring says the identity "is shared with any other session in this checkout".
+      Under that key a matching run id proves nothing, so it does not license a delete.
+    - its `repo` is this checkout, and its `host` — written by both lease modes since
+      AS-03, absent only in locks taken before it — is this machine.
+
+    Everything else is reported and left alone: `foreign` where it demonstrably belongs to
+    somebody else, `ambiguous` where the question cannot be answered at all. In doubt the
+    answer is `ambiguous`, never `reapable`.
+    """
+    out: dict[str, Any] = {"key": key, "state": AMBIGUOUS, "run": None, "repo": None,
+                           "host": None, "ts": "", "expired_for": None, "why": ""}
+    try:
+        held = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        out["why"] = "the lock is not readable JSON, so nothing in it identifies an owner"
+        return out
+    if not isinstance(held, dict):
+        out["why"] = "the lock is not an object, so nothing in it identifies an owner"
+        return out
+
+    out["run"] = held.get("run") or None
+    out["repo"] = held.get("repo") or None
+    out["host"] = held.get("host") or None
+    out["ts"] = str(held.get("ts") or "")
+
+    taken = parse_iso_or_none(out["ts"])
+    if taken is None:
+        out["why"] = (f"its timestamp ({out['ts'] or 'absent'}) is not one, so whether this "
+                      "lock is spent cannot be established")
+        return out
+    try:
+        ttl = int(held.get("ttl", default_ttl))
+    except (TypeError, ValueError):
+        out["why"] = (f"its ttl ({held.get('ttl')!r}) is not a number, so whether this lock "
+                      "is spent cannot be established")
+        return out
+
+    expires = taken + ttl
+    if at <= expires:
+        out["state"] = LIVE
+        out["why"] = (f"held by {out['run'] or 'an unnamed run'} for another "
+                      f"{int(expires - at)}s")
+        return out
+    out["expired_for"] = int(at - expires)
+
+    if not out["run"]:
+        out["why"] = "it records no run, so there is nobody it can be proved to belong to"
+        return out
+    if out["host"] and out["host"] != host:
+        out["state"] = FOREIGN
+        out["why"] = f"it was taken on {out['host']}, which is not this machine"
+        return out
+    if out["run"] != rid:
+        out["state"] = FOREIGN
+        out["why"] = f"it belongs to run {out['run']}, not to this one"
+        return out
+    if out["repo"] and out["repo"] != repo:
+        out["why"] = (f"its run id matches, but it names repository {out['repo']} while this "
+                      f"checkout is {repo}")
+        return out
+    if not identity_is_strong:
+        out["why"] = ("its run id matches, but this run's identity is the shared fallback — "
+                      "any other session in this checkout answers to the same id, so the "
+                      "match proves nothing")
+        return out
+    out["state"] = REAPABLE
+    out["why"] = "this run took it and let it expire"
+    return out
+
+
+def since(seconds: int) -> str:
+    """A duration an operator can act on."""
+    if seconds < 90:
+        return f"{seconds}s"
+    if seconds < 5400:
+        return f"{seconds // 60}m"
+    if seconds < 172800:
+        return f"{seconds // 3600}h"
+    return f"{seconds // 86400}d {(seconds % 86400) // 3600}h"
+
+
+def spent(entry: dict[str, Any]) -> str:
+    """How long this lock has been residue — said once, so no surface can phrase it
+    differently. A lock whose clock cannot be read is not "expired an unknown time ago";
+    it is a lock nobody can say is spent, which is why it is never reaped."""
+    if entry["state"] == LIVE:
+        return "live"
+    if entry.get("expired_for") is None:
+        return "expiry could not be established"
+    return f"expired {since(entry['expired_for'])} ago"
+
+
 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
@@ -882,6 +1045,8 @@ class Sync:
         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._identity: tuple[str, str] | None = None
+        self._holders: dict[str, str | None] = {}
 
     @property
     def gated(self) -> bool:
@@ -1148,8 +1313,14 @@ class Sync:
             return won, holder
 
         lock = self._local_lock(key)
+        # `host` is written in BOTH lease modes (AS-03). It used to be the git mode's alone,
+        # on the reasoning that a `local` lease is machine-local by construction — but the
+        # *file* is not: a checkout on a synced or shared directory is read by two machines,
+        # and `classify_lock` consumes `host` to decide `foreign`. Without it the classifier
+        # had one fewer way to refuse, on 25 of the 25 locks this family had on disk
+        # (2026-08-20). Absent stays legal: locks written before this line exist.
         payload = json.dumps({"run": self.rid, "ts": now_iso(), "ttl": self.ttl,
-                              "repo": repo_name()})
+                              "repo": repo_name(), "host": platform.node()})
 
         if lock.exists():
             try:
@@ -1356,6 +1527,188 @@ class Sync:
                 print(f"note: released locally, not published ({exc})", file=sys.stderr)
         return True
 
+    @property
+    def identity(self) -> tuple[str, str]:
+        """(key, how) for this run's identity — resolved once, because it walks `ps`."""
+        if self._identity is None:
+            self._identity = _session_key()
+        return self._identity
+
+    @property
+    def identity_is_strong(self) -> bool:
+        """Whether a matching run id is proof of anything.
+
+        False means `_session_key()` established nothing and `run_id()` served the shared
+        entry — the identity every other session in this checkout is also given. Enough to
+        coordinate with, and deliberately not enough to delete on.
+        """
+        return bool(self.identity[0])
+
+    def residue(self) -> list[dict[str, Any]]:
+        """Every lock file in this checkout, classified — the live ones included.
+
+        The enumerating read the tool never had. `held()` below globs the same directory
+        and keeps only what is BOTH this run's and alive, which makes it a liveness
+        predicate: it cannot tell an empty directory from one full of corpses, and no
+        other reader here can either.
+        """
+        d = self.root / STATE_DIR / "leases"
+        now, host, repo = time.time(), platform.node(), repo_name()
+        out: list[dict[str, Any]] = []
+        for p in sorted(d.glob("*.lock") if d.exists() else []):
+            try:
+                raw = p.read_text()
+            except OSError as exc:
+                entry: dict[str, Any] = {
+                    "key": p.stem, "state": AMBIGUOUS, "run": None, "repo": None,
+                    "host": None, "ts": "", "expired_for": None,
+                    "why": f"the lock cannot be read ({exc})"}
+            else:
+                entry = classify_lock(p.stem, raw, rid=self.rid,
+                                      identity_is_strong=self.identity_is_strong,
+                                      repo=repo, host=host, default_ttl=self.ttl, at=now)
+            entry["path"] = p
+            out.append(entry)
+        return out
+
+    def stale(self) -> list[dict[str, Any]]:
+        """The residue only — every lock whose lease has already ended."""
+        return [e for e in self.residue() if e["state"] != LIVE]
+
+    def reap(self, keys: list[str] | None = None) -> dict[str, list[dict[str, Any]]]:
+        """Clear only `reapable` residue, and prove it went by LOOKING AGAIN.
+
+        The second observation is the whole point. `unlink` returns nothing and raises
+        nothing on a filesystem where the entry survives the call — a read-only mount, an
+        NFS write that never lands, a directory whose write bit was dropped between two
+        commands, another process recreating the name — so a teardown that reports success
+        out of its own return value is reporting the wish rather than the state. What comes
+        back here is the difference between two reads of the directory.
+
+        Identity decides the second read, not absence: a key that came back as another
+        run's live lease WAS torn down, and calling that a failure would teach an operator
+        to ignore the one message that matters.
+        """
+        before = self.residue()
+        named = None
+        if keys:
+            named = set()
+            for k in keys:
+                named.add(k)
+                named.add(self._local_lock(k).stem)
+        wanted = [e for e in before
+                  if e["state"] == REAPABLE and (named is None or e["key"] in named)]
+        refused = [e for e in before
+                   if e["state"] != REAPABLE and named is not None and e["key"] in named]
+        if named is not None:
+            known = {e["key"] for e in before}
+            for k in sorted(named - known):
+                if self._local_lock(k).stem in known:
+                    continue
+                refused.append({"key": k, "state": "absent", "run": None, "ts": "",
+                                "expired_for": None,
+                                "why": "there is no lock by that name in this checkout"})
+
+        for e in wanted:
+            try:
+                e["path"].unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                e["error"] = str(exc)
+
+        after = {e["key"]: e for e in self.residue()}
+        reaped, remaining = [], []
+        for e in wanted:
+            still = after.get(e["key"])
+            if still is not None and still["run"] == e["run"] and still["ts"] == e["ts"]:
+                remaining.append(e)
+            else:
+                reaped.append(e)
+        return {"reaped": reaped, "remaining": remaining, "refused": refused,
+                "left": [e for e in before if e["state"] in (FOREIGN, AMBIGUOUS)]}
+
+    def claim_tags_on_disk(self) -> list[dict[str, Any]]:
+        """Every claim tag written into a registry file, with the run each one names.
+
+        The enumerating read for the OTHER plane, and it did not exist. `held()`,
+        `_lease_holder()` and `residue()` all answer from the lease; nothing answered from
+        the board — so a tag whose lease had ended was reported by no command at all.
+        `release` printed success and changed nothing (`write_claim` had no saved cell to
+        undo), `residue` said "nothing on disk", `status` said "leases held: none", and
+        `reconcile` never mentioned it. Filed as ssheleg/agent-sync#5 and reproduced
+        verbatim at 1.14.0.
+        """
+        out: list[dict[str, Any]] = []
+        for pattern, spec in (self.cfg.get("claimTags") or {}).items():
+            if spec.get("mode") != "cell":
+                continue
+            rx = claim_marker_re(spec.get("held") or DEFAULT_CLAIM_TEMPLATE)
+            if rx is None:
+                continue
+            idx = int(spec.get("cell", -1))
+            for path in sorted(glob_files(self.root, pattern)):
+                if not path.is_file():
+                    continue
+                try:
+                    lines = path.read_text().splitlines()
+                except OSError:
+                    continue
+                rel = str(path.relative_to(self.root))
+                for n, line in enumerate(lines, 1):
+                    cells = self._row_cells(line)
+                    if not cells or not -len(cells) <= idx < len(cells):
+                        continue
+                    m = rx.search(cells[idx])
+                    if not m:
+                        continue
+                    out.append({"key": cells[0].strip(), "holder": m.group("holder"),
+                                "file": rel, "line": n, "cell": cells[idx].strip()})
+        return out
+
+    def _holder_of(self, key: str) -> str | None:
+        """`_lease_holder`, memoised for the length of one command.
+
+        One notion of held, and only one reader of it. Memoised because in git mode that
+        reader is an `ls-remote`: a report over a board with several tags would otherwise
+        pay a network round-trip per row. The bound is the number of TAGGED rows, not the
+        size of the board — an untagged row is never looked up.
+        """
+        if key not in self._holders:
+            self._holders[key] = self._lease_holder(key)
+        return self._holders[key]
+
+    def orphan_claims(self) -> list[dict[str, Any]]:
+        """Claim tags with no live lease behind them — one notion of held, both planes.
+
+        The TTL is the contract. A tag is a claim about a lease, so once `_lease_holder` —
+        the single reader every other command already trusts — answers `None`, the tag is
+        residue in the registry exactly as an expired lock is residue on disk, and is
+        reported the same way.
+
+        A tag naming a run that still holds the lease is not residue and never appears
+        here. A tag naming one run while the live lease belongs to another is `disputed`:
+        reported, never cleared, because clearing it would edit a registry under a run
+        that is still working.
+        """
+        out: list[dict[str, Any]] = []
+        for e in self.claim_tags_on_disk():
+            holder = self._holder_of(e["key"])
+            if holder == e["holder"]:
+                continue
+            e = dict(e)
+            if holder is None:
+                e["state"] = ORPHAN
+                e["why"] = (f"the tag names run {e['holder']}, and the {self.lease_mode} "
+                            f"lease plane holds no live lease for `{e['key']}` — the TTL "
+                            "has already ended it")
+            else:
+                e["state"] = DISPUTED
+                e["why"] = (f"the tag names run {e['holder']} while the live lease for "
+                            f"`{e['key']}` is held by {holder}")
+            out.append(e)
+        return out
+
     def held(self) -> list[str]:
         d = self.root / STATE_DIR / "leases"
         mine = []
@@ -1778,7 +2131,40 @@ class Sync:
                 state.setdefault(key, {})[str(rel)] = current
             else:
                 if saved is None:
-                    continue                      # nothing of ours to undo
+                    # NOT "nothing to undo" — that reading is ssheleg/agent-sync#5. The
+                    # state file is this run's memory of what it overwrote, and a tag
+                    # outlives it routinely: written by a run that died, by a session on
+                    # another machine, or with `.agent-sync/` wiped between the acquire and
+                    # the release. `release` then printed success, exited 0, and left
+                    # `(claimed: r-…)` on the board with nothing behind it — a claim no
+                    # command could reach.
+                    #
+                    # The TTL decides, exactly as it decides for a lock file: the lease
+                    # plane is asked who holds the key, and only a tag with no live lease
+                    # behind it is cleared. A live lease is somebody working, and its tag
+                    # is left alone whoever runs this.
+                    template = spec.get("held") or DEFAULT_CLAIM_TEMPLATE
+                    rx = claim_marker_re(template)
+                    m = rx.search(current) if rx else None
+                    if m is None:
+                        continue                  # no tag here either, so nothing to undo
+                    whose = m.group("holder")
+                    live = self._holder_of(key)
+                    if live is not None and live != self.rid:
+                        notes.append(
+                            f"{rel}: `{key}` carries a claim tag naming {whose}, and the "
+                            f"lease is live under {live} — left alone")
+                        continue
+                    stripped = (current[:m.start()] + current[m.end():]).strip()
+                    cells[idx] = f" {stripped} " if stripped else " "
+                    notes.append(
+                        f"{rel}: cleared an orphaned claim tag on `{key}` — it named run "
+                        f"{whose}, and no live lease stands behind it (ssheleg/agent-sync#5)")
+                    lines[i] = row_prefix + "|" + "|".join(cells) + row_suffix
+                    tmp = path.with_suffix(path.suffix + ".agent-sync.tmp")
+                    tmp.write_text("".join(lines))
+                    tmp.replace(path)
+                    continue
                 # Restoring VERBATIM loses any edit made while the claim was held, and in
                 # this family the claim cell IS the status cell — so `close then release`
                 # silently reopened a row closed with evidence minutes earlier (B-35,
@@ -1820,14 +2206,18 @@ class Sync:
         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.
+
+        Both directions, since AS-04. It used to return on `if not held` — so divergence
+        was reported only to a run holding a lease, and the one shape that needs reporting
+        most, a tag with NO lease behind it, was structurally invisible: nobody holds it,
+        so nobody could be told (ssheleg/agent-sync#5). The lease side is still keyed by
+        what this run holds; the registry side is now swept whether it holds anything or not.
         """
         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():
@@ -1855,6 +2245,15 @@ class Sync:
                         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")
+
+        # The other direction: a tag whose lease the TTL has already ended, or one naming a
+        # run that is not the run holding the key. Reported to every session, not only to a
+        # session that happens to hold a lease.
+        for e in self.orphan_claims():
+            remedy = ("`release` it" if e["state"] == ORPHAN
+                      else "ask the holder, and do not edit the row")
+            out.append(f"{e['file']}:{e['line']}: `{e['key']}` [{e['state']}] — "
+                       f"{e['why']}. NEXT: {remedy}")
         return out
 
     # -- as-built record and reconciliation ---------------------------------
@@ -1994,6 +2393,15 @@ class Sync:
                 "no id registers declared here, so register checks are not evaluated in "
                 "this repository — run reconcile in the umbrella for those")
 
+        # 4. A claim tag on the board whose lease the TTL has already ended. Mechanical,
+        #    two-plane divergence — the definition of what this command reports — and it
+        #    was the one kind `reconcile` never mentioned (ssheleg/agent-sync#5).
+        for e in self.orphan_claims():
+            findings.append({
+                "kind": f"claim tag with no live lease ({e['state']})",
+                "detail": f"{e['file']}:{e['line']} `{e['key']}` names {e['holder']}",
+                "means": e["why"]})
+
         self.backlog = notes_backlog
         return findings
 
@@ -2193,6 +2601,8 @@ class Sync:
             "| 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 |",
+            "| A lock left by a run that stopped | the lease directory | until it is "
+            "reported and reaped |",
             "| Per-run narrative | that run's journal | permanent |",
             "| The board and these pages | generated | replaced on every regeneration |",
             "",
@@ -2224,6 +2634,10 @@ class Sync:
             "merge --key → land the branch: conflicts checked first, the merge recorded,",
             "              that lease released. Without a branch, `release ID` by hand",
             "              — on every path, including failure",
+            "residue     → what this run leaves on disk. Expiry ends a lease and leaves",
+            "              the file, so `status` and `finish` enumerate them; `reap`",
+            "              clears only what THIS run can prove it owns and has spent,",
+            "              and reports foreign or ambiguously owned locks untouched",
             "```",
             "",
             f"This project's integration branch is `{self.integration_branch}`.",
@@ -2509,6 +2923,49 @@ def cmd_status(_args: argparse.Namespace) -> int:
         return 1
     print(f"  leases held    : {', '.join(held) if held else 'none'}")
 
+    # A run produces more than a diff, and what it leaves behind has to be reported by the
+    # command every session runs. Until this line existed, `status` printed `leases held:
+    # none` beside three expired locks in the directory it had just read — every reader of
+    # lease state here applies the TTL, so "expired" and "absent" were one answer.
+    stale = s.stale()
+    reapable = [e for e in stale if e["state"] == REAPABLE]
+    left_alone = [e for e in stale if e["state"] != REAPABLE]
+    if not stale:
+        print("  expired locks  : none")
+    else:
+        print(f"  expired locks  : {len(stale)} — {len(reapable)} this run's to clear, "
+              f"{len(left_alone)} left alone")
+        print("\n  Expired leases still on disk. Nobody holds these: the TTL ended the "
+              "lease\n  and left the file.")
+        for e in stale[:6]:
+            print(f"    · {e['key']}  [{e['state']}] {e['why']} ({spent(e)})")
+        if len(stale) > 6:
+            print(f"    · … and {len(stale) - 6} more — agent_sync.py residue")
+        if reapable:
+            print("    Clear what this run owns:  agent_sync.py reap")
+        if left_alone:
+            print("    The rest are foreign or ambiguously owned — reported, not touched.")
+
+    # The registry plane's residue, on the same footing as the lease plane's. A claim tag
+    # is a claim about a lease, and until this line the TTL could end the lease while the
+    # tag stayed on the board reading live — with `leases held: none` printed above it.
+    try:
+        orphans = s.orphan_claims()
+    except Fail:
+        orphans = []
+    if not (s.cfg.get("claimTags") or {}):
+        pass
+    elif not orphans:
+        print("  orphan claims  : none")
+    else:
+        print(f"  orphan claims  : {len(orphans)} claim tag(s) with no live lease behind "
+              "them")
+        for e in orphans[:6]:
+            print(f"    · {e['file']}:{e['line']}  {e['key']}  [{e['state']}] {e['why']}")
+        if len(orphans) > 6:
+            print(f"    · … and {len(orphans) - 6} more")
+        print("    Clear one:  agent_sync.py release <KEY>")
+
     # 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.
     plane_broken = False
@@ -2554,7 +3011,7 @@ def cmd_status(_args: argparse.Namespace) -> int:
 
     claim_issues = s.claim_divergence()
     if claim_issues:
-        print("\n  Claim tags not written through:")
+        print("\n  Claim tags out of step with the lease plane:")
         for c in claim_issues:
             print(f"    ! {c}")
 
@@ -2674,6 +3131,97 @@ def cmd_release_id(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_residue(_args: argparse.Namespace) -> int:
+    """What this run leaves behind, classified — and never quietly cleared.
+
+    Reporting and clearing are two commands on purpose. This one is safe to run anywhere,
+    including in somebody else's checkout, because it cannot remove anything.
+    """
+    s = Sync()
+    entries = s.residue()
+    print(f"run {s.rid} · identity from {s.identity[1]}")
+    print(f"lease mode {s.lease_mode} · ttl {s.ttl}s · {len(entries)} lock file(s) in "
+          f"{STATE_DIR}/leases\n")
+    if not entries:
+        print("  nothing in the lock directory — no lease has been taken in this checkout, "
+              "or every\n  one was released")
+    for e in entries:
+        print(f"  {e['key']}")
+        print(f"    state : {e['state']}"
+              + ("" if e["state"] == LIVE else f" ({spent(e)})"))
+        print(f"    run   : {e['run'] or '—'} · repo {e['repo'] or '—'}"
+              f"{' · host ' + e['host'] if e['host'] else ''}")
+        print(f"    why   : {e['why']}")
+    reapable = [e for e in entries if e["state"] == REAPABLE]
+    other = [e for e in entries if e["state"] in (FOREIGN, AMBIGUOUS)]
+    if entries:
+        print()
+        if reapable:
+            print(f"  {len(reapable)} reapable — this run's own, spent: agent_sync.py reap")
+        if other:
+            print(f"  {len(other)} foreign or ambiguous — reported, never cleared from here. "
+                  "An expired\n  lock in another run's name is that run's to explain, and a "
+                  "lock whose owner\n  cannot be established is nobody's to delete.")
+        if not reapable and not other:
+            print("  no residue — every lock on disk is a live lease")
+
+    # The second plane. A claim tag is residue too, and reporting only the lock directory
+    # was the whole of ssheleg/agent-sync#5: `residue` printed "nothing on disk" over a
+    # board row reading `(claimed: r-…)` that no command could reach.
+    if s.cfg.get("claimTags"):
+        orphans = s.orphan_claims()
+        tags = len(s.claim_tags_on_disk())
+        print(f"\n  claim tags: {tags} on disk, {len(orphans)} with no live lease behind them")
+        for e in orphans:
+            print(f"    · {e['file']}:{e['line']}  {e['key']}  [{e['state']}]")
+            print(f"      why   : {e['why']}")
+            if e["state"] == ORPHAN:
+                print(f"      clear : agent_sync.py release {e['key']}")
+            else:
+                print("      leave : the lease is live under another run — ask the holder")
+        if tags and not orphans:
+            print("    every tag names the run that still holds its key")
+    else:
+        print("\n  claim tags: not configured here, so none are swept "
+              "(`claimTags` in the config)")
+
+    # AS-01a. Said where the report prints, not only on a board: a check that cannot look
+    # must not read as one that looked.
+    if s.lease_mode == "git":
+        print("\n  ⚠ INCOMPLETE IN THIS MODE. The read above walks "
+              f"{STATE_DIR}/leases only, and in\n"
+              "  git mode the authority is `refs/agent-sync/leases/*` on "
+              f"{s.cfg.get('leaseRemote') or 'origin'}.\n"
+              "  A ref won on ANOTHER machine leaves no local note here, so it is absent "
+              "from this\n  report — absent, not proven gone. Sweeping the refs is board row "
+              "AS-01a; until it\n  lands, enumerate them by hand:\n"
+              f"    git ls-remote {s.cfg.get('leaseRemote') or 'origin'} "
+              "'refs/agent-sync/leases/*'")
+    return 0
+
+
+def cmd_reap(args: argparse.Namespace) -> int:
+    """Clear this run's spent locks, and verify the teardown by reading the state again."""
+    s = Sync()
+    result = s.reap(args.keys or None)
+    for e in result["reaped"]:
+        print(f"  reaped {e['key']} — {e['why']}, confirmed gone by re-reading "
+              f"{STATE_DIR}/leases")
+    for e in result["remaining"]:
+        detail = f" ({e['error']})" if e.get("error") else ""
+        print(f"  ✗ {e['key']} is STILL PRESENT after the delete{detail} — the teardown was "
+              "not\n    verified, whatever the call returned. Nothing was reported as "
+              "cleared.", file=sys.stderr)
+    for e in result["refused"]:
+        print(f"  · {e['key']} [{e['state']}] left alone — {e['why']}")
+    if not args.keys:
+        for e in result["left"]:
+            print(f"  · {e['key']} [{e['state']}] left alone — {e['why']}")
+    if not result["reaped"] and not result["remaining"] and not result["refused"]:
+        print("  nothing this run can prove it owns and has spent — nothing reaped")
+    return 1 if result["remaining"] or result["refused"] else 0
+
+
 def cmd_journal(args: argparse.Namespace) -> int:
     return 0 if Sync().journal(" ".join(args.text)) else 1
 
@@ -3173,6 +3721,22 @@ def cmd_finish(args: argparse.Namespace) -> int:
     else:
         ok.append("no lease left held")
 
+    #    And the other half of that question, which for six versions nothing asked: what is
+    #    left on disk. `held()` answers `none` for a directory full of expired locks, so
+    #    "no lease left held" was printed beside a two-day-expired one. Proof of Done
+    #    records what remains — it does not license deleting all of it, so only what this
+    #    run can prove it owns is a problem to fix here.
+    stale = s.stale()
+    reapable = [e for e in stale if e["state"] == REAPABLE]
+    left_alone = [e for e in stale if e["state"] != REAPABLE]
+    if not stale:
+        ok.append("no expired lock left behind")
+    if reapable:
+        problems.append(
+            f"{len(reapable)} expired lock(s) this run owns are still on disk ("
+            + ", ".join(e["key"] for e in reapable)
+            + ") — clear them with `agent_sync.py reap`")
+
     # 3. the declared gates, on request. They are the project's own commands and can be slow, so
     #    running them is opt-in — but a `finish` that never ran them is a claim, not a check.
     if args.gates:
@@ -3193,6 +3757,11 @@ def cmd_finish(args: argparse.Namespace) -> int:
         print(f"  \u2713 {line}")
     for line in problems:
         print(f"  \u2717 {line}")
+    if left_alone:
+        print("\n  Left alone — residue this run cannot prove it owns:")
+        for e in left_alone:
+            print(f"    · {e['key']}  [{e['state']}] {e['why']}")
+        print("    Reported, not touched: another run's expired lock is that run's to explain.")
     print()
     if problems:
         print(f"{len(problems)} problem(s) — this work is not finished. The usual one is a "
@@ -3746,6 +4315,13 @@ def build_parser() -> argparse.ArgumentParser:
     sg.add_argument("state")
     sg.set_defaults(fn=cmd_signal)
 
+    sub.add_parser("residue", help="expired locks left on disk, classified by who can "
+                                    "prove they own them").set_defaults(fn=cmd_residue)
+    rp = sub.add_parser("reap", help="clear expired locks this run provably owns; foreign "
+                                     "and ambiguous ones are reported, never touched")
+    rp.add_argument("keys", nargs="*", help="which to clear (default: every reapable one)")
+    rp.set_defaults(fn=cmd_reap)
+
     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)