Cloud sessions ship gh 2.45 (Ubuntu archive); work-item-tracker seam requires >= 2.94, so every seam verb fails

[claude]

Summary

Cloud sessions install gh from Ubuntu's own archives, which ships 2.45.0. The work-item-tracker seam requires >= 2.94, so every seam verb fails in every cloud session — including claim, which /work-items:work treats as a non-optional prerequisite of dispatch.

Observed in this session:

$ gh --version
gh version 2.45.0 (2025-07-18 Ubuntu 2.45.0-1ubuntu0.3)

$ plugins/work-items/tools/work-item-tracker/work-item-tracker.sh capabilities
work-item-tracker: gh >= 2.94 required for native sub-issue/dependency flags (found: 2.45)

$ plugins/work-items/tools/work-item-tracker/work-item-tracker.sh list-frontier --autonomous
work-item-tracker: gh >= 2.94 required for native sub-issue/dependency flags (found: 2.45)

Why this matters

/work-items:work is coordination-dependent. Step 0 reclaim, Step 1 list-frontier, and the Step 5 claim are all seam verbs. With the seam unusable:

• No race-safe claim is available. claim (assignee + lease) is the atomic acquisition point and the only collision signal between concurrent lanes; worktree isolation is explicitly not a substitute. A cloud lane can only degrade to an assignee-only claim with no lease, which the tracker-seam reference calls out as a parked decision, not yet a supported mode.
• Stale leases never get reclaimed. Step 0's idempotent reclaim cannot run, so leases from crashed cloud sessions accumulate until an operator clears them.
• Frontier selection falls back to hand-rolled REST. list-frontier derives open ∧ unblocked ∧ unassigned and applies --autonomous; without it, a lane must reimplement that filter per-invocation, which is exactly what the seam exists to prevent.

This is not a work-items-only blocker — it is every seam verb (create-item, get-item, claim, renew-lease, reclaim, link-blocks, add-sub-item, list-sub-items, list-frontier, capabilities).

Root cause

melodic-software/standards → components/cloud-environment/setup.sh, Track A:

# gh comes from Ubuntu's own archives: the official cloud-environments
# worked example is exactly `apt update && apt install -y gh`, and
# cli.github.com (the newer upstream apt repo) is NOT on the default
# allowlist. A silent miss is caught by the verification checklist.
if apt-get install -y gh >>"$LOG" 2>&1; then

The comment is accurate about why the archive was chosen. What it does not account for is that the archive's gh is far behind the floor a fleet component now depends on. Ubuntu ships 2.45.0; the seam needs 2.94+.

The stated "silent miss is caught by the verification checklist" does not cover this case: gh is installed, so the presence check passes. Nothing checks its version against consumers' floors.

Constraint on the fix

Two obvious remedies are both blocked by the environment's network allowlist, so neither is a drop-in:

• cli.github.com (upstream apt repo) — the setup script's own comment records it as not on the default allowlist.

• Release tarball from github.com/cli/cli/releases — verified unreachable from this session:

  $ curl -sIL -o /dev/null -w "%{http_code}\n" https://github.com/cli/cli/releases/latest
  403
  

So this likely needs an allowlist change alongside the script change, not a script change alone. Recording that here so whoever picks it up does not burn a cycle discovering it.

Suggested approach

1. Add whichever host the chosen install path needs (cli.github.com, or objects.githubusercontent.com for release assets) to the environment's Custom allowlist.
2. Install a pinned gh >= 2.94 in Track A, keeping the apt install as the fallback so a blocked allowlist costs an outdated gh rather than none.
3. Add a version assertion to the verification checklist, not just a presence check — this class of failure is invisible to command -v.

Alternative worth considering

The seam's floor exists for native sub-issue/dependency flags. Verbs that need none of that (claim, renew-lease, reclaim, capabilities) arguably should not be gated behind the same version check as add-sub-item / link-blocks. A per-verb floor would let cloud sessions claim work race-safely on an older gh while only the native-hierarchy verbs hard-fail. That is a work-items change rather than a standards one, and may be the cheaper half of the fix.

---

Generated by Claude Code

[kyle-sexton]

[kyle-sexton]

This was generated by AI during triage.

Triage notes

Verified (by code inspection, not live reproduction — this session's gh is 2.97, so gh 2.45 was not reproduced locally):

• The seam dispatcher gates every verb for the github provider on a single, uniform gh >= 2.94 check performed once before verb dispatch — confirmed by reading work-item-tracker.sh's provider-github gating call. It is not currently per-verb, so the "Alternative worth considering" in this issue's body describes work not yet done.
• The GitHub adapter's assignee operations (used by claim / renew-lease / reclaim) already deliberately avoid gh issue edit / GraphQL and go through gh api REST instead, with an adjacent code comment explaining this is specifically because sandboxed/remote sessions serve only a pinned set of GraphQL operations and 403 the rest. That's the same restriction Cloud sessions 403 non-review GraphQL: documented gh issue view --json and gh pr create both fail; REST equivalents work #3170 reports independently — so the lease-protocol verbs this issue cares about most (claim, renew-lease, reclaim) already have a REST-only path, which is corroborating evidence that a relaxed version floor for those verbs specifically is plausible without re-tripping Cloud sessions 403 non-review GraphQL: documented gh issue view --json and gh pr create both fail; REST equivalents work #3170's GraphQL block. (Not verified end-to-end against a real fix: correct plugin-system inaccuracies and harden references #2.45 + GraphQL-403 environment.)
• Field corroboration: issue feat(docs-hygiene): three residue shapes have no markdown owner, so residue in .md is invisible to the fleet #3125 (closed, different subject) carries a first-hand comment from a cloud session hitting this exact combination — gh 2.45, seam dispatcher gate failing, forced into a degraded assignee-only claim with no lease because reclaim/list-frontier/claim/renew-lease were all unavailable. That comment independently confirms this issue's premise.
• Related, not duplicate: Cloud sessions 403 non-review GraphQL: documented gh issue view --json and gh pr create both fail; REST equivalents work #3170 (GraphQL 403 for non-review queries in cloud sessions) and Cloud sessions compose no permission floor: standards claude-permissions (allow AND deny) is never applied #3172 (fleet permission floor never composed into cloud sessions) share the same environment (cloud sessions) as this issue but are separate underlying defects with separate fix locations — not a shared single decision, so they are not folded into a cluster here and are left untouched.

Redundancy check: searched work-item-tracker.sh and the GitHub adapter for an existing per-verb version gate or any cloud-session-specific gh-version handling — none found. Not already implemented.

Rejected-concept ledger: repo has no docs/out-of-scope/ directory — check skipped.

Why a human must act

This routes to human-gated rather than autonomous-eligible for two reasons, not one:

1. Cross-repo policy / scope split. The issue's own "Suggested approach" places the primary remediation (pin a gh >= 2.94 install in melodic-software/standards → components/cloud-environment/setup.sh, plus an allowlist change for whichever install path is chosen) in a different repo than the one this issue is filed in. The "Alternative worth considering" (a per-verb floor in this repo's seam) is explicitly called out by the reporter as "may be the cheaper half of the fix" — meaning even a full implementation of it here does not resolve the issue's stated root cause on its own. Deciding how the fix splits across the two repos (seam-side mitigation only vs. environment-side fix only vs. both, and in what order) is a scope/ownership call, not a single reversible code fork.
2. External-access capability blocker. Step 1 of the suggested approach requires adding a host to the cloud environment's Custom network allowlist. No agent working in this repo (or any repo) can make that change — it requires whoever administers the cloud-environment allowlist.

If a maintainer decides the seam-side mitigation alone is worth doing independently of the environment fix, the shape below is ready to hand to an agent as-is (drop the human-gated label, add the autonomous-eligible label + a work-class: label, and this becomes a normal agent brief).

Agent Brief (scoped to the seam-side mitigation only, pending the human decision above)

Type: Bug
Summary: The work-item-tracker seam's gh version gate is checked once, uniformly, for every verb — so an environment with an older gh (e.g. the 2.45 that cloud sessions currently get from the Ubuntu archive) cannot use any seam verb, including the lease-coordination verbs (claim, renew-lease, reclaim, capabilities, get-item, list-items, list-frontier) that don't touch the native sub-issue/dependency flags the version floor exists to guarantee.

Current behavior:
The dispatcher performs one gh >= 2.94 check for the github provider before routing to any verb. A gh binary below that floor fails every verb identically, with no distinction between verbs that need the native --parent / --blocked-by flags and verbs that don't.

Desired behavior:
Verbs whose GitHub-adapter implementation does not invoke a native sub-issue/dependency flag (candidates: claim, renew-lease, reclaim, get-item, list-items, list-frontier, capabilities) run successfully on whatever gh version their actual invoked subcommands/flags require — verified against the reported minimum (gh 2.45) — rather than being blocked by the higher floor. Verbs that do invoke native sub-issue/dependency flags (candidates: add-sub-item, link-blocks, create-item when given --parent/--blocked-by, and list-sub-items if it relies on the native subIssues field) keep the existing >= 2.94 hard gate, with a clear error naming the flag that requires it.

Key interfaces:

• The dispatcher's provider-gating step (currently a single unconditional call ahead of verb dispatch) — becomes verb-aware, consulting a declared floor per verb rather than one global floor.
• The GitHub adapter's capabilities.json manifest — is a natural place to declare, per verb, whether it needs the native-flag floor, so the dispatcher doesn't hardcode a verb list.
• Any REST-only code paths already in the adapter (the assignee-ops wrapper is one such path) should be preserved as-is — this change relaxes the version gate, not the underlying REST-vs-GraphQL routing.

Acceptance criteria:

• capabilities, claim, renew-lease, reclaim, get-item, list-items, and list-frontier succeed against a gh binary reporting version 2.45 in a test harness (mocked or version-forced), given a valid binding and repo context.
• add-sub-item, link-blocks, and create-item --parent/--blocked-by still fail fast with a clear >= 2.94 message against a gh binary below the floor.
• Existing seam test suite (adapter .test.sh files and dispatcher tests) passes unchanged where behavior is unaffected, and gains coverage for the new per-verb gating.
• CONTRACT.md's Prerequisites section is updated to describe the per-verb floor instead of a single blanket floor.

Out of scope:

• Any change to melodic-software/standards (allowlist, pinned gh install, verification-checklist version assertion) — tracked separately, cross-repo, and gated on the human decision above.
• Changing REST-vs-GraphQL routing for any verb (already handled; not this issue).
• Cloud sessions 403 non-review GraphQL: documented gh issue view --json and gh pr create both fail; REST equivalents work #3170 and Cloud sessions compose no permission floor: standards claude-permissions (allow AND deny) is never applied #3172 — related cloud-session environment gaps, separate fixes.

---

Generated by Claude Code

[kyle-sexton]

This was generated by AI during triage.

Correction to the brief above: list-items / list-frontier likely can't be relaxed as written

The prior brief's acceptance criteria listed list-items and list-frontier alongside claim/renew-lease/reclaim/get-item/capabilities as verbs that should run on the older, non-native-flag floor. On closer look that's probably wrong for those two specifically:

• list-items' GitHub adapter requests --json … blockedBy …. blockedBy is the read side of the same native dependency feature the >= 2.94 floor exists to guarantee — plausibly unsupported (Unknown JSON field-style failure) on gh 2.45, the same failure shape as an unsupported --json field on any gh version.
• list-frontier is core-derived from list-items and is defined (CONTRACT.md) as filtering on blocked_by_count == 0, so it structurally depends on that same field. It can't be relaxed without either an explicit degraded fallback (treat missing dependency data as "not blocked," which changes frontier correctness) or accepting a wrong frontier — a decision of its own, not a free relaxation.

Whoever picks this up (human or, later, an agent under a human-approved scoped brief) should treat the safely-relaxable candidate set as capabilities, claim, renew-lease, reclaim, get-item only, and treat list-items/list-frontier as needing their own explicit call on whether a blockedBy-less degraded mode is acceptable — verify against gh's actual --json field support at 2.45 before committing to either path.

This narrows, not reverses, the scoped-mitigation option described above; it doesn't change the human-gated routing or the cross-repo/allowlist reasoning.

---

Generated by Claude Code

[claude]

This was generated by AI during triage.

Decision-ready summary — the headline premise no longer holds; the item needs re-scoping, not execution

Lane: autonomous triage, instance vm-triage-202609050304. No labels changed.

Empirical finding: this triage session IS the failing configuration, and the seam works

This session runs gh version 2.45.0 (2025-07-18 Ubuntu 2.45.0-1ubuntu0.3) — byte-for-byte the version in the issue's reproduction block. The issue states that with this gh, "every seam verb fails," and shows capabilities and list-frontier both erroring out.

Re-run on current main, same gh 2.45:

$ plugins/work-items/tools/work-item-tracker/work-item-tracker.sh capabilities
{"schema_version":"1.0","provider":"github","verbs":{"create-item":true,"get-item":true,
"claim":true,"renew-lease":true,"reclaim":true,"link-blocks":true,"add-sub-item":true,
"list-items":true,"list-sub-items":true,"capabilities":true},...}

capabilities returns cleanly. And claim is not merely reachable — this lane successfully claimed eight issues through it during this cycle (#3346, #3347, #3348, #3349, #3351, #3352, #3356, #3357), each returning a well-formed lease with acquired_at, ttl_hours and lease_comment_id. Race-safe claiming works on gh 2.45 today.

What changed: the per-verb floor was implemented

The issue's closing section, "Alternative worth considering," proposed exactly this:

Verbs that need none of that (claim, renew-lease, reclaim, capabilities) arguably should not be gated behind the same version check as add-sub-item / link-blocks. A per-verb floor would let cloud sessions claim work race-safely on an older gh while only the native-hierarchy verbs hard-fail.

That is now the shipped design. CONTRACT.md:69 states it directly: below 2.94, "only the native-surface paths above are refused; the lease trio, get-item, …" continue to work. lib/gh-version.sh exposes wit_gh_has_native_surface as a non-exiting predicate rather than a uniform pre-dispatch gate, and create-item.sh:72 degrades gracefully — it drops the 2.94 --type flag and applies the coarse type: label instead of failing.

So the issue's own "cheaper half of the fix" landed, and it was the half that mattered: /work-items:work is no longer blocked in cloud sessions. The three consequences the issue lists under "Why this matters" — no race-safe claim, stale leases never reclaimed, frontier selection falling back to hand-rolled REST — are all resolved.

Why the gate is still legitimate

needs-human should stay, and this triage did not lift it. What remains is genuinely human work:

1. The standards half is untouched and is cross-repo. melodic-software/standards → components/cloud-environment/setup.sh still installs gh from Ubuntu's archives. Changing that is a change to another repository's fleet component.
2. It needs an allowlist change, not just a script change. The issue verified that both remedies are blocked by the environment's network allowlist (cli.github.com not on the default list; github.com/cli/cli/releases returns 403). An allowlist change is an operator action this lane cannot take and cannot evaluate the security posture of.
3. The verification-checklist gap is a policy question. Nothing checks an installed tool's version against consumers' floors — only its presence. Deciding whether the fleet's verification contract should assert versions is a standards-level call.

The decision, with a recommendation

RECOMMENDED — re-scope this issue to the residual, and drop the "every seam verb fails" framing.

The title and summary are now actively misleading; a reader picking this up would go hunting for a blocker that no longer exists. Concretely:

• Retitle to something like "Cloud sessions ship gh 2.45; native sub-issue/dependency verbs still hard-fail, and nothing version-checks fleet tool floors."
• Record in-thread that the per-verb floor shipped and that claim/renew-lease/reclaim/capabilities/get-item are confirmed working on 2.45 — so the next reader does not re-derive it.
• Keep three open items: (a) the standards allowlist + pinned-gh install; (b) a version assertion in the verification checklist, not just a presence check; (c) confirm which native-surface verbs cloud lanes actually need — if none, the residual is priority-low rather than medium.

Alternative a maintainer might prefer: close this and open a narrow standards issue for the allowlist plus a separate one for version assertions. Reasonable — the remaining work lives almost entirely in the other repo. Recommended only if the cross-repo pointer is preserved, since the evidence gathered here is the reason anyone would prioritize it.

One caution

The verification above establishes that the seam's lease trio and capabilities work on 2.45. It does not establish that list-frontier --autonomous works on 2.45 — that verb was not exercised this cycle, and a prior correction on this thread already flagged that list-items/list-frontier likely cannot be relaxed as the original brief assumed, because they depend on native filter fields. Whoever re-scopes should test that verb specifically rather than inferring it from capabilities reporting true, which advertises the verb's existence, not its version-independence.

---

Generated by Claude Code

[kyle-sexton]

Fresh evidence from a cloud session on 2026-09-11 (gh 2.45.0, /work-items:track add filing #4094):

• capabilities and the version guard now pass on 2.45, so the blanket "every seam verb fails" is no longer the failure mode. create-item still fails, for a different reason: it runs gh issue create, which is GraphQL-backed and returns HTTP 403: GitHub GraphQL is not available from Claude Code sessions. The REST create (gh api repos/{owner}/{repo}/issues, or the GitHub MCP issue_write) succeeds with the same title, body, labels, and native type.
• The --type fallback on gh < 2.94 substitutes a type: task label (create-item.sh lines 68-72). This repository defines no type: labels (it uses native Issue Types), so on a repo like this one the fallback would fail the create even after the GraphQL problem is fixed. The fallback should check the live label set before applying a type: label, or skip the type entirely and say so.
• The add action's search-before-create pre-flight (gh issue list --search, adapter README "Search items") is also GraphQL and 403s the same way; the search/issues REST endpoint is blocked as non-repo-scoped in cloud sessions too, so the only working duplicate check from a cloud session is the GitHub MCP search_issues tool or a repo-scoped repos/{owner}/{repo}/issues listing filtered client-side.

Net: from a cloud session the seam's GitHub adapter needs a REST path for create-item and for the search pre-flight, independent of the gh version bump this issue tracks.

---

Generated by Claude Code