work-item-tracker: lease TTL is integer-hours only — sub-hour granularity needed for high-cadence consumers

[kyle-sexton]

The lease protocol (plugins/work-items/tools/work-item-tracker: CONTRACT.md config.lease_ttl_hours, lib/lease.sh expiry = renewed_epoch + ttl*3600, adapters' claim.sh --ttl-hours validated ^[0-9]+$) cannot represent TTLs under one hour, and 0 disables leasing.

Consumer driving this: the autonomy-demo drain (kyle-sexton/autonomy-demo-scratch) moved to a 15-minute fire cadence; its runs finish in ~3.5min, and a stuck claim should block ~2 cycles (~30min), not 4 (1h). It is running --ttl-hours 1 as an explicitly marked stopgap; the vendored seam copy is upstream-synced, so the protocol change belongs here, not downstream.

Proposed shape (maintainer's call): additive ttl_minutes (or fractional-hours) across CONTRACT.md, lib/lease.sh, both adapters' claim.sh, and conformance bindings — backward compatible with existing ttl_hours records. Downstream stopgap comment cites this issue for the TODO back-reference.

[kyle-sexton]

This was generated by AI during triage.

Problem

The lease protocol represents TTL only in whole hours, so the smallest non-disabling lease is 1h and 0 disables leasing entirely — there is no way to express a sub-hour TTL. A downstream high-cadence consumer (the autonomy-demo drain on a 15-min fire cadence, ~3.5-min runs) wants a stuck claim to block ~2 cycles (~30min) rather than 4 (1h), and is running an explicitly-marked --ttl-hours 1 stopgap that cites this issue.

What the code does today

• Config: wit_read_binding (lib/binding.sh) reads config.lease_ttl_hours, validates it ^[0-9]+$, and exports WIT_LEASE_TTL_HOURS. It is REQUIRED — a binding without it is invalid (exit 3).
• CLI: both adapters' claim.sh (adapters/github, adapters/local-markdown) default ttl from WIT_LEASE_TTL_HOURS, accept --ttl-hours <n>, and re-validate ^[0-9]+$.
• Storage: claim.sh writes ttl_hours (via tonumber) into the lease marker JSON.
• Expiry: computed in exactly ONE place — wit_lease_is_live (lib/lease.sh): ((now_epoch < renewed_epoch + ttl * 3600)), with an inline ^[0-9]+$ guard on the field. Every caller (claim.sh arbitration, renew-lease.sh, github/reclaim.sh) routes through this function; no adapter re-implements expiry math. Verified: * 3600 appears nowhere else in the tree.
• Renewal: both renew-lease.sh scripts bump renewed_at via . + {renewed_at: $ts}, preserving the entire marker JSON — so a new sibling TTL field survives renewal automatically. The emitted result JSON, however, reconstructs named fields (ttl_hours: .ttl_hours), so a new field must be added there explicitly.

Two facts make this cheap and low-risk: (1) expiry is never baked into a stored record — it is recomputed from renewed_at + ttl on every liveness check, so nothing needs migrating; (2) that recomputation lives in a single function.

Rejected on the merits: fractional ttl_hours (e.g. 1.5). Bash (( )) is integer-only; renewed_epoch + 1.5 * 3600 raises arithmetic syntax error (verified). It would also change the meaning/validation of a field other consumers already parse as integer hours. Not viable without reworking the arithmetic to bc/awk.

Recommended shape

Additive minute-granularity knob, one unit per record, read-time fallback:

• Add CLI --ttl-minutes <n> (regex ^[0-9]+$) to both claim.sh adapters and optional config lease_ttl_minutes. Keep --ttl-hours and required lease_ttl_hours unchanged (no break).
• Reject both at the same layer: erroring when a caller passes both --ttl-hours and --ttl-minutes (and when both config keys are set) means each claim resolves to exactly ONE unit and writes exactly ONE ttl_* field. CLI overrides config wholesale, as today.
• wit_lease_is_live gains a read-time fallback: ttl_minutes if present else ttl_hours, computing renewed_epoch + ttl_minutes * 60 or + ttl_hours * 3600. Because no record ever carries both, this is a simple presence check, not a permanent precedence puzzle re-litigated on every liveness call.
• 0 is a load-bearing sentinel (ttl 0 = immediately-expired = leasing disabled; conformance depends on it). Presence must be detected by empty-vs-non-empty string, never by value — 0 is a valid disabling value and cannot double as "unset."
• Span: CONTRACT.md (lease-protocol section + the claim/renew-lease result-field table), lib/lease.sh, both claim.sh, both renew-lease.sh result JSON, lib/binding.sh validation, and a new conformance case (conformance/run-conformance.sh) proving a sub-hour lease expires — mirroring the existing ttl 0 case.

Rationale: keeps integer arithmetic clean, leaves ttl_hours semantics untouched for existing consumers, needs no migration (expiry is always recomputed), and directly unblocks the consumer, who swaps --ttl-hours 1 for --ttl-minutes 30.

Backward compatibility

Purely forward. Existing stored leases keep their ttl_hours field and recompute unchanged through the fallback. No schema-version bump and no record rewrite required. The one genuine contract-surface change is the emitted result JSON / CONTRACT.md result table gaining the new field — flagged as a contract change, echoing whichever unit the record used.

Routing

Single clear fork. The alternative — ttl_seconds as the canonical fine-grained unit instead of minutes — is a mechanical veto: identical surgery (* 1 vs * 60, key rename), no blast-radius difference. It answers the maintainer's own note about unit-name proliferation; recommend minutes for config-author ergonomics, but seconds is a one-line swap if the maintainer prefers a single canonical unit. Two smaller bundled sub-decisions are also low-risk vetoes: reject-both vs a precedence rule (reject-both recommended — it keeps every stored record single-unit), and keeping lease_ttl_hours REQUIRED (recommended as the no-break default; the tradeoff is a minutes-only repo must still set an hours default, relaxable to "at least one of hours/minutes required" if preferred).

Decision defaulted: additive --ttl-minutes / lease_ttl_minutes, reject-both-units-per-layer, read-time minutes-else-hours fallback, lease_ttl_hours stays required — veto before merge

[kyle-sexton]

Drain: tracked by open PR #2463 feat(work-items): add sub-hour lease TTL via ttl_minutes (no duplicate opened).