Unlock by path fails with 404/409 when the snapshot names a released-and-reissued lock id: the spec's one refresh + one retry isn't implemented

[matt-edmondson]

Plan

docs/superpowers/specs/2026-08-19-locks-subsystem-design.md#L126

Unlock by path resolves ids from the current snapshot. A resolution that upstream then answers 404 or 409 triggers one snapshot refresh and one retry for that item only, because a stale snapshot can name a lock id that has since been released and reissued.

The spec's As built section doesn't record a departure from this.

What exists today

LockFanOut.RunOneAsync (GitLfsCache/Locks/LockFanOut.cs:130-160) resolves a path to an id from the snapshot. It refreshes only when the path is missing from the snapshot. SendWithRetriesAsync retries only on throttling (429, or 403 with Retry-After), so a 404 or 409 for a stale id goes back to the client as ok:false immediately.

What's missing

Suppose the path's lock was released and re-taken under a new id after the snapshot was built. The unlock is sent to the old id, upstream answers 404 or 409, and the user's unlock fails even though the lock exists. The spec asks for:

• one snapshot refresh on that answer,
• re-resolving the path,
• one retry.

This applies only to items the proxy resolved from a path. Ids the client supplied are never retried.

Acceptance criteria

• A path-resolved unlock whose first attempt returns 404 or 409 refreshes once, re-resolves, and retries once. If the retry also fails, the item reports upstream's status.
• An unlock by a client-supplied id is never retried on 404/409.
• The retry refresh goes through the same single-flight and limiter as the other resolution refreshes.
• Tests cover both the retry path and the no-retry path for client-supplied ids.

Dependencies

Coordinate with #63. It restructures unlock-by-path resolution into one refresh per request, and this retry should use that same mechanism.

[matt-edmondson]

Triage

• Category: Improvement. This is a spec gap: the design calls for one refresh and one retry.
• Priority: Medium. A user's unlock by path fails with ok:false when the lock was released and reissued after the snapshot was built. The user can retry by hand, but the spec's promised behaviour is missing.
• Area / suggested assignee: Locks fan-out (Locks/LockFanOut.cs), @matt-edmondson.
• Duplicates: None.
• In progress: No open PR covers it.
• Notes: Depends on Unlocking many paths through locks/batch can run a full lock-list walk per path, outside single-flight and the upstream limiter #63, which restructures unlock-by-path into one refresh per request, and should reuse that mechanism. Also benefits from A lock created or released during an in-flight lock-list refresh is missing from listings for a full ListTtl: the refresh publishes its stale walk after the invalidation ran #70 so the refreshed snapshot isn't itself stale.

---

Generated by Claude Code