Skip to content

fix(gateway-lock): take the read-side lock-file probe shared - #22188

Merged
bolichen97 merged 1 commit into
mainfrom
fix/21194-shared-lock-probe
Oct 19, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/21194-shared-lock-probe

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Two read-only lock checks on an idle home (kirocrew stop beside kirocrew perf sample) never read each other as the running gateway.

gateway_lock.lock_holder probes gateway.lock with an exclusive try-lock. release() never deletes the file, so an idle home keeps a free gateway.lock. When two checks probe it at the same moment, the second one fails to take the lock and reads it as held. On Linux it can then name the first check's own pid as the holder (source="flock_owner"). Elsewhere it usually ends in an indeterminate LockProbeError.

Why it matters

stop, restart and the perf probe act on the answer. A false holder can point stop at a pid that is not a gateway, and an indeterminate answer makes a command refuse on a home where nothing runs. #21192 fixed the same collision one probe later, in the home-anchor probe.

Not a goal

  • Windows. msvcrt has no shared lock, so its probe stays exclusive. The collision there is two syscalls wide and ends in LockProbeError, which the docstring now states.
  • The gateway's own acquire(). Its exclusive attempt can meet a reader's probe exactly as it did before; that window is unchanged.
  • The probe's open mode. It stays read-write; only its documented reason changes.

What changed (motivation → approach → change)

Two readers collided because each took the lock file exclusive. A shared lock is refused only by an exclusive hold, and the gateway holds gateway.lock exclusive for its whole life. So a shared probe still sees a running gateway as held, while two probes on a free file both get it.

_lock_is_held in src/kiro_crew/gateway_lock.py now calls try_acquire_lock(fd, exclusive=False): LOCK_SH|LOCK_NB on POSIX, unchanged on Windows. Its docstring states what a Windows collision reads as. _open_probe_descriptor's docstring is re-derived: a shared record lock needs only read access, so the read-write open is kept for the FIFO and lease-break reasons, not the lock.

Backwards compatibility

Compatible: a held lock still reads as held, and a free one as free; only two concurrent readers change, from a false holder to nobody.

Removes nothing: the same probe runs, with a weaker lock mode that every holder still refuses.

Tests

  • test_two_overlapping_probes_of_a_free_lock_file_both_read_nobody: two threads call lock_holder on a home with a free gateway.lock, each keeping its lock-file probe until the other has probed. Both answer nobody, with no error. Red on origin/main (LockProbeError: ... no live holder pid can be established), green here. Skipped where fcntl is missing.
  • test_the_shared_lock_file_probe_still_reads_a_held_lock_as_held: a real GatewayLock.acquire() holds the file; _lock_is_held on a second descriptor reads True. Runs on every platform.
  • Determinism: the two new tests pass 30 repeats each (60 runs), and all of test/test_gateway_lock.py passes in a seeded shuffled order (87 passed, 3 skipped).

Manual verification

N/A — unit coverage sufficient: the new test reproduces the collision with two real descriptors and real flock calls.

Related Issues

Closes #21194

Pattern harvest

Rule candidate: review-prompt
Pattern: a non-destructive "is it held?" probe takes an exclusive lock when a shared one would be refused by the same holders.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 19, 2026 14:49
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a2561024390061671adc4a724297c9060d0017d8 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 19, 2026
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of a2561024390061671adc4a724297c9060d0017d8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] a256102

Description read

[DESCRIPTION-READ] 886ad07ddd0bed158d25235a338e6f456a7656823be0d78a0477c722d207cfef

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of a2561024390061671adc4a724297c9060d0017d8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (4 items) — 4 justified

Intent: let kirocrew stop and a perf sample check an idle home at the same moment without either one taking the other for the running gateway. FIX.

  1. On POSIX, two read-only lock checks that run at once on an idle home both report no gateway, instead of a false holder pid or a LockProbeError — justified
  2. The probe-descriptor docstring now gives the FIFO and lease-break reasons for opening the lock file read-write, not the lock mode — justified
  3. The comment on the read-write-descriptor test is rewritten to match; its assertion is unchanged — justified
  4. Two tests: a concurrent-probe reproduction that fails on base, and a check that a real held lock still reads as held — justified

[FIRST-PRINCIPLES-REVIEWED] a256102

Description read

[DESCRIPTION-READ] a303b38ce2861961a058cb44b9256c6646a9b937b43e5ccc67371be46f0eb9f6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of a2561024390061671adc4a724297c9060d0017d8 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a256102

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a2561024390061671adc4a724297c9060d0017d8: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed a2561024390061671adc4a724297c9060d0017d8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] a256102

Verdict parsed from the review's SHA-scoped output markers for commit a2561024390061671adc4a724297c9060d0017d8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a2561024390061671adc4a724297c9060d0017d8: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 19, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head ba2459d. The change looks correct to me and I have no findings.

What I checked:

  • _lock_is_held is the first try_acquire_lock call in lock_holder, so the new overlap test parks on the lock file probe, not the home anchor, and two LOCK_SH probes on separate descriptors both succeed while the gateway's LOCK_EX still refuses them.
  • The read-only fallback descriptor and the NFS record-lock case both still work: a shared record lock needs only read access.
  • The gateway's own acquire() race window is unchanged, as stated in the description.
  • This matches the shared anchor probe from #21192, and main has not touched this function since.
  • Linked issue #21194 is tier T1; no path is on the security denylist.

Why I am not approving yet: the Harness Parity Gate is red on main itself (a stale claude member-capabilities allowlist row, unrelated to this change), so the Fast Gate failed here and the backend, lint and coverage jobs were skipped. This PR's tests have not run in CI. Once the main fix (#22178 or #22186) lands, please rebase or re-run; I will approve when readiness: passed is on the new head.

Optional nit: one docstring line in _open_probe_descriptor ("read-only descriptor instead, which the shared probe locks as well. Windows opens read-only through") runs past 100 columns; rewrapping it would keep the paragraph consistent.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Red on this head is main's, not this PR's: Harness Parity Gate fails with ACP_BACKENDS_MEMBER_CAPABILITIES [claude]: allowlisted but now proven; delete the entry, the same line main's own Fast Gate push runs fail on. Fast Gate, Await Fast Gate and Coverage Gate follow from it. Fixes in flight: #22178 and #22186. This PR waits for one to merge, then rebases and re-runs.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

macOS shard 3 red on this head (job 118129280736) is main's too: test/test_acp_frame_replay.py::test_a_live_header_names_the_agent_its_capture_answered_as and test/test_backend_cards_advertised.py::test_no_new_runtime_site_gates_a_field_backed_line_on_a_set both fail on a clean origin/main e5e6f1c worktree (2 failed, Linux). Neither touches gateway_lock. #22178 fixes both; this PR rebases onto it once it merges.

@iamwhatever
iamwhatever force-pushed the fix/21194-shared-lock-probe branch from ba2459d to a256102 Compare October 19, 2026 17:34
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main 3e39e7a, which carries #22178 (main's Harness Parity and macOS reds). New head a256102; test/test_gateway_lock.py, test/test_gateway_lock_diagnosis.py and the two former main-red tests pass locally (152 passed, 3 skipped). CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 19, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving head a256102.

This head is a rebase onto current main; the patch to gateway_lock.py and its test is identical to the revision I reviewed earlier, so my earlier read still holds: the read-side probe takes LOCK_SH, two concurrent probes no longer collide, the gateway's LOCK_EX still refuses them, and the read-only and NFS fallback paths keep working.

What was blocking before is resolved: main's Harness Parity red is fixed on the new base, and the backend, lint and coverage jobs now ran on this head.

Gates checked on this head:

  • readiness: passed, PR Readiness green, every required check green.
  • Design, First Principles, Opus and GPT lanes report no blocking findings; UX skipped (no UI surface).
  • Linked issue is tier T1; no file is on the security path denylist; base is main and the branch is mergeable.

One macOS backend shard is still re-running after a cancelled first attempt; it is not a required check and its cancellation was not a test failure.

@bolichen97
bolichen97 merged commit 02eeb00 into main Oct 19, 2026
109 of 111 checks passed
@bolichen97
bolichen97 deleted the fix/21194-shared-lock-probe branch October 19, 2026 18:27
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

gateway lock: take the read-side lock-file probe shared, not exclusive

2 participants