@ssheleg/agent-sync 1.4.3 → 1.7.1

package/CHANGELOG.md

@@ -1,3 +1,403 @@
+## v1.7.1
+
+**A second audit, along a different axis: not whether the tool keeps its promises, but whether an
+agent reading this skill can follow it and get a correct result.** The scenarios were executed, not
+imagined — cold start, the whole adoption chain, the per-task cycle, two agents contending for one
+task, every hook with a realistic payload, and the edges (no git repository, uninitialised project,
+absolute paths, `git -C <dir> commit`). The coordination core came through clean. What did not was
+everything the agent *reads*.
+
+### The documents the tool generates were two versions behind the doctrine it teaches
+
+`setup` writes the snapshot every agent is told to read first — *"it states how documentation and
+coordination work here"* — and `scaffold` seeds `AGENTS.md`. Neither mentioned a branch or `merge`
+even once. Both prescribed a cycle ending in `release`, and the snapshot stated *"the claim tag in
+git is written through"* as an unconditional fact, which has been false on any branch since 1.4.0 —
+the branch being where the doctrine says the work belongs.
+
+So an agent doing exactly what the skill instructs — trust the generated snapshot — got the
+workflow from two releases ago. Regenerating did not help: the generator was what was stale. Both
+now carry the branch rule, `merge --key`, and this project's integration branch by name.
+
+`AGENTS.md` stopped restating the cycle altogether. It is seeded once and **never overwritten**, so
+a copy of the protocol there is frozen on the day the project was created while the tool moves on —
+and every project scaffolded before today would have kept the old one forever. It now points at the
+snapshot, which is regenerable and which `check` fails on when it goes stale. One fact, one home.
+
+### `check` blessed a project an agent cannot work in
+
+A configuration declaring `idRegisters` on a backend whose `reserve` always raises passed as
+`setup healthy`. `check`'s own promise is that it refuses a rule pointing at what is not there, and
+a register nobody can allocate from is exactly that — while the snapshot it generates instructs
+every agent to run `agent_sync.py reserve DEC`, which cannot succeed there. It is now a problem,
+named with both ways out.
+
+### The slash command offered a verb the CLI does not have
+
+`argument-hint` advertised `claim <KEY>` and the README showed `/agent-sync claim ASC-072`. The
+command is `acquire`; `claim` is an `invalid choice`. First thing an agent reads, first thing it
+types.
+
+### `$SKILL_DIR` was used in every example and defined nowhere
+
+Six invocations tell the agent to run `python3 "$SKILL_DIR/scripts/agent_sync.py"`, and the only
+explanation was the prose *"this skill's own directory"*. Nothing gave a value. The Cursor rule
+names a concrete path; the skill body now names both — `${CLAUDE_PLUGIN_ROOT}/skills/agent-sync`
+and `~/.agents/skills/agent-sync`.
+
+### What the audit found working
+
+Worth recording, because a report that only lists faults says nothing about the rest: two agents
+contending for one task behave correctly end to end — the second loses, sees who holds it and in
+which repository, is denied the guarded file, and cannot release a lease it does not hold. The
+guard denies `Edit`, `Write`, `NotebookEdit` and absolute paths, and blocks `git commit`,
+`git -C <dir> commit` and `cd <dir> && git commit` when a guarded file is staged, while letting
+`git log --grep=commit` and malformed JSON through. `SessionStart` stamps the identity and prints
+the awareness block; `SessionEnd` releases. The adoption chain works with and without a pre-existing
+`docs/`. An uninitialised project and a non-git directory both answer with the next action and a
+non-zero exit.
+
+### New checks
+
+`check_every_advertised_verb_exists`, `check_generated_docs_carry_current_doctrine`,
+`check_registers_need_a_backend_that_can_reserve`, `check_skill_gives_a_resolvable_script_path` —
+with four more self-test fixtures. The validator now plants and catches 32 distinct defects.
+
+## v1.7.0
+
+**Observability, honest degradation, and the removal of things that were never load-bearing.**
+1.5.3 stopped the tool saying untrue things; 1.6.0 made its guarantees hold. This closes the
+remaining findings from the 2026-08-10 audit — each one a place where the tool was quiet rather
+than wrong, which is the harder failure to notice.
+
+### `status` and `check` gave two answers about one project
+
+`status` printed `NEXT: acquire a lease` and exited 0 on a setup `check` called NOT healthy — a
+guard pattern matching no file, a snapshot nobody links, an env file tracked by git. `status` is
+the command every session runs and the only one most agents ever read, so anything it stays quiet
+about is effectively unreported.
+
+The validation now lives in one function, `check_setup()`, which both commands call. `status`
+prints the count, the first four problems and one next action; `check` prints the whole list.
+
+### Credentials were adopted from anywhere above the project
+
+`find_env_file` walked every parent directory until something matched, so a stray
+`.env.agent-sync` in a home or work directory silently configured every project beneath it and
+pointed them all at one collection — a coordination plane shared by projects with nothing to do
+with each other. A found file looks exactly like a configured one, so nothing reported it.
+
+The search is now `AGENT_SYNC_ENV` if set, then this repository, then each **superproject** in
+turn — a tree git can vouch for, which is the case the walk existed to serve. `check` prints which
+file is in force and says when it comes from outside the repository.
+
+### "New since you last looked" lost entries that arrived out of order
+
+The watermark was an index into a list re-sorted on every read. An entry appended with an earlier
+timestamp — clock skew, or a shard that was briefly unreachable — lands before the mark, shifts
+everything after it, and is never reported; the slice returns an entry already seen instead. The
+one section of `status` whose job is to announce what changed went quiet about exactly the change
+that arrived late.
+
+Entries are now remembered by identity, capped at 500, with a floor timestamp covering only what
+fell out of that window — set only when something actually did, or the fix would have re-created
+the bug in a new shape.
+
+### `merge` released every lease the run held
+
+The documentation says it releases the lease; it released all of them, quietly freeing work that
+had not landed. It now releases the one named by `--key`, and says what it left held.
+
+### An `acquire`/`release` round-trip left a diff
+
+`SKILL.md` promises `git diff` empty afterwards. The claimed row was rebuilt from its cells, so
+indentation and the original line ending were dropped — an unexplained change to a shared registry
+file, which is the one kind of file agents are told never to touch casually. The bytes outside the
+edited cell are now carried through rather than reconstructed.
+
+### Declarations that were never load-bearing
+
+`LOGS` carried a `blockers` document nothing wrote and nothing read, so a reader looking for
+blockers found an empty page and concluded there were none. `_held_legacy` and
+`Adapter.is_exclusive` had no callers. `Sync.settle` was computed and never used —
+`settleSeconds` stays in the schema for a backend that must wait for writes to become visible,
+and `check` now says plainly that nothing shipped reads it.
+
+`os.uname()` and a literal `/dev/null` are gone in favour of `platform.node()` and `os.devnull`;
+the coordinator now runs wherever python3 does, and only the enforcement hooks need bash.
+
+### The setup verdict sat behind the task-pipeline gate
+
+`status` checked for `task-pipeline` and returned before it ever reported on the project. On any
+machine without the dependency installed — every CI runner — a project defect was therefore
+invisible: the command exited non-zero for a reason that had nothing to do with it. The order is
+now project first, machine second, because one is a fact about the repository everyone shares and
+the other is a fact about the box you happen to be on.
+
+Found by CI, on the release run for this very version, against a check that had passed locally
+all day — and the check has been tightened to assert the problem is *named*, not merely that the
+exit code is non-zero.
+
+### Three tagged releases never reached npm
+
+`v1.5.0`, `v1.5.1` and `v1.5.2` each pushed a tag, ran the release workflow, and failed at the same
+step: *"no CHANGELOG section for 1.5.2"*. The extraction matched `## 1.5.2` while this file writes
+`## v1.5.2` — a heading style that changed at 1.4.x and a workflow that did not. The registry sat
+three releases behind while every tag looked delivered, and the failure lived in the one place CI
+never runs on `main`.
+
+Both patterns now accept the `v` prefix — the stop pattern too, or the notes run to the bottom of
+the file — and `check_release_notes_are_extractable` runs the workflow's **own** awk program,
+lifted out of the YAML, against the current version. A release that cannot be described now fails
+on `main`, before the tag.
+
+### New checks
+
+`check_status_reports_the_setup_verdict`, `check_env_discovery_is_bounded`,
+`check_watermark_survives_a_late_entry`, `check_no_orphan_logs`, `check_no_dead_declarations`,
+`check_claim_round_trip_is_byte_exact` — with six more self-test fixtures. The validator now
+plants and catches 27 distinct defects.
+
+## v1.6.0
+
+**Four guarantees that were described but not delivered, and the one number now stated once.**
+1.5.3 stopped the tool reporting things that were untrue; this release makes the properties it
+claims actually hold, each with a check that has been watched fail against the defect it exists to
+catch.
+
+### Stealing an expired lease had a window two runs could both pass through
+
+`unlink` then `O_EXCL create` are two operations. A second stealer that has already read the lock
+as expired removes the lock the first one just created, and both then hold what each believes is an
+exclusive lease. Twelve racing processes never exposed it — with a 300 ms delay injected between the
+two calls, two of two won, and in production that delay is an ordinary scheduler hiccup.
+
+The reap and the create are now one critical section: `<key>.lock.steal` is created with `O_EXCL`,
+the expiry is re-read **inside** it (the holder may have renewed; another stealer may have finished),
+and the section carries a 30-second abandonment grace, because without one a crash between two
+filesystem calls costs the key until a human deletes a file nobody documents.
+
+This mattered more after 1.5.3 than before it: with `renew` finally refreshing leases, the steal path
+stops being the common case — but for four versions every long task went through it.
+
+### `merge` measured one base and merged into another
+
+Conflicts and the diff were computed against `origin/<target>`; the merge was made into the **local**
+`<target>`, which nothing advances. So `merge` printed the staleness it had just measured — `main
+moved: 1 commit(s)` — then `✓ merged as …`, wrote a merge-log entry, released the lease, and the push
+was rejected as non-fast-forward. The work had not landed, `docs/MERGES.md` said it had, and the task
+was free for somebody else to take.
+
+The local integration branch is now fast-forwarded to its upstream before anything else, so the
+preflight and the merge share a base. One that has genuinely diverged cannot be fast-forwarded and is
+refused, with both counts named.
+
+### One glob meant two things
+
+The guard matched with `Path.match`, which anchors at the **right**: with `docs/DECISIONS.md` in
+`guardedFiles`, an edit to `vendor/docs/DECISIONS.md` was denied — a file `check` never enumerated
+and never validated, protected by a rule nobody wrote. In the other direction `Path.match` does not
+walk `**` before Python 3.13, so `docs/**/*.md` guarded less than `check` reported. A pattern that
+means two things means nothing. Both commands now resolve patterns through one function, anchored at
+the repository root.
+
+### The 2% rule was a constant nothing read
+
+`MAX_UNPARSEABLE` was declared in 1.0.0 and never referenced. `SKILL.md`, `lease-protocol.md` and the
+README all stated that a log past the threshold stops the run; the only implementation was a warning
+line on the board that returned 0. Every reader now refuses a log past the limit and names the ratio,
+so `status`, `board`, `check`, `reconcile` and `reserve` stop rather than replaying a partial history
+— which reports holders who do not exist and silence where the real ones are, both of which look like
+an answer.
+
+`acquire` is deliberately not in that list, and the documents now say so: a lease is decided by the
+lock or the ref, never by the log, so a corrupt log cannot make one look lost.
+
+### The stage binding said three different things
+
+`SKILL.md` announced "four of the eleven stages" and listed five (0, 1, 3, 9, 10); the README named
+0, 3, 4, 5, 9 and 10; `pipeline-binding.md` agreed with the README and separately called stage 1
+*"nothing shared to coordinate"* — the stage `reconcile` belongs to, and the one the tool's own
+doctrine says must resolve every divergence before code is written. An agent wiring `pipeline.json`
+from any one of the three got a pipeline missing a rule.
+
+The numbers now live in a marker in `pipeline-binding.md` — `rules=0,1,3,9,10`,
+`wired=0,1,3,4,5,9,10` — the two lists answer two different questions instead of being conflated,
+stage 1 has its row and its `pipeline.json` entry, and a check fails when a surface stops agreeing.
+
+### New checks
+
+`check_steal_is_atomic`, `check_merge_refuses_stale_target`, `check_guard_and_check_agree_on_globs`,
+`check_unparseable_log_fails_loudly`, `check_stage_binding_agrees` — plus five self-test fixtures
+planting each defect back.
+
+## v1.5.3
+
+**Five surfaces told the caller something that was not true.** An audit on 2026-08-10 ran the
+commands instead of reading them, and every finding below was reproduced before it was fixed. The
+validator was green throughout — which is the finding behind the findings, and the reason this
+release ships six new checks that drive the tool rather than its functions.
+
+### `reserve` handed three runs the same id
+
+`reserve` replayed `log_id("reservations")` — the document **this run writes**. Every other run's
+shard was invisible to it, so three runs each saw an empty history, each seeded a `base` from the
+register, and each was handed `DEC-0007`. Measured, three processes, one number.
+
+The pure allocator was correct and tested; nothing ever asked it about the whole log. This is the
+same failure that disqualified per-writer documents as a *lease* store in 1.0.0 — eight processes
+reading only their own shard, eight winners — arriving in the allocation path, where the tested
+unit hid it. Allocation now runs over the merged log.
+
+Merging alone would have replaced one collision with another: two runs opening a register in the
+same minute both append the same seed, and a `base` that re-seated unconditionally restarts the
+count and hands the second run the id the first just took. A `base` now only ever moves allocation
+**forward**; one at or below the current position is ignored.
+
+### `renew` renewed nothing
+
+It appended `op=renew` to the record plane — which has not decided a lease since 1.0.0 — and
+touched a throttle file. The timestamp expiry is actually computed from, the one inside the lock
+(or the git ref payload), was written once, by `acquire`.
+
+So a run holding a lease lost it at TTL **while still working**: `whoami` reported `holds:
+nothing`, its own `PreToolUse` guard began denying its edits, and another run acquired the task it
+was in the middle of. With the default 2700 s, every task longer than forty-five minutes. The
+`PostToolUse` hook made no difference, because there was nothing for it to move — and from the
+record plane's side the renewals arrived exactly on schedule, so nothing looked wrong anywhere.
+`renew` now rewrites the lock in `local` mode and re-pushes the ref with `--force-with-lease`
+against the exact object it read in `git` mode.
+
+### `check` rejected the config `init` had just written
+
+`check` carried its own literal list of legal keys. `mergeLog` — written by `init` itself — and
+`integrationBranch` — in the schema, in the shipped example, read by the code — were not in it, so
+a freshly initialised project reported `config key 'mergeLog' is not in the schema — it will be
+ignored`. Both halves false: it is in the schema, and it is not ignored.
+
+That is worse than a wrong message; it is an instruction. An agent making `check` green deletes
+working configuration. The list now lives in one place, `CONFIG_KEYS`, and the validator asserts it
+equals the schema's properties exactly.
+
+### Three commands reported success they had not achieved
+
+`release-id` printed `released DEC-0007` and exited 0 on a backend that records nothing — the id
+stayed a hole the board reports as a leak, and the only party who could have fixed it had been told
+it was handled. `record` and `signal` printed success and exited 0 while stderr said the entry was
+never published. All three now fail loudly.
+
+An adapter `OSError` also walked past every `except Fail` into `main`: an unwritable state
+directory handed the agent a Python traceback as the state of the coordination plane. Store errors
+are now the tool's own failure type.
+
+### The guard named a holder who held something else
+
+A denial read `<path> is a guarded registry file and this run holds no lease — r-x holds a lease
+right now`, where `r-x` held an unrelated task. Beside a path, that sentence gets repeated as "r-x
+holds this file". The denial now names the run **and its key**, and says plainly that exit 2 is a
+statement about the asking run, not about the file.
+
+### The marketplace listing still sold the design 1.0.0 refuted
+
+`marketplace.json` — the first thing anyone reads — described coordination as "decided by replaying
+one append-only log so no backend needs compare-and-swap". That is the belief the first trap in
+`SKILL.md` exists to forbid. Rewritten, and a check now fails on the phrase.
+
+### Documentation corrected where it described behaviour that did not exist
+
+`SKILL.md` and the Cursor rule on what exit 2 means; `lease-protocol.md` on what `renew` moves and
+on the log a reader replays; the claim-tag vocabulary in `README.md` and `lease-protocol.md`, which
+showed a role where the tool writes a run id; `hooks.md` on the `NotebookEdit` matcher, on what
+`session-end.sh` actually does, and on the two timeouts that really apply.
+
+### New checks
+
+`check_reserve_is_race_free`, `check_renew_extends_the_lease`, `check_config_round_trip`,
+`check_no_success_on_failed_publish`, `check_guard_denial_names_only_what_it_knows`,
+`check_doctrine_is_current`. Each drives the real commands from more than one identity, because
+every defect above lived in the gap between two things the validator already tested separately.
+
+## v1.5.2
+
+### `reserve` handed out ids that were already written
+
+`reserve DEC` returned `DEC-0270`, then `0271`, then `0272`, in a project whose register's highest
+heading was `DEC-0281` and whose own "next free" line read `DEC-0282`. All three were occupied;
+`DEC-0270` was cited by name in another document.
+
+The counter was not stuck — it incremented on every call. It was **11 behind**. The `base` event is
+seeded once, from the register, and never consulted again. Every id written by a path that is not
+this tool — a person editing the file, another session's Doc Loop, a merge — advances the register
+and leaves the log where it was. The gap only ever grows.
+
+This inverts the mechanism. An agent that follows the protocol exactly — reserve before minting,
+never trust the register's own "next free" line, which is the rule the protocol states — is the one
+that writes a duplicate, and it is silent at the point of use: the id looks fresh, the register
+accepts a second heading with that number, and every citation to it becomes ambiguous. An agent that
+ignored the tool and read the line would have been correct. That is the worst incentive a
+coordination tool can teach.
+
+The register is now consulted on **every** reserve and treated as a **floor**: it can push the
+allocation forward, never pull it back. Ids reserved through this tool but not yet written do not
+appear in the register, so honouring the floor never revokes a live reservation. The floor is
+applied by re-basing mid-log, which the allocator now supports properly — a new `base` restarts the
+count (it previously kept serving from the old one, skipping as many ids as had been handed out) and
+drops freed ids that fall below it (the register has moved past them, so a heading exists there now,
+and recycling one is the same collision through the other door). Ids freed at or above the base are
+still reused, so the fix does not turn every release into a leak.
+
+Proven end to end against the register that exposed it: the shipped 1.5.1 returns `DEC-0273`, an
+occupied id; this build returns `DEC-0282`, then `DEC-0283`. Three assertions in `test/validate.py`,
+all watched failing against a planted revert of the allocator — 202 where 200 was due, and a freed
+`0100` handed back.
+
+Found in nicegram-business, 2026-08-09, by an agent that recognised the returned number from another
+document. That is luck, not a control, which is why the check now exists.
+
+## v1.5.1
+
+### `release` could not remove the claim it had written
+
+`acquire` writes a marker into the status cell; `release` found the row again **by searching for the
+task id**. Between the two, a run's own work can add another mention of that id — a new row, a
+cross-reference — and release then sees several candidates, refuses to guess, and leaves
+`(claimed: r-…)` in the cell **permanently**.
+
+The result is worse than no claim: a status cell advertising a live lease that nobody holds, which
+the next agent reads as an occupied file.
+
+Release now narrows by the marker before falling back to the id. The marker names *this run*, so it
+is unambiguous however many rows mention the id. Proven both ways on the same scenario — acquire
+writes the tag, a second mention is inserted, and release removes it (`claim restored`); the
+previous version leaves it behind.
+
+## v1.5.0
+
+### The commit guard was blind to `git -C <dir> commit`, and to submodules
+
+Two defects, and the second is why the first went unnoticed.
+
+**The test was a contiguous substring.** `case "$cmd" in *"git commit"*)` — and `git -C <dir> commit`
+does not contain the string `git commit`. Every commit made that way skipped the guard entirely, in
+any repository, submodule or not.
+
+**The repository was hardcoded to `CLAUDE_PROJECT_DIR`.** So even a bare `git commit` inside a
+submodule read the *umbrella's* index, found it empty, and passed: the staged files live in the
+submodule's index.
+
+Together they meant a full day of commits to guarded registers went unchecked, on 2026-08-07, while
+the Edit-tool half of the same hook refused correctly the whole time — so the protection looked
+present and was measured as present by anyone who tested it with the Edit tool.
+
+The command is now tokenised in python rather than globbed in shell: `-C`, `-c` and `--namespace`
+are consumed with their arguments, `cd <dir> &&` is honoured, each `&&`/`;`/`||` segment is examined,
+and the guard runs **from** the resolved repository — `agent_sync.py` resolves the project from
+`git rev-parse --show-toplevel` of its cwd, so a submodule gets its own `guardedFiles`.
+
+Proven against the previous version on all three forms: `git -C <sub> commit` and
+`cd <sub> && git commit` go from `rc=0` to `rc=2`, and `git log --grep=commit` stays `rc=0` — the
+tokeniser exists so that one does not become a false positive.
+
 # Changelog
 
 All notable changes to this project are documented here.

package/README.md

@@ -225,8 +225,9 @@ action:
 
 ## Everyday use
 
-In an agent session you use the slash command (`/agent-sync claim ASC-072`); the same
-commands run directly against the coordinator script, which is what the hooks and CI do:
+In an agent session you use the slash command (`/agent-sync acquire ASC-072` — the verb is
+`acquire`, the same one the CLI takes); the same commands run directly against the
+coordinator script, which is what the hooks and CI do:
 
 ```bash
 python3 "$SKILL_DIR/scripts/agent_sync.py" <command>
@@ -235,10 +236,10 @@ python3 "$SKILL_DIR/scripts/agent_sync.py" <command>
 | Command | Does |
 |---|---|
 | `init` | **Run first.** Ask where state lives, write config + gitignored env file, print your step |
-| `status` | Inspect, repair, report — including other runs' leases and signals new since you last looked |
+| `status` | Inspect, repair, report — other runs' leases, signals new since you last looked, and `check`'s verdict on the setup |
 | `bootstrap` | Create the cloud container and print the id to paste into the env file |
 | `acquire <KEY>` | Take the lease on a task id. Prints `won`, or `lost <holder>` |
-| `renew <KEY>` | Extend the lease. In Claude Code the `PostToolUse` hook does this for you |
+| `renew <KEY>` | Extend the lease — moves the timestamp expiry is computed from. In Claude Code the `PostToolUse` hook does this for you |
 | `release <KEY>` | Give the lease back. Always, including on failure |
 | `reserve <REG>` | Reserve the next id in a register (`DEC`, `OQ`, `DEP`, …). Prints the id |
 | `release-id <REG> <ID>` | Return an id you did not end up writing to git |
@@ -273,11 +274,13 @@ see who has what, and the shared roadmap does not become the file every branch e
 python3 "$SKILL_DIR/scripts/agent_sync.py" merge --key ASC-072 --summary "what landed"
 ```
 
-Conflicts are computed with `git merge-tree` **before anything is touched** — on conflict
-it names the files, changes nothing and exits non-zero, so a resolution nobody reviewed
-never reaches the integration branch. Then it merges `--no-ff`, records the merge, and
-releases every lease this run holds. `--dry-run` stops after the checks; `--push` pushes
-afterwards.
+The local integration branch is fast-forwarded to `origin/<target>` first, so the
+preflight and the merge share a base; one that has genuinely diverged is refused with both
+counts. Conflicts are then computed with `git merge-tree` **before anything is touched** —
+on conflict it names the files, changes nothing and exits non-zero, so a resolution nobody
+reviewed never reaches the integration branch. Then it merges `--no-ff`, records the merge,
+and releases the lease named by `--key`. `--dry-run` stops after the checks; `--push`
+pushes afterwards.
 
 **The merge log** — `docs/MERGES.md`, configurable via `mergeLog` — answers the question an
 agent coming back from a branch cannot answer from `git log` alone: *what landed while I
@@ -296,8 +299,9 @@ right one. Full doctrine:
 [`references/branching.md`](plugins/agent-sync/skills/agent-sync/references/branching.md).
 
 **The lease is not the claim.** The lease says who holds the task *now* and expires; the
-durable claim is the tag in git (`[name]`, `todo (claimed: <role>)`). `acquire` writes
-that tag through and `release` clears it, so one fact keeps one home.
+durable claim is the tag in git — `todo (claimed: r-7f3a91)`, rendered from the
+`claimTags.held` template, naming the **run**, not a role. `acquire` writes that tag
+through and `release` restores exactly what was there, so one fact keeps one home.
 
 ## Configuration
 
@@ -319,7 +323,12 @@ that tag through and `release` clears it, so one fact keeps one home.
 | `integrationBranch` | where work lands and the only branch a claim is written on (default: the repo's own) |
 | `mergeLog` | `file` and `retentionDays` for the merge log (default `docs/MERGES.md`, 7) |
 
-`.env.agent-sync` — gitignored, mode 600:
+`.env.agent-sync` — gitignored, mode 600. It is looked for in this repository, then in
+each **superproject** above it (so one credentials file serves a tree of submodules), and
+nowhere else. `AGENT_SYNC_ENV=/path/to/file` names one explicitly and wins over both.
+Until 1.7.0 the search continued into any parent directory, so a stray file in a home or
+work directory silently pointed every project beneath it at one collection — `check`
+now prints which file is in force, and says when it comes from outside the repository.
 
 ```
 AGENT_SYNC_BACKEND=outline
@@ -384,9 +393,11 @@ Details and removal:
 ## Where it plugs into task-pipeline
 
 `agent-sync` supplies stages; it does not define them. It binds to task-pipeline's
-stages 0, 3, 4, 5, 9 and 10 — lease before the brief is committed, reserve ids before
-they reach git, register file ownership for parallel groups, signal and regenerate the
-board at docs, release everything at acceptance. Wiring:
+stages 0, 1, 3, 4, 5, 9 and 10 — lease before the brief is committed, reconcile before
+code is written, reserve ids before they reach git, register file ownership for parallel
+groups, signal and regenerate the board at docs, release everything at acceptance. The
+stage numbers are stated once, in the marker at the top of the binding reference, and a
+check fails when a document stops agreeing with it. Wiring:
 [`references/pipeline-binding.md`](plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md).
 
 ## Limits, stated plainly
@@ -410,7 +421,8 @@ board at docs, release everything at acceptance. Wiring:
 | `task-pipeline is not installed` and `status` stops | Intentional — there are no stages to bind to. `npx sshlg-skills install` |
 | `⚠ this lease is advisory, not enforced` | `gated: false` in the config, or a `leaseBackend` that is neither `local` nor `git`. Fix the mode — an unknown one claims nothing on purpose |
 | `lease: local — advisory across machines` | Expected on the default. Set `leaseBackend: "git"` (and a reachable `leaseRemote`) when agents run on more than one machine |
-| Every `acquire` reports `lost` | Check the holder in `status`. If the log itself is unreadable, `acquire` raises instead — that is a parse failure, not a race |
+| Every `acquire` reports `lost` | Check the holder in `status`. The lease is decided by a lock file or a git ref, never by the log, so this is a real holder — not a parse failure |
+| A command stops with `the … log is N/M unparseable` | Past 2%, every command that *replays* a log refuses it rather than acting on a partial history. Fix or remove the malformed lines; `acquire` is unaffected, because a lease is not decided there |
 | Guarded edit blocked in Claude Code | Working as designed: `acquire` the key first, or unstage the file |
 | Guarded edit *not* blocked | You are not on Claude Code. Run `guard <path>` yourself; the run is `ungated` |
 | `AGENT_SYNC_OUTLINE_COLLECTION is not set` | Run `bootstrap` and paste the printed id into `.env.agent-sync` |
@@ -437,7 +449,7 @@ npm test                             # both of the above
 ```
 
 What ships: one skill (`agent-sync`), `scripts/agent_sync.py` (stdlib only), four hook
-scripts, the slash command, `agent-sync.schema.json`, and eight reference contracts the
+scripts, the slash command, `agent-sync.schema.json`, and ten reference contracts the
 agent loads on their own trigger rather than by default:
 
 | Reference | Read it when |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.4.3",
+  "version": "1.7.1",
   "description": "Let concurrent coding agents share one project without colliding \u2014 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.4.3",
+  "version": "1.7.1",
   "description": "Coordination layer for multi-agent repositories \u2014 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/commands/agent-sync.md

@@ -1,6 +1,6 @@
 ---
-description: Coordinate concurrent agents — initialise the shared knowledge store, check status, claim a task, reserve an id, or regenerate the board.
-argument-hint: "[init|status|claim <KEY>|release <KEY>|reserve <REG>|board|finish]"
+description: Coordinate concurrent agents — initialise the shared knowledge store, check status, take a task, reserve an id, or regenerate the board.
+argument-hint: "[init|status|check|acquire <KEY>|release <KEY>|reserve <REG>|board|merge|finish]"
 ---
 
 Invoke the `agent-sync` skill.

package/plugins/agent-sync/hooks/guard.sh

@@ -20,25 +20,71 @@ print(ti.get("file_path") or ti.get("path") or ti.get("notebook_path") or "")
 
 # git commit: check every staged path instead of a single file argument.
 if [ -z "$path" ]; then
-  cmd=$(python3 -c '
-import json,sys
+  # What repository, and is this even a commit. Both used to be wrong, and the second one is why
+  # the first went unnoticed: the old test was `case "$cmd" in *"git commit"*)`, a CONTIGUOUS
+  # substring. `git -C <dir> commit` does not contain it, so every commit made that way skipped the
+  # guard entirely -- in any repository, submodule or not. The repo was then hardcoded to
+  # CLAUDE_PROJECT_DIR, so even a bare `git commit` inside a submodule read the umbrella's empty
+  # index and passed. Measured 2026-08-07: a full day of commits to guarded registers, with the
+  # Edit-tool half of this hook refusing correctly the whole time, so the protection looked present.
+  #
+  # Tokenised in python rather than globbed in shell: `git log --grep=commit` must not match, and
+  # `git -c user.name=x -C dir commit` must.
+  read -r is_commit repo <<<"$(python3 -c '
+import json, shlex, sys
 try:
-    d=json.load(sys.stdin)
+    d = json.load(sys.stdin)
 except Exception:
-    sys.exit(0)
-print((d.get("tool_input") or {}).get("command",""))
-' <<<"$input" 2>/dev/null)
-  case "$cmd" in
-    *"git commit"*)
-      while IFS= read -r staged; do
-        [ -n "$staged" ] || continue
-        if ! python3 "$S" guard "$staged" >/dev/null 2>&1; then
-          echo "agent-sync: '$staged' is staged but this run holds no lease on it. Acquire one, or unstage it." >&2
-          exit 2
-        fi
-      done < <(git -C "${CLAUDE_PROJECT_DIR:-$PWD}" diff --cached --name-only 2>/dev/null)
-      ;;
-  esac
+    print("0 ."); sys.exit(0)
+cmd = (d.get("tool_input") or {}).get("command", "")
+is_commit, repo = 0, "."
+# Each &&/;/| segment is its own command; a commit anywhere in the chain counts.
+for seg in cmd.replace("&&", "\n").replace(";", "\n").replace("||", "\n").split("\n"):
+    try:
+        toks = shlex.split(seg)
+    except ValueError:
+        continue
+    if not toks:
+        continue
+    if toks[0] == "cd" and len(toks) > 1:
+        repo = toks[1]
+        continue
+    if toks[0] != "git":
+        continue
+    k, r = 1, None
+    while k < len(toks):
+        t = toks[k]
+        if t == "-C" and k + 1 < len(toks):
+            r = toks[k + 1]; k += 2; continue
+        if t in ("-c", "--namespace") and k + 1 < len(toks):
+            k += 2; continue
+        if t.startswith("-"):
+            k += 1; continue
+        break
+    if k < len(toks) and toks[k] == "commit":
+        is_commit = 1
+        if r:
+            repo = r
+        break
+print(is_commit, repo)
+' <<<"$input" 2>/dev/null)"
+  [ -n "${is_commit:-}" ] || is_commit=0
+  [ -n "${repo:-}" ] || repo="."
+  [ -d "$repo" ] || repo="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+  if [ "$is_commit" = "1" ]; then
+    # The guard runs FROM that repository, not merely against its file list: agent_sync.py resolves
+    # the project from `git rev-parse --show-toplevel` of its cwd, so a submodule gets its own
+    # .claude/agent-sync.json and its own guardedFiles -- the only reading under which
+    # "docs/ROADMAP.md" means the right file in each repo.
+    while IFS= read -r staged; do
+      [ -n "$staged" ] || continue
+      if ! (cd "$repo" && python3 "$S" guard "$staged") >/dev/null 2>&1; then
+        echo "agent-sync: '$staged' is staged in $repo and this run holds no lease on it. Acquire one, or unstage it." >&2
+        exit 2
+      fi
+    done < <(git -C "$repo" diff --cached --name-only 2>/dev/null)
+  fi
   exit 0
 fi