Harden shared issue/PR lock handling against concurrent LLM session clobbering #438

New Issue

2026-07-07T12:26:59-05:00

jcwalker3 commented

2026-07-07 12:26:59 -05:00

Problem

During work on issue #306 / PR #423, the shared global lock file /tmp/gitea_issue_lock.json was repeatedly clobbered by concurrent author sessions working on #403 and #407. A concurrent session also opened PR #423 on the same already-pushed branch during the race. This indicates the current lock mechanism may not reliably prevent duplicate ownership, branch races, or cross-session mutation collisions.

The lock is a single global path (ISSUE_LOCK_FILE = "/tmp/gitea_issue_lock.json") updated by normal read-modify-write JSON. gitea_mark_issue / gitea_lock_issue write it; gitea_create_pr reads it and fails closed on a worktree mismatch. Under simultaneous sessions the last writer wins, so a session can lose its lock to another issue's session between claiming and PR creation.

Why this matters

The MCP/Gitea workflow depends on live queue ownership and role separation. If concurrent sessions can overwrite or ignore the shared lock, multiple LLMs may:

claim the same issue or branch
open duplicate or competing PRs
mutate work owned by another session
produce misleading handoffs
bypass queue-ordering or in-progress protections
make reviewer/reconciler state harder to trust

Acceptance criteria

Lock acquisition must be atomic and fail closed under concurrent writers.
Lock ownership must include issue number, repo, branch, role/profile, PID or session identifier if available, timestamp, and expiry/heartbeat metadata.
A session must not silently overwrite another live lock.
Stale lock recovery must require explicit stale proof, such as expired heartbeat or dead-process proof.
Queue selection must treat a live lock as status:in-progress or equivalent.
Branch/PR creation must re-check lock ownership immediately before mutation.
The workflow must produce clear proof in final reports:
- lock acquired
- lock owner
- lock freshness
- no competing live lock
- lock released or intentionally retained
Add tests that simulate concurrent lock acquisition attempts and prove only one session can own the issue.
Add tests that prove stale locks can be recovered safely without allowing active-lock clobbering.
Update docs/templates so author/reviewer/reconciler sessions report lock proof consistently.

Suggested implementation direction

Use an atomic filesystem operation such as exclusive create (O_EXCL), rename-based compare/swap, or an OS-level file lock (flock/fcntl) instead of read-modify-write JSON updates. Consider keying the lock per issue rather than a single global file so distinct issues never contend. The exact implementation is the author's choice, but the result must be race-safe under simultaneous LLM sessions.

Related observation

Observed while authoring PR #423 for issue #306. Concurrent sessions around #403/#407 repeatedly clobbered /tmp/gitea_issue_lock.json, and another session opened #423 on the already-pushed branch. See also the current lock code in issue_lock_worktree.py (verify_pr_worktree_matches_lock, base-equivalence gate) and gitea_mcp_server.py (ISSUE_LOCK_FILE).

## Problem During work on issue #306 / PR #423, the shared global lock file `/tmp/gitea_issue_lock.json` was repeatedly clobbered by concurrent author sessions working on #403 and #407. A concurrent session also opened PR #423 on the same already-pushed branch during the race. This indicates the current lock mechanism may not reliably prevent duplicate ownership, branch races, or cross-session mutation collisions. The lock is a single global path (`ISSUE_LOCK_FILE = "/tmp/gitea_issue_lock.json"`) updated by normal read-modify-write JSON. `gitea_mark_issue` / `gitea_lock_issue` write it; `gitea_create_pr` reads it and fails closed on a worktree mismatch. Under simultaneous sessions the last writer wins, so a session can lose its lock to another issue's session between claiming and PR creation. ## Why this matters The MCP/Gitea workflow depends on live queue ownership and role separation. If concurrent sessions can overwrite or ignore the shared lock, multiple LLMs may: * claim the same issue or branch * open duplicate or competing PRs * mutate work owned by another session * produce misleading handoffs * bypass queue-ordering or in-progress protections * make reviewer/reconciler state harder to trust ## Acceptance criteria 1. Lock acquisition must be atomic and fail closed under concurrent writers. 2. Lock ownership must include issue number, repo, branch, role/profile, PID or session identifier if available, timestamp, and expiry/heartbeat metadata. 3. A session must not silently overwrite another live lock. 4. Stale lock recovery must require explicit stale proof, such as expired heartbeat or dead-process proof. 5. Queue selection must treat a live lock as `status:in-progress` or equivalent. 6. Branch/PR creation must re-check lock ownership immediately before mutation. 7. The workflow must produce clear proof in final reports: * lock acquired * lock owner * lock freshness * no competing live lock * lock released or intentionally retained 8. Add tests that simulate concurrent lock acquisition attempts and prove only one session can own the issue. 9. Add tests that prove stale locks can be recovered safely without allowing active-lock clobbering. 10. Update docs/templates so author/reviewer/reconciler sessions report lock proof consistently. ## Suggested implementation direction Use an atomic filesystem operation such as exclusive create (`O_EXCL`), rename-based compare/swap, or an OS-level file lock (`flock`/`fcntl`) instead of read-modify-write JSON updates. Consider keying the lock per issue rather than a single global file so distinct issues never contend. The exact implementation is the author's choice, but the result must be race-safe under simultaneous LLM sessions. ## Related observation Observed while authoring PR #423 for issue #306. Concurrent sessions around #403/#407 repeatedly clobbered `/tmp/gitea_issue_lock.json`, and another session opened #423 on the already-pushed branch. See also the current lock code in `issue_lock_worktree.py` (`verify_pr_worktree_matches_lock`, base-equivalence gate) and `gitea_mcp_server.py` (`ISSUE_LOCK_FILE`).

jcwalker3 referenced this issue

2026-07-07 12:39:16 -05:00

Add own-branch lock adoption / recovery path to gitea_lock_issue #442

jcwalker3 referenced this issue

2026-07-07 12:48:11 -05:00

Replace single global issue-lock file with repo/session-safe lock ownership #443

jcwalker3 referenced this issue

2026-07-07 12:58:07 -05:00

Block manual issue-lock seeding and require lock mutation proof in final reports #447

jcwalker3 commented

2026-07-07 13:32:37 -05:00

Related enforcement wall filed as #447: manual /tmp/gitea_issue_lock.json seeding must be blocked/reported while this atomic repo/session-safe lock redesign is being implemented.

Related enforcement wall filed as #447: manual `/tmp/gitea_issue_lock.json` seeding must be blocked/reported while this atomic repo/session-safe lock redesign is being implemented.

jcwalker3 referenced this issue

2026-07-07 15:19:09 -05:00

feat: block manual issue-lock seeding and require lock disclosure (Closes #447) #463

jcwalker3 added the status:in-progress label 2026-07-07 15:22:43 -05:00

jcwalker3 commented

2026-07-07 15:22:44 -05:00

Issue claim heartbeat

kind: claim
issue: Harden shared issue/PR lock handling against concurrent LLM session clobbering (#438)
branch: feat/issue-438-lock-hardening
phase: claimed
profile: prgs-author
pr: none
blocker: none
next_action: create worktree and begin implementation

**Issue claim heartbeat** - kind: claim - issue: #438 - branch: feat/issue-438-lock-hardening - phase: claimed - profile: prgs-author - pr: none - blocker: none - next_action: create worktree and begin implementation

jcwalker3 referenced this issue from a commit

2026-07-07 15:25:38 -05:00

feat: harden issue lock store against concurrent session clobbering (Closes #438)

jcwalker3 referenced a pull request that will close this issue

2026-07-07 15:26:16 -05:00

feat: harden issue lock store against concurrent session clobbering (Closes #438) #464

jcwalker3 referenced this issue

2026-07-07 15:44:20 -05:00

⛔ SUPERSEDED — do not review/merge (#440 umbrella duplicate) #466

sysadmin referenced this issue

2026-07-07 15:48:06 -05:00

feat: keyed issue-lock store replaces global lock file (Closes #443) #465