Skip to content

fix(work-items): hand back on an outranked release and judge hand-back leases at a clock read before the list - #16515

Merged
kyle-sexton merged 6 commits into
mainfrom
fix/work-items-release-outranked-hand-back
Nov 16, 2026
Merged

kyle-sexton merged 6 commits into
mainfrom
fix/work-items-release-outranked-hand-back

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Refs: #16505
Refs: #16458

Summary

A TLA+ model check of the work-item tracker's GitHub claim protocol found two approved rules failing in the GitHub adapter:

  • HolderAssigned (a default claimant that holds the item is assigned): wit_hand_back_assignee listed the leases, and _wit_login_holds_other read the clock only after that list. If a same-login session renewed its lease after the list and the old expiry then passed, the stale listed body looked expired and the login was removed.
  • NoStrandedAssignee (every assigned login belongs to a claim still in flight): release of a live lease that an earlier live lease outranks exited 7 with nothing written, so the caller's live lease and its login stayed until the TTL.

Fix

  • adapters/github/common.sh: wit_hand_back_assignee lists through _wit_list_at_clock, which reads the clock just before each list attempt (retries included) and hands that reading to _wit_login_holds_other as a fourth argument; the helper no longer reads the clock. A renew only moves an expiry later, so judging the listed body at a clock read taken before the list never makes a renewing holder look expired. A lease that expires during the list still counts as live, and its login then stays for reclaim. The only callers of _wit_login_holds_other are in wit_hand_back_assignee.
  • adapters/github/release.sh: the "outranked by the earlier live lease" refusal now backs off as renew-lease's back-off does since fix(work-items): back off on a failed renew PATCH near expiry and hand back only after a supersede #16509: it tries to supersede its own lease twice and runs the hand-back only after one try succeeded. When both fail, the lease may still be live, so the assignee is kept and the message says so. It exits 7 either way. The hand-back alone would not be enough: with two sessions of one login, each hand-back would see the other's live lease and keep the login forever.
  • CONTRACT.md "Lease protocol": the Release section says what an outranked refusal writes now, and claim step 4's hand-back says when the clock is read and what that guarantees.
  • Changelog fragment under .changes/work-items/.

The Linear seed has no release script, so no other adapter carries this refusal.

Verification

adapters/github/lease-coordination.test.sh, with new cases:

  • an outranked release under another login's earlier live lease: exits 7, supersedes its own lease, leaves the earlier lease live, removes the login;
  • the same under the same login's earlier live lease: exits 7, supersedes its own lease, keeps the login;
  • an outranked release whose supersede fails twice: exits 7, tries the supersede twice, keeps the login, never removes it, and says the assignee is kept;
  • a hand-back whose listed same-login lease is renewed after the list and whose old expiry passes before the judgment: the login is never removed;
  • the same race on the hand-back's re-list and on its confirm list: the login ends assigned.

The existing outranked-release case now asserts the supersede of its own lease and no write to the earlier lease.

Run against origin/main's adapter code, the first round's new cases fail 5 assertions (4 new ones plus the updated existing one). This branch passes all 300. Moving the clock read after the re-list fails only the re-list case, and moving it after the confirm list fails only the confirm-list case. shellcheck --rcfile .shellcheckrc is clean on the three changed shell files.

Not in this change

The lane steps in pr-run-activity-write.yml and pr-run-activity-read.yml print "it expires at its TTL" on any non-zero release exit. For an outranked release that is now inaccurate, since the lease is superseded. Only the message is wrong; the behavior is unchanged.

Related

🤖 Generated with Claude Code

kyle-sexton and others added 2 commits November 16, 2026 00:49
…k leases at a clock read before the list

A release refused because an earlier live lease outranks the handle now
supersedes its own lease and hands the assignee back before exiting 7,
as a claim step 4 loss does; before, the live lease and its login stayed
until the TTL (rule NoStrandedAssignee).

The assignee hand-back reads the clock before each of its three lease
lists and passes it to _wit_login_holds_other, so a same-login lease
renewed after the list is never judged expired on its stale listed body
(rule HolderAssigned).

Refs: #16505
Refs: #16458

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 05:57
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T06:06:05.916520Z 8400768 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton

Copy link
Copy Markdown
Member Author

Session note (agent, not an owner decision). Held with do-not-merge for the owner: this is option A of the question saved for him on #16458 (two of the seven approved claim-protocol rules fail in that pull request's shipped checks). It changes the lease scripts every lane uses, so it does not merge until he answers.

Model check of this change (the #16458 claim-protocol model, updated for this diff and for #16509; TLC 1.7.4, renew on, failures off, bounded stall):

Configuration Result Distinct states
local session + issue lane all of OneHolder, LaneAssignsNoOne, HolderAssigned, NoStrandedAssignee, LoserSupersedesOwn, CompletedRunHoldsNothing, ReleaseFreesItem, EndStateReclaimable hold 1,714,673
local session + same-or-other-login triage all eight hold 1,374,839

Controls: with the outranked release handing back but not superseding its own lease, NoStrandedAssignee breaks in the same-login configuration (two sessions each keep the login for the other's live lease), which is why the supersede is part of this change. The seeded break (latest live lease wins) still trips OneHolder (1,355 and 1,986 states).

Still breaking only with a failure switched on, unchanged in kind from #16458's known results: a failed best-effort write or a failed lease list inside the hand-back, and a process killed mid-rollback. One of these is new to this diff: when the outranked release's supersede fails, the hand-back still runs (as claim step 4 does), so the login can come off while that lease is live until its TTL.

The updated model goes onto #16458 after this merges, with the sync commit moved to the merge commit.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg base
Run job success
Activity step skipped
Commits pushed none (read lane)
Run 43813628381

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 57b3e270913636ec4ed15280da4616f8e0230ffe: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16515 at 57b3e27 (incremental since 32c4ce3)

No security issues found. I read the whole incremental diff, which changes 2 files. This lane already reviewed an earlier head, so this pass reports only CRITICAL and IMPORTANT findings.

What changed

  • plugins/work-items/tools/work-item-tracker/CONTRACT.md: the claim step 4 hand-back text has been reworded. A lease now counts as live when it is live at a clock read taken just before the list or at one taken after it. The new text also says this covers a same-login holder whose clock runs ahead, up to the skew bound, and that renews during the list.
    • This is protocol documentation for lease liveness, not a standing instruction (CLAUDE.md, a rules file, a skill or agent body, or a hook list).
    • It removes no guardrail, so the instruction-surface lens does not apply.
  • plugins/work-items/tools/work-item-tracker/adapters/github/lease-coordination.test.sh: one new test scenario. A same-login holder with a clock 300 s fast renews lease 2 during the hand-back's list, and the test asserts that alice is never removed.
    • The test runs only against the repository's gh stub.
    • Its bash -c hook receives fixed, test-authored arguments, so no untrusted input reaches it.

Other notes

  • Neither changed file matches a trusted-path glob, and neither is a trust control: no trusted-actor check, token scope, kill switch, merge hold or .github/actions/ gate is touched.
  • There are no plugin manifest changes.
  • The earlier summary comment has no line anchor, and nothing in it needs restating for this change.
  • Spend: one review run on prepaid credit. Nothing here can cause a charge.

critical-findings: 0

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 57b3e270913636ec4ed15280da4616f8e0230ffe: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

claude-review of 57b3e270: no blocking findings.

This review covered only what changed since 32c4ce37, and it reported blocking findings only, because the lane already reviewed earlier heads. I read every hunk of both files on the list.

What changed

  • plugins/work-items/tools/work-item-tracker/CONTRACT.md: the hand-back paragraph now says that each lease list counts a lease as live if it is live at the clock read taken just before the list or at one taken after it. This matches the code. _wit_list_at_clock reads now before the list (common.sh#L527-L530). _wit_login_holds_other then checks wit_lease_is_live at that now and again at a fresh date -u +%s (common.sh#L540).
  • lease-coordination.test.sh: a new scenario covers a holder whose clock runs fast and renews during the hand-back's list. I traced it by hand:
    • The list-2 hook runs before the stub answers (test.sh#L144). It writes renewed_at 04:05:12Z, which is T0+312 (T0=1783828800 is 2026-07-12T04:00:00Z). It also moves the stub clock to T0+12.
    • The liveness check renewed_epoch <= now_epoch + 300 (lease.sh#L135) fails at the earlier read (312 > 310) and passes at the later one (312 ≤ 312).
    • So the scenario only passes because of the second clock read, and it would fail if that read were removed. This is the regression test the settled common.sh thread's fix needed.

Settled thread: the common.sh thread (original line 511) is still settled, and none of its lines changed. I did not raise it again.

Not verified: I ran no tests; this lane has no shell. The author's "300 of 300" count is their own claim, and I did not check it.

Plugin manifests: none changed in this push.

Closing issues: none in scope for this push.

Spend: none.

Verifier dropped 0 of 0 candidates.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8400768157

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…ersede

The outranked release refusal now backs off as renew-lease's back-off
does: it tries the supersede twice and hands the assignee back only after
one try succeeded, else keeps the assignee and says so; exit 7 either way.

The hand-back reads the clock before each list attempt, retries included,
through _wit_list_at_clock. CONTRACT.md and the comment state the
property that holds: a renew only moves an expiry later, so a renewing
holder never looks expired, and a lease expiring during the list still
counts as live.

Refs: #16505

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton

Copy link
Copy Markdown
Member Author

Session note (agent). Update for head 4cae0ac: after an independent reread (verdict safe, no defect), the outranked release now hands the assignee back only once a supersede succeeded (two tries), as renew's back-off does, so the limit named in the comment above (login removed while the lease is still live after a failed supersede) no longer applies; the hand-back also re-reads its clock before each list retry. The model was updated to match and rerun: all eight rules hold in both configurations (1,721,943 and 1,361,412 distinct states), and with failed writes switched on OneHolder and ReleaseFreesItem still hold. Lease suite: 300 of 300. Still held with do-not-merge for the owner.

kyle-sexton and others added 3 commits November 16, 2026 01:35
A renew landing during the lease list can carry a renewed_at more than the
skew margin ahead of the clock read taken before the list, when the
holder's clock runs fast; the lease is then also judged at a read taken
after the list.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A same-login holder whose clock runs 300 s ahead renews two seconds into
the hand-back's lease list. The case fails when the hand-back judges only
at the clock read before the list. CONTRACT.md now states both reads.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@kyle-sexton

Copy link
Copy Markdown
Member Author

Session note (agent, not an owner decision). Head 57b3e27 covers the last code change (a46a5a1..32c4ce3: a hand-back lease counts live at the clock read before the list or at one after it), which had no test and no independent read.

  • Test: new case [hand-back clock, fast holder] in lease-coordination.test.sh: a same-login holder whose clock runs 300 s ahead renews two seconds into the hand-back's list (renewed_at T0+312 against a pre-list clock of T0+10 and a post-list clock of T0+12). Suite at this head: 304 pass, 0 fail. With _wit_login_holds_other reverted to judge at the pre-list clock only, exactly that case fails (REMOVE_ASSIGNEE alice).
  • Independent read (separate agent, read-only, of that diff plus its callers and wit_lease_is_live): verdict safe, no defect. The OR only adds leases with now0 + skew < renewed_at <= now1 + skew that are unexpired at the later read, so no dead lease becomes live; expired, superseded and beyond-bound leases judge as before; claim's loss path and renew's back-off are unaffected. One finding, fixed in this commit: CONTRACT.md still said each attempt judges at one clock read. Remaining window: a holder more than the supported 300 s ahead. Not checked by that read: whether renew-lease.sh's pre-list clock judgment has the same exposure.
  • The model was not rerun: it has no future-timestamp bound.

Hold: do-not-merge stays until the owner answers the question saved for him on #16458 (merge this fix, then #16458 with every approved rule passing; or merge #16458 as is; or restate the two rules). No ETA: it waits only on that answer, and merges the same hour once given.

@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 16, 2026
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit a548b3a Nov 16, 2026
67 checks passed
@kyle-sexton
kyle-sexton deleted the fix/work-items-release-outranked-hand-back branch November 16, 2026 16:17
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 16, 2026
kyle-sexton added a commit that referenced this pull request Nov 16, 2026
…very rule holding

The model follows the hand-back's clock read before each lease list and
the outranked release that supersedes its own lease and hands back only
after a supersede succeeded (#16515), and renew's back-off on a failed
PATCH near expiry (#16509). Line citations are at a548b3a. Both
shipped cfgs hold every rule; the known results list the breaks left
under each failure flag.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant