#!/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//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//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//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()