work-items local-markdown claim.sh: lease/assignee integrity (expired lease never clears assignee; failed assignee write reports success)

[kyle-sexton]

Follow-up from #224 (bundle work-item-tracker seam, shape A). Two related local-markdown/claim.sh lease/assignee-integrity gaps, deferred by author delegation. Both are in byte-identical-moved code (relocated from medley, not changed by #224) and need care/design, not a mechanical patch.

Finding 1 (P1) — expired lease never clears the assignee, so abandoned claims never return to the frontier

Source: #224 review thread on adapters/local-markdown/claim.sh.

For the local-markdown binding, an expired lease still leaves the item's assignees frontmatter populated. /work now treats its unsupported reclaim (exit 6) as a no-op, while list-frontier always excludes assigned items — so any abandoned local claim is permanently absent from normal autonomous/manual selection after its TTL expires.

Assessment: is there a small safe fix?

No — both candidate fixes change runtime frontier-selection behavior on relocated code, and one raises a genuine design question:

1. Clear the stale assignee when an expired lease is detected during frontier/list derivation. Changes how list-frontier/list derivation treats expired-lease items — behavioral, not mechanical.
2. Add a genuine local-markdown reclaim.sh (mirroring github) and flip capabilities.json reclaim to true. github's reclaim also does an activity check (comments / PR cross-references) with no offline equivalent, since local-markdown is deliberately "never a coordination surface" (per the setup skill). Defining offline reclaim semantics is a design decision.

Note this is a direct consequence of #224's own commit f15a329; it does not regress below the pre-#224 state (where local-markdown reclaim was unsupported and exit-6 was a hard failure).

Finding 2 (P2) — a failed assignee write still reports a successful claim

Source: #224 re-review thread on adapters/local-markdown/claim.sh (post-merge-head re-review).

claim.sh appends the inline lease marker to the item file, then calls wit_fm_set "$file" assignees ... with no return-code check and no set -e. If wit_fm_set fails (e.g. the filesystem is full or the store cannot be rewritten), the nonzero result is ignored and the script still emits a successful claim JSON. The lease marker has already been appended, but assignees remains empty — so list-frontier presents the item as available while later claims conflict on the live lease until it expires.

Suggested direction

Propagate the wit_fm_set failure (fail the claim) and compensate for the partial write — roll back the lease marker appended immediately before — rather than reporting success on a half-applied claim. Extend the local-markdown conformance suite to cover a failed assignee write and expired-lease reclamation.

Why grouped

Both concern claim.sh's invariant that a claim's lease marker and assignees stay consistent (and that expired/failed claims return to the frontier). A single design/hardening pass over claim.sh should address both.

[kyle-sexton]

This was generated by AI during triage.

T2 triage — planning note. Read the two findings against the actual seam code (plugins/work-items/tools/work-item-tracker/): adapters/local-markdown/claim.sh and common.sh, adapters/local-markdown/list-items.sh / get-item.sh, lib/frontier.sh, lib/lease.sh, adapters/github/reclaim.sh, adapters/local-markdown/renew-lease.sh, capabilities.json, and CONTRACT.md "Lease protocol". Both findings confirmed. Below is a concrete, function-level plan and a defaulted decision for Finding 1.

---

Grounding: where the two derivation layers actually live

list-frontier is core-side (lib/frontier.sh → wit_filter_frontier). It runs only over the list-items envelope JSON and filters on state == "open" and blocked_by_count == 0 and ((.assignees // []) | length == 0). That layer is provider-agnostic and has no access to lease markers — those live inside the item file and are adapter-internal. So "detect an expired lease during derivation" is impossible in the core filter; it can only happen in the local-markdown adapter, where the emitted item object is built by wit_emit_local_item (in adapters/local-markdown/common.sh), the single code path feeding both list-items and get-item.

Linchpin fact for Finding 1. In local-markdown, create-item.sh always writes assignees: [], and only claim.sh ever populates assignees (to [holder]), and claim.sh always writes a lease marker alongside it. Therefore, on this adapter, a non-empty assignees always corresponds to a written lease — there is no manual, lease-less assignment path (unlike GitHub). This removes the one case that forces judgment in GitHub's reclaim (never touch a manual assignment). It is what makes the fix below a mechanical projection rather than a semantic adjudication.

---

Finding 1 (P1) — expired lease never clears the assignee

The fork is closed, not open

The github-parity third option (a real activity check over comments / PR cross-references) is provably unavailable offline — the issue states there is no offline equivalent, and CONTRACT.md declares local-markdown "NEVER a coordination surface." So the actual fork is not "auto-return vs github-style reclaim." It is:

• (a) return expired claims to the frontier via a derived-field rule, or
• (b) the bug persists — abandoned local claims are hidden forever (/work's local reclaim is exit-6 no-op; list-frontier always excludes assigned items).

That is fix-vs-regression, which is the definition of a maintainer-vetoable default, not open design space. This matches the issue author's own framing: of the two candidates they tagged only (b) — building reclaim.sh + flipping capabilities.json — as "a design decision"; option (a) they called "behavioral, not mechanical," which is not the same as "needs a design call."

Option (a), stated as one derived-field rule

In wit_emit_local_item, emit the stored assignees only while a live lease backs them; otherwise emit [].

Concretely, in wit_emit_local_item (adapters/local-markdown/common.sh): after reading assignees from frontmatter, if it is non-empty, resolve the active lease with the already-sourced wit_active_lease_json "$file" and test it with wit_lease_is_live "$active" "$now_epoch" (both from lib/lease.sh, already in scope). If there is no active lease, or it is not live (expired or superseded), project assignees: [] in the emitted object. The stored frontmatter is not modified.

This single rule is the direct encoding of the contract's own definition — "Claim = assignee + live lease record" — and it uniformly covers expired, superseded, and (should it ever arise) the anomalous assignee-without-lease case.

Why this is contained and non-architectural

• Read-only. No write occurs during a read verb; get-item.sh's "Read-only" header stays true.
• No new capability, no new verb, no offline reclaim semantics invented. capabilities.json reclaim stays false. No activity check is fabricated. Nothing in the core seam changes.
• The emitted item object is already a derived view, not raw frontmatter. blocked_by_count is computed live from blocker files, not stored. Lease-gated assignees is the same kind of derived field — this precedent is what makes the store-vs-emitted divergence a non-issue rather than a new architecture.
• Coherent with renew-lease. renew-lease.sh renews the active (newest non-superseded) lease in place and never touches assignees. An expired-but-non-superseded lease is still "active," so a holder can renew it back to live; because (a) never clears stored assignees, the very next derivation re-reflects the holder and the item leaves the frontier again. This is the offline, manually-driven analog of GitHub reclaim's "activity → renew in place." Single-writer store ⇒ sequential ⇒ no race.

Explicitly REJECTED sub-variant (the trap)

Do not implement (a) by clearing the assignees frontmatter during a read/derivation verb. Making get-item / list-items mutate the store on read is the genuinely architectural version (surprising write side-effects on read, concurrency implications, conformance expects reads not to mutate). If an implementer reaches for wit_fm_set inside a list/get path, that is out of scope and must be rejected. The fix is a projection in the emitted JSON only.

The one vetoable point to disclose

With (a), local-markdown's emitted assignees becomes live-lease-derived, diverging from the GitHub adapter's raw assignees (where an expired-lease item stays hidden until an explicit reclaim runs). This divergence is forced by the offline constraint (no activity signal exists to gate on), which is exactly why it is a vetoable default and not open design. Worth a one-line note in CONTRACT.md's local-markdown section when implemented.

Decision defaulted: option (a) — veto before merge

Ship option (a) as the read-only live-lease projection in wit_emit_local_item, reject the mutate-on-read variant, keep reclaim: false. A maintainer who wants GitHub-identical "stays hidden until explicit reclaim" semantics on the offline surface can veto and reopen the design — but note that path has no offline activity check to stand on.

---

Finding 2 (P2) — a failed assignee write still reports a successful claim

Confirmed call site

In claim.sh, immediately after the pre-write race check, two unchecked mutating writes run under set -uo pipefail (no set -e):

1. printf '%s%s -->\n' "$WIT_LEASE_MARKER" "$lease" >>"$file" — appends the lease marker.
2. wit_fm_set "$file" assignees "$(jq -cn --arg h "$holder" '[$h]')" — sets assignees.

wit_fm_set (common.sh) is awk … >"$tmp" && mv "$tmp" "$file" and returns non-zero if mktemp/redirect/mv fail (e.g. disk full). Its status is discarded, and the script proceeds to emit success JSON. Result: lease marker present, assignees empty — the item shows as available in the frontier while later claims conflict on the live lease until TTL expiry.

Concrete fix

Keep the append-first order (reordering to assignees-first is worse: a failed lease append would leave an assignee with no lease — an item hidden from the frontier with no lease to ever expire, i.e. permanently stuck, strictly worse than the current bug). Then:

• Capture the exact appended marker line in a variable before appending (it is unique: lease_comment_id comes from wit_next_lease_id, a store-global max+1).
• Check both writes, not just wit_fm_set — the printf … >>"$file" append is also unchecked today; on disk-full it can fail while a subsequent wit_fm_set succeeds, producing assignee-without-lease. A complete fix guards both.
• On wit_fm_set failure: best-effort roll back the just-appended marker (filter the exact captured line out via a temp file + mv, mirroring wit_fm_set's own tmp+mv idiom), emit a stderr diagnostic, and exit 1 (per CONTRACT.md exit-code catalog, a disk-full write is 1 "internal / unexpected"; not 3, which is "binding/config missing").
• If the rollback itself also fails (same disk-full cause), still exit 1 — a stranded lease marker over an empty assignee is the bounded, self-healing residue (it expires at TTL, and Finding 1's rule already re-surfaces it), whereas today's false-success is unbounded. Failing the claim is the core correctness fix regardless of whether rollback fully completes.

Note the invariant

Finding 2's fix preserves the "assignee ⟹ lease" invariant at write time; Finding 1's rule auto-heals any residual assignee-without-lease (or expired lease) back into the frontier at read time. They are mutually reinforcing — one coherent hardening pass over the lease/assignee consistency of claim.sh + wit_emit_local_item, exactly as the issue proposes.

---

Conformance

Local-markdown currently has no coverage of expired-lease → frontier return: in conformance/run-conformance.sh the expired-lease reclaim assertions are gated behind verb_supported reclaim, which is false for this adapter, so they are skipped. Extend the local-markdown conformance suite to cover:

1. Expired-lease frontier return — claim with --ttl-hours 0, then assert get-item emits assignees: [] and list-frontier re-includes the item; then renew-lease and assert it leaves the frontier again.
2. Failed assignee write — force wit_fm_set failure (e.g. a read-only store dir), assert claim exits non-zero, emits no success JSON, and leaves no residual live lease (marker rolled back).

---

Routing

• Confidence: HIGH. Finding 1 is a single clear fork with a maintainer-vetoable default and no architectural change (read-only projection; capabilities unchanged); Finding 2 is a mechanical correctness fix with a precise call site. Marking status: ready with the defaulted decision above.