Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/one-lease-comment-per-step.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"github-agent-workflow": patch
---

`claim` and `renew` now edit this account's own lease comment for the step in place instead of posting a new one each time, so an item taken through three claims of a step has one lease comment, not three. Each step keeps its own comment, a comment from another account is never edited, and if the edit fails the helper posts a new one. Because a comment's position in the thread no longer says which lease is newest, `lease_live` and `leaseState` now take the lease written last (`updated_at`, else `created_at`, else thread order); the expiry is still the `expires=` in the marker. New helper `ownLeaseComment` and CLI command `own-lease` in `helpers.mjs`, shared fixtures for the ordering, and shell tests for one comment per step, other accounts, the failed-edit fallback and the ordering (#69).
10 changes: 6 additions & 4 deletions skills/meta/agent-workflow-protocol/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,18 +160,20 @@ Some runners (a chat automation with a GitHub connector, for example) cannot run

## Leases

A lease is **live** only if the item carries the lease label **and** the newest trusted `agent:lease` marker has not expired. Anything else counts as unleased: a label with no marker, a label with an expired marker, a marker from an untrusted account, a missing label.
A lease is **live** only if the item carries the lease label **and** the newest trusted `agent:lease` marker has not expired. The newest marker is the one written last (a comment's `updated_at`, else its `created_at`; thread order if neither), because a comment can be edited in place (**One lease comment per step**). The expiry is always the `expires=` inside the marker, never a timestamp of the comment. Anything else counts as unleased: a label with no marker, a label with an expired marker, a marker from an untrusted account, a missing label.

| Helper | Does |
|---|---|
| `has_label N issue\|pr LABEL` | exit 0 if N currently carries LABEL |
| `lease_live N` | exit 0 if the newest trusted lease marker on N is unexpired |
| `claim N issue\|pr LABEL STEP TTL` | add the label, post a lease marker |
| `renew N issue\|pr STEP TTL` | post a newer marker. Do this before the lease runs out, if a long task needs it |
| `claim N issue\|pr LABEL STEP TTL` | add the label, write the lease marker (an edit of this step's own lease comment if there is one, else a new comment) |
| `renew N issue\|pr STEP TTL` | write a newer marker the same way. Do this before the lease runs out, if a long task needs it |
| `release N issue\|pr LABEL` | remove the label |

**Checking a lease changes nothing.** Eligibility only reads: `lease_live` and `has_label`. A lease label left by a run that died is not removed by looking at it. The next `claim` re-adds it and posts a fresh marker, and `release` removes it.

**One lease comment per step.** `claim` and `renew` look for this account's own earlier lease comment for the same step on the item (the author is the account the agent runs as, and the body holds `<!-- agent:lease step=STEP `). If there is one, they edit it in place; otherwise they post one. An item that goes through three claims of a step therefore has one lease comment for that step, not three, and a `noop` leaves that one comment and no more. Each step has its own comment, so triaging and implementing an issue leave two. A lease comment written by any other account is never edited, and if the edit fails the helper posts a new comment: `lease_live` reads the newest lease either way, so the fallback only adds noise. A runner whose tools cannot edit a comment may post instead, with the same result.

**Nested calls.** A skill that calls an item skill (itself, or another step) on an item it already holds passes `lease_held=true`. The callee then skips its own claim and release, and requires that the lease is live. Without it the callee would see the caller's live lease and skip the item, and a nested release would drop the caller's lease. Only the caller that took a lease releases it.

TTLs are `lease_ttl_triage`, `lease_ttl_implement` and `lease_ttl_pr`. Concurrency is best-effort: two runs can claim the same item in the same second. Every step is idempotent, so the worst case is duplicated work.
Expand All @@ -182,7 +184,7 @@ Hidden HTML comments make state readable without parsing prose. Append them as t

| Marker | Written by | Used for |
|---|---|---|
| `<!-- agent:lease step=… run=… expires=… -->` | `claim`, `renew` | lease expiry |
| `<!-- agent:lease step=… run=… expires=… -->` | `claim`, `renew` (edited in place, one comment per step) | lease expiry |
| `<!-- agent:implements issue=N -->` | Implementing, in the **PR description** | links a PR to its issue, so a second PR is never opened for it (`prs_for_issue N`) |
| `<!-- agent:handoff kind=ready sha=… -->` | Shepherding | the PR was reviewable at this head SHA |
| `<!-- agent:handoff kind=review sha=… open=N -->` | Reviewing, when it does not merge; `N` = findings still unfixed | counts review rounds; `open_findings N` tells Shepherding what is left |
Expand Down
46 changes: 41 additions & 5 deletions skills/meta/agent-workflow-protocol/scripts/helpers.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
* utc-plus DURATION [FROM] FROM (default: now) plus a duration, as UTC ISO-8601 (Z)
* utc-epoch TIMESTAMP Unix seconds
* lease-body STEP RUN EXPIRES [renew] the lease comment
* own-lease STEP SELF (JSON lines on stdin) id of SELF's own lease comment for STEP, or nothing
* failure-body STEP RUN REASON the failure comment
* log-window DAYS DAYS as a whole number of days, or 14 if it is not one
* log-title title for a new run-log issue
Expand Down Expand Up @@ -116,7 +117,10 @@ export function utcEpoch(iso) {

// ---- comment shapes -----------------------------------------------------------------------

/** The lease comment. `kind` is "claim" or "renew". */
/**
* The lease comment. `kind` is "claim" or "renew". A step keeps one lease comment per item: a later
* claim or renewal edits it (see ownLeaseComment) instead of posting another.
*/
export function leaseComment(step, runId, expiresIso, kind = 'claim') {
const marker = `<!-- agent:lease step=${step} run=${runId} expires=${expiresIso} -->`;
const verb = kind === 'renew' ? 'Lease renewed by' : 'Claimed by';
Expand Down Expand Up @@ -345,18 +349,46 @@ export function markersOf(comments, trust) {
return out;
}

/** The newest trusted lease on an item: its expiry and whether it is still live. Null if none. */
/**
* The newest trusted lease on an item: its expiry and whether it is still live. Null if none.
*
* "Newest" is the lease written last. A step edits its own lease comment in place when it claims or
* renews again, so the position of a comment in the thread no longer says which lease is newest:
* its last write (`updated_at`, else `created_at`) does. Comments with neither, such as the shared
* fixtures, fall back to thread order. The edit time only orders leases. The expiry is always the
* `expires=` in the marker, never a timestamp of the comment.
*/
export function leaseState(comments, trust, now = new Date()) {
let last = null;
let lastAt = '';
for (const c of comments) {
if (!isTrusted(c, trust)) continue;
const m = String(c.body ?? '').match(/<!-- agent:lease [^>]*expires=([0-9TZ:-]+)/);
if (m) last = m[1];
if (!m) continue;
const at = String(c.updated_at ?? c.created_at ?? '');
if (at >= lastAt) { last = m[1]; lastAt = at; }
}
if (!last) return null;
return { expires: last, live: Math.floor(now.getTime() / 1000) < utcEpoch(last) };
}

/**
* The id of the lease comment that `selfLogin` itself wrote for `step` on an item, or null. `claim`
* and `renew` edit it instead of posting another. Only the agent's own login counts: a comment from
* anyone else, trusted or not, cannot be edited and is never touched. If several exist (older runs
* posted one per claim), the last one is edited. Each entry is `{id, body, login}`.
*/
export function ownLeaseComment(comments, selfLogin, step) {
if (!selfLogin) return null;
const needle = `<!-- agent:lease step=${step} `;
let id = null;
for (const c of comments) {
if ((c?.login ?? c?.user?.login) !== selfLogin) continue;
if (String(c.body ?? '').includes(needle)) id = c.id ?? id;
}
return id;
}

/** Review handoffs since the last hand-off to a human. A person who takes a PR over starts it afresh. */
export function reviewRounds(markers) {
let c = 0;
Expand Down Expand Up @@ -572,8 +604,8 @@ export const NO_SHELL_OPS = {
log_issue: 'list_issues (not search_issues: search is a slow, approximate index and will not show an issue made a minute ago) with labels ["agent:log"], state OPEN, orderBy CREATED_AT, direction ASC. currentLogIssue picks the one to append to. None: issue_write create with logIssueTitle, label agent:log and logIssueBody. Then list again: if a lower-numbered one now exists, close yours as not_planned (duplicate_of it) and use that.',
log_run: 'issue_read get_comments on the log issue and stop if hasLogEntry says this run and step are already there. Otherwise add_issue_comment with stampLogEntry(formatLogComment(...)), then issue_write update on the log issue with touchLogIssueBody as the new body. Real line breaks, never the two characters backslash-n. There is no separate difficulty issue.',
read_logs: 'list_issues for agent:log (state all, newest first), read each one\'s comments newer than the lookback, skip readableLogEntries-idle ones (nothing eligible, Problems none).',
claim: 'Add the lease label, then add_issue_comment with leaseComment(..., "claim"). Do nothing when lease_held is true.',
renew: 'add_issue_comment with leaseComment(..., "renew").',
claim: 'Add the lease label, then write leaseComment(..., "claim"): if ownLeaseComment finds this account\'s lease comment for the step on the item, edit it in place, otherwise (or if your tools cannot edit a comment, or the edit fails) add_issue_comment. Do nothing when lease_held is true.',
renew: 'Same as claim, with leaseComment(..., "renew"): edit this account\'s lease comment for the step if there is one, else add_issue_comment.',
release: 'Remove the lease label. Do nothing when lease_held is true.',
client_guidance_files: 'get_file_contents on the repository root and on .github, docs, .cursor/rules, .claude/rules, .agents and .github/ISSUE_TEMPLATE, on the DEFAULT branch (no ref, never a PR branch). Keep what guidanceFiles accepts, then read each one in full.',
item_labels: 'issue_read get on the item for its label names, then get_label for each: its description is guidance too (references/client-guidance.md).',
Expand Down Expand Up @@ -605,6 +637,10 @@ function cli(argv) {
return codeownersFor(j.text, j.files ?? []).join('\n');
}
case 'lease-body': return leaseComment(a[0], a[1], a[2], a[3] === 'renew' ? 'renew' : 'claim').body;
case 'own-lease': {
const comments = stdin().split('\n').filter(Boolean).map((l) => JSON.parse(l));
return String(ownLeaseComment(comments, a[1] ?? '', a[0] ?? '') ?? '');
}
case 'failure-body': return failureComment(a[0], a[1], a[2] ?? '').body;
case 'log-window': return String(logWindowDays(a[0]));
case 'log-title': return logIssueTitle();
Expand Down
29 changes: 24 additions & 5 deletions skills/meta/agent-workflow-protocol/scripts/lib.sh
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
# export them first. Whatever the run does not set falls back to the default below, exactly as
# ../SKILL.md's Defaults table describes.
#
# Helpers: has_label lease_live claim renew release clear_stale_lease leases
# Helpers: has_label lease_live claim renew release clear_stale_lease leases (one comment per step)
# lane_holder ready_at the merge lane
# changed_files protected_files codeowners_for paths and owners
# markers review_rounds shepherd_attempts failures reading markers
Expand Down Expand Up @@ -134,28 +134,47 @@ _trusted_json_jq() {

has_label() { gh "$2" view "$1" --json labels --jq '.labels[].name' | grep -qx -- "$3"; }

# The newest trusted lease is the one written last (updated_at, else created_at; see leaseState in
# helpers.mjs), because claim and renew edit a step's lease comment in place. `sort -s` keeps thread
# order for equal times. The expiry is the one in the marker, never the comment's own timestamp.
lease_live() {
local exp now
exp=$(gh api "repos/{owner}/{repo}/issues/$1/comments" --paginate \
--jq ".[] | select($(trusted_jq)) | .body | capture(\"<!-- agent:lease [^>]*expires=(?<e>[0-9TZ:-]+)\") | .e" \
| tail -n1)
--jq ".[] | select($(trusted_jq)) | (.updated_at // .created_at // \"0\") as \$t | .body | capture(\"<!-- agent:lease [^>]*expires=(?<e>[0-9TZ:-]+)\") | \"\\(\$t) \\(.e)\"" \
| sort -s -k1,1 | tail -n1 | cut -d' ' -f2)
now=$(date -u +%s)
[ -n "$exp" ] && [ "$now" -lt "$(utc_epoch "$exp")" ]
}

# Write the lease comment for STEP on item N: edit this account's own lease comment for the step if
# the item has one, otherwise post one. An item that goes through several claims and renewals keeps
# one lease comment per step instead of one per claim. If the edit fails, post: lease_live reads the
# newest lease either way, so the fallback is only noisier.
_write_lease() {
local n=$1 kind=$2 step=$3 exp=$4 how=$5 body id
body="$(node "$AGENT_HELPERS" lease-body "$step" "$RUN_ID" "$exp" "$how")"
id=$(gh api "repos/{owner}/{repo}/issues/$n/comments" --paginate \
--jq '.[] | {id, body, login: .user.login} | @json' 2>/dev/null \
| node "$AGENT_HELPERS" own-lease "$step" "$(_agent_self)") || id=
if [ -n "$id" ] && gh api -X PATCH "repos/{owner}/{repo}/issues/comments/$id" -f body="$body" >/dev/null 2>&1; then
return 0
fi
gh "$kind" comment "$n" --body "$body" >/dev/null
}

# claim and release do nothing when $lease_held is true: the caller holds the lease (a nested call).
claim() {
[ "$lease_held" = true ] && return 0
local n=$1 kind=$2 label=$3 step=$4 ttl=$5 exp
exp=$(utc_plus "$ttl")
gh "$kind" edit "$n" --add-label "$label" >/dev/null
gh "$kind" comment "$n" --body "$(node "$AGENT_HELPERS" lease-body "$step" "$RUN_ID" "$exp")" >/dev/null
_write_lease "$n" "$kind" "$step" "$exp" claim
}

renew() {
local n=$1 kind=$2 step=$3 ttl=$4 exp
exp=$(utc_plus "$ttl")
gh "$kind" comment "$n" --body "$(node "$AGENT_HELPERS" lease-body "$step" "$RUN_ID" "$exp" renew)" >/dev/null
_write_lease "$n" "$kind" "$step" "$exp" renew
}

release() {
Expand Down
32 changes: 32 additions & 0 deletions tests/fixtures/markers.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,38 @@
"lease_live": true
}
},
{
"name": "the lease written last wins, even when its comment was posted first",
"comments": [
{
"body": "x <!-- agent:lease step=Triaging run=a expires=2099-01-01T00:00:00Z -->",
"updated_at": "2026-03-01T00:00:00Z"
},
{
"body": "x <!-- agent:lease step=Implementing run=b expires=2020-01-01T00:00:00Z -->",
"updated_at": "2026-02-01T00:00:00Z"
}
],
"expect": {
"lease_live": true
}
},
{
"name": "the other way round, the later write is the expired one",
"comments": [
{
"body": "x <!-- agent:lease step=Triaging run=a expires=2099-01-01T00:00:00Z -->",
"updated_at": "2026-01-01T00:00:00Z"
},
{
"body": "x <!-- agent:lease step=Implementing run=b expires=2020-01-01T00:00:00Z -->",
"updated_at": "2026-02-01T00:00:00Z"
}
],
"expect": {
"lease_live": false
}
},
{
"name": "an expired lease is not live",
"comments": [
Expand Down
35 changes: 35 additions & 0 deletions tests/helpers.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ const asComment = (c) => ({
body: c.body,
author_association: c.author_association ?? 'OWNER',
user: { login: c.login ?? 'maintainer' },
...(c.updated_at ? { created_at: c.updated_at, updated_at: c.updated_at } : {}),
});

for (const f of fixtures) {
Expand All @@ -34,6 +35,40 @@ for (const f of fixtures) {
});
}

test('ownLeaseComment finds this account\'s own lease comment for the step, and nothing else', () => {
const lease = (step, run) => `Claimed by ${step} run ${run}.\n<!-- agent:lease step=${step} run=${run} expires=2099-01-01T00:00:00Z -->`;
const comments = [
{ id: 1, login: 'agent-bot', body: lease('Triaging', 'r1') },
{ id: 2, login: 'agent-bot', body: lease('Implementing', 'r2') },
{ id: 3, login: 'maintainer', body: lease('Triaging', 'r3') },
{ id: 4, login: 'agent-bot', body: 'a plain comment' },
{ id: 5, login: 'agent-bot', body: lease('Triaging', 'r4') },
];
assert.equal(h.ownLeaseComment(comments, 'agent-bot', 'Triaging'), 5, 'the last one, if older runs left several');
assert.equal(h.ownLeaseComment(comments, 'agent-bot', 'Implementing'), 2);
assert.equal(h.ownLeaseComment(comments, 'agent-bot', 'Reviewing'), null);
assert.equal(h.ownLeaseComment(comments, 'maintainer', 'Implementing'), null, 'another account\'s comment is never ours');
assert.equal(h.ownLeaseComment(comments, '', 'Triaging'), null, 'no login, no match');
assert.equal(h.ownLeaseComment([{ id: 9, login: 'agent-bot', body: lease('Triaging2', 'r') }], 'agent-bot', 'Triaging'), null, 'a step name that only starts the same does not match');
});

test('own-lease CLI reads JSON lines and prints the id or nothing', () => {
const run = (step, self, lines) => execFileSync('node', [helpersPath, 'own-lease', step, self], { input: lines.map((l) => JSON.stringify(l)).join('\n') }).toString().trim();
const body = 'x\n<!-- agent:lease step=Triaging run=r expires=2099-01-01T00:00:00Z -->';
assert.equal(run('Triaging', 'agent-bot', [{ id: 7, login: 'agent-bot', body }]), '7');
assert.equal(run('Triaging', 'agent-bot', [{ id: 7, login: 'someone', body }]), '');
assert.equal(run('Triaging', 'agent-bot', []), '');
});

test('the edit time of a lease comment orders leases but is never its expiry', () => {
const trust = { selfLogin: 'agent-bot' };
const c = (body, at) => ({ body, user: { login: 'agent-bot' }, author_association: 'NONE', updated_at: at, created_at: at });
const now = new Date('2026-10-15T12:00:00Z');
const state = h.leaseState([c('<!-- agent:lease step=Triaging run=a expires=2026-10-15T11:00:00Z -->', '2026-10-15T11:59:00Z')], trust, now);
assert.equal(state.expires, '2026-10-15T11:00:00Z');
assert.equal(state.live, false, 'edited a minute ago, but the lease in the marker ran out an hour ago');
});

test('isTrusted reads both the REST and the gh --json shapes', () => {
assert.equal(h.isTrusted({ authorAssociation: 'COLLABORATOR', author: { login: 'x' } }), true);
assert.equal(h.isTrusted({ author_association: 'CONTRIBUTOR', user: { login: 'x' } }), false);
Expand Down
Loading
Loading