sentiment-engine/pi_wake_agent.py

#!/usr/bin/env python3
"""
pi_wake_agent.py — Reusable multi-agent wake-up timer with self-cron/daemon/succession

Usage:
    pi_wake_agent.py --install --interval 1h --session cc_UV_dev0_Fb --msg "Operator says CONTINUE. Pi here!"
    pi_wake_agent.py --once --interval 2h --session cc_UV_dev0_Fb --msg "Time's up!"
    pi_wake_agent.py --daemon --interval 1h --session cc_UV_dev0_Fb
    pi_wake_agent.py --succession --count 3 --interval 1h --session cc_UV_dev0_Fb --msg "Scheduled wake"
    pi_wake_agent.py --remove --session cc_UV_dev0_Fb --interval 1h
    pi_wake_agent.py --list
    pi_wake_agent.py --status
    pi_wake_agent.py --validate --session cc_UV_dev0_Fb
"""

import argparse
import logging
import os
import re
import shutil
import shlex
import signal
import subprocess
import sys
import threading
import time
from pathlib import Path
from typing import List, Optional

# ─── Constants ────────────────────────────────────────────────────────────
SCRIPT_PATH = Path(__file__).resolve()
LOG_FILE = Path("/tmp/pi_wake_agent.log")
LOG_MAX_SIZE = 10 * 1024 * 1024  # 10 MB
LOG_MAX_FILES = 5
CRON_COMMENT_PREFIX = "pi_wake_agent"
AGENT_NICK = "pi_nvnemo"
H5I_AGENT = "pi_nvnemo"
H5I_BUS_ROOT = Path("/mnt/dolphinng5_predict")
DEFAULT_INTERVAL = "1h"
CRONICLE_CONFIG = Path(os.environ.get("PI_WAKE_CRONICLE_CONFIG", "/mnt/dolphinng5_predict/cronicle.hcl"))
BACKEND_ENV = "PI_WAKE_BACKEND"
CRON_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
PYTHON_BIN = "/usr/bin/python3"

# Bootstrap PATH at import: crnd fires this script under a minimal env, so
# make zjet/h5i/cronicle discoverable for the subprocess calls below. (The
# shebang resolves python3 via the caller PATH; the script is stdlib-only.)
os.environ["PATH"] = CRON_PATH + os.environ.get("PATH", "")

# ─── Logging Setup ───────────────────────────────────────────────────────
ZELIG_BIN = 'zellij'
# ── Context-occupancy steering (pi status bar: '<pct>%/1.0M') ──────────────────────
# Per AGENTS.md §4.2: >70%% degradation risk, >85%% 'ship partial NOW',
# >95%% emergency (pi runs out of room to compact -> lockup). A doorbell that
# sees critical context appends a /compact heads-up to the steer.
CONTEXT_WARN_PCT = 85
CONTEXT_CRIT_PCT = 95
CONTEXT_RE = re.compile(r"(\d+(?:\.\d+)?)%/1\.0M")


def setup_logging(debug: bool = False) -> logging.Logger:
    log_rotate()
    logger = logging.getLogger("pi_wake_agent")
    logger.setLevel(logging.DEBUG if debug else logging.INFO)
    
    fh = logging.FileHandler(LOG_FILE)
    fh.setLevel(logging.DEBUG)
    fh.setFormatter(logging.Formatter("[%(asctime)s] [%(levelname)s] %(message)s", datefmt="%Y-%m-%d %H:%M:%S"))
    logger.addHandler(fh)
    
    ch = logging.StreamHandler(sys.stderr)
    ch.setLevel(logging.WARNING)
    ch.setFormatter(logging.Formatter("[%(asctime)s] [%(levelname)s] %(message)s", datefmt="%Y-%m-%d %H:%M:%S"))
    logger.addHandler(ch)
    
    return logger


def log_rotate() -> None:
    if not LOG_FILE.exists():
        return
    size = LOG_FILE.stat().st_size
    if size < LOG_MAX_SIZE:
        return
    for i in range(LOG_MAX_FILES - 1, 0, -1):
        src = LOG_FILE.with_suffix(f".log.{i}") if i > 1 else LOG_FILE.with_suffix(".log.1")
        if src.exists():
            dst = LOG_FILE.with_suffix(f".log.{i + 1}")
            src.rename(dst)
    LOG_FILE.rename(LOG_FILE.with_suffix(".log.1"))


# ─── Interval Parsing ────────────────────────────────────────────────────
def parse_interval(interval: str) -> int:
    """Parse interval string (e.g., '1h', '30m', '90m', '2h', '10s') to seconds."""
    match = re.match(r"^(\d+)([hms])$", interval)
    if not match:
        raise ValueError(f"Invalid interval format '{interval}'. Use like 1h, 30m, 90m, 2h, 10s")
    value, unit = int(match.group(1)), match.group(2)
    if unit == "h":
        return value * 3600
    elif unit == "m":
        return value * 60
    elif unit == "s":
        return value
    raise ValueError(f"Unknown unit: {unit}")


def interval_to_cron(interval: str) -> str:
    """Convert interval to cron schedule."""
    match = re.match(r"^(\d+)([hm])$", interval)
    if not match:
        raise ValueError(f"Cron only supports minutes/hours intervals: {interval}")
    value, unit = int(match.group(1)), match.group(2)
    if unit == "h":
        return f"0 */{value} * * *"
    elif unit == "m":
        if value >= 60:
            raise ValueError(f"For minutes >= 60, use hours (e.g., 1h not 60m)")
        return f"*/{value} * * * *"
    raise ValueError(f"Cron only supports minutes/hours intervals: {interval}")


def interval_to_human(interval: str) -> str:
    match = re.match(r"^(\d+)([hms])$", interval)
    if not match:
        return interval
    value, unit = match.group(1), match.group(2)
    if unit == "h":
        return f"{value} hour(s)"
    elif unit == "m":
        return f"{value} minute(s)"
    elif unit == "s":
        return f"{value} second(s)"
    return interval


# ─── Cronicle Support ────────────────────────────────────────────────────
def cronicle_available() -> bool:
    """True if the cronicle binary is installed (backend present)."""
    return shutil.which("cronicle") is not None


def cronicle_daemon_running() -> bool:
    """True if a cronicle daemon is actually serving (binary alone is not enough).

    On this host cronicle has been flaky (the walker never ran) and its daemon
    is NOT supervised (see AGENTS.md). Schedules written to cronicle.hcl only
    fire while a daemon is serving it.
    """
    try:
        result = subprocess.run(["pgrep", "-f", "cronicle run --path"],
                                capture_output=True, text=True, timeout=5)
        return result.returncode == 0
    except Exception:
        return False


def use_cronicle() -> bool:
    """Decide the live scheduler backend.

    PI_WAKE_BACKEND override (cronicle|crontab) wins for tests/ops. Otherwise
    cronicle is used only when the binary is installed AND its daemon is
    running; otherwise crontab (system crnd is the live scheduler here).
    """
    backend = os.environ.get(BACKEND_ENV, "").strip().lower()
    if backend == "cronicle":
        return True
    if backend == "crontab":
        return False
    return cronicle_available() and cronicle_daemon_running()


def cron_comment(sessions: List[str], interval: str) -> str:
    sessions_str = ",".join(sessions)
    return f"{CRON_COMMENT_PREFIX}:{sessions_str}:{interval}"


def cronicle_config_path() -> Path:
    """Return path to cronicle config file."""
    return CRONICLE_CONFIG


def cronicle_schedule_name(sessions: List[str], interval: str) -> str:
    """Generate unique schedule name for cronicle."""
    sessions_str = "_".join(sessions)
    return f"pi_wake_{sessions_str}_{interval}"


def wake_command_args(sessions: List[str], interval: str, message: str, pane: Optional[str] = None) -> List[str]:
    """Build the argv list for the --run wake command (shared by both backends).

    Always passes --interval so the cronicle/crnd entry is self-describing.
    --pane targets a specific zjet pane (e.g. the bottom Soundcheck pane).
    """
    args = [str(SCRIPT_PATH), "--run", "--interval", interval, "--sessions", ",".join(sessions)]
    if pane:
        args += ["--pane", pane]
    args += ["--msg", message]
    return args


def cronicle_install(sessions: List[str], interval: str, message: str, logger: logging.Logger, pane: Optional[str] = None) -> None:
    """Install wake schedule using cronicle HCL config."""
    schedule_name = cronicle_schedule_name(sessions, interval)
    
    # Build task command
    sessions_arg = f"'{','.join(sessions)}'"
    cmd = f"cd {H5I_BUS_ROOT} && export H5I_AGENT={H5I_AGENT} && {SCRIPT_PATH} --run --interval {interval} --sessions {sessions_arg} --msg {shlex.quote(message)}"
    
    # Read existing config
    config_path = cronicle_config_path()
    existing = ""
    if config_path.exists():
        existing = config_path.read_text()
    
    # Remove existing schedule with same name
    lines = existing.splitlines()
    new_lines = []
    i = 0
    while i < len(lines):
        if f'schedule "{schedule_name}"' in lines[i]:
            # Skip this schedule block (find closing brace)
            brace_count = 0
            while i < len(lines):
                brace_count += lines[i].count('{')
                brace_count -= lines[i].count('}')
                i += 1
                if brace_count == 0:
                    break
            continue
        new_lines.append(lines[i])
        i += 1
    
    # Add new schedule
    cron_sched = interval_to_cron(interval)
    cron_sched = cron_sched.replace("*/", "@every ").replace("0 */", "@every ").replace(" * * *", "")
    # Convert cron to cronicle format
    match = re.match(r"^(\d+)([hm])$", interval)
    if match:
        value, unit = int(match.group(1)), match.group(2)
        if unit == "h":
            cronicle_cron = f"@every {value}h"
        else:
            cronicle_cron = f"@every {value}m"
    else:
        cronicle_cron = "@every 1h"
    
    new_schedule = f'''
schedule "{schedule_name}" {{
  cron = "{cronicle_cron}"

  task "wake" {{
    command = [{", ".join(chr(34) + a + chr(34) for a in wake_command_args(sessions, interval, message, pane))}]
  }}
}}'''
    
    new_config = "\n".join(new_lines) + "\n\n" + new_schedule + "\n"
    config_path.write_text(new_config)
    logger.info(f"Installed cronicle schedule: {schedule_name} -> {sessions} every {interval}")


def cronicle_remove(sessions: List[str], interval: str, logger: logging.Logger) -> None:
    """Remove wake schedule from cronicle HCL config."""
    schedule_name = cronicle_schedule_name(sessions, interval)
    config_path = cronicle_config_path()
    
    if not config_path.exists():
        return
    
    existing = config_path.read_text()
    lines = existing.splitlines()
    new_lines = []
    i = 0
    while i < len(lines):
        if f'schedule "{schedule_name}"' in lines[i]:
            brace_count = 0
            while i < len(lines):
                brace_count += lines[i].count('{')
                brace_count -= lines[i].count('}')
                i += 1
                if brace_count == 0:
                    break
            continue
        new_lines.append(lines[i])
        i += 1
    
    config_path.write_text("\n".join(new_lines) + "\n")
    logger.info(f"Removed cronicle schedule: {schedule_name}")


def cronicle_list(logger: logging.Logger) -> None:
    """List cronicle wake schedules."""
    config_path = cronicle_config_path()
    if not config_path.exists():
        print("  (none)")
        return
    
    existing = config_path.read_text()
    found = False
    for line in existing.splitlines():
        if 'schedule "pi_wake_' in line:
            print(f"  {line.strip()}")
            found = True
    if not found:
        print("  (none)")



def install_cron(sessions: List[str], interval: str, message: str, logger: logging.Logger, pane: Optional[str] = None) -> None:
    if use_cronicle():
        if not cronicle_daemon_running():
            logger.warning(
                "cronicle binary present but its daemon is NOT running "
                "schedules written to cronicle.hcl will not fire; set "
                "PI_WAKE_BACKEND=crontab to use system crnd."
            )
        cronicle_install(sessions, interval, message, logger, pane)
    else:
        cron_sched = interval_to_cron(interval)
        comment = cron_comment(sessions, interval)
        sessions_arg = f"'{','.join(sessions)}'"
        run_cmd = f"{PYTHON_BIN} {SCRIPT_PATH} --run --interval {interval} --sessions {sessions_arg} --msg {shlex.quote(message)}"
        if pane:
            run_cmd += f" --pane {shlex.quote(pane)}"
        cmd = f"cd {H5I_BUS_ROOT} && export PATH={CRON_PATH} && export H5I_AGENT={H5I_AGENT} && {run_cmd}"
        
        result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
        existing = result.stdout if result.returncode == 0 else ""
        lines = [line for line in existing.splitlines() if comment not in line]
        lines.append(f"{cron_sched} {cmd} # {comment}")
        new_cron = "\n".join(lines) + "\n"
        subprocess.run(["crontab", "-"], input=new_cron, text=True, check=True)
        logger.info(f"Installed cron: {cron_sched} -> {sessions} every {interval}")


def remove_cron(sessions: List[str], interval: str, logger: logging.Logger) -> None:
    if use_cronicle():
        cronicle_remove(sessions, interval, logger)
    else:
        comment = cron_comment(sessions, interval)
        result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
        existing = result.stdout if result.returncode == 0 else ""
        lines = [line for line in existing.splitlines() if comment not in line]
        new_cron = "\n".join(lines) + ("\n" if lines else "")
        subprocess.run(["crontab", "-"], input=new_cron, text=True, check=True)
        logger.info(f"Removed cron for {sessions} ({interval})")


def list_cron(logger: logging.Logger) -> None:
    if use_cronicle():
        cronicle_list(logger)
    else:
        print("=== pi_wake_agent cron entries ===")
        result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
        existing = result.stdout if result.returncode == 0 else ""
        found = False
        for line in existing.splitlines():
            if CRON_COMMENT_PREFIX in line:
                print(f"  {line}")
                found = True
        if not found:
            print("  (none)")


# ─── Zellij Operations ──────────────────────────────────────────────────
def zellij_session_exists(session: str) -> bool:
    try:
        result = subprocess.run(["zellij", "list-sessions"], capture_output=True, text=True, timeout=5)
        clean = re.sub(r'\x1b\[[0-9;]*m', '', result.stdout)
        for line in clean.splitlines():
            if line.startswith(session + " ") or line == session:
                return True
    except Exception:
        pass
    return False


def zellij_write_chars(session: str, text: str, pane: Optional[str] = None) -> bool:
    """Write text into a zjet pane (focused, or --pane-id when given)."""
    cmd = [ZELIG_BIN, "--session", session, "action", "write-chars"]
    if pane:
        cmd += ["--pane-id", pane]
    cmd.append(text)
    try:
        subprocess.run(cmd, capture_output=True, timeout=5)
        return True
    except Exception:
        return False


def zellij_write_enter(session: str, pane: Optional[str] = None) -> bool:
    """Press ENTER (CR) in a zjet pane (focused, or --pane-id when given)."""
    cmd = [ZELIG_BIN, "--session", session, "action", "write", "13"]
    if pane:
        cmd += ["--pane-id", pane]
    try:
        subprocess.run(cmd, capture_output=True, timeout=5)
        return True
    except Exception:
        return False


# ─── Wake Action ────────────────────────────────────────────────────────────────────
    logger.info(f"One-shot timer set for {interval} ({interval_to_human(interval)})")
    
    def _wake():
        time.sleep(interval_seconds)
        run_wake(sessions, message, logger, pane)
    
    thread = threading.Thread(target=_wake, daemon=True)
    thread.start()
    logger.info(f"Background timer started (thread: {thread.ident})")
    pid_file = Path(f"/tmp/pi_wake_agent_{sessions[0]}.pid")
    pid_file.write_text(str(os.getpid()))



def parse_context_occupancy(session: str, pane: Optional[str] = None) -> Optional[float]:
    """Parse the agent's context-occupancy % from its status bar.

    pi's status bar reads like '<cost> <pct>%/1.0M (auto) ...'. We extract the
    '<pct>' before '/1.0M'. Returns None if the pane is not a pi CLI, the dump
    fails, or no figure is present (a doorbell must never block on a read).
    """
    cmd = [ZELIG_BIN, "--session", session, "action", "dump-screen"]
    if pane:
        cmd += ["--pane-id", pane]
    try:
        result = subprocess.run(cmd, capture_output=True, text=True, timeout=8)
    except Exception:
        return None
    m = CONTEXT_RE.search(str(result.stdout or ""))
    if not m:
        return None
    try:
        return float(m.group(1))
    except ValueError:
        return None


def context_warning(session: str, pane: Optional[str] = None) -> str:
    """Build a context-occupancy heads-up to append to the steer (or '').

    Critical (>=95%) => '/compact NOW' steer; warn (>=85%) => 'consider /compact'.
    """
    pct = parse_context_occupancy(session, pane)
    if pct is None:
        return ""
    if pct >= CONTEXT_CRIT_PCT:
        return (f" | \U0001f534 HEADS UP: context at {pct:g}%/1.0M \u2014 /compact NOW or "
                f"you'll lock up (no room to compact)")
    if pct >= CONTEXT_WARN_PCT:
        return f" | \u26a0\ufe0f heads up: your context is at {pct:g}% \u2014 consider /compact"
    return ""


def run_wake(sessions: List[str], message: str, logger: logging.Logger, pane: Optional[str] = None) -> None:
    sessions_str = ",".join(sessions)
    logger.info(f"Waking {sessions_str} with message: {message}" + (f" (pane={pane})" if pane else ""))

    warns: List[str] = []
    for session in sessions:
        # Verify session exists before attempting to wake
        if not zellij_session_exists(session):
            logger.warning(f"Session {session} does not exist, skipping")
            continue

        # Read the agent's context-occupancy and append a heads-up to the steer
        # when approaching the compact threshold (pi can lock up if she runs out
        # of room to compact).
        warn = context_warning(session, pane)
        warns.append(warn)
        logger.info(f"Context warning for {session}: {warn or '(none)'}")

        steer = f"[{AGENT_NICK} via {ZELIG_BIN}] {message} Run: h5i-bus msg inbox{warn}"
        zellij_write_chars(session, steer, pane)
        # Send ENTER keypresses with delay for reliability
        for _ in range(10):
            zellij_write_enter(session, pane)
            time.sleep(0.5)

    # Fire-and-forget h5i bus message (non-blocking)
    def _send_bus():
        try:
            bus_warn = next((w for w in warns if w), "")
            subprocess.run(
                ["h5i", "msg", "send", "Fable", f"{message} (timer wakeup){bus_warn}"],
                cwd=H5I_BUS_ROOT,
                env={**os.environ, "H5I_AGENT": H5I_AGENT},
                capture_output=True,
                timeout=5
            )
        except Exception:
            pass  # Silently ignore - fire and forget

    threading.Thread(target=_send_bus, daemon=True).start()

    logger.info(f"Wake sent to {sessions_str}")

def run_once(sessions: List[str], interval: str, message: str, logger: logging.Logger, pane: Optional[str] = None) -> None:
    interval_seconds = parse_interval(interval)
    logger.info(f"One-shot timer set for {interval} ({interval_to_human(interval)})")
    
    def _wake():
        time.sleep(interval_seconds)
        run_wake(sessions, message, logger, pane)
    
    thread = threading.Thread(target=_wake, daemon=True)
    thread.start()
    logger.info(f"Background timer started (thread: {thread.ident})")
    pid_file = Path(f"/tmp/pi_wake_agent_{sessions[0]}.pid")
    pid_file.write_text(str(os.getpid()))
    return 0


def run_daemon(sessions: List[str], interval: str, message: str, logger: logging.Logger, pane: Optional[str] = None) -> None:
    interval_seconds = parse_interval(interval)
    logger.info("=== DAEMON START ===")
    logger.info(f"Interval: {interval} ({interval_to_human(interval)})")
    logger.info(f"Sessions: {sessions}")
    logger.info(f"Message: {message}")
    
    run_wake(sessions, message, logger, pane)
    
    while True:
        logger.debug(f"Sleeping for {interval_seconds}s...")
        time.sleep(interval_seconds)
        run_wake(sessions, message, logger, pane)


def run_succession(sessions: List[str], interval: str, count: int, message: str, logger: logging.Logger, pane: Optional[str] = None) -> None:
    """Run wake N times at interval, then self-clean (remove cron if installed)."""
    interval_seconds = parse_interval(interval)
    logger.info(f"=== SUCCESSION START === Count: {count}, Interval: {interval} ({interval_to_human(interval)})")
    logger.info(f"Sessions: {sessions}")
    logger.info(f"Message: {message}")
    
    for i in range(1, count + 1):
        logger.info(f"Succession {i}/{count}")
        run_wake(sessions, message, logger, pane)
        if i < count:
            logger.debug(f"Sleeping for {interval_seconds}s until next succession...")
            time.sleep(interval_seconds)
    
    # Self-clean: remove any cron entry for this session/interval combo
    try:
        remove_cron(sessions, interval, logger)
        logger.info("Self-cleanup complete (cron removed)")
    except Exception as e:
        logger.warning(f"Self-cleanup failed: {e}")
    
    logger.info("=== SUCCESSION COMPLETE ===")


def status(logger: logging.Logger) -> None:
    print("=== pi_wake_agent Status ===")
    print(f"Script: {SCRIPT_PATH}")
    print(f"Log: {LOG_FILE}")
    print(f"Log size: {LOG_FILE.stat().st_size if LOG_FILE.exists() else 'N/A'} bytes")
    print(f"Agent: {AGENT_NICK}")
    backend = os.environ.get(BACKEND_ENV, "").strip().lower()
    if backend == "cronicle":
        backend_label = "cronicle (forced by PI_WAKE_BACKEND)"
    elif backend == "crontab":
        backend_label = "crontab (forced by PI_WAKE_BACKEND)"
    elif use_cronicle():
        backend_label = "cronicle"
    else:
        backend_label = "crontab (system crnd)"
    print(f"Backend: {backend_label}")
    print(f"cronicle binary={cronicle_available()} daemon_running={cronicle_daemon_running()}")
    print()
    list_cron(logger)
    print()
    print("=== Active one-shot timers ===")
    found = False
    for pid_file in Path("/tmp").glob("pi_wake_agent_*.pid"):
        found = True
        try:
            pid = int(pid_file.read_text().strip())
            os.kill(pid, 0)
            print(f"  PID {pid} (active)")
        except (ProcessLookupError, ValueError):
            print(f"  PID {pid_file.read_text().strip()} (dead, cleaning up)")
            pid_file.unlink(missing_ok=True)
    if not found:
        print("  (none)")


def validate_sessions(sessions: List[str], logger: logging.Logger) -> None:
    logger.info(f"Validating sessions: {sessions}")
    for session in sessions:
        if zellij_session_exists(session):
            logger.info(f"  {session}: EXISTS")
        else:
            logger.warning(f"  {session}: NOT FOUND (may be dead/EXITED)")


# ─── Session Parsing ─────────────────────────────────────────────────────
def parse_sessions(raw) -> List[str]:
    if not raw:
        return []
    if isinstance(raw, list):
        return [s.strip() for s in raw]
    return [s.strip() for s in raw.split(",") if s.strip()]


# ─── Usage ──────────────────────────────────────────────────────────────
def create_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="pi_wake_agent.py — Reusable multi-agent wake-up timer with self-cron/daemon/succession",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
EXAMPLES:
  # Install recurring 1-hour timer for one session
  pi_wake_agent.py --install --interval 1h --session cc_UV_dev0_Fb

  # Install 30-minute timer for multiple sessions
  pi_wake_agent.py --install --interval 30m --sessions "cc_UV_dev0_Fb,cc_UV_dev1_48" --msg "Wake up!"

  # One-shot wake in 2 hours (no cron)
  pi_wake_agent.py --once --interval 2h --session cc_UV_dev0_Fb --msg "Time's up!"

  # Run N times at interval, then self-clean
  pi_wake_agent.py --succession --count 3 --interval 1h --session cc_UV_dev0_Fb --msg "Scheduled wake"

  # Run as daemon (long-lived process, no cron)
  pi_wake_agent.py --daemon --interval 1h --session cc_UV_dev0_Fb

  # Remove timer
  pi_wake_agent.py --remove --session cc_UV_dev0_Fb --interval 1h

  # List all timers
  pi_wake_agent.py --list

  # Show status
  pi_wake_agent.py --status

  # Validate sessions
  pi_wake_agent.py --validate --session cc_UV_dev0_Fb
"""
    )
    parser.add_argument("--install", action="store_const", const="install", dest="mode", help="Install recurring cron timer")
    parser.add_argument("--once", action="store_const", const="once", dest="mode", help="One-shot wake (no cron)")
    parser.add_argument("--daemon", action="store_const", const="daemon", dest="mode", help="Run as long-lived daemon (no cron)")
    parser.add_argument("--succession", action="store_const", const="succession", dest="mode", help="Run N times at interval, then self-clean")
    parser.add_argument("--count", type=int, default=1, help="Number of successions (for --succession mode)")
    parser.add_argument("--run", action="store_const", const="run", dest="mode", help="Internal: run wake action (called by cron)")
    parser.add_argument("--remove", action="store_const", const="remove", dest="mode", help="Remove cron timer")
    parser.add_argument("--list", action="store_const", const="list", dest="mode", help="List active cron timers")
    parser.add_argument("--status", action="store_const", const="status", dest="mode", help="Show status (cron + one-shot timers)")
    parser.add_argument("--validate", action="store_const", const="validate", dest="mode", help="Validate sessions exist in zellij")
    parser.add_argument("--interval", default=DEFAULT_INTERVAL, help="Interval (default: 1h). Formats: 30m, 1h, 90m, 2h, etc.")
    parser.add_argument("--session", action="append", dest="session_list", help="Zellij session name (can repeat)")
    parser.add_argument("--sessions", help="Comma-separated list of sessions")
    parser.add_argument("--pane", dest="pane", default=None, help="Target a specific zjet pane (focused pane if unset), e.g. terminal_1")
    parser.add_argument("--msg", default=f"Operator says CONTINUE. {AGENT_NICK} here, saying hi!", help="Wake message")
    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
    parser.add_argument("--dry-run", action="store_true", help="Show what would be done without executing")
    parser.set_defaults(mode="install")
    return parser


# ─── Main ───────────────────────────────────────────────────────────────
def main() -> int:
    parser = create_parser()
    args = parser.parse_args()
    
    # Combine sessions
    sessions: List[str] = []
    if args.sessions:
        sessions.extend(parse_sessions(args.sessions))
    if args.session_list:
        sessions.extend(args.session_list)
    
    # Setup logging
    logger = setup_logging(args.debug)
    
    # Validate
    if len(sessions) == 0 and args.mode not in ("list", "status"):
        logger.error("--session or --sessions required")
        parser.print_help()
        return 1
    
    if args.mode == "succession" and args.count < 1:
        logger.error("--count must be >= 1 for succession mode")
        return 1
    
    logger.info(f"=== pi_wake_agent {args.mode} ===")
    logger.info(f"Interval: {args.interval} ({interval_to_human(args.interval)})")
    logger.info(f"Sessions: {sessions}")
    if args.pane:
        logger.info(f"Pane target: {args.pane}")
    logger.info(f"Message: {args.msg}")
    if args.mode == "succession":
        logger.info(f"Count: {args.count}")
    if args.dry_run:
        logger.info("DRY RUN: no actions will be executed")
    
    if args.dry_run:
        logger.info("DRY RUN: would execute mode '%s' with sessions=%s, interval=%s, message='%s'", args.mode, sessions, args.interval, args.msg)
        return 0
    
    try:
        if args.mode == "install":
            install_cron(sessions, args.interval, args.msg, logger, args.pane)
        elif args.mode == "once":
            run_once(sessions, args.interval, args.msg, logger, args.pane)
        elif args.mode == "daemon":
            run_daemon(sessions, args.interval, args.msg, logger, args.pane)
        elif args.mode == "succession":
            run_succession(sessions, args.interval, args.count, args.msg, logger, args.pane)
        elif args.mode == "run":
            run_wake(sessions, args.msg, logger, args.pane)
        elif args.mode == "remove":
            remove_cron(sessions, args.interval, logger)
        elif args.mode == "list":
            list_cron(logger)
        elif args.mode == "status":
            status(logger)
        elif args.mode == "validate":
            validate_sessions(sessions, logger)
        else:
            logger.error(f"Unknown mode: {args.mode}")
            return 1
    except Exception as e:
        logger.error(f"Error: {e}")
        if args.debug:
            import traceback
            traceback.print_exc()
        return 1
    
    return 0


if __name__ == "__main__":
    sys.exit(main())