#!/usr/bin/env python3
"""Nudge a lane session that has gone quiet. Run it from cron or launchd every 30 minutes.

A lane can stop with nothing set to wake it: its last job ends, the agent replies once and sits at the prompt.
`rh lanes cadence` notices, but only on the lane's delivery window (often a day), and only if someone runs it.
Detection without delivery does nothing, so this script delivers. When a lane's tmux pane is idle (no transcript
write for --idle-min, and no running shell or agent shown in the pane) AND either cadence is WARN/STALLED/BROKEN
or the pane has simply been idle that long, it types one resume prompt into the pane. That happens at most once
per --reask seconds per lane.

Sessions are tmux sessions named PREFIX + owner_session (default prefix `claude-`). Idle time is measured from the
last real turn (a user or assistant message) in the session's Claude Code transcript, never from the file's mtime:
11-08 to 11-11 every lane slept because idle compaction and session metadata rewrote transcripts about hourly, so
no pane ever looked idle and nothing was nudged for three days. Lanes marked EXEMPT or UNCONFIGURED by cadence,
and names in --skip, are never nudged. --dry prints decisions and types nothing. Run one copy per Mac that hosts
lane sessions; each scans its own tmux (pass --tmux when tmux is not on the scheduler's PATH).
"""
import argparse
import glob
import json
import os
import re
import shlex
import subprocess
import sys
import time
from datetime import datetime
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
import lane_registry

BEHIND = ('WARN', 'STALLED', 'BROKEN')
RUNNING = re.compile(r'esc to interrupt|shells? still running|agents? running|still running')
MSG = ("Harness check (lane-nudge): lane {lane} is {why}, and this session has been idle {idle} min with nothing "
       "running. Start the next round from the lane's idea queue now, put bounded work on background jobs, and arm "
       "a watcher on every job so you wake on results. If you are blocked on a human decision, send it through the "
       "conductor inbox and keep working on something else.")


RESULT_MSG = ("Harness check (lane-nudge): a job result for lane {lane} landed after your last turn and nothing woke "
              "you: {path}. Read it and take the next step now. Then check why your watcher missed it (the file it "
              "watched, or a missing rule) and fix that rule.")


def pickup(row):
    """11-11: the digest -> lane loop. Name the newest digest idea no round has picked up, so the
    next round starts there (rh lanes cadence reports it as digest.newest_unrun)."""
    idea = ((row or {}).get('digest') or {}).get('newest_unrun')
    if not idea:
        return ''
    return (' Start from the newest digest idea no round has picked up: {} ({}). Promote or freeze it when '
            'the round starts and log its result or close it with the verdict, so idea -> round -> verdict '
            'shows in rh lanes cadence.'.format(idea['id'], idea.get('claim', '')[:140]))


def decide(idle_min, running, status, last_nudge, now, idle_limit=60, reask=7200, unread=None, last_output=None,
           blocked=None):
    """Return the reason to nudge, or None. Pure, so it can be tested without tmux.

    unread: a job output newer than the session's last real turn (see unread_output). It overrides
    `running` and the idle limit: 11-12, math waited on its own watcher shell for 5.5 h after its review
    had finished, and that shell is exactly what made the pane look busy. One nudge per output file."""
    if status in ('EXEMPT', 'UNCONFIGURED', 'HELD'):    # HELD: lanes/<lane>/HOLD, paused by its owner
        return None
    if unread and unread != last_output:
        return 'a job result landed after your last turn and nothing woke you: {}'.format(unread)
    if blocked:      # waiting on a decision only the owner can make; a result above still wakes it
        return None
    if running or idle_min < idle_limit or now - last_nudge < reask:
        return None
    return f'{status} on cadence' if status in BEHIND else 'quiet'


def unread_output(globs, lane, last_turn, now, settle=15 * 60):
    """The newest job output (from the --outputs globs, {lane} filled in) written after last_turn and at
    least `settle` seconds ago, or None. Finished-job files only (a .last.md, a review's final text, a
    watch event): a live log changes all the time and would always look newer."""
    newest, best = None, None
    for pattern in globs:
        for f in glob.glob(os.path.expanduser(pattern.replace('{lane}', lane))):
            try:
                m = os.path.getmtime(f)
            except OSError:
                continue
            if last_turn < m <= now - settle and (best is None or m > best):
                newest, best = f, m
    return newest


BLOCKED_HOURS = 12


def blocked_on(lane_dir, now, hours=BLOCKED_HOURS):
    """The first line of lanes/<lane>/BLOCKED when it was written in the last `hours`, else None.

    friends, 11-13: blocked on seven decisions only the owner can make, every in-brief job done, and nudged
    three times in a night to "keep working on something else", which only invites busywork. A lane writes
    BLOCKED (first line: the decision it waits on and where it was sent) and deletes it once answered.
    It lapses after `hours` so a forgotten one cannot silence a lane; rewrite it to stay blocked."""
    path = Path(lane_dir) / 'BLOCKED'
    try:
        if now - path.stat().st_mtime > hours * 3600:
            return None
        return (path.read_text(errors='replace').strip().splitlines() or ['(no reason given)'])[0][:200]
    except OSError:
        return None


def panes(tmux, prefix):
    out = subprocess.run([tmux, 'list-panes', '-a', '-F', '#{session_name}\t#{pane_id}\t#{pane_current_path}'],
                         capture_output=True, text=True).stdout
    for row in out.splitlines():
        name, pane, path = row.split('\t')
        if name.startswith(prefix):
            yield name[len(prefix):], pane, path


def transcripts(path, projects, now, recent=2 * 86400):
    """Transcripts for a pane: those Claude Code files under the pane's directory, plus recent ones whose
    latest recorded cwd is the pane's (a session that cd'd after launch files under its launch directory)."""
    d = projects / re.sub(r'[/.]', '-', path)
    found = list(d.glob('*.jsonl')) if d.is_dir() else []
    needle = '"cwd":' + json.dumps(path)
    for f in projects.glob('*/*.jsonl'):
        if f in found or now - f.stat().st_mtime > recent:
            continue
        cwds = re.findall(r'"cwd":"[^"]*"', tail_text(f, 1 << 16))
        if cwds and cwds[-1] == needle:
            found.append(f)
    return found


def tail_text(f, size):
    with open(f, 'rb') as fh:
        fh.seek(0, 2)
        fh.seek(max(0, fh.tell() - size))
        return fh.read().decode('utf-8', 'replace')


def real_turn(row):
    """A message someone sent or the model wrote. Not compaction (its boundary and summary rows carry fresh
    timestamps), not meta rows, not the untimestamped title/mode/bridge rows a session rewrites while idle."""
    return (row.get('type') in ('user', 'assistant') and not row.get('isCompactSummary')
            and not row.get('isMeta') and not row.get('isSidechain') and bool(row.get('timestamp')))


def last_turn(f, chunk=1 << 20):
    """Epoch seconds of the newest real turn in transcript f, or None. Reads from the end, widening the
    window until it finds one, so a multi-GB transcript costs one chunk."""
    size = f.stat().st_size
    window = chunk
    while True:
        lines = tail_text(f, window).split('\n')   # not splitlines(): U+2028 inside JSON splits a record
        if window < size:
            lines = lines[1:]      # the first line of a partial window is cut
        for line in reversed(lines):
            try:
                row = json.loads(line)
            except ValueError:
                continue
            if isinstance(row, dict) and real_turn(row):
                try:
                    return datetime.fromisoformat(row['timestamp'].replace('Z', '+00:00')).timestamp()
                except ValueError:
                    continue
        if window >= size:
            return None
        window *= 4


def idle_minutes(path, projects, now):
    """Minutes since the newest real turn across the pane's transcripts, or None when there is none."""
    turns = [t for t in (last_turn(f) for f in transcripts(path, projects, now)) if t is not None]
    return int((now - max(turns)) / 60) if turns else None


def cadence(rh):
    """({owner_session: row}, None) or (None, error). A failed read is never all clear: one Mini ran
    this under launchd with a bare `rh` that was not on launchd's PATH, every read failed for 8 hours,
    and every lane read as fine. `rh lanes cadence` exits 1 when a lane is behind, so only output that
    is not the JSON list counts as a failed read."""
    try:
        run = subprocess.run([rh, 'lanes', 'cadence', '--json'], capture_output=True, text=True, timeout=120)
        try:
            data = json.loads(run.stdout)
        except ValueError:
            return None, 'exit {}, no JSON: {}'.format(run.returncode, (run.stderr or run.stdout).strip()[-200:])
        rows = {r['owner_session']: r for r in data if isinstance(r, dict) and r.get('owner_session')}
        return (rows, None) if rows else (None, 'no lanes in the cadence output')
    except (OSError, subprocess.SubprocessError) as exc:
        return None, '{}: {}'.format(type(exc).__name__, exc)


def report_failure(error, state, alert, dry):
    """Print a loud row on every failed run and push once per failure streak (ALERT, a command that
    takes the message as its last argument); log recovery the same way."""
    flag = state / 'cadence-failed.json'
    if error:
        line = 'CADENCE READ FAILED: {}. Every lane is UNKNOWN this run, not fine.'.format(error)
        print(line, file=sys.stderr)
        if not flag.exists() and not dry:
            if alert:
                subprocess.run(shlex.split(alert) + ['lane-nudge: ' + line], capture_output=True, timeout=60)
            flag.write_text(json.dumps({'since': time.time(), 'error': error}))
        return line
    if flag.exists() and not dry:
        if alert:
            subprocess.run(shlex.split(alert) + ['lane-nudge: cadence read recovered'], capture_output=True, timeout=60)
        flag.unlink()
    return None


def say(log, line, dry=False):
    print(line)
    if log and not dry:
        with open(os.path.expanduser(log), 'a') as fh:
            fh.write(time.strftime('%Y-%m-%d %H:%M:%S ') + line + '\n')


def main():
    home = Path.home()
    ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
    ap.add_argument('--prefix', default=os.environ.get('LANE_NUDGE_PREFIX', 'claude-'))
    ap.add_argument('--skip', default=os.environ.get('LANE_NUDGE_SKIP', ''),
                    help='comma-separated owner sessions that are idle by design')
    ap.add_argument('--idle-min', type=int, default=60)
    ap.add_argument('--reask', type=int, default=7200)
    ap.add_argument('--tmux', default=os.environ.get('TMUX_BIN', 'tmux'))
    ap.add_argument('--rh', default=os.environ.get('RH_BIN', 'rh'))
    ap.add_argument('--projects', default=str(home / '.claude/projects'))
    ap.add_argument('--state', default=str(home / '.local/state/lane-nudge'))
    ap.add_argument('--alert', default=os.environ.get('LANE_NUDGE_ALERT', ''),
                    help='command run with one message argument when the cadence read fails (and on recovery)')
    ap.add_argument('--log', default=os.environ.get('LANE_NUDGE_LOG', ''), help='append each nudge to this file')
    ap.add_argument('--lanes', default=os.environ.get('LANE_NUDGE_LANES', '~/.local/share/research-harness/lanes'),
                    help='lanes root, for lanes/<lane>/BLOCKED')
    ap.add_argument('--outputs', default=os.environ.get('LANE_NUDGE_OUTPUTS', ''),
                    help='comma-separated globs of finished-job outputs, {lane} for the lane name; one newer than '
                         "the session's last turn nudges it even while a watcher shell runs")
    ap.add_argument('--dry', action='store_true')
    a = ap.parse_args()
    skip = {s for s in a.skip.split(',') if s}
    outputs = [g.strip() for g in a.outputs.split(',') if g.strip()]
    state = Path(a.state)
    state.mkdir(parents=True, exist_ok=True)
    registry = lane_registry.load(a.lanes)
    cad, error = cadence(a.rh)
    failed = report_failure(error, state, a.alert, a.dry)
    if failed:
        say(a.log, failed, a.dry)
    cad = cad or {}
    for lane, pane, path in panes(a.tmux, a.prefix):
        session = lane
        lane = registry.lane_of_session(session)
        if registry.status(lane) in ('retired', 'ended', 'held'):
            say(a.log, f'{a.prefix}{session}: skipped ({registry.reason(lane)})', a.dry)
            continue
        if session in skip or lane in skip:
            continue
        idle = idle_minutes(path, Path(a.projects), time.time())
        if idle is None:
            continue
        tail = subprocess.run([a.tmux, 'capture-pane', '-p', '-t', pane, '-S', '-15'],
                              capture_output=True, text=True).stdout
        sf = state / f'{session}.json'
        saved = json.loads(sf.read_text()) if sf.exists() else {}
        last = saved.get('at', 0)
        c = cad.get(session, cad.get(lane, {}))
        now = time.time()
        unread = unread_output(outputs, lane, now - idle * 60, now) if outputs else None
        blocked = blocked_on(Path(os.path.expanduser(a.lanes)) / lane, now)
        why = decide(idle, bool(RUNNING.search(tail)), c.get('status'), last, now, a.idle_min, a.reask,
                     unread, saved.get('output'), blocked)
        if blocked and not why and idle >= a.idle_min:
            say(a.log, f'{a.prefix}{session}: blocked, not nudged ({blocked})', True)
        if not why:
            continue
        if c.get('status') in BEHIND and c.get('deliverable'):
            why += ' ({}, {:.0f} h since the last one)'.format(c['deliverable'], c.get('hours_since_last_delivery') or 0)
        if c.get('last_sweep_refused'):
            why += '; the last sweep was REFUSED, not idle: ' + c['last_sweep_refused'] + '. Fix that first'
        if error and why == 'quiet':
            why = 'quiet (cadence unknown: the read failed)'
        text = (RESULT_MSG.format(lane=lane, path=unread) if unread and why.startswith('a job result')
                else MSG.format(lane=lane, why=why, idle=idle) + pickup(c))
        say(a.log, f'{a.prefix}{session}: nudge ({why}; idle {idle} min)', a.dry)
        if a.dry:
            continue
        subprocess.run([a.tmux, 'send-keys', '-t', pane, '-l', '--', text])
        time.sleep(1)
        subprocess.run([a.tmux, 'send-keys', '-t', pane, 'Enter'])
        sf.write_text(json.dumps({'at': time.time(), 'why': why, 'output': unread or saved.get('output')}))


if __name__ == '__main__':
    main()
