zeno-cli 0.3.4__py3-none-any.whl

zeno_core/rtlx_s.py

@@ -0,0 +1,460 @@
+"""RTLX-S: Raw NASA-TLX, Supervision-augmented (research 1, 2026-06-07 PM3).
+
+Five-item cognitive-load probe. Three items are validated raw NASA-TLX
+subscales (mental demand, effort, frustration); two are novel additions
+specific to AI-supervised work (supervision load, execution load).
+
+Design contract from research 1:
+  - 5 items, 0-10 each (NOT 0-100 like classic TLX-S)
+  - Single keypress per item, Enter accepts the previous answer
+  - End-anchored labels only ("0 = none / very low", "10 = very high")
+  - NO pairwise weighting step (dropped entirely)
+  - NEVER collapse to a single index at capture time - store all 5 raw values
+  - Default each item to the user's last-entered value, persisted in the
+    local zeno data dir at ~/.zeno/rtlxs_last.json
+  - Total prompt completes in well under 5 seconds for an experienced user
+
+The five items are PINNED. Wording is locked here so the Stage 2 CFA / alpha
+validation pass has a stable instrument across cohorts. Do NOT edit wording
+without recording the change as a new schema_version constant - mixing
+re-worded items into the same response stream invalidates the validation.
+
+The novel two items (supervision_load, execution_load) are NOT yet
+empirically validated. Research 1 specifies that they pass validation only
+if Cronbach alpha >= 0.7 and CFA model fit is acceptable at N>=150-300
+sessions across two cohorts. Until then they are treated as candidate
+correlates, not load-bearing for any policy gate.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import sys
+import termios
+import tty
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+# Schema version for the persisted defaults + API payloads. Bump when adding
+# or rewording items so CFA / alpha analyses don't silently mix instruments.
+#
+# v1 (2026-06-07): initial 5-item probe.
+# v2 (2026-06-10): supervision_load + execution_load rewritten from
+# proportion-of-effort phrasing ("how much of your effort went into...")
+# to absolute cost. Research 3 (2026-06-10) flagged the proportion framing
+# as an internal-contamination threat: by definition the two share total
+# effort and will correlate near-perfectly negatively, undermining factor
+# independence. Absolute-cost framing anchors each item on its own
+# construct (Sheridan monitor+intervene for supervision; raw mental
+# demand of own work for execution) and is the wording the prior-art scan
+# explicitly recommended pre-survey to protect Stage 2 discriminant
+# validity vs RTLX Mental Demand + Frustration (the vigilance "workload
+# signature" - Warm, Parasuraman & Matthews 2008).
+RTLXS_SCHEMA_VERSION: int = 2
+
+# Randomized single-case-experiment (SCED) condition tags (2026-06-15).
+# A per-session experimental condition lets occasions be randomly assigned
+# to autonomy blocks (ABAB / alternating-treatments) so the within-person
+# double dissociation can be tested: autonomy should move supervision_load
+# but not execution_load. None = untagged. See
+# docs/STAGE_2A_WITHIN_PERSON_DESIGN.md.
+RTLXS_AUTONOMY_CONDITIONS: tuple[str, ...] = (
+    "high_autonomy",
+    "low_autonomy",
+    "control",
+)
+
+# Rating-time concealment control (SCED v2, 2026-06-19; pre-reg Section 12 A.2).
+# In a BLINDED SCED session the survey never shows the condition; after the load
+# items it asks the operator to GUESS the concealed condition + rate confidence.
+# The Bang/James leakage index is computed from these at N=90 (NOT trial blinding
+# - the operator enacts the condition; this measures whether the RATINGS leaked
+# it). The guess is placed strictly AFTER the load items so it cannot prime them.
+RTLXS_BLIND_GUESS_OPTIONS: tuple[str, ...] = ("high", "low", "unsure")
+
+
+# Ordered tuple of (key, label) pairs - presentation order is the response
+# field order in storage too, so downstream stats can index by position.
+RTLXS_ITEMS: tuple[tuple[str, str], ...] = (
+    (
+        "mental_demand",
+        "Mental demand: How mentally demanding was this session?",
+    ),
+    (
+        "effort",
+        "Effort: How hard did you have to work to get the result you wanted?",
+    ),
+    (
+        "frustration",
+        "Frustration: How frustrated, stressed, or annoyed did you feel?",
+    ),
+    (
+        "supervision_load",
+        "Supervision load: How much effort did watching, reviewing, or "
+        "correcting the agent's work cost you?",
+    ),
+    (
+        "execution_load",
+        "Execution load: How mentally demanding was the work you did " "yourself?",
+    ),
+)
+
+
+# Trust anchor (research 3, 2026-06-10). One Jian/Bisantz/Drury-derived
+# item, fixed across all sessions (not rotated): a single item with full
+# N gives stronger convergent-validity evidence than rotation across n=300.
+# Wording is adapted from Jian et al. (2000) "The system is dependable"
+# to zeno's per-session context. Captured alongside the 5 RTLX-S items;
+# scored 0-10. Persisted in a separate column so it is never collapsed
+# into the RTLX-S latent structure. Establishes discriminant validity
+# vs trust: we expect a moderate negative correlation with supervision_load
+# (higher trust -> lower oversight burden) but NOT a near-perfect one.
+RTLXS_TRUST_ITEM_KEY: str = "trust_dependable"
+RTLXS_TRUST_ITEM_LABEL: str = "Trust: The AI agent(s) I used this session were dependable."
+
+
+# Anchor labels (end-anchored only - research 1 contract)
+LOW_ANCHOR: str = "0 = none / very low"
+HIGH_ANCHOR: str = "10 = very high"
+
+
+@dataclass(slots=True)
+class RTLXResponse:
+    """One complete RTLX-S response. Stores raw integers, never a composite.
+
+    Five validated/candidate items are 0-10 each. ``session_id`` ties the
+    response to a CLI session aggregate. ``active_agents`` and
+    ``parallel_agent_count`` are operational context for the Stage 2
+    validation pass: they let CFA / alpha analyses stratify by agent mix.
+
+    ``schema_version`` pins the item wording version for the row so a
+    pooled Stage 2 CFA can exclude / stratify by wording cohort.
+
+    ``trust_dependable`` (research 3, 2026-06-10) is a single Jian-derived
+    trust anchor item, captured alongside the 5 RTLX-S items to provide
+    discriminant-validity evidence against trust constructs.
+
+    ``agent_interrupts_count``, ``agent_turns_count``, and
+    ``verification_seconds`` (research 3, 2026-06-10) are behavioral
+    anchors populated from CLI session telemetry. They are the strongest
+    discriminant-validity evidence the Stage 2 CFA can use: supervision
+    load should correlate positively with them; mental demand should not
+    (or should correlate less). All three are Optional - the CLI fills
+    them in when telemetry is available, otherwise they remain None.
+    """
+
+    mental_demand: int
+    effort: int
+    frustration: int
+    supervision_load: int
+    execution_load: int
+    captured_at: datetime
+    session_id: str
+    active_agents: list[str]
+    parallel_agent_count: int
+    schema_version: int = RTLXS_SCHEMA_VERSION
+    trust_dependable: int | None = None
+    agent_interrupts_count: int | None = None
+    agent_turns_count: int | None = None
+    verification_seconds: int | None = None
+    autonomy_condition: str | None = None
+    # SCED v2 rating-time concealment (2026-06-19, pre-reg Section 12 A.1/A.2).
+    # ``blind_guess`` is the operator's forced post-rating guess of the concealed
+    # condition (one of RTLXS_BLIND_GUESS_OPTIONS); ``blind_confidence`` is 0..10.
+    # ``sced_session_index`` is the locked-schedule slot this session was assigned;
+    # in a blinded session ``autonomy_condition`` stays None (the true condition
+    # lives only in the sealed log, joined back by this index at N=90).
+    blind_guess: str | None = None
+    blind_confidence: int | None = None
+    sced_session_index: int | None = None
+
+    def to_payload(self) -> dict[str, object]:
+        """Wire format for POST /v1/sessions/{session_id}/rtlxs."""
+        payload: dict[str, object] = {
+            "mental_demand": self.mental_demand,
+            "effort": self.effort,
+            "frustration": self.frustration,
+            "supervision_load": self.supervision_load,
+            "execution_load": self.execution_load,
+            "captured_at": self.captured_at.isoformat(),
+            "active_agents": list(self.active_agents),
+            "parallel_agent_count": self.parallel_agent_count,
+            "schema_version": self.schema_version,
+        }
+        if self.trust_dependable is not None:
+            payload["trust_dependable"] = self.trust_dependable
+        if self.agent_interrupts_count is not None:
+            payload["agent_interrupts_count"] = self.agent_interrupts_count
+        if self.agent_turns_count is not None:
+            payload["agent_turns_count"] = self.agent_turns_count
+        if self.verification_seconds is not None:
+            payload["verification_seconds"] = self.verification_seconds
+        if self.autonomy_condition is not None:
+            payload["autonomy_condition"] = self.autonomy_condition
+        if self.blind_guess is not None:
+            payload["blind_guess"] = self.blind_guess
+        if self.blind_confidence is not None:
+            payload["blind_confidence"] = self.blind_confidence
+        if self.sced_session_index is not None:
+            payload["sced_session_index"] = self.sced_session_index
+        return payload
+
+
+def _data_dir() -> Path:
+    """Local zeno data directory. Mirrors the SDK's ZENO_HOME convention."""
+    home = Path.home()
+    base_dir = Path(os.environ.get("ZENO_HOME", home / ".zeno")).expanduser()
+    base_dir.mkdir(parents=True, exist_ok=True)
+    return base_dir
+
+
+def _last_response_path() -> Path:
+    return _data_dir() / "rtlxs_last.json"
+
+
+def load_last_defaults() -> dict[str, int]:
+    """Read the most recently submitted RTLX-S response.
+
+    Returns a dict mapping each item key to its previous value, or 5 for
+    every item on first run / corrupted file. 5 is chosen as the
+    midpoint default so an out-of-the-box submission doesn't bias the
+    score toward either extreme. Falls back silently on any IO error -
+    the user must NEVER see a stacktrace from the survey TUI.
+    """
+    keys = [key for key, _ in RTLXS_ITEMS] + [RTLXS_TRUST_ITEM_KEY]
+    fallback: dict[str, int] = {key: 5 for key in keys}
+    path = _last_response_path()
+    if not path.exists():
+        return fallback
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return fallback
+    if not isinstance(raw, dict):
+        return fallback
+    out: dict[str, int] = {}
+    for key in keys:
+        value = raw.get(key)
+        if isinstance(value, int) and 0 <= value <= 10:
+            out[key] = value
+        else:
+            out[key] = 5
+    return out
+
+
+def save_last_defaults(values: dict[str, int]) -> None:
+    """Persist the freshly submitted response so the next run defaults to it.
+
+    Silent on any IO error - never disrupt the CLI survey path. Only the
+    five item keys are written; metadata stays out of this file by design
+    so it can be safely git-ignored as a per-user preference.
+    """
+    keys = [key for key, _ in RTLXS_ITEMS] + [RTLXS_TRUST_ITEM_KEY]
+    payload = {key: int(values.get(key, 5)) for key in keys}
+    try:
+        _last_response_path().write_text(
+            json.dumps(payload, sort_keys=True),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+
+def _read_single_keypress() -> str:
+    """Read one keypress from stdin in raw mode. Handles Enter + digits.
+
+    POSIX-only (termios). The TUI fallback in run_rtlxs_survey_tui()
+    guards isatty() before reaching here. Returns the character as a
+    string; raw control chars are returned as-is so the caller can
+    handle Ctrl-C / Ctrl-D / Enter.
+    """
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        ch = sys.stdin.read(1)
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+    return ch
+
+
+def _prompt_one_item(*, label: str, previous: int) -> int | None:
+    """Show one item, read a single keypress 0-10.
+
+    Returns the integer chosen, or None on cancel (Ctrl-C / Ctrl-D).
+    Enter keeps ``previous``. Digits 0-9 commit immediately. The
+    pseudo-"10" path: press 1 followed by 0 within the same prompt -
+    callers handle the two-digit case by re-prompting if needed.
+
+    For simplicity at MVP, "10" is entered as a single keypress: the
+    upper-case 'T' (think "ten") OR the digit 9 + 1. We pick the most
+    accessible default: digits 0..9 commit immediately as their value,
+    'T' or 't' commits 10. This keeps the whole prompt single-keypress
+    per item AND under 5 seconds total - the research 1 contract.
+    """
+    sys.stdout.write(f"  {label}\n")
+    sys.stdout.write(
+        f"    [{LOW_ANCHOR}, {HIGH_ANCHOR}] (last = {previous}, Enter keeps, T = 10): "
+    )
+    sys.stdout.flush()
+    try:
+        ch = _read_single_keypress()
+    except (OSError, termios.error):
+        sys.stdout.write(f"{previous}\n")
+        return previous
+    if ch in ("\x03", "\x04"):
+        sys.stdout.write("\n")
+        return None
+    if ch in ("\r", "\n"):
+        sys.stdout.write(f"{previous}\n")
+        return previous
+    if ch in ("t", "T"):
+        sys.stdout.write("10\n")
+        return 10
+    if ch.isdigit():
+        sys.stdout.write(f"{ch}\n")
+        return int(ch)
+    # Unknown key - treat as Enter (keep previous) and move on. Refusing
+    # to advance would put the user in a stuck-prompt state, which is a
+    # worse failure mode than accepting the previous value.
+    sys.stdout.write(f"{previous}\n")
+    return previous
+
+
+def _prompt_blind_guess() -> str | None:
+    """Forced guess of the concealed SCED condition (rating-time leakage check).
+
+    Single keypress: h = high_autonomy, l = low_autonomy, anything else = unsure.
+    Returns one of RTLXS_BLIND_GUESS_OPTIONS, or None on cancel (Ctrl-C/Ctrl-D).
+    Never blocks on an unknown key - defaults to "unsure" so the prompt cannot
+    strand the operator (same failure-mode contract as _prompt_one_item).
+    """
+    sys.stdout.write("  Which condition do you think this session was?\n")
+    sys.stdout.write("    [h = high autonomy, l = low autonomy, u = unsure]: ")
+    sys.stdout.flush()
+    try:
+        ch = _read_single_keypress()
+    except (OSError, termios.error):
+        sys.stdout.write("unsure\n")
+        return "unsure"
+    if ch in ("\x03", "\x04"):
+        sys.stdout.write("\n")
+        return None
+    if ch in ("h", "H"):
+        sys.stdout.write("high\n")
+        return "high"
+    if ch in ("l", "L"):
+        sys.stdout.write("low\n")
+        return "low"
+    sys.stdout.write("unsure\n")
+    return "unsure"
+
+
+def run_rtlxs_survey_tui(
+    *,
+    session_id: str,
+    active_agents: list[str] | None = None,
+    parallel_agent_count: int = 0,
+    agent_interrupts_count: int | None = None,
+    agent_turns_count: int | None = None,
+    verification_seconds: int | None = None,
+    autonomy_condition: str | None = None,
+    sced_blinded: bool = False,
+    sced_session_index: int | None = None,
+) -> RTLXResponse | None:
+    """Five-item RTLX-S prompt plus one trust anchor item.
+
+    Returns None if skipped/cancelled. Non-tty stdin returns None
+    (background daemon / piped invocation should skip the probe rather
+    than block on stdin.read). Single keypress per item, Enter keeps the
+    previous answer. Total time well under 6 seconds for an experienced
+    user (5 RTLX-S items + 1 trust item).
+
+    The three behavioral-anchor parameters
+    (``agent_interrupts_count``, ``agent_turns_count``,
+    ``verification_seconds``) are populated from CLI session telemetry
+    by the caller. They are never user-keyed - they are the objective
+    behavioral side of the discriminant-validity check for supervision
+    load. Pass None when telemetry is unavailable.
+    """
+    if not sys.stdin.isatty():
+        return None
+    defaults = load_last_defaults()
+    sys.stdout.write("RTLX-S probe (5 items + 1 trust, single keypress each):\n")
+    sys.stdout.flush()
+    answers: dict[str, int] = {}
+    # Item-order randomization (SCED v2 A.4): in a blinded session the 5 load
+    # items are presented in a random order to disrupt response sets. Storage is
+    # keyed by item name, so the order is presentation-only and does not affect
+    # stored values or downstream analysis. Non-blinded surveys keep the pinned
+    # order (so the validated daily-dogfood instrument is unchanged).
+    items = list(RTLXS_ITEMS)
+    if sced_blinded:
+        random.shuffle(items)
+    for key, label in items:
+        value = _prompt_one_item(label=label, previous=defaults[key])
+        if value is None:
+            sys.stdout.write("Cancelled.\n")
+            return None
+        answers[key] = value
+    trust_previous = defaults.get(RTLXS_TRUST_ITEM_KEY, 5)
+    trust_value = _prompt_one_item(label=RTLXS_TRUST_ITEM_LABEL, previous=trust_previous)
+    if trust_value is None:
+        sys.stdout.write("Cancelled.\n")
+        return None
+    answers[RTLXS_TRUST_ITEM_KEY] = trust_value
+    save_last_defaults(answers)
+    # Rating-time concealment capture (SCED v2 A.2): AFTER all load items, a
+    # blinded session collects a forced condition guess + confidence. The true
+    # autonomy_condition is forced None for a blinded session (it is never stored
+    # in the queryable row; it lives only in the sealed log and is joined back by
+    # sced_session_index at N=90).
+    blind_guess: str | None = None
+    blind_confidence: int | None = None
+    if sced_blinded:
+        blind_guess = _prompt_blind_guess()
+        if blind_guess is None:
+            sys.stdout.write("Cancelled.\n")
+            return None
+        conf = _prompt_one_item(
+            label="Confidence in that guess (0 = pure guess, 10 = certain)",
+            previous=5,
+        )
+        if conf is None:
+            sys.stdout.write("Cancelled.\n")
+            return None
+        blind_confidence = conf
+    return RTLXResponse(
+        mental_demand=answers["mental_demand"],
+        effort=answers["effort"],
+        frustration=answers["frustration"],
+        supervision_load=answers["supervision_load"],
+        execution_load=answers["execution_load"],
+        captured_at=datetime.now(tz=UTC),
+        session_id=session_id,
+        active_agents=list(active_agents or []),
+        parallel_agent_count=parallel_agent_count,
+        trust_dependable=trust_value,
+        agent_interrupts_count=agent_interrupts_count,
+        agent_turns_count=agent_turns_count,
+        verification_seconds=verification_seconds,
+        autonomy_condition=None if sced_blinded else autonomy_condition,
+        blind_guess=blind_guess,
+        blind_confidence=blind_confidence,
+        sced_session_index=sced_session_index,
+    )
+
+
+def validate_item_keys() -> tuple[str, ...]:
+    """Sanity helper for tests / API schema. Order matters."""
+    return tuple(key for key, _ in RTLXS_ITEMS)
+
+
+def response_to_dict(response: RTLXResponse) -> dict[str, object]:
+    """Plain dict view of a response for ad-hoc logging."""
+    data = asdict(response)
+    data["captured_at"] = response.captured_at.isoformat()
+    return data

zeno_core/streak.py

@@ -0,0 +1,178 @@
+"""Survey streak tracker (research 1 PM3, 2026-06-07).
+
+Intrinsic-motivation lever for the RTLX-S probe. The streak counts the
+number of consecutive local-calendar days on which the user has logged at
+least one RTLX-S response. Habit-formation literature (BJ Fogg, Tiny Habits;
+Wood 2019, Good Habits Bad Habits) shows that visible streaks plus a
+"don't break the chain" frame drive higher self-report compliance than
+abstract progress meters, especially for low-effort daily probes like this
+one. We display BOTH current and longest-ever streak so a broken chain
+still leaves the user with a personal-best target to beat.
+
+Day boundary policy: a "day" runs from 03:00 LOCAL time (NOT UTC midnight).
+Late-night sessions count toward the previous calendar day so a 2am wrap-up
+does not artificially extend or break a streak. This matches the convention
+used by `morning-pipeline-timezone` (MEMORY.md) and the dashboard digest.
+
+Storage neutrality: the helper takes any object exposing a
+``timestamps_after(cutoff_iso)`` async method that returns ISO timestamps
+of probe responses for a user. The CLI passes its local ZenoStorage (reads
+``load_probes`` where ``skipped=0``); the API uses ``RTLXSResponse`` rows
+via ``streak_for_user``. Same algorithm, two storage drivers, one return
+shape.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+
+# The local-day cutoff (hour of day). Sessions before this are bucketed into
+# the previous calendar day. Mirrors `morning-pipeline-timezone` policy.
+DAY_CUTOFF_HOUR: int = 3
+
+
+@dataclass(slots=True)
+class StreakResult:
+    """One streak snapshot.
+
+    ``current``    : streak length ending on (or extending to) today's bucket
+                     after applying the 03:00 cutoff. 0 if the user has not
+                     logged in the current bucket AND the previous bucket.
+    ``longest``    : longest streak ever recorded.
+    ``last_response_at`` : ISO timestamp of the most recent response, or None
+                     if the user has never submitted one.
+    """
+
+    current: int
+    longest: int
+    last_response_at: str | None
+
+
+def _bucket_day(ts: datetime, *, cutoff_hour: int = DAY_CUTOFF_HOUR) -> date:
+    """Map a timestamp to its streak-day bucket.
+
+    Sessions before ``cutoff_hour`` count toward the previous calendar day.
+    Naive timestamps are treated as local-tz wall-clock - good enough at MVP
+    because both writers (CLI local SQLite and the API RTLXS table) record
+    UTC-aware values today, and the tz the caller chose to convert to is
+    where the user lives. Tests pass tz-aware UTC datetimes to keep the
+    bucket math deterministic across CI machines.
+    """
+    if ts.time() < time(cutoff_hour):
+        return (ts - timedelta(days=1)).date()
+    return ts.date()
+
+
+def compute_streak(
+    timestamps: Sequence[datetime],
+    *,
+    today: date,
+    cutoff_hour: int = DAY_CUTOFF_HOUR,
+) -> StreakResult:
+    """Pure function: given response timestamps and today's date, return the streak.
+
+    Algorithm:
+      1. Bucket each timestamp into a streak-day via ``_bucket_day``.
+      2. Sort unique buckets descending.
+      3. Current streak = number of consecutive days starting at today and
+         walking back. Allow a one-day grace: if the user has not yet logged
+         today but they DID log yesterday, the streak is preserved (counting
+         from yesterday). This avoids penalizing them mid-day before they
+         have had a chance to wrap up. The CLI surfaces a "you have not
+         logged today" warning separately so they still see the nudge.
+      4. Longest streak = max run of consecutive-day buckets across history.
+      5. last_response_at = max raw timestamp.
+
+    Empty input returns all zeros + None.
+    """
+    if not timestamps:
+        return StreakResult(current=0, longest=0, last_response_at=None)
+
+    buckets = sorted({_bucket_day(ts, cutoff_hour=cutoff_hour) for ts in timestamps})
+    last_ts = max(timestamps)
+
+    # Longest run: single pass over sorted ascending buckets
+    longest = 1
+    run = 1
+    for prev, curr in zip(buckets, buckets[1:], strict=False):
+        if curr - prev == timedelta(days=1):
+            run += 1
+            longest = max(longest, run)
+        else:
+            run = 1
+
+    # Current streak: walk backwards from the most recent bucket, allowing
+    # the user to be at most 1 day stale (today vs yesterday). If the latest
+    # bucket is older than yesterday, the streak is broken (0).
+    latest_bucket = buckets[-1]
+    if latest_bucket == today or latest_bucket == today - timedelta(days=1):
+        current = 1
+        i = len(buckets) - 2
+        while i >= 0 and buckets[i + 1] - buckets[i] == timedelta(days=1):
+            current += 1
+            i -= 1
+    else:
+        current = 0
+
+    return StreakResult(
+        current=current,
+        longest=longest,
+        last_response_at=last_ts.isoformat(),
+    )
+
+
+def has_logged_today(
+    timestamps: Sequence[datetime],
+    *,
+    today: date,
+    cutoff_hour: int = DAY_CUTOFF_HOUR,
+) -> bool:
+    """True iff the user has at least one response that buckets to today.
+
+    Used by the CLI to decide whether to print the "you have not logged
+    today" warning. Distinct from `current > 0` because the one-day grace
+    means current can be non-zero with no response yet today.
+    """
+    if not timestamps:
+        return False
+    return any(_bucket_day(ts, cutoff_hour=cutoff_hour) == today for ts in timestamps)
+
+
+async def read_streak_from_local_storage(
+    storage,
+    project_id: str,
+    *,
+    today: date | None = None,
+    cutoff_hour: int = DAY_CUTOFF_HOUR,
+) -> StreakResult:
+    """Read the streak from a local SDK ZenoStorage instance.
+
+    Pulls timestamps from ``load_probes`` joined to ``sessions`` (project
+    scope), keeping only non-skipped probes - those are the rows the RTLX-S
+    survey writes for a real response. ISO-string columns are parsed with
+    ``datetime.fromisoformat``; rows that fail to parse are dropped (the
+    helper is read-only / best-effort, never bubbles a SQLite or parse
+    error to the user).
+    """
+    rows = await storage._fetchall(
+        """
+        SELECT lp.responded_at, lp.prompted_at
+        FROM load_probes lp
+        JOIN sessions s ON s.id = lp.session_id
+        WHERE s.project_id = ? AND lp.skipped = 0
+        """,
+        (project_id,),
+    )
+    timestamps: list[datetime] = []
+    for row in rows:
+        raw = row[0] or row[1]
+        if not raw:
+            continue
+        try:
+            timestamps.append(datetime.fromisoformat(str(raw)))
+        except ValueError:
+            continue
+    today = today or datetime.now().date()
+    return compute_streak(timestamps, today=today, cutoff_hour=cutoff_hour)