Skip to content

work-items GitHub adapter: lease release, renew and same-login assignee defects found by the claim-protocol model #16472

Closed

Description

@kyle-sexton

Three defects in the work-item tracker's GitHub adapter lease protocol (plugins/work-items/tools/work-item-tracker/adapters/github/). They were found by the formal-verification claim-protocol model (TLA+) on pull request #16458 and confirmed by a line-by-line replay of the scripts.

1. Release and renew refuse the holder's own live lease while a newer lease is not yet superseded

Severity: medium. A finished session cannot hand the item back, so every later claim loses to its lease until the TTL, and reclaim may renew it on activity. The contract's purpose for release ("hands it back at once instead of blocking every later claim") fails in an ordinary race.

Steps to reproduce:

  1. Session A claims the item and holds lease comment 1.
  2. A second claimant (for example the issue lane's claim --lease-only) posts lease comment 2 and has not yet reached its step 4 back-off.
  3. Session A runs release --lease-comment-id 1.

Expected: lease 1 is released (it is the earliest live lease, the one claim step 4 says holds the item); the second claimant then wins.

Actual: release exits 7 and writes nothing, because it requires the handle to be the newest non-superseded lease (release.sh:81-87, wit_select_active_lease). The callers leave it (attend-queue/SKILL.md, triage/SKILL.md). The second claimant then loses to lease 1 and backs off. A default-mode claim that fails after its post leaves its comment live as well, which keeps the window open. renew-lease.sh:56-58 has the same check, so a live holder's renew is refused in the same window.

Fix location: release.sh and renew-lease.sh should apply claim step 4's rule (the handle is the caller's own live lease and no earlier live lease outranks it, the completed-run rule included), shared with claim.sh through one function in lib/lease.sh; claim.sh should supersede its own comment on failure in default mode too, as --lease-only does at claim.sh:139.

2. A same-login hand-back unassigns the login while another session of that login holds a live lease

Severity: low. The item shows as unassigned on the frontier while a live lease holds it; arbitration is by lease, so two claimants never proceed, but the frontier and the assignee disagree.

Steps to reproduce:

  1. A local session holds lease 1 and is assigned.
  2. A same-login triage claim passes claim step 2 (its login is already the only assignee).
  3. The local session releases lease 1, and its caller removes @me unconditionally.
  4. The triage claim posts its lease and wins.

Expected: the login stays assigned, since the triage session holds a live lease.

Actual: the item is held with no assignee. release.sh never touches assignees, and the callers' --remove-assignee @me steps are unconditional.

Fix location: release.sh (unassign after the supersede, only when no other live lease of that login remains) and the three callers (attend-queue, triage, work skills).

3. A same-login loser keeps @me for a winner that has finished, stranding the assignee

Severity: medium. The permanent variant leaves an assignee that nothing ever clears, so the item drops off the frontier for good.

Steps to reproduce (permanent variant):

  1. A local session holds lease 1; its caller clears @me before releasing (the order attend-queue/SKILL.md gives).
  2. A same-login triage claim assigns the login, passes step 2, posts lease 3, loses to the still-live lease 1, and keeps @me "for the winner" (claim.sh:200-204).
  3. The local session releases lease 1.

Expected: no assignee once every lease is superseded.

Actual: the login stays assigned, every lease is superseded, and reclaim reports "no active lease record", so nothing clears it.

Fix location: claim.sh should read the assignees before step 1 and, on a same-login loss, keep @me only when the login was already assigned before the claim started.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 16, 2026
  2. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Size: Medium
    Complexity: High
    Uncertainty: Known
    Flags: none
    Blocked by: none

    I read this as three defects in the work-items GitHub adapter's lease protocol. (1) release and renew-lease refuse the holder's own live lease while a newer lease is not yet superseded. (2) A same-login hand-back unassigns the login even though another session of that login holds a live lease. (3) A same-login claim loser keeps @​me for a winner that has since finished, which strands the assignee.

    The issue gives repro steps, the expected and actual behavior, and a fix location for each defect. The refinement comment already lists acceptance criteria. I found no open duplicate and no merged pull request that fixes this. Related context: #11897 and #15049 touch the same scripts. #16458 (the claim-protocol model that found these) is not a dependency, but the model and scripts should stay consistent if it merges first.

    Automated triage. A maintainer reviews it.

  3. removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 16, 2026
  4. melodic-automation-lanes commented on Nov 16, 2026

    @melodic-automation-lanes
    Contributor

    Not admitted to the issue lane yet: open pull request #16475 is for it.

  5. melodic-automation-lanes commented on Nov 16, 2026

    @melodic-automation-lanes
    Contributor

    Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.

    Intended outcome: Fix the three GitHub adapter lease defects: release and renew accept the holder's own earliest-live lease via a shared lib/lease.sh rule, release unassigns the login only when no other live lease of that login remains, and a same-login claim loser keeps @​me only if the login was assigned before the claim.

    Acceptance criteria

    • lib/lease.sh defines one function applying claim step 4's rule (own live lease, no earlier live lease outranks it, completed-run rule included), and claim.sh, release.sh and renew-lease.sh all call it
    • release.sh no longer requires the handle to equal the newest non-superseded lease (the wit_select_active_lease check at release.sh:81-87 is gone); with lease 1 held by the caller and live lease 2 posted by another claimant, release of lease 1 exits 0 and writes superseded_at on comment 1
    • renew-lease.sh no longer requires the handle to be the newest non-superseded lease (renew-lease.sh:54-60); in the same two-lease state a live holder's renew of lease 1 succeeds
    • release and renew still exit 7 for a lease with an earlier live lease outranking it, a lease held by another login, an already superseded lease, and (renew) an expired lease
    • claim.sh supersedes its own lease comment on any failure after the post in default mode too, not only with --lease-only (claim.sh:139)
    • release.sh unassigns the lease holder's login after the supersede only when no other live lease of that login remains; with another live same-login lease the assignee stays
    • The attend-queue, triage and work skills no longer run an unconditional --remove-assignee @​me on hand-back; their steps match the new release behavior
    • claim.sh reads the assignees before step 1 and, on a same-login loss in default mode, keeps @​me only when the login was already assigned before the claim; otherwise it removes @​me (claim.sh:200-204)
    • Tests in release.test.sh, renew-lease.test.sh, claim.test.sh and lease-coordination.test.sh cover the three scenarios in the issue and pass
    • The adapter README, CONTRACT.md lease protocol text and the plugin CHANGELOG describe the new release, renew and assignee behavior

    External state: none

    Dependencies

    • Pull request #​16458 (the claim-protocol model that found the defects): none required for the fix, but keep the model and scripts consistent if it merges first

    Related work

    Sources read

    • plugins/work-items/tools/work-item-tracker/adapters/github/release.sh:81-87: requires the handle to equal wit_select_active_lease's newest non-superseded lease, else exit 7
    • plugins/work-items/tools/work-item-tracker/adapters/github/release.sh:3-4: the assignee is left alone and the caller clears it
    • plugins/work-items/tools/work-item-tracker/adapters/github/renew-lease.sh:54-60: same newest-active-lease check refusing the renew
    • plugins/work-items/tools/work-item-tracker/adapters/github/claim.sh:139: the supersede-on-failure trap is armed only for --lease-only
    • plugins/work-items/tools/work-item-tracker/adapters/github/claim.sh:154-186: step 4 arbitration, earliest live lease wins, completed-run leases superseded
    • plugins/work-items/tools/work-item-tracker/adapters/github/claim.sh:198-204: same-login loser keeps @​me unconditionally in default mode
    • plugins/work-items/tools/work-item-tracker/lib/lease.sh:38-42: wit_select_active_lease, the place for the shared function
    • plugins/work-items/skills/triage/SKILL.md:144: caller removes @​me because release never touches assignees

    Automated refinement by the lanes App. Intake triages the issue again with it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Fields

    Work status

    deferred

    Priority

    medium

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions