You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
work-item-tracker: lease TTL is integer-hours only — sub-hour granularity needed for high-cadence consumers #1034
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.
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).
Activity
kyle-sexton commentedon Jul 22, 2026
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
0disables 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 1stopgap that cites this issue.What the code does today
wit_read_binding(lib/binding.sh) readsconfig.lease_ttl_hours, validates it^[0-9]+$, and exportsWIT_LEASE_TTL_HOURS. It is REQUIRED — a binding without it is invalid (exit 3).claim.sh(adapters/github,adapters/local-markdown) defaultttlfromWIT_LEASE_TTL_HOURS, accept--ttl-hours <n>, and re-validate^[0-9]+$.claim.shwritesttl_hours(viatonumber) into the lease marker JSON.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.sharbitration,renew-lease.sh,github/reclaim.sh) routes through this function; no adapter re-implements expiry math. Verified:* 3600appears nowhere else in the tree.renew-lease.shscripts bumprenewed_atvia. + {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 + ttlon 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 * 3600raisesarithmetic 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 tobc/awk.Recommended shape
Additive minute-granularity knob, one unit per record, read-time fallback:
--ttl-minutes <n>(regex^[0-9]+$) to bothclaim.shadapters and optional configlease_ttl_minutes. Keep--ttl-hoursand requiredlease_ttl_hoursunchanged (no break).--ttl-hoursand--ttl-minutes(and when both config keys are set) means each claim resolves to exactly ONE unit and writes exactly ONEttl_*field. CLI overrides config wholesale, as today.wit_lease_is_livegains a read-time fallback:ttl_minutesif present elsettl_hours, computingrenewed_epoch + ttl_minutes * 60or+ 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.0is 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 —0is a valid disabling value and cannot double as "unset."claim/renew-leaseresult-field table),lib/lease.sh, bothclaim.sh, bothrenew-lease.shresult JSON,lib/binding.shvalidation, and a new conformance case (conformance/run-conformance.sh) proving a sub-hour lease expires — mirroring the existingttl 0case.Rationale: keeps integer arithmetic clean, leaves
ttl_hourssemantics untouched for existing consumers, needs no migration (expiry is always recomputed), and directly unblocks the consumer, who swaps--ttl-hours 1for--ttl-minutes 30.Backward compatibility
Purely forward. Existing stored leases keep their
ttl_hoursfield 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_secondsas the canonical fine-grained unit instead of minutes — is a mechanical veto: identical surgery (* 1vs* 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 keepinglease_ttl_hoursREQUIRED (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_hoursstays required — veto before mergedocs(ignition): predicate re-bind ratification + cadence + delegated-…
kyle-sexton commentedon Aug 12, 2026
Drain: tracked by open PR #2463 feat(work-items): add sub-hour lease TTL via ttl_minutes (no duplicate opened).
feat(work-items): add sub-hour lease TTL via ttl_minutes
feat(work-items): add sub-hour lease TTL via ttl_minutes
feat(work-items): add sub-hour lease TTL via ttl_minutes
feat(work-items): add sub-hour lease TTL via ttl_minutes
feat(work-items): add sub-hour lease TTL via ttl_minutes
feat(work-items): add sub-hour lease TTL via ttl_minutes
feat(work-items): add sub-hour lease TTL via ttl_minutes