autolimit 0.2.0

package/lib/autolimit.py

@@ -0,0 +1,1215 @@
+#!/usr/bin/env python3
+"""
+autolimit: terminal-agnostic PTY wrapper for CLI tools with reset-time limit messages.
+
+It launches an arbitrary runner inside a pseudo-terminal, mirrors stdin/stdout,
+detects configured limit messages, and automatically sends a configured message
+when the reset time arrives.
+
+This file intentionally uses only the Python standard library.
+"""
+from __future__ import annotations
+
+import errno
+import fcntl
+import json
+import os
+import pty
+import re
+import select
+import shlex
+import signal
+import subprocess
+import sys
+import termios
+import time
+import tty
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+try:
+    from zoneinfo import ZoneInfo
+except Exception:  # pragma: no cover - Python < 3.9 guard
+    ZoneInfo = None  # type: ignore
+
+VERSION = "0.2.0"
+
+DEFAULT_CONFIG_DIR = Path.home() / ".config" / "autolimit"
+CONFIG_DIR = Path(os.environ.get("AUTOLIMIT_CONFIG_DIR", str(DEFAULT_CONFIG_DIR))).expanduser()
+CONFIG_FILE = Path(os.environ.get("AUTOLIMIT_CONFIG_FILE", str(CONFIG_DIR / "config.json"))).expanduser()
+MESSAGE_FILE = Path(os.environ.get("AUTOLIMIT_MESSAGE_FILE", str(CONFIG_DIR / "message.txt"))).expanduser()
+LOG_FILE = Path(os.environ.get("AUTOLIMIT_LOG_FILE", str(CONFIG_DIR / "limit-watch.log"))).expanduser()
+
+LEGACY_MESSAGE_FILE = Path.home() / ".config" / "claude-auto" / "message.txt"
+
+DEFAULT_MESSAGE = "이어서 계속 진행해줘."
+DEFAULT_TZ_NAME = os.environ.get("AUTOLIMIT_DEFAULT_TZ", "Asia/Seoul")
+DEFAULT_SEND_GRACE_SECONDS = 5.0
+
+# A parsed reset time further ahead than this is treated as stale text (for
+# example an already-handled message re-fed from scrollback after midnight
+# rollover) and is ignored instead of scheduled.
+DEFAULT_MAX_SCHEDULE_AHEAD_HOURS = 12.0
+DATED_MAX_SCHEDULE_AHEAD_HOURS = 8 * 24.0  # date-carrying (weekly) messages
+
+# Fallback-after-exit refuses to sleep longer than this.
+DEFAULT_MAX_FALLBACK_WAIT_HOURS = 26.0
+
+# A reset time up to this far in the past still means "send now" (fresh
+# messages truncate seconds and can be read a little late); anything older
+# rolls over to the next day/year and is then subject to the stale guard.
+RECENT_PAST_TOLERANCE = timedelta(minutes=10)
+
+# If the wrapped process exits within this many seconds of a live auto-send,
+# assume the message was never processed and run the fallback instead.
+SEND_CONFIRM_SECONDS = 10.0
+
+# If the same limit message is still being displayed this long after an
+# auto-send, the send did not unblock the session: retry with backoff.
+RETRY_QUIET_SECONDS = 30.0
+RETRY_BACKOFF_SECONDS = (60.0, 120.0, 240.0)
+
+# Fixed-offset fallbacks for common abbreviations that zoneinfo does not know.
+# Deliberately omits ambiguous ones such as CST (US Central vs China) and IST.
+TZ_ABBREVIATIONS: dict[str, float] = {
+    "UTC": 0, "GMT": 0,
+    "KST": 9, "JST": 9,
+    "HKT": 8, "SGT": 8, "AWST": 8,
+    "ICT": 7, "WIB": 7,
+    "PST": -8, "PDT": -7,
+    "MST": -7, "MDT": -6,
+    "CDT": -5,
+    "EST": -5, "EDT": -4,
+    "BST": 1, "CET": 1, "CEST": 2, "EET": 2, "EEST": 3, "MSK": 3,
+    "ACST": 9.5, "AEST": 10, "AEDT": 11, "NZST": 12, "NZDT": 13,
+}
+
+_TZ_OFFSET_RE = re.compile(r"^(?:UTC|GMT)\s*([+-])(\d{1,2})(?::?(\d{2}))?$", re.IGNORECASE)
+
+_MONTHS = ("jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec")
+
+ANSI_RE = re.compile(rb"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+# The v0.1 default pattern. Existing config files that still carry it are
+# upgraded in place by load_config().
+OLD_DEFAULT_PATTERN = (
+    r"You[\u2019']?ve\s+hit\s+your\s+session\s+limit.*?"
+    r"resets\s+(?P<hour>\d{1,2})(?::(?P<minute>\d{2}))?\s*"
+    r"(?P<ampm>[aApP]\.?[mM]\.?)\s*\((?P<tzname>[^)]+)\)"
+)
+
+# Bounded gap (instead of `.*?`) so unrelated text cannot bridge a match, an
+# optional am/pm so 24-hour clocks work, and a broadened "your ... limit"
+# prefix for session/usage/weekly wording.
+DEFAULT_PATTERN = (
+    r"You[\u2019']?ve\s+hit\s+your(?:\s+[\w-]+)?\s+limit.{0,120}?"
+    r"resets\s+(?P<hour>\d{1,2})(?::(?P<minute>\d{2}))?\s*"
+    r"(?P<ampm>[aApP]\.?[mM]\.?)?\s*\((?P<tzname>[^)]{1,64})\)"
+)
+
+# Date-carrying variant such as "resets Jul 8 at 10:59am (Asia/Seoul)".
+DEFAULT_PATTERN_DATED = (
+    r"You[\u2019']?ve\s+hit\s+your(?:\s+[\w-]+)?\s+limit.{0,120}?"
+    r"resets\s+(?P<month>[A-Za-z]{3,9})\.?\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?,?\s*(?:at\s+)?"
+    r"(?P<hour>\d{1,2})(?::(?P<minute>\d{2}))?\s*"
+    r"(?P<ampm>[aApP]\.?[mM]\.?)?\s*\((?P<tzname>[^)]{1,64})\)"
+)
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "version": 1,
+    "message_file": str(MESSAGE_FILE),
+    "log_file": str(LOG_FILE),
+    "default_timezone": DEFAULT_TZ_NAME,
+    "send_grace_seconds": DEFAULT_SEND_GRACE_SECONDS,
+    "max_schedule_ahead_hours": DEFAULT_MAX_SCHEDULE_AHEAD_HOURS,
+    "max_fallback_wait_hours": DEFAULT_MAX_FALLBACK_WAIT_HOURS,
+    "patterns": [
+        {
+            "name": "Claude-style session limit",
+            "regex": DEFAULT_PATTERN,
+        },
+        {
+            "name": "Claude-style dated limit",
+            "regex": DEFAULT_PATTERN_DATED,
+        },
+    ],
+    "runners": {
+        # Fallback is only used when the wrapped process exits after printing a
+        # limit message. For Claude Code style runners, `-c -p <message>` resumes
+        # the most recent conversation non-interactively.
+        "claude": {
+            "fallback": ["{runner}", "{args}", "-c", "-p", "{message}"],
+        },
+        "cc": {
+            "fallback": ["{runner}", "{args}", "-c", "-p", "{message}"],
+        },
+    },
+}
+
+RESERVED_COMMANDS = {
+    "--help",
+    "-h",
+    "--version",
+    "-V",
+    "--show-config",
+    "--test-parser",
+    "--init",
+    "--list-runners",
+    "--dry-run",
+    "--direct",
+    "--shell",
+    "--no-fallback",
+    "--autolimit-version",
+    "--autolimit-show-config",
+    "--autolimit-test-parser",
+    # Compatibility with the earlier claude-auto package.
+    "--claude-auto-version",
+    "--claude-auto-show-config",
+    "--claude-auto-test-parser",
+}
+
+KNOWN_WRAPPER_FLAGS = {"--direct", "--shell", "--no-fallback", "--dry-run"}
+
+
+@dataclass(frozen=True)
+class ScheduledJob:
+    timestamp: int
+    reset_at: datetime
+    pattern_name: str
+    # Stable identity of the matched message (pattern + captured groups) so a
+    # re-displayed message maps back to the same job across repaints.
+    text_key: str = ""
+
+
+@dataclass(frozen=True)
+class RunnerInvocation:
+    command: list[str]
+    runner_name: str
+    mode: str  # "shell" or "direct"
+    fallback_allowed: bool = True
+
+
+class AutolimitError(Exception):
+    pass
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    result = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = deep_merge(result[key], value)  # type: ignore[arg-type]
+        else:
+            result[key] = value
+    return result
+
+
+def expand_path(value: Any, default: Path) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        return default
+    return Path(value).expanduser()
+
+
+def default_config_for_file() -> dict[str, Any]:
+    cfg = json.loads(json.dumps(DEFAULT_CONFIG))
+    cfg["message_file"] = str(MESSAGE_FILE)
+    cfg["log_file"] = str(LOG_FILE)
+    cfg["default_timezone"] = DEFAULT_TZ_NAME
+    return cfg
+
+
+def ensure_default_config() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    if not MESSAGE_FILE.exists():
+        if LEGACY_MESSAGE_FILE.exists():
+            try:
+                MESSAGE_FILE.write_text(LEGACY_MESSAGE_FILE.read_text(encoding="utf-8"), encoding="utf-8")
+            except Exception:
+                MESSAGE_FILE.write_text(DEFAULT_MESSAGE + "\n", encoding="utf-8")
+        else:
+            MESSAGE_FILE.write_text(DEFAULT_MESSAGE + "\n", encoding="utf-8")
+
+    if not CONFIG_FILE.exists():
+        CONFIG_FILE.write_text(
+            json.dumps(default_config_for_file(), ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+
+def _normalized_regex(value: Any) -> str:
+    # Config files may carry the curly apostrophe either as a literal character
+    # or as the ’ regex escape; compare both forms the same way.
+    return str(value).replace("’", "\\u2019")
+
+
+def migrate_legacy_patterns(loaded: dict[str, Any]) -> bool:
+    patterns = loaded.get("patterns")
+    if not isinstance(patterns, list):
+        return False
+    old_norm = _normalized_regex(OLD_DEFAULT_PATTERN)
+    changed = False
+    migrated: list[Any] = []
+    for item in patterns:
+        regex = item.get("regex") if isinstance(item, dict) else item
+        if isinstance(regex, str) and _normalized_regex(regex) == old_norm:
+            migrated.extend(json.loads(json.dumps(DEFAULT_CONFIG["patterns"])))
+            changed = True
+        else:
+            migrated.append(item)
+    if changed:
+        loaded["patterns"] = migrated
+    return changed
+
+
+def load_config() -> dict[str, Any]:
+    ensure_default_config()
+    cfg = default_config_for_file()
+    try:
+        loaded = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        if isinstance(loaded, dict):
+            if migrate_legacy_patterns(loaded):
+                try:
+                    CONFIG_FILE.write_text(
+                        json.dumps(loaded, ensure_ascii=False, indent=2) + "\n",
+                        encoding="utf-8",
+                    )
+                    log(f"Upgraded legacy default limit pattern in {CONFIG_FILE}.")
+                except Exception:
+                    log(f"Upgraded legacy default limit pattern in memory only; could not rewrite {CONFIG_FILE}.")
+            cfg = deep_merge(cfg, loaded)
+    except Exception as exc:
+        log(f"Failed to read config file {CONFIG_FILE}: {exc}; using defaults.")
+    return cfg
+
+
+def _tz_from_name(name: str):
+    """Best-effort tzinfo for an IANA name, common abbreviation, or UTC offset.
+
+    Returns None when the name is unrecognized.
+    """
+    name = (name or "").strip()
+    if not name:
+        return None
+    if ZoneInfo is None:
+        raise RuntimeError("Python 3.9+ is required because autolimit uses zoneinfo.")
+    try:
+        return ZoneInfo(name)
+    except Exception:
+        pass
+    offset = TZ_ABBREVIATIONS.get(name.upper())
+    if offset is not None:
+        return timezone(timedelta(hours=offset), name.upper())
+    match = _TZ_OFFSET_RE.match(name)
+    if match:
+        sign = -1 if match.group(1) == "-" else 1
+        delta = timedelta(hours=int(match.group(2)), minutes=int(match.group(3) or 0))
+        return timezone(sign * delta, name)
+    return None
+
+
+def resolve_timezone(name: str, cfg: Optional[dict[str, Any]] = None):
+    tz = _tz_from_name(name)
+    if tz is not None:
+        return tz
+    fallback_name = default_tz_name(cfg) if cfg is not None else DEFAULT_TZ_NAME
+    tz = _tz_from_name(fallback_name)
+    if tz is None:
+        tz = timezone.utc
+        fallback_name = "UTC"
+    log(f"Unknown timezone {name!r} in limit message; assuming {fallback_name!r}.", cfg)
+    return tz
+
+
+def _now_for_log() -> str:
+    try:
+        tz = _tz_from_name(DEFAULT_TZ_NAME)
+        if tz is not None:
+            return datetime.now(tz).isoformat(timespec="seconds")
+    except Exception:
+        pass
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def log(message: str, cfg: Optional[dict[str, Any]] = None) -> None:
+    if os.environ.get("AUTOLIMIT_LOG", "1") in {"0", "false", "False", "no", "NO"}:
+        return
+    try:
+        if os.environ.get("AUTOLIMIT_LOG_FILE"):
+            # Environment override wins, mirroring AUTOLIMIT_MESSAGE_FILE.
+            log_file = LOG_FILE
+        elif cfg is not None:
+            log_file = expand_path(cfg.get("log_file"), LOG_FILE)
+        else:
+            log_file = LOG_FILE
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        with log_file.open("a", encoding="utf-8") as f:
+            f.write(f"[{_now_for_log()}] {message}\n")
+    except Exception:
+        pass
+
+
+def configured_message_file(cfg: dict[str, Any]) -> Path:
+    env_path = os.environ.get("AUTOLIMIT_MESSAGE_FILE")
+    if env_path:
+        return Path(env_path).expanduser()
+    return expand_path(cfg.get("message_file"), MESSAGE_FILE)
+
+
+def load_message(cfg: dict[str, Any]) -> str:
+    env_message = os.environ.get("AUTOLIMIT_MESSAGE")
+    if env_message is not None:
+        return " ".join(env_message.splitlines()).strip()
+
+    message_file = configured_message_file(cfg)
+    if not message_file.exists():
+        try:
+            message_file.parent.mkdir(parents=True, exist_ok=True)
+            message_file.write_text(DEFAULT_MESSAGE + "\n", encoding="utf-8")
+        except Exception:
+            return DEFAULT_MESSAGE
+
+    try:
+        return " ".join(message_file.read_text(encoding="utf-8").splitlines()).strip()
+    except Exception:
+        return DEFAULT_MESSAGE
+
+
+def config_float(cfg: Optional[dict[str, Any]], key: str, env_name: str, default: float) -> float:
+    raw = os.environ.get(env_name)
+    if raw is None and isinstance(cfg, dict):
+        raw = cfg.get(key, default)
+    if raw is None:
+        raw = default
+    try:
+        return float(raw)
+    except Exception:
+        return default
+
+
+def send_grace_seconds(cfg: dict[str, Any]) -> float:
+    value = config_float(cfg, "send_grace_seconds", "AUTOLIMIT_SEND_GRACE_SECONDS", DEFAULT_SEND_GRACE_SECONDS)
+    return max(0.0, value)
+
+
+def default_tz_name(cfg: dict[str, Any]) -> str:
+    raw = os.environ.get("AUTOLIMIT_DEFAULT_TZ", cfg.get("default_timezone", DEFAULT_TZ_NAME))
+    return str(raw or DEFAULT_TZ_NAME)
+
+
+def shell_join(argv: Iterable[str]) -> str:
+    return " ".join(shlex.quote(str(x)) for x in argv)
+
+
+def strip_ansi_bytes(data: bytes) -> str:
+    cleaned = ANSI_RE.sub(b"", data)
+    return cleaned.decode("utf-8", errors="replace")
+
+
+def _month_number(token: str) -> int:
+    prefix = token.strip().lower()[:3]
+    for idx, name in enumerate(_MONTHS, start=1):
+        if prefix == name:
+            return idx
+    raise ValueError(f"unrecognized month name {token!r}")
+
+
+def parse_reset_at(match: re.Match[str], cfg: dict[str, Any], now: Optional[datetime] = None) -> datetime:
+    gd = match.groupdict()
+
+    def get_group(name: str, index: int, default: Optional[str] = None) -> Optional[str]:
+        value = gd.get(name)
+        if value not in {None, ""}:
+            return value
+        try:
+            value = match.group(index)
+            if value not in {None, ""}:
+                return value
+        except Exception:
+            pass
+        return default
+
+    hour_s = get_group("hour", 1)
+    if hour_s is None:
+        raise ValueError("limit pattern matched but did not provide an hour group")
+
+    hour = int(hour_s)
+    minute = int(get_group("minute", 2, "0") or "0")
+    ampm = (get_group("ampm", 3, "") or "").lower().replace(".", "")
+    tzname = (get_group("tzname", 4, default_tz_name(cfg)) or default_tz_name(cfg)).strip()
+    month_s = gd.get("month")
+    day_s = gd.get("day")
+
+    if ampm:
+        if ampm == "pm" and hour != 12:
+            hour += 12
+        elif ampm == "am" and hour == 12:
+            hour = 0
+
+    tz = resolve_timezone(tzname, cfg)
+    now = datetime.now(tz) if now is None else now.astimezone(tz)
+
+    max_ahead_hours = config_float(
+        cfg, "max_schedule_ahead_hours", "AUTOLIMIT_MAX_SCHEDULE_AHEAD_HOURS", DEFAULT_MAX_SCHEDULE_AHEAD_HOURS
+    )
+
+    if month_s and day_s:
+        reset_at = now.replace(
+            month=_month_number(month_s), day=int(day_s), hour=hour, minute=minute, second=0, microsecond=0
+        )
+        if reset_at < now - RECENT_PAST_TOLERANCE:
+            reset_at = reset_at.replace(year=reset_at.year + 1)
+        max_ahead_hours = max(max_ahead_hours, DATED_MAX_SCHEDULE_AHEAD_HOURS)
+    else:
+        reset_at = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
+        # If the reset time is recently past, send immediately. If it is
+        # materially in the past, the message likely refers to tomorrow.
+        if reset_at < now - RECENT_PAST_TOLERANCE:
+            reset_at += timedelta(days=1)
+
+    # A same-day limit never resets further ahead than a few hours; anything
+    # beyond the window is stale text (for example an old message re-fed from
+    # scrollback whose time already passed and rolled over to tomorrow).
+    ahead = reset_at - now
+    if ahead > timedelta(hours=max_ahead_hours):
+        raise ValueError(
+            f"parsed reset time {reset_at.isoformat(timespec='seconds')} is "
+            f"{ahead.total_seconds() / 3600:.1f}h ahead (max {max_ahead_hours:g}h); ignoring as stale"
+        )
+
+    return reset_at
+
+
+class LimitScanner:
+    def __init__(self, cfg: dict[str, Any]) -> None:
+        self.cfg = cfg
+        self.buffer = ""
+        # Match identity -> {"state": pending|fired|failed|dropped, "attempts", "fired_at", ...}
+        self.entries: dict[str, dict[str, Any]] = {}
+        self.scheduled_ts: set[int] = set()
+        self.jobs: list[ScheduledJob] = []
+        self.patterns: list[tuple[str, re.Pattern[str]]] = []
+        self._compile_patterns()
+
+    def _compile_patterns(self) -> None:
+        raw_patterns = self.cfg.get("patterns")
+        if not isinstance(raw_patterns, list) or not raw_patterns:
+            raw_patterns = DEFAULT_CONFIG["patterns"]
+
+        for idx, item in enumerate(raw_patterns):
+            if isinstance(item, str):
+                name = f"pattern #{idx + 1}"
+                regex = item
+            elif isinstance(item, dict):
+                name = str(item.get("name") or f"pattern #{idx + 1}")
+                regex = item.get("regex")
+            else:
+                continue
+
+            if not isinstance(regex, str) or not regex.strip():
+                continue
+            try:
+                self.patterns.append((name, re.compile(regex, re.IGNORECASE | re.DOTALL)))
+            except re.error as exc:
+                log(f"Ignoring invalid regex pattern {name!r}: {exc}", self.cfg)
+
+        if not self.patterns:
+            self.patterns.append(("default Claude-style session limit", re.compile(DEFAULT_PATTERN, re.IGNORECASE | re.DOTALL)))
+            self.patterns.append(("default Claude-style dated limit", re.compile(DEFAULT_PATTERN_DATED, re.IGNORECASE | re.DOTALL)))
+
+    @staticmethod
+    def _match_key(pattern_name: str, gd: dict[str, Any]) -> str:
+        # Built from the captured components (not the raw matched text, which
+        # varies across TUI repaints, and not the computed timestamp, which
+        # changes once the reset time passes).
+        parts = [pattern_name] + [str(gd.get(k) or "") for k in ("month", "day", "hour", "minute", "ampm", "tzname")]
+        return "|".join(parts)
+
+    def feed(self, data: bytes) -> list[ScheduledJob]:
+        text = strip_ansi_bytes(data).replace("\r", "\n")
+        # Keep enough scrollback for messages split across redraw chunks without
+        # allowing unbounded growth.
+        self.buffer = (self.buffer + text)[-12000:]
+
+        now = time.time()
+        new_jobs: list[ScheduledJob] = []
+        for pattern_name, pattern in self.patterns:
+            for match in pattern.finditer(self.buffer):
+                key = self._match_key(pattern_name, match.groupdict())
+                entry = self.entries.get(key)
+                if entry is None:
+                    self._schedule_new(key, pattern_name, match, new_jobs)
+                elif entry["state"] == "fired":
+                    self._maybe_retry(key, entry, pattern_name, now, new_jobs)
+                # pending/failed/dropped entries need no further action.
+
+        if new_jobs:
+            self.jobs.sort(key=lambda job: job.timestamp)
+        return new_jobs
+
+    def _schedule_new(self, key: str, pattern_name: str, match: re.Match[str], out: list[ScheduledJob]) -> None:
+        try:
+            reset_at = parse_reset_at(match, self.cfg)
+        except Exception as exc:
+            self.entries[key] = {"state": "dropped"}
+            log(f"Ignoring limit match via {pattern_name!r}: {exc}", self.cfg)
+            return
+
+        ts = int(reset_at.timestamp())
+        if ts in self.scheduled_ts:
+            # Another pattern already scheduled this exact reset time.
+            self.entries[key] = {"state": "dropped"}
+            return
+
+        job = ScheduledJob(timestamp=ts, reset_at=reset_at, pattern_name=pattern_name, text_key=key)
+        self.scheduled_ts.add(ts)
+        self.entries[key] = {"state": "pending", "attempts": 0, "fired_at": None}
+        self.jobs.append(job)
+        out.append(job)
+        log(
+            f"Detected limit via {pattern_name!r}; scheduled auto-send at {reset_at.isoformat(timespec='seconds')}",
+            self.cfg,
+        )
+
+    def _maybe_retry(self, key: str, entry: dict[str, Any], pattern_name: str, now: float, out: list[ScheduledJob]) -> None:
+        # The buffer is cleared when a job fires, so seeing the same message
+        # again means the session is still limited and the send did not stick.
+        fired_at = entry.get("fired_at") or 0.0
+        if now - fired_at < RETRY_QUIET_SECONDS:
+            return
+        attempts = int(entry.get("attempts", 0))
+        if attempts >= len(RETRY_BACKOFF_SECONDS):
+            if not entry.get("gave_up"):
+                entry["gave_up"] = True
+                log(f"Limit message still visible after {attempts} retries via {pattern_name!r}; giving up.", self.cfg)
+            return
+
+        delay = RETRY_BACKOFF_SECONDS[attempts]
+        entry["attempts"] = attempts + 1
+        entry["state"] = "pending"
+        retry_at = datetime.now().astimezone() + timedelta(seconds=delay)
+        job = ScheduledJob(
+            timestamp=int(now + delay),
+            reset_at=retry_at,
+            pattern_name=f"{pattern_name} (retry {attempts + 1})",
+            text_key=key,
+        )
+        self.jobs.append(job)
+        out.append(job)
+        log(f"Limit message still visible after auto-send; retrying in {delay:.0f}s (attempt {attempts + 1}).", self.cfg)
+
+    def mark_fired(self, job: ScheduledJob) -> None:
+        entry = self.entries.get(job.text_key)
+        if entry is not None:
+            entry["state"] = "fired"
+            entry["fired_at"] = time.time()
+        # Drop scrollback so the handled message cannot be re-parsed later
+        # (once its time is past it would otherwise re-schedule for tomorrow).
+        self.buffer = ""
+
+    def mark_failed(self, job: ScheduledJob) -> None:
+        entry = self.entries.get(job.text_key)
+        if entry is not None:
+            entry["state"] = "failed"
+
+    def pop_due_jobs(self, now: Optional[float] = None) -> list[ScheduledJob]:
+        if now is None:
+            now = time.time()
+        due: list[ScheduledJob] = []
+        while self.jobs and self.jobs[0].timestamp <= now:
+            due.append(self.jobs.pop(0))
+        return due
+
+    def next_timeout(self, default: float = 0.25, grace: float = 0.0) -> float:
+        if not self.jobs:
+            return default
+        return min(default, max(0.0, self.jobs[0].timestamp + grace - time.time()))
+
+
+def copy_winsize(src_fd: int, dst_fd: int) -> None:
+    try:
+        size = fcntl.ioctl(src_fd, termios.TIOCGWINSZ, b"\0" * 8)
+        fcntl.ioctl(dst_fd, termios.TIOCSWINSZ, size)
+    except Exception:
+        pass
+
+
+def status_to_exit_code(status: Optional[int]) -> int:
+    if status is None:
+        return 0
+    if os.WIFEXITED(status):
+        return os.WEXITSTATUS(status)
+    if os.WIFSIGNALED(status):
+        return 128 + os.WTERMSIG(status)
+    return 1
+
+
+def send_message_to_fd(master_fd: int, cfg: dict[str, Any]) -> bool:
+    """Type the configured message into the live session.
+
+    Returns False when the write fails (the wrapped process is likely gone),
+    so the caller can hand the job to the fallback path instead.
+    """
+    msg = load_message(cfg)
+    if not msg:
+        log("Auto-send skipped because the configured message is empty.", cfg)
+        return True
+    try:
+        # \r is what a real Enter keypress sends; raw-mode TUIs expect it and
+        # canonical-mode programs receive it as \n via ICRNL.
+        os.write(master_fd, msg.encode("utf-8") + b"\r")
+    except OSError as exc:
+        log(f"Auto-send failed; the wrapped process is likely gone ({exc}).", cfg)
+        return False
+    log("Auto-sent configured message to live session.", cfg)
+    return True
+
+
+def fallback_disabled(invocation: RunnerInvocation) -> bool:
+    if not invocation.fallback_allowed:
+        return True
+    value = os.environ.get("AUTOLIMIT_DISABLE_FALLBACK", "0")
+    return value in {"1", "true", "True", "yes", "YES"}
+
+
+def profile_for_runner(cfg: dict[str, Any], runner_name: str) -> dict[str, Any]:
+    runners = cfg.get("runners")
+    if not isinstance(runners, dict):
+        return {}
+    exact = runners.get(runner_name)
+    if isinstance(exact, dict):
+        return exact
+    lower = runners.get(runner_name.lower())
+    if isinstance(lower, dict):
+        return lower
+    return {}
+
+
+def expand_fallback_template(template: Any, invocation: RunnerInvocation, message: str) -> list[str]:
+    runner = invocation.command[0]
+    args = invocation.command[1:]
+
+    if isinstance(template, str):
+        # String templates are split after expansion. Prefer list templates in
+        # config.json when arguments may contain whitespace.
+        rendered = template.replace("{runner}", runner).replace("{message}", message)
+        rendered = rendered.replace("{args}", shell_join(args))
+        return shlex.split(rendered)
+
+    if not isinstance(template, list):
+        return []
+
+    out: list[str] = []
+    for item in template:
+        if not isinstance(item, str):
+            item = str(item)
+        if item == "{args}":
+            out.extend(args)
+            continue
+        if item == "{command}":
+            out.extend(invocation.command)
+            continue
+        out.append(item.replace("{runner}", runner).replace("{message}", message))
+    return out
+
+
+def shell_path() -> str:
+    raw = os.environ.get("AUTOLIMIT_SHELL") or os.environ.get("SHELL") or "/bin/zsh"
+    if raw and Path(raw).exists():
+        return raw
+    for candidate in ("/bin/zsh", "/bin/bash", "/bin/sh"):
+        if Path(candidate).exists():
+            return candidate
+    return "/bin/sh"
+
+
+def shell_argv_for_command(argv: list[str]) -> list[str]:
+    shell = shell_path()
+    command_line = shell_join(argv)
+    # Separate -i and -c works for zsh, bash, fish, and POSIX-ish sh.
+    return [shell, "-i", "-c", command_line]
+
+
+def child_exec_argv(invocation: RunnerInvocation) -> list[str]:
+    if invocation.mode == "direct":
+        return invocation.command
+    return shell_argv_for_command(invocation.command)
+
+
+def fallback_after_exit(job: ScheduledJob, invocation: RunnerInvocation, cfg: dict[str, Any]) -> int:
+    if fallback_disabled(invocation):
+        log("Wrapped process exited before reset; fallback is disabled.", cfg)
+        return 0
+
+    profile = profile_for_runner(cfg, invocation.runner_name)
+    template = os.environ.get("AUTOLIMIT_FALLBACK") or profile.get("fallback")
+    if not template:
+        reset_local = job.reset_at.isoformat(timespec="seconds")
+        print(
+            f"\n[autolimit] The wrapped process exited before reset ({reset_local}). "
+            f"No fallback is configured for runner {invocation.runner_name!r}.",
+            file=sys.stderr,
+        )
+        print(
+            "[autolimit] Live auto-send only works while the process is still running. "
+            "Add a fallback in ~/.config/autolimit/config.json if this runner can resume non-interactively.",
+            file=sys.stderr,
+        )
+        log(f"No fallback configured for runner {invocation.runner_name!r}; skipped.", cfg)
+        return 0
+
+    delay = max(0.0, job.timestamp - time.time() + send_grace_seconds(cfg))
+    reset_local = job.reset_at.isoformat(timespec="seconds")
+
+    max_wait = max(
+        0.0,
+        config_float(cfg, "max_fallback_wait_hours", "AUTOLIMIT_MAX_FALLBACK_WAIT_HOURS", DEFAULT_MAX_FALLBACK_WAIT_HOURS)
+        * 3600.0,
+    )
+    if delay > max_wait:
+        print(
+            f"\n[autolimit] Reset at {reset_local} is {delay / 3600.0:.1f}h away, beyond "
+            f"max_fallback_wait_hours ({max_wait / 3600.0:g}h); not waiting for fallback.",
+            file=sys.stderr,
+        )
+        log(f"Fallback skipped; reset is {delay / 3600.0:.1f}h away (max {max_wait / 3600.0:g}h).", cfg)
+        return 0
+
+    print(f"\n[autolimit] Wrapped process exited before reset. Waiting until {reset_local} before fallback. Press Ctrl-C to abort.", file=sys.stderr)
+    log(f"Wrapped process exited before reset; waiting {delay:.1f}s for fallback.", cfg)
+    try:
+        time.sleep(delay)
+    except KeyboardInterrupt:
+        print("\n[autolimit] Fallback wait interrupted; exiting without running the fallback.", file=sys.stderr)
+        log("Fallback wait interrupted by user.", cfg)
+        return 130
+
+    msg = load_message(cfg)
+    if not msg:
+        print("[autolimit] Configured message is empty; fallback skipped.", file=sys.stderr)
+        log("Fallback skipped because the configured message is empty.", cfg)
+        return 0
+
+    fallback_cmd = expand_fallback_template(template, invocation, msg)
+    if not fallback_cmd:
+        print(f"[autolimit] Empty fallback for runner {invocation.runner_name!r}; skipped.", file=sys.stderr)
+        log(f"Empty fallback for runner {invocation.runner_name!r}; skipped.", cfg)
+        return 0
+
+    display = shell_join(fallback_cmd[:-1] + ["<message>"]) if fallback_cmd[-1] == msg else shell_join(fallback_cmd)
+    print(f"\n[autolimit] Running fallback: {display}\n", file=sys.stderr)
+    log("Running fallback command after reset: " + display, cfg)
+
+    try:
+        if invocation.mode == "direct":
+            return subprocess.run(fallback_cmd).returncode
+        return subprocess.run(shell_argv_for_command(fallback_cmd)).returncode
+    except FileNotFoundError:
+        print(f"[autolimit] Command not found: {fallback_cmd[0]}", file=sys.stderr)
+        log(f"Fallback failed; command not found: {fallback_cmd[0]}", cfg)
+        return 127
+    except KeyboardInterrupt:
+        print("\n[autolimit] Fallback interrupted.", file=sys.stderr)
+        log("Fallback command interrupted by user.", cfg)
+        return 130
+
+
+def select_exit_job(
+    pending: list[ScheduledJob],
+    failed_sends: list[ScheduledJob],
+    last_sent_job: Optional[ScheduledJob],
+    last_sent_at: float,
+    now: Optional[float] = None,
+) -> Optional[ScheduledJob]:
+    """Pick the job the fallback should handle after the wrapped process exits.
+
+    Pending jobs and failed live sends always qualify. A live send issued just
+    before the exit also qualifies: the process was likely already dead or
+    dying, so the message was never processed.
+    """
+    if now is None:
+        now = time.time()
+    candidates = list(pending) + list(failed_sends)
+    if not candidates and last_sent_job is not None and now - last_sent_at <= SEND_CONFIRM_SECONDS:
+        candidates = [last_sent_job]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda job: job.timestamp)
+
+
+def parse_invocation(argv: list[str]) -> tuple[Optional[RunnerInvocation], dict[str, Any]]:
+    opts: dict[str, Any] = {
+        "dry_run": False,
+        "mode": os.environ.get("AUTOLIMIT_EXEC_MODE", "shell").lower(),
+        "fallback_allowed": True,
+    }
+
+    if opts["mode"] not in {"shell", "direct"}:
+        opts["mode"] = "shell"
+
+    rest = list(argv)
+    while rest and rest[0] in KNOWN_WRAPPER_FLAGS:
+        flag = rest.pop(0)
+        if flag == "--direct":
+            opts["mode"] = "direct"
+        elif flag == "--shell":
+            opts["mode"] = "shell"
+        elif flag == "--no-fallback":
+            opts["fallback_allowed"] = False
+        elif flag == "--dry-run":
+            opts["dry_run"] = True
+
+    if not rest:
+        return None, opts
+
+    if rest[0] == "--":
+        command = rest[1:]
+        if not command:
+            raise AutolimitError("No command was provided after --.")
+    elif rest[0].startswith("--") and rest[0] not in RESERVED_COMMANDS:
+        runner = rest[0][2:]
+        if not runner:
+            raise AutolimitError("Empty runner name.")
+        if "=" in runner:
+            raise AutolimitError("Runner selector cannot contain '='. Use `autolimit -- <command> ...` instead.")
+        command = [runner] + rest[1:]
+    elif rest[0].startswith("-"):
+        raise AutolimitError(f"Unknown autolimit option: {rest[0]}")
+    else:
+        command = rest
+
+    runner_name = Path(command[0]).name
+    invocation = RunnerInvocation(
+        command=command,
+        runner_name=runner_name,
+        mode=opts["mode"],
+        fallback_allowed=bool(opts["fallback_allowed"]),
+    )
+    return invocation, opts
+
+
+def run_pty(invocation: RunnerInvocation, cfg: dict[str, Any]) -> int:
+    if not os.isatty(sys.stdin.fileno()) or not os.isatty(sys.stdout.fileno()):
+        print("[autolimit] stdin and stdout must be terminals. Run autolimit from an interactive terminal.", file=sys.stderr)
+        return 2
+
+    child_argv = child_exec_argv(invocation)
+    log(
+        f"Starting runner={invocation.runner_name!r}, mode={invocation.mode}, command={shell_join(invocation.command)}",
+        cfg,
+    )
+
+    stdin_fd = sys.stdin.fileno()
+    stdout_fd = sys.stdout.fileno()
+
+    try:
+        old_tty = termios.tcgetattr(stdin_fd)
+    except termios.error as exc:
+        print(f"[autolimit] Failed to read terminal attributes: {exc}", file=sys.stderr)
+        return 2
+
+    pid, master_fd = pty.fork()
+
+    if pid == 0:
+        try:
+            os.execvp(child_argv[0], child_argv)
+        except FileNotFoundError:
+            os.write(2, f"[autolimit] Command not found: {child_argv[0]}\n".encode("utf-8"))
+            os._exit(127)
+        except Exception as exc:
+            os.write(2, f"[autolimit] Failed to exec {child_argv[0]}: {exc}\n".encode("utf-8"))
+            os._exit(126)
+
+    scanner = LimitScanner(cfg)
+    child_status: Optional[int] = None
+    child_alive = True
+    failed_sends: list[ScheduledJob] = []
+    last_sent_job: Optional[ScheduledJob] = None
+    last_sent_at = 0.0
+
+    def on_winch(signum, frame):  # noqa: ARG001 - signal handler signature
+        copy_winsize(stdin_fd, master_fd)
+        try:
+            os.kill(pid, signal.SIGWINCH)
+        except ProcessLookupError:
+            pass
+
+    old_winch = signal.getsignal(signal.SIGWINCH)
+    signal.signal(signal.SIGWINCH, on_winch)
+    copy_winsize(stdin_fd, master_fd)
+
+    try:
+        tty.setraw(stdin_fd)
+
+        while child_alive:
+            grace = send_grace_seconds(cfg)
+            due_cutoff = time.time() - grace
+            for job in scanner.pop_due_jobs(now=due_cutoff):
+                if send_message_to_fd(master_fd, cfg):
+                    scanner.mark_fired(job)
+                    last_sent_job, last_sent_at = job, time.time()
+                else:
+                    scanner.mark_failed(job)
+                    failed_sends.append(job)
+
+            timeout = scanner.next_timeout(default=0.25, grace=grace)
+
+            try:
+                rlist, _, _ = select.select([stdin_fd, master_fd], [], [], timeout)
+            except InterruptedError:
+                continue
+
+            if stdin_fd in rlist:
+                try:
+                    data = os.read(stdin_fd, 4096)
+                except OSError:
+                    data = b""
+                if data:
+                    os.write(master_fd, data)
+                else:
+                    try:
+                        os.kill(pid, signal.SIGHUP)
+                    except ProcessLookupError:
+                        pass
+                    child_alive = False
+                    break
+
+            if master_fd in rlist:
+                try:
+                    data = os.read(master_fd, 4096)
+                except OSError as exc:
+                    if exc.errno == errno.EIO:
+                        child_alive = False
+                        break
+                    raise
+
+                if not data:
+                    child_alive = False
+                    break
+
+                os.write(stdout_fd, data)
+                scanner.feed(data)
+
+            try:
+                done_pid, status = os.waitpid(pid, os.WNOHANG)
+            except ChildProcessError:
+                done_pid, status = pid, child_status or 0
+            if done_pid == pid:
+                child_status = status
+                child_alive = False
+                break
+
+        # Drain output still buffered in the PTY at exit so a limit message
+        # printed just before the process died is displayed and scanned.
+        drain_deadline = time.time() + 1.0
+        while time.time() < drain_deadline:
+            try:
+                rlist, _, _ = select.select([master_fd], [], [], 0.05)
+            except (InterruptedError, OSError):
+                break
+            if master_fd not in rlist:
+                break
+            try:
+                data = os.read(master_fd, 4096)
+            except OSError:
+                break
+            if not data:
+                break
+            os.write(stdout_fd, data)
+            scanner.feed(data)
+
+    finally:
+        try:
+            termios.tcsetattr(stdin_fd, termios.TCSAFLUSH, old_tty)
+        except Exception:
+            pass
+        try:
+            signal.signal(signal.SIGWINCH, old_winch)
+        except Exception:
+            pass
+        try:
+            os.close(master_fd)
+        except Exception:
+            pass
+
+    if child_status is None:
+        try:
+            _, child_status = os.waitpid(pid, 0)
+        except ChildProcessError:
+            child_status = 0
+
+    exit_job = select_exit_job(scanner.jobs, failed_sends, last_sent_job, last_sent_at)
+    if exit_job is not None:
+        log(f"Wrapped process exited with an unresolved limit job ({exit_job.pattern_name}); using fallback path.", cfg)
+        return fallback_after_exit(exit_job, invocation, cfg)
+
+    exit_code = status_to_exit_code(child_status)
+    log(f"Wrapped command exited with status {exit_code}.", cfg)
+    return exit_code
+
+
+def print_help() -> None:
+    print(
+        """autolimit - wrap any interactive CLI runner and auto-send a message after a reset-time limit message.
+
+Usage:
+  autolimit --cc [args...]              Wrap command `cc [args...]`
+  autolimit --claude [args...]          Wrap command `claude [args...]`
+  autolimit <command> [args...]         Wrap an explicit command
+  autolimit -- <command> [args...]      Wrap a command when you want exact parsing
+
+Wrapper options, placed before the runner selector:
+  --shell           Run through your interactive shell so aliases/functions work. Default.
+  --direct          Exec the command directly without shell alias expansion.
+  --no-fallback     Disable fallback after the wrapped process exits.
+  --dry-run         Show the resolved invocation and exit.
+
+Utility commands:
+  --init            Create ~/.config/autolimit/config.json and message.txt
+  --show-config     Print resolved config paths and default runner profiles
+  --list-runners    Print runner profiles that have configured fallback commands
+  --test-parser     Test the default limit-message parser
+  --version         Print version
+
+Examples:
+  autolimit --cc
+  autolimit --cc --model sonnet
+  autolimit --claude --dangerously-skip-permissions
+  autolimit --direct --python3 my_repl.py
+  autolimit -- npx some-runner --flag
+
+The message sent after reset is read from ~/.config/autolimit/message.txt by default.
+""".rstrip()
+    )
+
+
+def print_config(cfg: dict[str, Any]) -> None:
+    ensure_default_config()
+    print(f"autolimit {VERSION}")
+    print(f"config dir:     {CONFIG_DIR}")
+    print(f"config file:    {CONFIG_FILE}")
+    print(f"message file:   {configured_message_file(cfg)}")
+    print(f"log file:       {expand_path(cfg.get('log_file'), LOG_FILE)}")
+    print(f"default tz:     {default_tz_name(cfg)}")
+    print(f"grace seconds:  {send_grace_seconds(cfg):g}")
+    max_ahead = config_float(cfg, "max_schedule_ahead_hours", "AUTOLIMIT_MAX_SCHEDULE_AHEAD_HOURS", DEFAULT_MAX_SCHEDULE_AHEAD_HOURS)
+    max_wait = config_float(cfg, "max_fallback_wait_hours", "AUTOLIMIT_MAX_FALLBACK_WAIT_HOURS", DEFAULT_MAX_FALLBACK_WAIT_HOURS)
+    print(f"max ahead:      {max_ahead:g}h (time-of-day patterns)")
+    print(f"max fb wait:    {max_wait:g}h")
+    print(f"exec mode:      {os.environ.get('AUTOLIMIT_EXEC_MODE', 'shell')}")
+    print(f"shell:          {shell_path()}")
+
+
+def list_runners(cfg: dict[str, Any]) -> None:
+    runners = cfg.get("runners")
+    if not isinstance(runners, dict) or not runners:
+        print("No runner profiles configured.")
+        return
+    for name in sorted(runners):
+        profile = runners[name]
+        fallback = profile.get("fallback") if isinstance(profile, dict) else None
+        if fallback:
+            print(f"{name}: fallback={fallback}")
+        else:
+            print(f"{name}: no fallback")
+
+
+def test_parser(cfg: dict[str, Any]) -> int:
+    ensure_default_config()
+    tz = resolve_timezone(default_tz_name(cfg), cfg)
+    now = datetime.now(tz)
+
+    def clock(dt: datetime, ampm: bool = True) -> str:
+        if ampm:
+            hour = dt.hour % 12 or 12
+            return f"{hour}:{dt.minute:02d}{'am' if dt.hour < 12 else 'pm'}"
+        return f"{dt.hour}:{dt.minute:02d}"
+
+    soon = now + timedelta(hours=2)
+    dated = now + timedelta(days=3)
+    month = _MONTHS[dated.month - 1].capitalize()
+    tzn = default_tz_name(cfg)
+
+    # (example line, should it schedule a job?)
+    examples = [
+        (f"You've hit your session limit · resets {clock(soon)} ({tzn})", True),
+        (f"You’ve hit your usage limit - resets {clock(soon)} (KST)", True),
+        (f"You've hit your session limit · resets {clock(soon, ampm=False)} ({tzn})", True),
+        (f"You've hit your weekly limit · resets {month} {dated.day} at {clock(dated)} ({tzn})", True),
+        (f"You've hit your session limit · resets {clock(now - timedelta(hours=3))} ({tzn})", False),
+    ]
+
+    ok = True
+    for line, should_schedule in examples:
+        jobs = LimitScanner(cfg).feed(line.encode("utf-8"))
+        if should_schedule and len(jobs) == 1:
+            print(f"OK: {line} -> {jobs[0].reset_at.isoformat(timespec='seconds')} via {jobs[0].pattern_name}")
+        elif not should_schedule and not jobs:
+            print(f"OK: {line} -> ignored as stale")
+        else:
+            print(f"FAIL: {line} -> {[job.reset_at.isoformat(timespec='seconds') for job in jobs]}", file=sys.stderr)
+            ok = False
+    return 0 if ok else 1
+
+
+def dry_run(invocation: RunnerInvocation, cfg: dict[str, Any]) -> int:
+    print("Resolved autolimit invocation")
+    print(f"runner:          {invocation.runner_name}")
+    print(f"mode:            {invocation.mode}")
+    print(f"command:         {shell_join(invocation.command)}")
+    print(f"child exec argv: {shell_join(child_exec_argv(invocation))}")
+    profile = profile_for_runner(cfg, invocation.runner_name)
+    fallback = profile.get("fallback") if profile else None
+    print(f"fallback:        {fallback if fallback else '(none configured)'}")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    if sys.version_info < (3, 9):
+        print("[autolimit] Python 3.9+ is required.", file=sys.stderr)
+        return 2
+
+    # Handle help/version before config initialization where possible.
+    if argv and argv[0] in {"--help", "-h"}:
+        print_help()
+        return 0
+    if argv and argv[0] in {"--version", "-V", "--autolimit-version", "--claude-auto-version"}:
+        print(VERSION)
+        return 0
+
+    cfg = load_config()
+
+    if argv and argv[0] == "--init":
+        ensure_default_config()
+        print(f"Created or verified config at {CONFIG_FILE}")
+        print(f"Message file: {configured_message_file(cfg)}")
+        return 0
+    if argv and argv[0] in {"--show-config", "--autolimit-show-config", "--claude-auto-show-config"}:
+        print_config(cfg)
+        return 0
+    if argv and argv[0] == "--list-runners":
+        list_runners(cfg)
+        return 0
+    if argv and argv[0] in {"--test-parser", "--autolimit-test-parser", "--claude-auto-test-parser"}:
+        return test_parser(cfg)
+
+    try:
+        invocation, opts = parse_invocation(argv)
+    except AutolimitError as exc:
+        print(f"[autolimit] {exc}", file=sys.stderr)
+        print("Run `autolimit --help` for usage.", file=sys.stderr)
+        return 2
+
+    if invocation is None:
+        print_help()
+        return 2
+
+    if opts.get("dry_run"):
+        return dry_run(invocation, cfg)
+
+    return run_pty(invocation, cfg)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))