dsh-aris-panel 0.1.0

package/tools/verify_wiki_coverage.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# verify_wiki_coverage.sh — Diagnostic (NOT a gate) for research-wiki coverage.
+#
+# Compares arXiv IDs referenced in recent session artifacts against those
+# already ingested into `research-wiki/papers/`. Reports the delta so the
+# user can run `/research-wiki sync --arxiv-ids <missing>` to backfill.
+#
+# This is a best-effort diagnostic. Because ARIS has no canonical "papers
+# I actually read" log (unlike paper-writing's audit artifacts), scans
+# grep over likely sources and will miss papers read via channels it
+# doesn't scan. See `shared-references/integration-contract.md` §6
+# (Verifier or diagnostic) — this tool is intentionally non-blocking.
+#
+# Usage:
+#   bash tools/verify_wiki_coverage.sh <wiki_root> [--scan <path> ...] [--json-out <path>]
+#
+# Defaults:
+#   --scan: scans CWD-level `.aris/traces/`, `paper/`, `PAPER_PLAN.md`,
+#           `NARRATIVE_REPORT.md`, `references.bib` if they exist.
+#   --json-out: <wiki_root>/.wiki-coverage-report.json
+#
+# Exit codes:
+#   0  Diagnostic ran. Any coverage gap is reported but not blocking.
+#   2  Bad arguments / wiki_root not found.
+#
+# Note: exit 0 regardless of coverage outcome — this is NOT a gate.
+
+set -uo pipefail
+
+WIKI_ROOT=""
+JSON_OUT=""
+SCAN_PATHS=()
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --scan)     SCAN_PATHS+=("${2:?--scan requires a path}"); shift 2 ;;
+        --json-out) JSON_OUT="${2:?--json-out requires a path}"; shift 2 ;;
+        -h|--help)  sed -n '2,22p' "$0" | sed 's/^# \?//'; exit 0 ;;
+        --*)        echo "unknown option: $1" >&2; exit 2 ;;
+        *)
+            if [[ -z "$WIKI_ROOT" ]]; then WIKI_ROOT="$1"
+            else echo "unexpected positional: $1" >&2; exit 2; fi
+            shift ;;
+    esac
+done
+
+[[ -n "$WIKI_ROOT" ]] || { echo "usage: $0 <wiki_root> [--scan <path> ...] [--json-out <path>]" >&2; exit 2; }
+[[ -d "$WIKI_ROOT" ]] || { echo "wiki_root not found: $WIKI_ROOT" >&2; exit 2; }
+WIKI_ROOT="$(cd "$WIKI_ROOT" && pwd)"
+
+# Default scan set: obvious places where arxiv IDs show up
+if [[ ${#SCAN_PATHS[@]} -eq 0 ]]; then
+    for p in .aris/traces paper PAPER_PLAN.md NARRATIVE_REPORT.md references.bib; do
+        [[ -e "$p" ]] && SCAN_PATHS+=("$p")
+    done
+fi
+
+[[ -n "$JSON_OUT" ]] || JSON_OUT="$WIKI_ROOT/.wiki-coverage-report.json"
+
+# Regex: 4-digit year + . + 4-5 digits + optional vN (modern arXiv) OR
+#        category(.subclass)?/Ndigits (legacy, e.g. cs/0601001, cs.LG/0703124)
+ARXIV_RE='\b(arXiv:|arxiv:|abs/)?([0-9]{4}\.[0-9]{4,5}(v[0-9]+)?|[a-z\-]+(\.[A-Z]{2})?\/[0-9]{7}(v[0-9]+)?)\b'
+
+# Collect referenced arxiv ids from scan set
+REFERENCED=$(mktemp)
+trap 'rm -f "$REFERENCED" "$INGESTED" "$MISSING"' EXIT
+
+# bash 3.2: empty-array "${ARR[@]}" trips `set -u`; SCAN_PATHS is empty when no
+# scan target exists in the invoking directory — the report should just be empty.
+{
+    if [[ ${#SCAN_PATHS[@]} -gt 0 ]]; then
+        for path in "${SCAN_PATHS[@]}"; do
+            if [[ -e "$path" ]]; then
+                # grep recursively for files, flat for directories; suppress "is a directory"
+                grep -rohE "$ARXIV_RE" "$path" 2>/dev/null || true
+            fi
+        done
+    fi
+} \
+    | sed -E 's#^(arXiv:|arxiv:|abs/)##; s/v[0-9]+$//' \
+    | grep -v '^$' \
+    | sort -u > "$REFERENCED"
+
+# Collect ingested ids from wiki frontmatter.
+# Use POSIX [[:space:]] (BSD sed on macOS does not understand \s).
+INGESTED=$(mktemp)
+if [[ -d "$WIKI_ROOT/papers" ]]; then
+    grep -hoE 'arxiv:[[:space:]]*"?[^"[:space:]]+' "$WIKI_ROOT/papers"/*.md 2>/dev/null \
+        | sed -E 's/^arxiv:[[:space:]]*"?//; s/"$//; s/v[0-9]+$//' \
+        | grep -v '^null$' \
+        | grep -v '^$' \
+        | sort -u > "$INGESTED"
+else
+    > "$INGESTED"
+fi
+
+# Missing = referenced but not ingested
+MISSING=$(mktemp)
+comm -23 "$REFERENCED" "$INGESTED" > "$MISSING"
+
+REF_COUNT=$(wc -l < "$REFERENCED" | tr -d ' ')
+ING_COUNT=$(wc -l < "$INGESTED" | tr -d ' ')
+MISS_COUNT=$(wc -l < "$MISSING" | tr -d ' ')
+
+# Write JSON report
+mkdir -p "$(dirname "$JSON_OUT")"
+{
+    echo "{"
+    echo "  \"tool\": \"verify_wiki_coverage.sh\","
+    echo "  \"wiki_root\": \"$WIKI_ROOT\","
+    echo "  \"scanned_paths\": ["
+    if [[ ${#SCAN_PATHS[@]} -gt 0 ]]; then
+        printf '    "%s"' "${SCAN_PATHS[0]}"
+        for ((i=1; i<${#SCAN_PATHS[@]}; i++)); do printf ',\n    "%s"' "${SCAN_PATHS[$i]}"; done
+        echo ""
+    fi
+    echo "  ],"
+    echo "  \"generated_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\","
+    echo "  \"referenced_arxiv_ids\": $REF_COUNT,"
+    echo "  \"ingested_arxiv_ids\": $ING_COUNT,"
+    echo "  \"missing_from_wiki\": $MISS_COUNT,"
+    echo "  \"diagnostic_only\": true,"
+    echo "  \"missing_ids\": ["
+    if [[ "$MISS_COUNT" -gt 0 ]]; then
+        first=1
+        while read -r id; do
+            if [[ "$first" -eq 1 ]]; then
+                printf '    "%s"' "$id"
+                first=0
+            else
+                printf ',\n    "%s"' "$id"
+            fi
+        done < "$MISSING"
+        echo ""
+    fi
+    echo "  ]"
+    echo "}"
+} > "$JSON_OUT"
+
+# Human-readable summary
+echo "" >&2
+echo "Research wiki coverage (diagnostic — not blocking)" >&2
+echo "  wiki:       $WIKI_ROOT" >&2
+echo "  scanned:    ${SCAN_PATHS[*]:-<none>}" >&2
+echo "  referenced: $REF_COUNT arxiv id(s)" >&2
+echo "  ingested:   $ING_COUNT arxiv id(s)" >&2
+echo "  missing:    $MISS_COUNT" >&2
+echo "  report:     $JSON_OUT" >&2
+echo "" >&2
+
+if [[ "$MISS_COUNT" -gt 0 ]]; then
+    echo "Missing from wiki (first 20):" >&2
+    head -20 "$MISSING" | sed 's/^/    /' >&2
+    [[ "$MISS_COUNT" -gt 20 ]] && echo "    ... ($((MISS_COUNT-20)) more)" >&2
+    echo "" >&2
+    # Build comma-joined list up to 20 ids for backfill hint
+    HINT_IDS=$(head -20 "$MISSING" | paste -sd, -)
+    # Resolve helper path the same way the skills do (per
+    # skills/shared-references/wiki-helper-resolution.md)
+    HINT_SCRIPT=".aris/tools/research_wiki.py"
+    [[ -f "$HINT_SCRIPT" ]] || HINT_SCRIPT="tools/research_wiki.py"
+    [[ -f "$HINT_SCRIPT" ]] || { [[ -n "${ARIS_REPO:-}" ]] && HINT_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
+    # Layer 4: global pointer file written by the installer/updater (#366).
+    if [[ -z "${ARIS_REPO:-}" && ! -f "$HINT_SCRIPT" && -f "$HOME/.aris/repo" ]]; then
+        ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
+        [[ -n "$ARIS_REPO" ]] && HINT_SCRIPT="$ARIS_REPO/tools/research_wiki.py"
+    fi
+    [[ -f "$HINT_SCRIPT" ]] || HINT_SCRIPT="<resolve-via-shared-ref>/research_wiki.py"
+    echo "Backfill suggestion:" >&2
+    echo "    python3 \"$HINT_SCRIPT\" sync $WIKI_ROOT --arxiv-ids $HINT_IDS" >&2
+    [[ "$MISS_COUNT" -gt 20 ]] && echo "    (or --from-file to pass the full list)" >&2
+    echo "" >&2
+fi
+
+# Always exit 0 — this is a diagnostic, not a gate.
+exit 0

package/tools/watchdog.py

@@ -0,0 +1,485 @@
+#!/usr/bin/env python3
+"""
+watchdog.py — Server-side unified monitoring daemon for ARIS.
+
+One process per server, monitors all registered tasks (training / download / loop).
+Outputs per-task status JSON + aggregated summary.txt for low-frequency polling.
+
+Usage:
+    # Start the daemon (runs in foreground, use tmux/screen to persist)
+    python3 watchdog.py [--base-dir /tmp/aris-watchdog] [--interval 60]
+
+    # Register a training task
+    python3 watchdog.py --register '{"name":"exp01","type":"training","session":"exp01","session_type":"screen","gpus":[0,1,2,3]}'
+
+    # Register a download task
+    python3 watchdog.py --register '{"name":"dl01","type":"download","session":"dl01","session_type":"tmux","target_path":"/path/to/file"}'
+
+    # Unregister a task
+    python3 watchdog.py --unregister exp01
+
+    # Check current summary
+    python3 watchdog.py --status
+
+Directory structure:
+    /tmp/aris-watchdog/
+    ├── watchdog.pid
+    ├── tasks.json          # [{name, type, session, session_type, ...}, ...]
+    ├── alerts.log          # anomaly log (DEAD/STALLED/IDLE) for cross-session recovery
+    └── status/
+        ├── <task-name>.json   # per-task status
+        └── summary.txt        # one-line-per-task summary for CronCreate polling
+"""
+
+import argparse
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+DEFAULT_BASE = "/tmp/aris-watchdog"
+DEFAULT_INTERVAL = 60
+SLOW_SPEED_THRESHOLD = 1 * 1024 * 1024  # 1 MB/s
+GPU_IDLE_THRESHOLD = 5  # percent
+
+
+def get_paths(base_dir):
+    base = Path(base_dir)
+    return {
+        "base": base,
+        "pid": base / "watchdog.pid",
+        "tasks": base / "tasks.json",
+        "status": base / "status",
+        "alerts": base / "alerts.log",
+    }
+
+
+# ── Task registration ────────────────────────────────────────────
+
+
+def register_task(base_dir, task_json):
+    paths = get_paths(base_dir)
+    paths["base"].mkdir(parents=True, exist_ok=True)
+    paths["status"].mkdir(parents=True, exist_ok=True)
+
+    task = json.loads(task_json)
+    missing = {"name", "type"} - set(task.keys())
+    if missing:
+        print(f"error: missing required fields: {missing}", file=sys.stderr)
+        sys.exit(1)
+
+    ttype = task["type"]
+    if ttype not in ("training", "download", "loop"):
+        print(f"error: type must be 'training', 'download', or 'loop', got '{ttype}'", file=sys.stderr)
+        sys.exit(1)
+    if ttype in ("training", "download") and "session" not in task:
+        print(f"error: {ttype} task requires 'session'", file=sys.stderr)
+        sys.exit(1)
+    if ttype == "loop" and ("state_file" not in task or "stale_after_seconds" not in task):
+        print("error: loop task requires 'state_file' and 'stale_after_seconds'", file=sys.stderr)
+        sys.exit(1)
+
+    if ttype == "loop":
+        try:
+            if int(task["stale_after_seconds"]) <= 0:
+                raise ValueError
+        except (ValueError, TypeError):
+            print("error: loop 'stale_after_seconds' must be a positive integer (seconds)", file=sys.stderr)
+            sys.exit(1)
+        # Absolutize WITHOUT resolving symlinks: a loop may update its state file via
+        # atomic os.replace, which swaps a symlink for a new file; we must keep watching
+        # the registered path, not its resolve()-time target. (os is imported at module top.)
+        task["state_file"] = os.path.abspath(os.path.expanduser(task["state_file"]))
+    elif "session_type" not in task:
+        # Default session_type for session-backed tasks: fallback to screen
+        task["session_type"] = "screen"
+
+    tasks = []
+    if paths["tasks"].exists():
+        try:
+            tasks = json.loads(paths["tasks"].read_text())
+        except (json.JSONDecodeError, OSError):
+            tasks = []
+
+    # Deduplicate: replace existing task with same name
+    tasks = [t for t in tasks if t["name"] != task["name"]]
+    task["registered_at"] = time.strftime("%Y-%m-%dT%H:%M:%S")
+    task["registered_epoch"] = time.time()  # tz-free grace anchor (loop PENDING→MISSING)
+    tasks.append(task)
+
+    paths["tasks"].write_text(json.dumps(tasks, indent=2))
+    detail = f"stale_after={task['stale_after_seconds']}s" if ttype == "loop" else task["session_type"]
+    print(f"registered: {task['name']} ({ttype}, {detail})")
+
+
+def unregister_task(base_dir, name):
+    paths = get_paths(base_dir)
+    if not paths["tasks"].exists():
+        print(f"no tasks file found")
+        return
+    try:
+        tasks = json.loads(paths["tasks"].read_text())
+    except (json.JSONDecodeError, OSError):
+        return
+    tasks = [t for t in tasks if t["name"] != name]
+    paths["tasks"].write_text(json.dumps(tasks, indent=2))
+    status_file = paths["status"] / f"{name}.json"
+    if status_file.exists():
+        status_file.unlink()
+    print(f"unregistered: {name}")
+
+
+# ── Session checks (tmux + screen) ──────────────────────────────
+
+
+def session_alive(session_name, session_type="screen"):
+    """Check if a tmux or screen session is alive."""
+    if session_type == "tmux":
+        r = subprocess.run(
+            ["tmux", "has-session", "-t", session_name],
+            capture_output=True,
+        )
+        return r.returncode == 0
+    else:  # screen
+        r = subprocess.run(
+            ["screen", "-list"], capture_output=True, text=True,
+        )
+        return session_name in r.stdout
+
+
+# ── GPU checks ───────────────────────────────────────────────────
+
+
+def get_gpu_util():
+    """Return list of GPU utilization percentages, e.g. [85, 92, 0, ...]"""
+    try:
+        r = subprocess.run(
+            ["nvidia-smi", "--query-gpu=utilization.gpu", "--format=csv,noheader,nounits"],
+            capture_output=True, text=True, timeout=10,
+        )
+        return [int(x.strip()) for x in r.stdout.strip().split("\n") if x.strip()]
+    except Exception:
+        return []
+
+
+# ── File size checks ─────────────────────────────────────────────
+
+
+def get_path_size(path):
+    """Get size of a file or directory in bytes."""
+    try:
+        r = subprocess.run(
+            ["du", "-sb", path], capture_output=True, text=True, timeout=30,
+        )
+        return int(r.stdout.split()[0])
+    except Exception:
+        return 0
+
+
+# ── Task checking logic ─────────────────────────────────────────
+
+
+def check_download(task, status_dir, interval):
+    name = task["name"]
+    session = task["session"]
+    session_type = task.get("session_type", "screen")
+    target = task.get("target_path", "")
+    status_file = status_dir / f"{name}.json"
+    now = time.strftime("%Y-%m-%dT%H:%M:%S")
+
+    if not session_alive(session, session_type):
+        return write_status(status_file, {
+            "status": "DEAD", "task": name, "type": "download",
+            "msg": f"{session_type} session gone", "ts": now,
+        })
+
+    if not target:
+        return write_status(status_file, {
+            "status": "OK", "task": name, "type": "download",
+            "msg": "alive, no target_path to check size", "ts": now,
+        })
+
+    current_size = get_path_size(target)
+
+    # Read previous size for delta
+    prev_size = 0
+    if status_file.exists():
+        try:
+            prev = json.loads(status_file.read_text())
+            prev_size = prev.get("size", 0)
+        except Exception:
+            pass
+
+    if current_size == prev_size and current_size > 0:
+        return write_status(status_file, {
+            "status": "STALLED", "task": name, "type": "download",
+            "size": current_size, "msg": "no size growth", "ts": now,
+        })
+
+    speed = (current_size - prev_size) / max(interval, 1)
+
+    if 0 < speed < SLOW_SPEED_THRESHOLD:
+        return write_status(status_file, {
+            "status": "SLOW", "task": name, "type": "download",
+            "size": current_size, "speed_mbps": round(speed / 1024 / 1024, 2),
+            "ts": now,
+        })
+
+    return write_status(status_file, {
+        "status": "OK", "task": name, "type": "download",
+        "size": current_size, "speed_mbps": round(speed / 1024 / 1024, 2),
+        "ts": now,
+    })
+
+
+def check_training(task, status_dir):
+    name = task["name"]
+    session = task["session"]
+    session_type = task.get("session_type", "screen")
+    status_file = status_dir / f"{name}.json"
+    now = time.strftime("%Y-%m-%dT%H:%M:%S")
+
+    if not session_alive(session, session_type):
+        return write_status(status_file, {
+            "status": "DEAD", "task": name, "type": "training",
+            "msg": f"{session_type} session gone", "ts": now,
+        })
+
+    gpu_utils = get_gpu_util()
+
+    # Check specified GPUs for activity
+    gpus = task.get("gpus", [])
+    if gpus and gpu_utils:
+        used_utils = [gpu_utils[i] for i in gpus if i < len(gpu_utils)]
+        if used_utils and all(u < GPU_IDLE_THRESHOLD for u in used_utils):
+            return write_status(status_file, {
+                "status": "IDLE", "task": name, "type": "training",
+                "gpu_util": {str(i): gpu_utils[i] for i in gpus if i < len(gpu_utils)},
+                "msg": f"GPUs idle (<{GPU_IDLE_THRESHOLD}%)", "ts": now,
+            })
+
+    return write_status(status_file, {
+        "status": "OK", "task": name, "type": "training",
+        "gpu_util": gpu_utils, "ts": now,
+    })
+
+
+# ── Loop-liveness check (detect-only) ───────────────────────────
+
+
+LOOP_COMPLETED_STATUSES = {"completed", "done", "finished"}
+
+
+def _loop_is_completed(state):
+    """True if the watched JSON shows the loop finished (silence is then expected, not a stall)."""
+    if not isinstance(state, dict):
+        return False
+    if str(state.get("status", "")).lower() in LOOP_COMPLETED_STATUSES:
+        return True
+    phases = state.get("phases")  # run_state.py shape: all phases terminal ⇒ done
+    if isinstance(phases, list) and phases and all(
+        isinstance(p, dict) and p.get("status") in ("accepted", "skipped") for p in phases
+    ):
+        return True
+    return False
+
+
+def check_loop(task, status_dir):
+    """Loop-liveness via state-file mtime, DETECT-ONLY.
+
+    Liveness = freshness of the file the loop rewrites/touches each iteration, judged against the
+    loop's OWN declared `stale_after_seconds` (NOT the daemon interval). This function only reads
+    files and writes a status; it NEVER restarts the loop, spawns a process, or invokes a skill —
+    a STALE loop is surfaced via alerts.log + summary.txt for a human/cron, honoring
+    external-cadence.md's fence on verdict-bearing loops. JSON is read best-effort only to
+    recognize a COMPLETED loop; an unparseable file never causes STALE on its own.
+    """
+    name = task["name"]
+    state_file = Path(task.get("state_file", ""))
+    stale_after = int(task.get("stale_after_seconds", 21600))
+    status_file = status_dir / f"{name}.json"
+    now_str = time.strftime("%Y-%m-%dT%H:%M:%S")
+
+    if not state_file.exists():
+        # Fail-safe: a missing registered_epoch ⇒ epoch 0 ⇒ MISSING, never infinite grace.
+        grace = time.time() - float(task.get("registered_epoch", 0.0))
+        if grace <= stale_after:
+            return write_status(status_file, {
+                "status": "PENDING", "task": name, "type": "loop",
+                "msg": "state file not present yet", "ts": now_str})
+        return write_status(status_file, {
+            "status": "MISSING", "task": name, "type": "loop",
+            "msg": f"state file absent {int(grace)}s after register (path typo?)", "ts": now_str})
+
+    try:
+        state = json.loads(state_file.read_text())
+        if _loop_is_completed(state):
+            return write_status(status_file, {
+                "status": "COMPLETED", "task": name, "type": "loop",
+                "msg": "loop reports completion", "ts": now_str})
+    except (json.JSONDecodeError, OSError):
+        pass  # not a terminal state we can read → fall through to mtime liveness
+
+    age = int(time.time() - state_file.stat().st_mtime)
+    if age > stale_after:
+        return write_status(status_file, {
+            "status": "STALE", "task": name, "type": "loop",
+            "age_s": age, "stale_after": stale_after,
+            "msg": f"no state write in {age}s (> {stale_after}s)", "ts": now_str})
+    return write_status(status_file, {
+        "status": "OK", "task": name, "type": "loop",
+        "age_s": age, "stale_after": stale_after, "ts": now_str})
+
+
+# ── Status output ────────────────────────────────────────────────
+
+
+def write_status(path, data):
+    """Write per-task status and append to alerts.log on anomalies."""
+    path.write_text(json.dumps(data))
+
+    status = data.get("status", "OK")
+    if status in ("DEAD", "STALLED", "STALE", "MISSING", "IDLE", "ERROR"):
+        alert_file = path.parent.parent / "alerts.log"
+        ts = data.get("ts", time.strftime("%Y-%m-%dT%H:%M:%S"))
+        task = data.get("task", "?")
+        msg = data.get("msg", "")
+        alert_line = f"[{ts}] {task}: {status} — {msg}\n"
+        with open(alert_file, "a") as f:
+            f.write(alert_line)
+
+    return data
+
+
+def write_summary(status_dir):
+    """Aggregate all task statuses into summary.txt (one line per task)."""
+    lines = []
+    for f in sorted(status_dir.glob("*.json")):
+        try:
+            d = json.loads(f.read_text())
+            name = d.get("task", f.stem)
+            status = d.get("status", "?")
+            typ = d.get("type", "?")
+            extra = ""
+            if status == "SLOW":
+                extra = f" speed={d.get('speed_mbps', '?')}MB/s"
+            elif status == "IDLE":
+                extra = f" gpu={d.get('gpu_util', '?')}"
+            elif status == "DEAD":
+                extra = f" {d.get('msg', '')}"
+            elif status in ("STALE", "MISSING"):
+                extra = f" {d.get('msg', '')}"
+            elif status == "PENDING":
+                extra = " (awaiting first state write)"
+            elif status == "COMPLETED":
+                extra = " ✓"
+            lines.append(f"{name}({typ}): {status}{extra}")
+        except Exception:
+            continue
+
+    summary = "\n".join(lines) if lines else "no tasks"
+    (status_dir / "summary.txt").write_text(summary)
+    return summary
+
+
+# ── Main loop ────────────────────────────────────────────────────
+
+
+def run_watchdog(base_dir, interval):
+    paths = get_paths(base_dir)
+    paths["base"].mkdir(parents=True, exist_ok=True)
+    paths["status"].mkdir(parents=True, exist_ok=True)
+
+    # Write PID for liveness checks
+    paths["pid"].write_text(str(os.getpid()))
+
+    def handle_signal(sig, frame):
+        paths["pid"].unlink(missing_ok=True)
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+
+    print(f"watchdog started (pid={os.getpid()}, base={base_dir}, interval={interval}s)")
+
+    while True:
+        if not paths["tasks"].exists():
+            time.sleep(interval)
+            continue
+
+        try:
+            tasks = json.loads(paths["tasks"].read_text())
+        except (json.JSONDecodeError, OSError):
+            time.sleep(interval)
+            continue
+
+        for task in tasks:
+            try:
+                if task["type"] == "download":
+                    check_download(task, paths["status"], interval)
+                elif task["type"] == "training":
+                    check_training(task, paths["status"])
+                elif task["type"] == "loop":
+                    check_loop(task, paths["status"])
+            except Exception as e:
+                write_status(
+                    paths["status"] / f"{task['name']}.json",
+                    {"status": "ERROR", "task": task["name"], "msg": str(e),
+                     "ts": time.strftime("%Y-%m-%dT%H:%M:%S")},
+                )
+
+        write_summary(paths["status"])
+        time.sleep(interval)
+
+
+# ── CLI ──────────────────────────────────────────────────────────
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ARIS Watchdog — server-side task monitoring daemon",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Start daemon
+  python3 watchdog.py
+
+  # Register a training task (screen session)
+  python3 watchdog.py --register '{"name":"exp01","type":"training","session":"exp01","gpus":[0,1]}'
+
+  # Register a download task (tmux session)
+  python3 watchdog.py --register '{"name":"dl01","type":"download","session":"dl01","session_type":"tmux","target_path":"/data/imagenet"}'
+
+  # Check summary
+  python3 watchdog.py --status
+        """,
+    )
+    parser.add_argument("--base-dir", default=DEFAULT_BASE,
+                        help=f"Working directory (default: {DEFAULT_BASE})")
+    parser.add_argument("--interval", type=int, default=DEFAULT_INTERVAL,
+                        help=f"Check interval in seconds (default: {DEFAULT_INTERVAL})")
+    parser.add_argument("--register", metavar="JSON",
+                        help="Register a task (JSON with name, type, session)")
+    parser.add_argument("--unregister", metavar="NAME",
+                        help="Unregister a task by name")
+    parser.add_argument("--status", action="store_true",
+                        help="Print current summary and exit")
+    args = parser.parse_args()
+
+    if args.register:
+        register_task(args.base_dir, args.register)
+    elif args.unregister:
+        unregister_task(args.base_dir, args.unregister)
+    elif args.status:
+        paths = get_paths(args.base_dir)
+        summary = paths["status"] / "summary.txt"
+        print(summary.read_text() if summary.exists() else "no status")
+    else:
+        run_watchdog(args.base_dir, args.interval)
+
+
+if __name__ == "__main__":
+    main()