"""Block until the helpers' needs file grows (a helper appended something only Claude can do), then print the new
part and exit, so the coordinator's background task wakes it. Also exits after --minutes as a heartbeat.

    py -3.12 -B tools/watch_needs.py [--file R:/Workspace/Scratch/helpers/needs.md] [--minutes 60]"""
import argparse
import time
from pathlib import Path

ap = argparse.ArgumentParser()
ap.add_argument("--file", default=r"R:/Workspace/Scratch/helpers/needs.md")
ap.add_argument("--minutes", type=float, default=60)
args = ap.parse_args()
path = Path(args.file)
path.parent.mkdir(parents=True, exist_ok=True)
path.touch(exist_ok=True)
start = path.stat().st_size
deadline = time.monotonic() + args.minutes * 60
while time.monotonic() < deadline:
    size = path.stat().st_size
    if size > start:
        time.sleep(3)                      # let the writer finish its entry
        with path.open(encoding="utf-8", errors="replace") as f:
            f.seek(start)
            print(f.read().strip())
        raise SystemExit(0)
    if size < start:                       # the file was cleared: follow it from here
        start = size
    time.sleep(10)
print(f"no new needs for {args.minutes:g} minutes")