res: queue coalesces same-lock gates on descendant commitsHEADmaster

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JEAjUkQRrCYX5MZhWxdtj2

1 files changed, 15 insertions, 1 deletions

diff --git a/docs/resource-ledger.md b/docs/resource-ledger.md
index 4417517..a3ba3f8 100644
--- a/docs/resource-ledger.md
+++ b/docs/resource-ledger.md
@@ -157,6 +157,8 @@ id, systemd failure) · 2 usage.
   `gate` locks `gate` unasked (2026-10-06: two hand-started gates overlapped in one gate checkout). Held → exit 3
   `busy: lock 'KEY' held by r-N "title" (ETA ~HH:MM|queued): …; --queue waits for it (--force does not override
   a lock)`; `--queue` → queued `(lock held by r-N)`. Ledger field `lock` = `KEY@<main tree>`.
+- `--commit REV`: the commit the job tests (ledger `commit`, full sha); default for a locked job: a 7–40 hex word
+  of the title that resolves to a commit in the cwd (`gate 1a2b3c4`). Coalescing, §4.2.
 - The command reaches the job verbatim (no systemd `%` specifier expansion: `--format='%h %s'` is safe).
 
 ### 4.2 Queue
@@ -171,6 +173,18 @@ batch waiting for its own gate never deadlocks (direct run and queue alike; not
 whose parent job ended (done or gone) is dropped at prune (`r-N dropped (batch r-M gone)`, why `owner gone`):
 nobody waits for it, and it must not head the queue.
 
+Coalescing (ruling 2026-10-07, t-coalesce-batch-gates; chosen over "batch queues one gate at its end": works for
+every caller, batch or not, needs no batch-end hook): when a locked job with a `commit` is queued, same-lock queued
+entries are compared by ancestry (`git merge-base --is-ancestor` in the cwd). Queued entries on ancestor commits end
+`superseded by r-N` (ledger `superseded_by`); the new entry takes the earliest queued time of those (keeps its turn)
+and lists their commits in `covers` (oldest queued first). A queued entry on the same or a descendant commit
+already exists → nothing is queued: `r-M queued, position … ; covers <sha7> (queued on descendant <sha7>, nothing
+new queued): wf res wait r-M` (r-M gains the commit in `covers`). Running entries and unrelated commits (side
+branches) are never touched. So a batch of N commits yields ≤ 1 queued gate per lock. `wf res wait` on a
+superseded id prints `r-N superseded by r-M …; waiting for it` and follows the chain. Done line of a coalesced
+entry: `…; covers a,b`; red (rc ≠ 0): `; red: culprit is any commit in <oldest>^..<sha> -> bisect (git bisect
+start <sha> <oldest>^, rerun the job per step) or name that range in the P0 fix task`.
+
 ### 4.3 `wf res status [r-N] [--json]`
 
 Without id: one line per entry (id, project, title, state, reserved / used / peak GB, cpus, started, ETA or
@@ -191,7 +205,7 @@ With id: that entry in full, including `rc`, `peak_gb`, `why` for done entries.
 ### 4.4 `wf res wait r-N [--timeout 2h]`
 
 Polls every 15 s (each poll is a normal locked call, so it also prunes and starts queued work) until the entry
-is `done`; prints `r-N done rc=0 peak 9.4 GB in 37 min`. The throttle warning (§4.3) goes to stderr once. Exit 0 when done (whatever `rc`), 1 on timeout. If
+is `done`; prints `r-N done rc=0 peak 9.4 GB in 37 min` (coalesced: superseded ids followed, §4.2). The throttle warning (§4.3) goes to stderr once. Exit 0 when done (whatever `rc`), 1 on timeout. If
 reaped, `status r-N` answers from the ledger.
 
 ### 4.5 `wf res release r-N [--stop]`