@ssheleg/agent-sync 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -1,3 +1,101 @@
+## Unreleased — both `AS-01` halves exercised outside their fixtures
+
+The two rows sat at priority `unverified`: shipped, and confirmed by nothing but their own
+fixtures. Both are now exercised against real state, and both hold. **Nothing in the tool
+changed** — this records that the mechanism was watched working on something other than its
+own test data, which is what `unverified` meant.
+
+**The git plane, on a real remote.** A git-mode checkout was built against a local bare
+remote, a lease taken at `ttl 2`, and its local note **deleted** — exactly the state a ref
+won on another machine leaves behind, and the state the row said `residue` could not see.
+`residue` printed *nothing in the lock directory* and then enumerated the git plane:
+`refs/agent-sync/leases/DEMO-KEY @ 495370743e`, run `r-rverifya`, **expired 18s ago**,
+`foreign`, closing with *1 ref(s) on the remote, 0 this run can prove it owns and has spent*.
+
+**Reap, in both directions.** Reaping as a **different** run left the ref standing and said so
+by name. Reaping as the run that took it removed it and reported *confirmed gone by re-reading
+the remote* — the proof coming from `ls-remote`, not from a push's exit code.
+
+**And on live residue.** `~/DATA/0xDEV` carries a genuine foreign expired lock —
+`BLOG-SITEMAP`, run `r-blog-1429e`, **expired 4d 22h ago**. `reap` named it, said *left alone
+— it belongs to run r-blog-1429e, not to this one*, and **deleted nothing**: both lock files
+byte-identical afterwards. State a run cannot prove is its own is reported and untouched.
+
+## v1.16.0 — the release that closes one version string over two trees
+
+**281 lines of shipped behaviour had been sitting behind the tag.** `AS-01a` (the
+git plane is swept, not only disclosed) and `AS-01b` (an ambiguous lock is
+clearable by a person, per key, attributably) landed on `main`, were pinned by the
+umbrella, and were never tagged. So three channels served `1.15.0` and two
+different trees:
+
+| channel | source | `agent_sync.py` |
+|---|---|---|
+| npm `@ssheleg/agent-sync@1.15.0` | the tag | 4344 lines |
+| the plugin marketplace | the branch tip | 4575 lines |
+| the skills CLI | the branch tip | 4575 lines |
+
+All three reported `1.15.0`. `check_pins.py` was green throughout — correctly,
+because it compares the version STRING, and the string did match. A version that
+identifies two artefacts cannot be reasoned about, and the family's own invariant
+("the pin is the promise") was satisfied to the letter while being false in
+substance.
+
+Found on 2026-08-23 by fetching the npm tarball and counting lines in all three
+channels rather than trusting any of them. This release makes the number true.
+
+Also in this range: the release workflow refuses a tag whose commit no clone can
+reach, and the evidence ledger records both `AS-01` halves exercised on a real
+remote rather than in a fixture.
+
+## v1.15.0 — a claim tag outlived its lease, and no command reached it
+
+**GitHub issue #5, filed 2026-08-17, reproduced verbatim at v1.14.0.** A board row shipped
+in a published release reading `(claimed: r-6e62c4dab)` while the lease plane said
+`leases held: none`. `release <key>` printed `released`, exited **0** and changed nothing;
+`residue` said *nothing on disk*; `reconcile` found *no mechanical divergence*. Three
+commands, none of which could reach the tag, because `write_claim(key, None)` restores the
+cell for the key it holds and it held none.
+
+This is #4 from the other side. #4 was a lease that outlived its run; this is a tag that
+outlived its lease — and the second is worse, because an invisible lease invites a check
+while a confident wrong answer does not. Closed the same way: **one notion of held,
+consulted by both planes.** `_lease_holder` stays the single reader, memoised per command
+so a report over a tagged board costs one `ls-remote` per *tagged row* in git mode rather
+than one per board row. `orphan_claims()` classifies a tag `orphan` — the TTL has ended its
+lease — or `disputed`, live under another run, which is reported and never touched.
+`release` clears an orphan and names the run it belonged to. `status`, `residue` and
+`reconcile` each report one, so the disagreement is visible to a gate rather than to a
+diff.
+
+Four more, each with its plant watched refusing:
+
+- **`residue` read as a complete answer in git mode and could not be.** It walks
+  `.agent-sync/leases/*.lock`, which only the local plane writes, so a ref won on another
+  machine was invisible. It now prints `⚠ INCOMPLETE IN THIS MODE` with the `ls-remote`
+  command it does not run. The sweep itself is still open, and the row says so — a check
+  that cannot look must not read as one that looked.
+- **A `local` lock recorded no host**, so residue could not tell a lock written here from
+  one written on another machine; 25 of 25 locks on this machine carried none. Both modes
+  write it now, with a fixture separating two machines.
+- **The ledger described an artifact nobody shipped**: its newest section was headed
+  *(in tree, unreleased)* and quoted `PASS: agent-sync v1.13.0` while v1.14.0 was tagged,
+  in `package.json` and on npm. Guarded three ways.
+- **Two divisors for one token budget.** The family's auditor measured the pack's body at
+  ~5084 tokens against a 5000 limit; this repo's own gate divided by 4 and passed at 4957.
+  One divisor now (3.9, the auditor's), and the body is under it at ~4683 after a split.
+
+Also corrected: the board's *"14 of the 17 live in repositories this row must not touch"*
+recomputes to **16 outside this checkout, 13 outside it and the umbrella**, with the `find`
+that produces each.
+
+**Found while doing it:** a plant had stopped planting. `the script path is prose only`
+substituted a paragraph that had since been reflowed, so it changed nothing — and a no-op
+plant still reported `detected` for a check that never ran. Re-anchored on the values the
+check actually reads.
+
+Self-test fixtures 43 → **51**; the claim-cell suite 9 → **16 cases**.
+
 ## v1.14.0 — expiry ended a lease and left the file, and every reader folded that away
 
 **`status` reported `leases held: none` over three expired locks in the directory it had

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Let concurrent coding agents share one project without colliding — leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
   "bin": {
     "agent-sync": "bin/agent-sync.js"

package/plugins/agent-sync/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Coordination layer for multi-agent repositories — leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
     "name": "ssheleg",

package/plugins/agent-sync/skills/agent-sync/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when several coding agents work one repository at the same tim
 compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
 license: MIT
 metadata:
-  version: "1.14.0"
+  version: "1.16.0"
   author: ssheleg
 ---
 
@@ -24,7 +24,6 @@ keep that true while several agents write at once.
 **1. The knowledge base never decides a lease.** It cannot: twelve concurrent appends to
 one Outline document returned twelve successes and left **three** lines. Exclusion comes
 from something with real compare-and-swap. The plane carries the record and nothing else.
-Full measurements in `references/lease-protocol.md`.
 
 **2. Know which lease you have, and say so.** `leaseBackend: "local"` is an atomic file
 create — exclusive between processes on one filesystem, **advisory across machines**.
@@ -38,14 +37,12 @@ round-trip. **Read `references/roadmap.md`** before configuring `claimTags` or c
 task; closing is a statement about the work and stays yours.
 
 **Work on a branch; the integration branch is somebody else's stable base.** `acquire`
-writes the claim through **only** there; on any other branch the holder stays in the
-coordination plane, where `status` shows it to every agent without anyone fetching your
-branch. Committed to a branch, a claim is invisible until the merge and turns the shared
-roadmap into a file two branches both edit. Land work with `merge`: conflicts computed by
-`git merge-tree` **before anything is touched**, named and refused if any, the merge
-recorded in `docs/MERGES.md` (recent days in full, older compacted on write), the `--key`
-lease released. `merges` tells the next agent what landed while it was away. **Read
-`references/branching.md`** before merging.
+writes the claim through **only** there — on any other branch the holder stays in the
+coordination plane, where `status` shows it to every agent. Committed to a branch, a claim
+is invisible until the merge and turns the shared roadmap into a file two branches both
+edit. Land work with `merge`: conflicts computed **before** anything is touched, the merge
+recorded in `docs/MERGES.md`, the `--key` lease released; `merges` says what landed while
+you were away. **Read `references/branching.md`** before merging.
 
 **3. Hooks exist only in Claude Code.** Elsewhere nothing blocks a guarded edit: run
 `guard` yourself and record the run as `ungated`. Do not describe a project as protected
@@ -55,8 +52,7 @@ when it is not.
 what you wrote — Outline turns a `- ` bullet into `* `. Emit `- `, accept `-`/`*`/`+`,
 count anything entry-shaped that fails, and **fail loudly** past 2% unparseable. Reporting
 `lost` when the truth is *unreadable* names a holder who does not exist. Watch for a
-silent pre-filter: a `continue` before the regex hides bad lines from the counter built to
-expose them.
+silent pre-filter: a `continue` before the regex hides bad lines from the counter.
 
 ## Bringing this into ANY project — the whole chain
 
@@ -70,19 +66,15 @@ setup     → generate the snapshot that describes this project's wiring
 check     → validate the whole thing; non-zero if it is not healthy
 ```
 
-**`check` is what makes the skill self-sufficient.** It refuses to call a setup healthy on
-a rule that protects nothing (a register, guard glob, claim pattern, gate or mirror source
+**`check` is what makes the skill self-sufficient.** It refuses to call a setup healthy on a
+rule that protects nothing (a register, guard glob, claim pattern, gate or mirror source
 pointing at what is not there), on missing credentials, on an env file **tracked by git** —
-the one unrecoverable mistake here — on a stale or unlinked snapshot, and on a register
-with no baseline. It names each one; every one failed for real during this tool's own
-adoption.
+the one unrecoverable mistake here — on a stale snapshot, or on a register with no baseline.
+It names each one; every one failed for real during this tool's own adoption. Run it after
+adopting, after changing the config, and in CI.
 
-Run `check` after adopting, after changing the config, and in CI.
-
-**`scaffold` never overwrites.** It seeds a decision register with an allocation line and
-an `AGENTS.md` that points at the snapshot, and leaves every existing file untouched — a
-tool that rewrites a project's own conventions on adoption is worse than one that does
-nothing.
+**`scaffold` never overwrites.** It seeds a decision register and an `AGENTS.md` pointing at
+the snapshot, and leaves every existing file untouched.
 
 ## Existing project: start with `adopt`
 
@@ -95,15 +87,14 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" adopt
 ```
 
 Confirm the registers and guarded files with the operator first: a register pointed at the
-wrong file makes every later check confidently wrong, and a guarded list that misses a
-shared file leaves the one place collisions happen unprotected. In a submodule it declares
-no registers: decisions belong to the parent repository. Then take the chain above from
-`init`.
+wrong file makes every later check confidently wrong, and a guarded list that misses a shared
+file leaves the one place collisions happen unprotected. In a submodule it declares no
+registers — decisions belong to the parent. Then take the chain above from `init`.
 
 ## First command in a project: `init`
 
-**Never run anything else against an uninitialised project.** `init` is where the
-storage question gets asked and answered, once, and written down.
+**Never run anything else against an uninitialised project.** `init` is where the storage
+question gets asked and answered, once, and written down.
 
 **Ask the operator these two things in chat — do not guess, do not pick a default:**
 
@@ -127,15 +118,11 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend outline --url https://
 python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend fs
 ```
 
-`init` writes `.claude/agent-sync.json` (shape, committed), writes
-`.env.agent-sync` with the keys and an **empty** token line (identity, mode 600),
-adds `.env.agent-sync` and `.agent-sync/` to `.gitignore`, and then prints exactly
-what the operator must do themselves — create the token in their own instance and
-paste it into that one line. It never overwrites an existing config or env file
-without `--force`.
-
-Relay those closing instructions to the operator verbatim. Getting the token into
-the file is their step, and the design depends on it staying theirs.
+`init` writes `.claude/agent-sync.json` (shape, committed) and `.env.agent-sync` with an
+**empty** token line (identity, mode 600), gitignores both, and prints the one step that is
+the operator's — creating the token and pasting it into that line. Never overwrites either
+file without `--force`. **Relay those closing instructions verbatim**; the design depends on
+the token staying theirs.
 
 ## Then, before every session
 
@@ -144,25 +131,23 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" status
 ```
 
 Idempotent. Inspects, repairs, reports, names exactly ONE next action — and carries
-`check`'s verdict, so the command every session runs and the one that validates the
-setup cannot give two answers about one project.
+`check`'s verdict, so the command every session runs and the one that validates the setup
+cannot give two answers about one project.
 
 **Read the two awareness sections it prints — they are the point, not decoration.**
 
-- **Other runs working this project right now.** Who holds what, this minute. Do not
-  take those on, and do not "just look at" the files they cover. A lease you cannot
-  see makes you blocked; a lease you can see makes you coordinated.
-- **New since you last looked.** Cross-repo dependency moves that landed while you
-  were away. A dependency that moved may unblock what you planned — or invalidate it.
-  This list is watermarked per run, so it stays quiet until something actually
-  changes; when it speaks, it matters.
+- **Other runs working this project right now.** Who holds what, this minute. Do not take
+  those on, and do not "just look at" the files they cover.
+- **New since you last looked.** Cross-repo dependency moves that landed while you were
+  away — watermarked per run, so it stays quiet until something changes. A dependency that
+  moved may unblock what you planned, or invalidate it.
 
 An agent that skips this block will re-derive work someone else is doing and act on a
 dependency state that changed an hour ago.
 
-What else `status` decides: no credentials → degraded mode, reported, and it continues (a
-smaller mode, not an error); `task-pipeline` absent → it prints the install line and stops.
-Do not improvise a substitute flow — without those stages there is nothing to bind to.
+What else `status` decides: no credentials → degraded mode, reported, and it continues;
+`task-pipeline` absent → it prints the install line and stops. Do not improvise a substitute
+flow — without those stages there is nothing to bind to.
 
 ```bash
 npx sshlg-skills install
@@ -187,37 +172,32 @@ npx sshlg-skills install
 | `guard <path>` | Answer whether this run may write that path. Exit 0 = yes, 2 = no |
 | `board` | Regenerate the shared board and this repo's page. `--mirror` also renders the configured git docs into the plane |
 | `whoami` | Print this run's id and its held leases |
-| `residue` | Expired locks still on disk: this run's spent ones, and the foreign or ambiguous ones it reports and never touches |
+| `residue` | What a run left behind in BOTH planes: expired locks on disk, and claim tags with no live lease behind them |
 | `reap [KEY…]` | Clear only what this run **proves** it owns and has spent, then re-read the directory to confirm it went |
 | `setup` | Write the generated snapshot of how **this** project is wired, for agents to read |
 | `adopt` | Inspect an existing project and **propose** a config — writes nothing |
-| `merge` | Land this branch: local target fast-forwarded, conflicts checked **before** anything is touched, merge log written, the `--key` lease released. `--summary`, `--dry-run`, `--push` |
+| `merge` | Land this branch: target fast-forwarded, conflicts checked **before** anything is touched, merge log written, the `--key` lease released. `--summary`, `--dry-run`, `--push` |
 | `merges` | What landed while you were on your branch. `--all` includes the compacted tail |
 | `check` | Validate the whole setup end to end. Non-zero when it is not healthy |
-| `scaffold [--full]` | Create only what is missing, never a line over anything that exists. `--full` also seeds the question register, the index, the dependency board, the data model with its entity register, and the docs gate |
-| `finish [--gates]` | Is the **work** finished — every repository clean, pushed and pointed at, no lease left held. `check` answers whether the project is wired correctly; this answers whether you are done |
+| `scaffold [--full]` | Create only what is missing, never a line over what exists. `--full` also seeds the question register, index, dependency board, data model and docs gate |
+| `finish [--gates]` | Is the **work** finished — every repository clean, pushed and pointed at, nothing left held. `check` answers whether the project is wired right; this, whether you are done |
 
-`$SKILL_DIR` is this skill's own directory: `${CLAUDE_PLUGIN_ROOT}/skills/agent-sync`
-under the Claude Code plugin, `~/.agents/skills/agent-sync` elsewhere. Resolve it once
-per session and reuse it — do not guess a path. Every command reads
-`.claude/agent-sync.json` from the project root and needs no arguments beyond those
-listed.
+`$SKILL_DIR` is this skill's own directory: `${CLAUDE_PLUGIN_ROOT}/skills/agent-sync` under
+the Claude Code plugin, `~/.agents/skills/agent-sync` elsewhere. Resolve it once per session
+and reuse it — do not guess. Every command reads `.claude/agent-sync.json` from the project
+root and needs no arguments beyond those listed.
 
 ## One identity per session, and how it is decided
 
-A lease is only a lease if two agents get two identities. Ordering matters here and both ends have
-bitten: deriving the id from `CLAUDE_SESSION_ID` alone gave **one session two identities** — it
-acquired as one and was denied by its own guard as the other — and keeping one id per checkout gave
-**two sessions one identity**, which is worse. The second is silent: both sessions acquire, both are
-guarded, and `release` takes a lease the caller never had.
+A lease is only a lease if two agents get two identities, and both ends have bitten:
+`CLAUDE_SESSION_ID` alone gave **one session two identities** — it acquired as one and was denied by
+its own guard as the other — and one id per checkout gave **two sessions one identity**, silently,
+so `release` took a lease the caller never had.
 
 The order is: `AGENT_SYNC_RUN_ID` · `CLAUDE_SESSION_ID` · **the session that started this shell** ·
-shared.
-
-The third matters because a plain shell command has no session id and a hook does. So
-`SessionStart` stamps `.agent-sync/sessions/<CLI pid>` with the session it knows, and a later
-command finds itself by walking its own process ancestry to a stamped pid. Why that and not
-command-line parsing: `references/earned-rules.md`.
+shared. The third exists because a plain shell command has no session id and a hook does, so
+`SessionStart` stamps `.agent-sync/sessions/<CLI pid>` and a later command walks its own process
+ancestry to it. Why that and not command-line parsing: `references/earned-rules.md`.
 
 When none of the four can be established the run says so — *"this identity is shared with any other
 session in this checkout"* — rather than presenting a shared entry as separation.
@@ -235,6 +215,11 @@ TTL expires, and the next agent cannot tell "in progress" from "crashed an hour
 claim is the tag in git, written through by `acquire` and cleared by `release`. One fact,
 one home — do not invent a third place that records ownership.
 
+**One notion of held, consulted by both planes.** The TTL ends the lease, so a tag naming a
+run whose lease has ended is residue: reported by `status`, `residue` and `reconcile`, and
+cleared by `release <KEY>`, which says whose it was. A tag whose lease is still live is
+never touched by another run.
+
 **Read `references/lease-protocol.md`** before changing acquisition, expiry, stealing or
 id allocation.
 
@@ -246,65 +231,59 @@ The config lists registry files several agents write. Before editing one:
 python3 "$SKILL_DIR/scripts/agent_sync.py" guard docs/DECISIONS.md
 ```
 
-**Exit 2 is about *this run*: it holds no lease** — not that somebody else holds that
-file. One lease covers every guarded file; hold one or write none. A denial names the
-other run **and its key**, because "r-x holds a lease" beside a path gets repeated as
-"r-x holds this file". Do not edit anyway, and do not "just fix one line" — a clobbered
-decision looks exactly like a decision.
+**Exit 2 is about *this run*: it holds no lease** — not that somebody else holds that file.
+One lease covers every guarded file; hold one or write none. A denial names the other run
+**and its key**, because "r-x holds a lease" beside a path gets repeated as "r-x holds this
+file". Do not edit anyway, and do not "just fix one line" — a clobbered decision looks exactly
+like a decision.
 
 Claude Code's `PreToolUse` hook runs this for you. Elsewhere nothing does.
 
 ## Reserving an id
 
-Reading a "Next free ID" line is not reserving it — two agents read the same number and
-both use it.
+Reading a "Next free ID" line is not reserving it — two agents read the same number and both
+use it.
 
 ```bash
 python3 "$SKILL_DIR/scripts/agent_sync.py" reserve DEC   # → DEC-0216
 ```
 
-Allocation is positional over the **merged** log — every shard, never just this run's —
-so every agent computes the same answer. Reserved and not written to git? `release-id`
-it, or the number is a hole the board reports as a leak.
+Allocation is positional over the **merged** log — every shard, never just this run's — so
+every agent computes the same answer. Reserved and not written to git? `release-id` it, or the
+number is a hole the board reports as a leak.
 
 ## Nothing in a log is ever edited or deleted
 
-Logs are **replayed in order**, so an edit silently rewrites a conclusion other agents
-already acted on. Correct by **appending**: release a lease, `release-id` an unused id,
-supersede a wrong as-built entry with a later one. Generated pages are the only
-exception, and one that lost its `agent-sync:generated` marker is **refused**, not
-overwritten. Lifetimes: `references/two-sources.md`.
+Logs are **replayed in order**, so an edit silently rewrites a conclusion other agents already
+acted on. Correct by **appending**: release a lease, `release-id` an unused id, supersede a
+wrong as-built entry with a later one. Generated pages are the only exception. Lifetimes and
+the generated-object contract: `references/two-sources.md`.
 
 ## Two documentation sources, and the duty to reconcile them
 
-Git docs answer **how it should be**; the as-built record answers **how it actually
-is**. Neither outranks the other, because they answer different questions — and
-**the gap between them is the finding**, not a defect.
+Git docs answer **how it should be**; the as-built record answers **how it actually is**.
+Neither outranks the other, and **the gap between them is the finding**, not a defect.
 
 The duty runs at both ends of a task: `reconcile` and resolve every divergence before
-starting, then `record` and `reconcile` again after finishing. Building on an
-unresolved divergence is writing code against a system that does not exist.
+starting, then `record` and `reconcile` again after finishing. Building on an unresolved
+divergence is writing code against a system that does not exist.
 
-**The trap: `reconcile` is mechanical and refuses to judge** whether the built thing
-matches the document — it compares ids, commits and presence. That reading is yours,
-and treating its green as agreement is how a divergence survives both ends.
+**The trap: `reconcile` is mechanical and refuses to judge** whether the built thing matches
+the document — it compares ids, commits, presence and claim tags. That reading is yours, and
+treating its green as agreement is how a divergence survives both ends.
 
-Every project also carries a **generated snapshot** of its own wiring (`setup`) — commit
-it and link it from the agent instructions, so agents read the pipeline instead of
-inferring it.
+Every project also carries a **generated snapshot** of its own wiring (`setup`) — commit it
+and link it from the agent instructions, so agents read the pipeline instead of inferring it.
 
-**Read `references/two-sources.md`** before the first reconcile, and whenever deciding
-which side a document belongs on: it carries what each side is for, what `reconcile`
-decides, why the check is a ratchet, where a document belongs, and why nothing is
-deleted.
+**Read `references/two-sources.md`** before the first reconcile, and whenever deciding which
+side a document belongs on.
 
 ## Binding to task-pipeline
 
-This skill supplies stages; the names are `task-pipeline`'s own.
-
-Five of the eleven stages carry an ordering rule: **0** `acquire` before the brief is
-committed; **1** `reconcile` before writing code; **3** `reserve` every id before it
-reaches git; **9** the main write point; **10** `merge` or `release` every lease.
+This skill supplies stages; the names are `task-pipeline`'s own. Five of the eleven stages
+carry an ordering rule: **0** `acquire` before the brief is committed; **1** `reconcile` before
+writing code; **3** `reserve` every id before it reaches git; **9** the main write point;
+**10** `merge` or `release` every lease.
 
 **Read `references/pipeline-binding.md`** when wiring `pipeline.json` — it holds the
 per-stage reasoning, the `skills[]` entries, what must be guarded, and the gate
@@ -326,41 +305,17 @@ the collection id to paste beside it. Found here, or in a superproject, or where
 set -a && . ./.env.agent-sync && set +a
 ```
 
-Never write a host name or token into the config, a test, an example or a commit. Do not
-handle a token value, echo it, or pass it in `argv`. If the operator offers one in chat,
-tell them to put it in that file instead.
+Never write a host name or token into the config, a test, an example or a commit; never
+handle, echo or `argv`-pass a token value. Offered one in chat, point at that file instead.
 
 **A submodule's config declares only its own registers.** Cross-repository facts belong to
 the parent; a service repo listing the parent's decision register is a config defect.
 
-## Backends
-
-| Backend | Read when |
-|---|---|
-| `outline` | `references/backend-outline.md` — before any Outline call |
-| `fs` | `references/backend-fs.md` — local files, no shared awareness |
-
-**Read `references/adapter-contract.md` before adding a backend** — six primitives, the
-capability flags, and a degradation path that must be honest.
-
-## Generated objects
-
-The board and the mirror are machine-written. Their first line is
-
-```
-<!-- agent-sync:generated source=<repo>@<sha> at=<iso8601> — edit in git, not here -->
-```
-
-A write to an object missing that marker is refused, not forced. If a human took over a
-generated page, report it and stop.
-
-The mirror is a **rendering** of git, stamped with the source commit. It has no
-authority. When its stamp and `HEAD` disagree, the board gate fails — that is
-drift, not a formatting problem.
-
 ## Non-negotiables
 
 - Append, read back, then act. Never rewrite a coordination document.
+- A generated object without its `agent-sync:generated` marker is **refused**, not
+  overwritten — a human took it over. Contract: `references/two-sources.md`.
 - `release` what you `acquire`, on every path including failure.
 - A run reports what it leaves behind: expiry ends a lease, not the file — `residue`.
 - Credentials never reach `argv`, a log line, or the repository.
@@ -375,16 +330,15 @@ Each file is loaded on its own trigger, not by default.
 
 | File | Read it when |
 |---|---|
-| `references/adapter-contract.md` | adding or auditing a knowledge backend |
+| `references/adapter-contract.md` | adding or auditing a knowledge backend — six primitives, the capability flags, an honest degradation path |
 | `references/lease-protocol.md` | changing acquisition, expiry, stealing or id allocation |
 | `references/backend-outline.md` | making any Outline API call, or debugging one |
 | `references/backend-fs.md` | running without a cloud backend, or explaining degraded mode |
 | `references/pipeline-binding.md` | wiring `pipeline.json`, or adding a stage hook |
 | `references/hooks.md` | installing, debugging or removing the Claude Code hooks |
-| `references/two-sources.md` | before the first reconcile, or when deciding where a document belongs |
+| `references/two-sources.md` | before the first reconcile, deciding where a document belongs, or writing a generated object |
 | `references/roadmap.md` | configuring `claimTags`, taking or closing a task, or re-planning a board |
 | `references/branching.md` | starting work that will produce commits, merging a branch, or asking what landed while you were away |
 | `references/earned-rules.md` | asking why identity resolves the way it does, or why `finish` exists |
 
-If this copy arrived without `references/`, fetch them from
-`https://raw.githubusercontent.com/ssheleg/agent-sync/main/plugins/agent-sync/skills/agent-sync/references/<file>`.
+Missing `references/`? Fetch from `https://raw.githubusercontent.com/ssheleg/agent-sync/main/plugins/agent-sync/skills/agent-sync/references/<file>`.

package/plugins/agent-sync/skills/agent-sync/references/lease-protocol.md

@@ -112,6 +112,21 @@ renewed in between.
 
 The tool reports which guarantee is in force; it never implies the stronger one.
 
+**Residue in this mode is on the remote, and the enumerating read goes there.** The local
+directory holds a *note* — `_note_local` writes one only for the run that won the key on
+this machine — so a ref won elsewhere leaves nothing to walk, and for a while `residue`
+could print `nothing on disk` over an expired lease sitting on the remote. That is the one
+shape a residue report must never take. `residue` and `reap` now sweep
+`refs/agent-sync/leases/*` on the configured remote and classify each ref with **the same
+classifier the local plane uses**, because whose lease this is must have one definition.
+`reap` deletes with the same `--force-with-lease=<ref>:<sha>` compare-and-swap `release`
+uses, and proves the ref went by re-reading `ls-remote` — a push's exit code is the wish,
+the second read is the state.
+
+**A remote that cannot be reached is `COULD NOT LOOK`, never an empty sweep.** The two read
+identically to an operator and mean opposite things, so they are printed differently and
+`reap` exits non-zero on the first.
+
 ## Expiry and stealing
 
 A lock is expired when `now > ts + ttl` for the timestamp inside it.
@@ -182,6 +197,28 @@ only thing that removes any of it. The split between the two kinds is the mechan
 In doubt the answer is `ambiguous`, never `reapable`. A classifier that resolves doubt by
 deleting is worse than none, because it deletes under a claim of authority.
 
+**And that has a consequence the classifier cannot fix: nobody could ever clear an
+`ambiguous` lock.** A shell with no session id answers to the shared identity, so a
+matching run id proves nothing, so the lock is `ambiguous`, so no run reaps it — for ever.
+28 of them had accumulated on this machine by 2026-08-20, the oldest overdue by 21 days
+against a 2700-second TTL, every one of them correctly refused.
+
+`reap --i-own-this <key>` is the way out, and it is a **person's** decision rather than a
+run's proof. M-50 forbids a RUN from deleting what it cannot establish; it does not forbid
+an operator from deciding. Three things keep it a decision instead of a sweep:
+
+* **named keys, and it refuses to run without them** — a blanket override is the sweep the
+  classifier exists to refuse, wearing a flag. Use `--` before a key that starts with a
+  dash: the tool slugifies guarded-file paths into keys like
+  `-claude-plugin-marketplace-json`, and a key the tool writes must be a key the tool can
+  address;
+* **it refuses a LIVE lease** — residue is what it clears, and a live lease belongs to a run
+  that may still be working;
+* **it prints the payload it destroyed** — run, timestamp, machine, how long expired — and
+  journals the decision where a record plane is configured. The classifier's verdict is
+  printed unchanged beside it, because the override does not make the lock provably yours;
+  it makes the deletion attributable.
+
 **Teardown is verified by re-reading the state, never by the delete's return value.**
 `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, another process recreating the

package/plugins/agent-sync/skills/agent-sync/references/two-sources.md

@@ -130,6 +130,16 @@ Generated pages are the exception, and a narrow one: they are rewritten wholesal
 page whose first line has lost its `agent-sync:generated` marker is **refused** rather
 than overwritten, because a human took it over.
 
+**The marker itself.** The board and the mirror are machine-written, and their first line is
+
+```
+<!-- agent-sync:generated source=<repo>@<sha> at=<iso8601> — edit in git, not here -->
+```
+
+A write to an object missing it is refused, not forced; report the takeover and stop. The
+mirror is a **rendering** of git stamped with the source commit, and has no authority — when
+its stamp and `HEAD` disagree the board gate fails, and that is drift, not formatting.
+
 **Growth.** These logs are small — one line per event — so rotation is not urgent. When a
 log does need trimming, archive the whole document and start a fresh one with a `base`
 line carrying the current allocation state. Never delete lines from a live log to shrink

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.14.0"
+VERSION = "1.16.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -847,6 +847,34 @@ 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]:
@@ -872,8 +900,8 @@ def classify_lock(key: str, raw: str, *, rid: str, identity_is_strong: bool,
       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 the git lease mode, absent
-      in local mode, where the lease is machine-local by construction — is this machine.
+    - 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
@@ -1018,6 +1046,7 @@ class Sync:
         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:
@@ -1284,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:
@@ -1509,6 +1544,102 @@ class Sync:
         """
         return bool(self.identity[0])
 
+    # -- the git plane's own enumerating read (AS-01a) -------------------------
+
+    def _git_lease_refs(self) -> tuple[list[tuple[str, str]], str | None]:
+        """Every lease ref on the remote as (sha, key), or the reason it could not look.
+
+        The authority in git mode is `refs/agent-sync/leases/*` on the remote, and a ref
+        won on another machine leaves NO local note — `_note_local` only fires for the run
+        that won it here. So the local directory walk cannot see it, and for a while
+        `residue` could print `nothing on disk` over an expired lease sitting on the
+        remote. That is the one shape a residue report must never take.
+
+        The failure is returned rather than raised, because the caller has to be able to
+        say `could not look` instead of `nothing there`.
+        """
+        remote = self._git_remote()
+        r = subprocess.run(["git", "ls-remote", remote, "refs/agent-sync/leases/*"],
+                           capture_output=True, text=True)
+        if r.returncode != 0:
+            why = (r.stderr or r.stdout or "").strip().splitlines()
+            return [], (why[-1] if why else f"`git ls-remote {remote}` failed")
+        out = []
+        for line in r.stdout.strip().splitlines():
+            parts = line.split()
+            if len(parts) != 2 or not parts[1].startswith("refs/agent-sync/leases/"):
+                continue
+            out.append((parts[0], parts[1].rsplit("/", 1)[-1]))
+        return out, None
+
+    def _git_lease_payload(self, sha: str) -> str:
+        """The lease object's body — the same JSON the local note carries.
+
+        One shape for both planes, so `classify_lock` is the only classifier in this file.
+        A second one would be a second definition of *whose lease this is*, which is the
+        question the whole tool exists to answer once.
+        """
+        body = git("log", "-1", "--format=%B", sha)
+        if body:
+            return body.strip()
+        # The object may not be local yet: the ref lives on the remote.
+        subprocess.run(["git", "fetch", "-q", self._git_remote(), sha],
+                       capture_output=True, text=True)
+        return (git("log", "-1", "--format=%B", sha) or "").strip()
+
+    def git_residue(self) -> tuple[list[dict[str, Any]], str | None]:
+        """The git plane, classified by the same rules as the local one."""
+        refs, why = self._git_lease_refs()
+        if why is not None:
+            return [], why
+        now, host, repo = time.time(), platform.node(), repo_name()
+        out: list[dict[str, Any]] = []
+        for sha, key in sorted(refs, key=lambda x: x[1]):
+            raw = self._git_lease_payload(sha)
+            if raw:
+                entry = classify_lock(key, raw, rid=self.rid,
+                                      identity_is_strong=self.identity_is_strong,
+                                      repo=repo, host=host, default_ttl=self.ttl, at=now)
+            else:
+                entry = {"key": key, "state": AMBIGUOUS, "run": None, "repo": None,
+                         "host": None, "ts": "", "expired_for": None,
+                         "why": "the lease object carries no readable payload"}
+            entry["plane"] = "git"
+            entry["ref"] = self._ref(key)
+            entry["sha"] = sha
+            entry["path"] = None
+            out.append(entry)
+        return out, None
+
+    def git_reap(self, entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Delete a reapable lease ref, and prove it went by looking again.
+
+        Same compare-and-swap `_git_release` uses: `--force-with-lease=<ref>:<sha>` refuses
+        if somebody won the key between the read and the delete, which is the whole reason
+        the sha travels with the entry. And the verdict comes from a second `ls-remote`,
+        not from the push's exit code — a teardown that reports success out of its own
+        return value is reporting the wish rather than the state.
+        """
+        done: list[dict[str, Any]] = []
+        for e in entries:
+            r = subprocess.run(["git", "push", self._git_remote(),
+                                f"--force-with-lease={e['ref']}:{e['sha']}",
+                                f":{e['ref']}"], capture_output=True, text=True)
+            after, why = self._git_lease_refs()
+            still = {k for _s, k in after}
+            if why is not None:
+                e["gone"] = None
+                e["why_gone"] = f"could not re-read the remote to prove it went ({why})"
+            elif e["key"] in still:
+                e["gone"] = False
+                e["why_gone"] = ((r.stderr or "").strip().splitlines() or
+                                 ["the ref is still on the remote"])[-1]
+            else:
+                e["gone"] = True
+                e["why_gone"] = ""
+            done.append(e)
+        return done
+
     def residue(self) -> list[dict[str, Any]]:
         """Every lock file in this checkout, classified — the live ones included.
 
@@ -1593,6 +1724,87 @@ class Sync:
         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 = []
@@ -2015,7 +2227,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,
@@ -2057,14 +2302,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():
@@ -2092,6 +2341,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 ---------------------------------
@@ -2231,6 +2489,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
 
@@ -2775,6 +3042,26 @@ def cmd_status(_args: argparse.Namespace) -> int:
         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
@@ -2820,7 +3107,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}")
 
@@ -2952,9 +3239,8 @@ def cmd_residue(_args: argparse.Namespace) -> int:
     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 on disk — no lease has been taken in this checkout, or every one "
-              "was released")
-        return 0
+        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']}"
@@ -2964,21 +3250,79 @@ def cmd_residue(_args: argparse.Namespace) -> int:
         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)]
-    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")
+    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. The sweep, and the disclosure is now about what it COULD NOT reach rather
+    # than about a plane nobody read. A check that cannot look must not read as one that
+    # looked — and a check that CAN look must not keep printing that it cannot.
+    if s.lease_mode == "git":
+        remote = s.cfg.get("leaseRemote") or "origin"
+        refs, why = s.git_residue()
+        print(f"\n  git plane · {remote} · refs/agent-sync/leases/*")
+        if why is not None:
+            print(f"    ⚠ COULD NOT LOOK — {why}")
+            print("    So this is not an empty sweep: the refs may be there and unread. "
+                  "Fix the remote, or")
+            print(f"    enumerate by hand: git ls-remote {remote} "
+                  "'refs/agent-sync/leases/*'")
+        elif not refs:
+            print("    no lease refs on the remote — swept and empty, not unread")
+        else:
+            local_keys = {e["key"] for e in entries}
+            reapable = [e for e in refs if e["state"] == REAPABLE]
+            for e in refs:
+                also = " · also noted locally" if e["key"] in local_keys else ""
+                print(f"    · {e['key']}  [{e['state']}]{also}")
+                print(f"      ref   : {e['ref']} @ {e['sha'][:10]}")
+                if e.get("run"):
+                    print(f"      run   : {e['run']}"
+                          + (f" · host {e['host']}" if e.get("host") else ""))
+                # `spent()` says this once for both planes: a second phrasing here is a
+                # second definition of what residue means.
+                print(f"      state : {spent(e)}")
+                if e.get("why"):
+                    print(f"      why   : {e['why']}")
+                if e["state"] == REAPABLE:
+                    print(f"      clear : agent_sync.py reap {e['key']}")
+            print(f"    {len(refs)} ref(s) on the remote, {len(reapable)} this run can prove "
+                  "it owns and has spent")
     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()
+    if getattr(args, "own", False):
+        return _reap_by_operator_decision(s, args.keys)
     result = s.reap(args.keys or None)
     for e in result["reaped"]:
         print(f"  reaped {e['key']} — {e['why']}, confirmed gone by re-reading "
@@ -2993,9 +3337,116 @@ def cmd_reap(args: argparse.Namespace) -> int:
     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"]:
+    # AS-01a. The git plane is a second place residue lives, and until this it was a
+    # second place nothing could clear: `reap` walked the lock directory only, so an
+    # expired ref this run had won stayed on the remote with no command able to reach it.
+    git_bad = 0
+    if s.lease_mode == "git":
+        refs, why = s.git_residue()
+        remote = s.cfg.get("leaseRemote") or "origin"
+        if why is not None:
+            print(f"  ⚠ the git plane could not be read ({why}) — its refs are "
+                  "neither reaped nor reported clean.", file=sys.stderr)
+            print(f"    Enumerate by hand: git ls-remote {remote} "
+                  "'refs/agent-sync/leases/*'", file=sys.stderr)
+            git_bad = 1
+        else:
+            named = set(args.keys or [])
+            want = [e for e in refs if e["state"] == REAPABLE and (not named or e["key"] in named)]
+            for e in s.git_reap(want):
+                if e["gone"]:
+                    print(f"  reaped {e['key']} on {remote} — {e['why']}, confirmed gone by "
+                          "re-reading the remote")
+                else:
+                    print(f"  ✗ {e['key']} is STILL on {remote} after the delete "
+                          f"({e['why_gone']}) — the compare-and-swap refused, which means "
+                          "somebody won it between the read and the delete",
+                          file=sys.stderr)
+                    git_bad = 1
+            for e in refs:
+                if e["state"] != REAPABLE and (not named or e["key"] in named):
+                    print(f"  · {e['key']} [{e['state']}] on {remote} left alone — {e['why']}")
+            if not refs:
+                print(f"  no lease refs on {remote} — swept and empty, not unread")
+    if not result["reaped"] and not result["remaining"] and not result["refused"] \
+            and s.lease_mode != "git":
         print("  nothing this run can prove it owns and has spent — nothing reaped")
-    return 1 if result["remaining"] or result["refused"] else 0
+    return 1 if (result["remaining"] or result["refused"] or git_bad) else 0
+
+
+def _reap_by_operator_decision(s: "Sync", keys: list[str]) -> int:
+    """`--i-own-this` — the one path that clears state no RUN can prove is its own.
+
+    AS-01b. The classifier is right to refuse: a run whose identity is the shared fallback
+    cannot prove a matching run id means anything, so every such lock is `ambiguous` and
+    nothing reaps it. The consequence is that expired locks accumulate with no path out for
+    anybody — 28 of them on this machine by 2026-08-20, the oldest overdue by 21 days
+    against a 2700-second TTL.
+
+    M-50 forbids a RUN from deleting what it cannot prove. A person deciding, per key, is
+    not a run guessing — so the decision is available, and three things make it a decision
+    rather than a sweep:
+
+    * **it takes named keys and refuses to run without them.** A blanket override is the
+      thing the classifier exists to prevent, wearing a flag;
+    * **it refuses a LIVE lease.** Residue is what this clears; a live lease belongs to a
+      run that may still be working, and taking it by hand is the collision the tool exists
+      to prevent;
+    * **it prints the payload it destroyed** — run, timestamp, machine — so the decision is
+      auditable afterwards by somebody who was not there, and journals it where a record
+      plane is configured.
+    """
+    if not keys:
+        print("reap --i-own-this needs the keys, one or more, by name.\n"
+              "  A blanket override is the sweep the classifier exists to refuse, wearing a "
+              "flag.\n"
+              "  `agent_sync.py residue` lists what is there and why each one is unclearable.",
+              file=sys.stderr)
+        return 2
+
+    by_key = {}
+    for e in s.residue():
+        by_key.setdefault(e["key"], e)
+        by_key.setdefault(s._local_lock(e["key"]).stem, e)
+
+    rc = 0
+    for k in keys:
+        e = by_key.get(k) or by_key.get(s._local_lock(k).stem)
+        if e is None:
+            print(f"  · {k} — there is no lock by that name in this checkout", file=sys.stderr)
+            rc = 1
+            continue
+        if e["state"] == LIVE:
+            print(f"  ✗ {e['key']} is LIVE under {e.get('run') or 'a run'}"
+                  f"{' on ' + e['host'] if e.get('host') else ''} — not cleared. An override "
+                  "is for residue;\n    a live lease belongs to a run that may still be "
+                  "working. Ask the holder, or wait for the TTL.", file=sys.stderr)
+            rc = 1
+            continue
+        had = (f"run {e.get('run') or 'unknown'}"
+               f"{' · host ' + e['host'] if e.get('host') else ''}"
+               f"{' · ' + e['ts'] if e.get('ts') else ''}"
+               f" · {spent(e)}")
+        try:
+            e["path"].unlink()
+        except OSError as exc:
+            print(f"  ✗ {e['key']} could not be removed ({exc})", file=sys.stderr)
+            rc = 1
+            continue
+        # Proved gone by looking again, the same rule the ordinary reap follows.
+        if any(x["key"] == e["key"] for x in s.residue()):
+            print(f"  ✗ {e['key']} is STILL PRESENT after the delete — the teardown was not "
+                  "verified, whatever the call returned", file=sys.stderr)
+            rc = 1
+            continue
+        print(f"  cleared {e['key']} by operator decision — it held {had}")
+        print(f"    the classifier called it `{e['state']}`, and that has not changed: this "
+              "was a person's\n    call, not a proof of ownership.")
+        try:
+            s.journal(f"reap --i-own-this {e['key']} — was {had}, classified {e['state']}")
+        except Exception:                                # noqa: BLE001 - the record plane is optional
+            pass
+    return rc
 
 
 def cmd_journal(args: argparse.Namespace) -> int:
@@ -4096,6 +4547,10 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument("--i-own-this", action="store_true", dest="own",
+                    help="clear the NAMED expired locks even though this run cannot prove "
+                         "they are its own — an operator's decision, per key, recorded. "
+                         "Refuses a live lease and refuses to run with no key.")
     rp.set_defaults(fn=cmd_reap)
 
     g = sub.add_parser("guard", help="may this run write that path? exit 2 = no")