Skip to content

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

Description

@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.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 22, 2026
  2. kyle-sexton commented on Jul 22, 2026

    @kyle-sexton
    MemberAuthor

    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

  3. added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 22, 2026
  4. added
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Jul 23, 2026
  5. kyle-sexton commented on Aug 12, 2026

    @kyle-sexton
    MemberAuthor

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

  6. added 2 commits that reference this issue on Aug 12, 2026
    f24f7a7
    5538291
  7. added 2 commits that reference this issue on Aug 12, 2026
    081adac
    1858fec
  8. added 3 commits that reference this issue on Aug 12, 2026
    10e5afa
    24b8d7c
    e50ad54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

    Fields

    No fields configured for Feature.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions