#!/usr/bin/env python3
"""Run a job under a hard memory cap on macOS, which has no cgroups.

  memcap.py [--cap-gib 3.7] [--min-free-gib 3] [--interval 2] [--log-every 15] --out PREFIX -- CMD [ARG ...]

The job starts in its own session. Every INTERVAL seconds this sums the physical footprint of the job's whole
process tree: ri_phys_footprint from proc_pid_rusage counts compressed pages at their full size, so it is stricter
than resident size. Above the cap, or below the free-disk floor, the job gets SIGTERM, then SIGKILL 15 s later.

Writes PREFIX.mem.csv (a memory curve) and PREFIX.mem.json (peaks and the reason it ended).
Exit code: the job's own, 99 if stopped at the cap, 98 if stopped at the disk floor.
Project rule, 7 Nov 2026: at most half of the 8 GB Mac; 3.7 GiB leaves 0.3 GiB of margin.
"""
import argparse
import ctypes
import json
import os
import shutil
import signal
import subprocess
import sys
import time

GIB = 1024 ** 3
EXIT_CAP, EXIT_DISK = 99, 98
_libproc = ctypes.CDLL('/usr/lib/libproc.dylib', use_errno=True)
RUSAGE_INFO_V2 = 2
# rusage_info_v2: 16 byte uuid, then uint64s: user, system, idle wakeups, interrupt wakeups, pageins, wired,
# resident, phys_footprint, ...
RESIDENT_OFFSET, FOOTPRINT_OFFSET = 64, 72


def usage(pid):
    """(footprint, resident) in bytes; (0, 0) for a process that has gone or cannot be read."""
    buf = ctypes.create_string_buffer(512)
    if _libproc.proc_pid_rusage(pid, RUSAGE_INFO_V2, buf) != 0:
        return 0, 0
    return (int.from_bytes(buf.raw[FOOTPRINT_OFFSET:FOOTPRINT_OFFSET + 8], 'little'),
            int.from_bytes(buf.raw[RESIDENT_OFFSET:RESIDENT_OFFSET + 8], 'little'))


def tree(root):
    """The root and every descendant still alive, and every process in the root's session."""
    out = subprocess.run(['ps', '-A', '-o', 'pid=,ppid=,sess='], capture_output=True, text=True).stdout
    rows = [line.split() for line in out.splitlines()]
    children, members = {}, set()
    root_sess = None
    for r in rows:
        if len(r) < 2:
            continue
        pid, ppid = int(r[0]), int(r[1])
        children.setdefault(ppid, []).append(pid)
        if pid == root and len(r) > 2:
            root_sess = r[2]
    for r in rows:
        if root_sess and len(r) > 2 and r[2] == root_sess and root_sess != '0':
            members.add(int(r[0]))
    stack = [root]
    while stack:
        p = stack.pop()
        if p not in members or p == root:
            members.add(p)
            stack.extend(children.get(p, []))
    return members


def swap_used_mib():
    out = subprocess.run(['sysctl', '-n', 'vm.swapusage'], capture_output=True, text=True).stdout
    try:
        return float(out.split('used = ')[1].split('M')[0])
    except (IndexError, ValueError):
        return -1.0


def main():
    a = argparse.ArgumentParser()
    a.add_argument('--cap-gib', type=float, default=3.7)
    a.add_argument('--min-free-gib', type=float, default=3.0)
    a.add_argument('--interval', type=float, default=2.0)
    a.add_argument('--log-every', type=float, default=15.0)
    a.add_argument('--out', required=True)
    a.add_argument('cmd', nargs=argparse.REMAINDER)
    p = a.parse_args()
    cmd = p.cmd[1:] if p.cmd[:1] == ['--'] else p.cmd
    if not cmd:
        a.error('no command')
    cap = p.cap_gib * GIB
    t0 = time.time()
    child = subprocess.Popen(cmd, start_new_session=True)

    def forward(sig, _frame):
        try:
            os.killpg(child.pid, sig)
        except ProcessLookupError:
            pass
    signal.signal(signal.SIGTERM, forward)
    signal.signal(signal.SIGINT, forward)

    peak_fp = peak_rss = 0
    peak_at = 0.0
    peak_swap = swap0 = swap_used_mib()
    reason, code = 'exited', None
    last_log = -1e9
    with open(p.out + '.mem.csv', 'w', buffering=1) as csv:
        csv.write('elapsed_s,footprint_gib,resident_gib,processes,swap_used_mib,free_disk_gib\n')
        while True:
            code = child.poll()
            if code is not None:
                break
            pids = tree(child.pid)
            fp = rss = 0
            for pid in pids:
                f, r = usage(pid)
                fp, rss = fp + f, rss + r
            now = time.time() - t0
            if fp > peak_fp:
                peak_fp, peak_at = fp, now
            peak_rss = max(peak_rss, rss)
            free = shutil.disk_usage(os.path.expanduser('~')).free
            if now - last_log >= p.log_every:
                last_log = now
                swap = swap_used_mib()
                peak_swap = max(peak_swap, swap)
                csv.write(f'{now:.0f},{fp / GIB:.3f},{rss / GIB:.3f},{len(pids)},{swap:.0f},{free / GIB:.2f}\n')
            stop = 'memory cap' if fp > cap else 'disk floor' if free < p.min_free_gib * GIB else None
            if stop:
                reason = stop
                csv.write(f'{now:.0f},{fp / GIB:.3f},{rss / GIB:.3f},{len(pids)},{swap_used_mib():.0f},{free / GIB:.2f}\n')
                try:
                    os.killpg(child.pid, signal.SIGTERM)
                except ProcessLookupError:
                    pass
                try:
                    child.wait(timeout=15)
                except subprocess.TimeoutExpired:
                    try:
                        os.killpg(child.pid, signal.SIGKILL)
                    except ProcessLookupError:
                        pass
                    child.wait()
                code = EXIT_CAP if stop == 'memory cap' else EXIT_DISK
                break
            time.sleep(p.interval)
    summary = {'command': cmd, 'cap_gib': p.cap_gib, 'min_free_gib': p.min_free_gib, 'reason': reason, 'exit': code,
               'elapsed_s': round(time.time() - t0, 1), 'peak_footprint_gib': round(peak_fp / GIB, 3),
               'peak_footprint_at_s': round(peak_at, 1), 'peak_resident_gib': round(peak_rss / GIB, 3),
               'swap_used_mib_start': swap0, 'swap_used_mib_peak': peak_swap,
               'note': 'peaks are sampled every interval, so a shorter spike can be missed'}
    with open(p.out + '.mem.json', 'w') as f:
        json.dump(summary, f, indent=1)
    print(f'memcap: {reason}, exit {code}, peak footprint {peak_fp / GIB:.3f} GiB at {peak_at:.0f} s, '
          f'peak resident {peak_rss / GIB:.3f} GiB', file=sys.stderr)
    sys.exit(code if code >= 0 else 128 - code)


if __name__ == '__main__':
    main()
