@matt82198/aesop 0.1.0-beta.5 → 0.1.0

package/tools/healthcheck.py

@@ -24,6 +24,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from time import time
 
+try:
+    from common import check_heartbeat_staleness
+except ImportError:
+    from tools.common import check_heartbeat_staleness
+
 # Import UI config for state path resolution
 UI_DIR = Path(__file__).parent.parent / "ui"
 if str(UI_DIR) not in sys.path:
@@ -94,31 +99,29 @@ def _check_heartbeat(name, heartbeat_file, threshold=300):
     Returns:
         tuple (severity, message) or None if all OK
     """
-    if not heartbeat_file.exists():
-        return ("YELLOW", f"no {name} heartbeat file")
+    is_stale, age_seconds, info = check_heartbeat_staleness(heartbeat_file, threshold)
 
-    try:
-        content = heartbeat_file.read_text(encoding="utf-8").strip()
-        if not content:
-            return ("YELLOW", f"{name} heartbeat empty")
+    if not is_stale:
+        return None
 
-        try:
-            timestamp = int(content)
-        except ValueError:
+    # Stale: determine severity and message
+    if age_seconds == 0:
+        # File missing/empty/unreadable - use generic message
+        if "missing" in info.lower():
+            return ("YELLOW", f"no {name} heartbeat file")
+        elif "empty" in info.lower():
+            return ("YELLOW", f"{name} heartbeat empty")
+        else:
             return ("YELLOW", f"{name} heartbeat unparseable")
 
-        age_seconds = int(time()) - timestamp
-        if age_seconds >= threshold * 2:
-            # Watchdog dead while orchestrator might be active
-            if name == "watchdog" and age_seconds >= 600:
-                return ("RED", f"watchdog dead ({age_seconds}s)")
-            return ("YELLOW", f"{name} stale ({age_seconds}s > {threshold}s threshold)")
-        elif age_seconds > threshold:
-            return ("YELLOW", f"{name} stale ({age_seconds}s)")
-
-        return None
-    except Exception as e:
-        return ("YELLOW", f"{name} heartbeat read error: {e}")
+    # File exists but is stale
+    if age_seconds >= threshold * 2:
+        # Watchdog dead while orchestrator might be active
+        if name == "watchdog" and age_seconds >= 600:
+            return ("RED", f"watchdog dead ({age_seconds}s)")
+        return ("YELLOW", f"{name} stale ({age_seconds}s > {threshold}s threshold)")
+    else:
+        return ("YELLOW", f"{name} stale ({age_seconds}s)")
 
 
 def _check_alerts(alerts_file):

package/tools/heartbeat.py

@@ -20,13 +20,10 @@ import time
 from pathlib import Path
 import argparse
 
-
-def get_state_dir():
-    """Resolve state directory from env var or current working directory."""
-    if os.environ.get("AESOP_STATE_ROOT"):
-        return Path(os.environ["AESOP_STATE_ROOT"])
-    # Default to ./state (relative to cwd)
-    return Path.cwd() / "state"
+try:
+    from common import get_state_dir
+except ImportError:
+    from tools.common import get_state_dir
 
 
 def beat(name, status=None, state_dir=None, brain=False):

package/tools/metrics_gate.py

@@ -54,9 +54,15 @@ class MetricsGate:
     VERIFICATION_PATTERN = re.compile(r'<!--\s*metrics-verified:\s*[^-]+\s*-->')
 
     def __init__(self, diff_range: str = "origin/main...HEAD"):
-        """Initialize with a git diff range."""
+        """Initialize with a git diff range.
+
+        The gate scans the git repository at the current working directory
+        (like git itself), not the directory the script happens to live in.
+        In CI it is invoked from the repo root, so behaviour is unchanged;
+        this also makes the gate exercisable against any repo under test.
+        """
         self.diff_range = diff_range
-        self.repo_root = Path(__file__).resolve().parent.parent
+        self.repo_root = Path.cwd()
 
     def get_diff_lines(self) -> List[Tuple[str, str]]:
         """Get lines added in diff. Returns list of (file, line_content)."""

package/tools/orchestrator_status.py

@@ -15,15 +15,10 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-
-def get_state_dir():
-    """Get state directory from env or fallback to AESOP_ROOT/state."""
-    state_root = os.getenv("AESOP_STATE_ROOT")
-    if state_root:
-        return Path(state_root)
-    
-    aesop_root = os.getenv("AESOP_ROOT", str(Path.home() / "aesop"))
-    return Path(aesop_root) / "state"
+try:
+    from common import get_state_dir
+except ImportError:
+    from tools.common import get_state_dir
 
 
 def set_status(activity, phase, id=None, role=None):

package/tools/reconcile.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""
+reconcile.py — drift detection between STATE.md (git) and state_store (SQLite).
+
+## Why this exists
+
+Critique: "SQLite state_store and git-committed STATE.md drift with NO reconcile
+logic." This tool is the conservative first step: detect + report drift by
+default; fix it only with an explicit ``--resolve``.
+
+## What was actually investigated (read STATE.md + state_store/*.py end to end)
+
+STATE.md (see ensure_state.py's own template) is unstructured orchestrator
+narrative: Intent / locked decisions / current Phase / NEXT STEPS, written and
+owned by the orchestrator (single-writer, per this project's CLAUDE.md Cardinal
+Rule #7 — "Single-writer: MEMORY.md (keeper), STATE.md (orchestrator)").
+
+state_store/ (store.py + api.py + projections.py) is an event-sourced SQLite
+log. Today it registers exactly ONE projection: ``tracker`` — a UI Kanban
+board of backlog items (``id``/``title``/``lane``/``status``/``tags``/
+``pr_link``/``completed_at``). That projection is a DIFFERENT domain from
+STATE.md: it was one-time-migrated from AUDIT-BACKLOG.md
+(``ui/collectors.py:migrate_tracker_from_backlog``), not from STATE.md, and is
+independently mutated via the UI CRUD endpoints thereafter. There is no
+shared id, key, or semantic concept between STATE.md's prose and a tracker
+item. Reconciling STATE.md against ``tracker`` would mean inventing a mapping
+that does not exist in the codebase's actual design — the task instructions
+explicitly warn against exactly that ("do not invent overlap").
+
+**Honest finding: STATE.md and state_store are almost entirely DISJOINT.**
+
+The ONE field that genuinely is meant to be "the same fact, told twice" is the
+orchestrator's **current phase/wave identifier** — STATE.md carries it today
+in a structured, reliably-parseable heading (``## Phase: `wave-N-name` ``);
+state_store has no field for it yet (it predates the "additive prototype... a
+later dual-read cutover" state_store/CLAUDE.md describes). Rather than
+pretend a comparable field exists where none does, this tool defines that
+field explicitly — a ``meta`` event stream, ``phase_set`` events, payload
+``{"phase": <str>}`` — read directly off the generic ``EventStore`` (no
+change to state_store/ itself; any stream name is legal there). Until
+something else populates that stream, real runs will simply show "state_store
+has no phase recorded" every time, which is itself an honest, useful signal:
+it names precisely the gap the critique is pointing at, rather than
+manufacturing a false "in sync".
+
+## Authority
+
+- ``phase`` is git-authoritative: STATE.md is the durable, human-reviewed,
+  single-writer checkpoint (Cardinal Rule #7); state_store's copy is a mirror
+  for read-side consumers (dashboards, MCP, etc.) that would rather not parse
+  markdown. ``--resolve`` therefore only ever WRITES to state_store (a new
+  ``phase_set`` event) and NEVER writes to STATE.md — the tool must not
+  become a second writer of the orchestrator's single-writer file.
+- The field registry (``FIELDS``) and ``decide_resolution`` are generic and
+  support a `state_store`-authoritative field the same way, for when
+  state_store gains its own independently event-derived facts (e.g. real
+  wave-tagged item counts) that STATE.md would want mirrored back — see
+  ``test_reconcile.py``'s ``DecideResolutionTest`` for that direction
+  exercised in isolation, since no current field actually uses it.
+
+## Usage
+
+    python tools/reconcile.py --state-md STATE.md --db state/events.db
+    python tools/reconcile.py --state-md STATE.md --db state/events.db --resolve
+    python tools/reconcile.py --state-md STATE.md --db state/events.db --json
+
+Exit codes: 0 = no drift (or drift cleanly resolved), 1 = drift detected and
+NOT resolved (report mode), 2 = usage/file error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from state_store.store import EventStore  # noqa: E402
+
+PHASE_RE = re.compile(r"^##\s*Phase:\s*`([^`]+)`", re.MULTILINE)
+
+META_STREAM = "meta"
+PHASE_EVENT_TYPE = "phase_set"
+
+
+# ---------------------------------------------------------------------------
+# Readers (read-only; never create/mutate anything)
+# ---------------------------------------------------------------------------
+
+def read_git_phase(state_md_path: str) -> str | None:
+    """Parse the current phase identifier out of STATE.md's ``## Phase:`` heading.
+
+    Returns None if the file has no such heading (or is missing entirely —
+    callers that need a hard error on a missing file should stat() first).
+    """
+    path = Path(state_md_path)
+    if not path.exists():
+        return None
+    content = path.read_text(encoding="utf-8")
+    match = PHASE_RE.search(content)
+    return match.group(1) if match else None
+
+
+def read_store_phase(db_path: str) -> str | None:
+    """Read the most recent ``phase_set`` event's ``phase`` payload from state_store.
+
+    Deliberately avoids ever constructing an EventStore against a
+    non-existent db_path in report mode: EventStore.__init__ creates the
+    sqlite file + tables as a side effect of merely connecting, which would
+    make a read-only "detect" invocation leave a footprint on disk. If the
+    file does not exist yet, there is by definition no phase recorded there.
+    """
+    if not db_path or not os.path.exists(db_path):
+        return None
+    store = EventStore(db_path)
+    events = store.read(META_STREAM)
+    phase = None
+    for ev in events:
+        if ev.get("type") == PHASE_EVENT_TYPE:
+            payload = ev.get("payload") or {}
+            if "phase" in payload:
+                phase = payload["phase"]
+    return phase
+
+
+def write_store_phase(db_path: str, phase: str, actor: str = "reconcile") -> int:
+    """Append a phase_set event to state_store's meta stream. Returns new version.
+
+    This is the ONLY write path in this module, and it only ever targets
+    state_store (SQLite) — STATE.md (git) is never written by this tool.
+    """
+    store = EventStore(db_path)
+    return store.append(META_STREAM, PHASE_EVENT_TYPE, {"phase": phase}, actor)
+
+
+# ---------------------------------------------------------------------------
+# Field registry — generic so a future state_store-authoritative field can be
+# added without restructuring the detect/resolve flow.
+# ---------------------------------------------------------------------------
+
+FIELDS = {
+    "phase": {
+        "authority": "git",
+        "read_git": read_git_phase,
+        "read_store": read_store_phase,
+    },
+}
+
+
+def decide_resolution(git_value, store_value, authority: str):
+    """Pure decision: given both current values and which side is authoritative,
+    return (drift: bool, target: 'git'|'store'|None, value) where ``target`` is
+    which side WOULD need writing to clear the drift (None if no drift, or if
+    already in agreement).
+
+    ``authority`` must be 'git' or 'store'. This function performs no I/O —
+    it only decides; callers apply the write.
+    """
+    if authority not in ("git", "store"):
+        raise ValueError(f"unknown authority: {authority!r}")
+
+    drift = git_value != store_value
+    if not drift:
+        return (False, None, git_value)
+
+    if authority == "git":
+        return (True, "store", git_value)
+    return (True, "git", store_value)
+
+
+# ---------------------------------------------------------------------------
+# Detect / resolve over the whole registry
+# ---------------------------------------------------------------------------
+
+def detect_drift(state_md_path: str, db_path: str) -> dict:
+    """Read both sources for every registered field; report drift per field.
+
+    Read-only: never creates or mutates STATE.md or the state_store db.
+    """
+    results = []
+    any_drift = False
+    for name, spec in FIELDS.items():
+        git_value = spec["read_git"](state_md_path)
+        store_value = spec["read_store"](db_path)
+        drift, target, _value = decide_resolution(git_value, store_value, spec["authority"])
+        any_drift = any_drift or drift
+        results.append({
+            "field": name,
+            "authority": spec["authority"],
+            "git_value": git_value,
+            "store_value": store_value,
+            "drift": drift,
+            "fix_target": target,
+        })
+    return {"drift": any_drift, "fields": results}
+
+
+def resolve_drift(state_md_path: str, db_path: str) -> dict:
+    """Detect drift, then apply the authoritative value to the non-authoritative
+    side for every drifted field. Idempotent: fields already in agreement are
+    left untouched (no event appended). Only ever writes to state_store.
+
+    A field whose authority is 'git' but is drifted is fixed by writing to
+    state_store. A field whose authority is 'store' but is drifted would
+    require writing to STATE.md — this tool refuses to do that (STATE.md is
+    single-writer/orchestrator-owned) and instead reports it unresolved with
+    a clear reason, rather than silently corrupting the git checkpoint.
+    """
+    report = detect_drift(state_md_path, db_path)
+    for entry in report["fields"]:
+        if not entry["drift"]:
+            entry["action"] = "noop"
+            continue
+        if entry["fix_target"] == "store" and entry["field"] == "phase":
+            write_store_phase(db_path, entry["git_value"])
+            entry["action"] = "resolved"
+            entry["store_value"] = entry["git_value"]
+        elif entry["fix_target"] == "git":
+            entry["action"] = "refused"
+            entry["reason"] = "STATE.md is single-writer (orchestrator); reconcile.py never writes it"
+        else:
+            entry["action"] = "unsupported"
+    report["drift"] = any(e["drift"] and e.get("action") not in ("resolved",) for e in report["fields"])
+    return report
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _format_human(report: dict) -> str:
+    lines = []
+    for entry in report["fields"]:
+        status = "DRIFT" if entry["drift"] else "OK"
+        line = (
+            f"[{status}] {entry['field']} (authority={entry['authority']}): "
+            f"git={entry['git_value']!r} store={entry['store_value']!r}"
+        )
+        if "action" in entry:
+            line += f" action={entry['action']}"
+        lines.append(line)
+    lines.append("DRIFT DETECTED" if report["drift"] else "no drift")
+    return "\n".join(lines)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--state-md", default="STATE.md", help="Path to STATE.md (default: ./STATE.md)")
+    parser.add_argument("--db", default="state/events.db", help="Path to state_store SQLite db")
+    parser.add_argument("--resolve", action="store_true", help="Fix drift by writing the authoritative value to the non-authoritative side (opt-in; default is detect+report only)")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON instead of human text")
+    args = parser.parse_args(argv)
+
+    if not os.path.exists(args.state_md):
+        print(f"error: STATE.md not found at {args.state_md}", file=sys.stderr)
+        return 2
+
+    if args.resolve:
+        report = resolve_drift(args.state_md, args.db)
+    else:
+        report = detect_drift(args.state_md, args.db)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(_format_human(report))
+
+    return 1 if report["drift"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tools/rotate_logs.py

@@ -5,6 +5,11 @@ Rotates log files by moving the oldest content to an archive file when the origi
 exceeds configured thresholds (--max-lines or --max-bytes). Preserves newest lines
 in the original, ensures no data loss (archive + original == original content).
 
+Uses advisory file locking to serialize concurrent rotations, and detects/preserves
+external O_APPEND writes (from non-locking writers) that occur during the rotation
+window. This ensures atomicity: no lines are lost even when external processes
+append concurrently.
+
 Exit codes:
   0: Success (no rotation needed or rotation completed)
   1: Error (invalid args, I/O failure, etc.)
@@ -17,6 +22,17 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+# Platform-specific locking imports
+if sys.platform == 'win32':
+    import msvcrt
+    HAS_FCNTL = False
+else:
+    try:
+        import fcntl
+        HAS_FCNTL = True
+    except ImportError:
+        HAS_FCNTL = False
+
 
 def count_lines(filepath):
     """Count lines in a file."""
@@ -53,6 +69,34 @@ def write_lines(filepath, lines):
         raise IOError(f"Failed to write {filepath}: {e}")
 
 
+def acquire_lock(fd):
+    """Acquire exclusive lock on file descriptor (cross-platform)."""
+    if HAS_FCNTL:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        except (AttributeError, TypeError):
+            pass
+    elif sys.platform == 'win32':
+        try:
+            msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+        except (OSError, IOError):
+            pass  # Locking may not be supported on all filesystems
+
+
+def release_lock(fd):
+    """Release exclusive lock on file descriptor (cross-platform)."""
+    if HAS_FCNTL:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except (AttributeError, TypeError):
+            pass
+    elif sys.platform == 'win32':
+        try:
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        except (OSError, IOError):
+            pass
+
+
 def needs_rotation(filepath, max_lines, max_bytes):
     """Check if file exceeds any threshold."""
     current_lines = count_lines(filepath)
@@ -66,7 +110,21 @@ def needs_rotation(filepath, max_lines, max_bytes):
 
 
 def rotate_log(logfile, max_lines, max_bytes, archive_dir, check_only=False):
-    """Rotate log file by archiving oldest lines.
+    """Rotate log file by archiving oldest lines atomically.
+
+    Uses exclusive file locking to serialize rotations against other lock-takers.
+    However, this is an ADVISORY lock: it only protects against other processes
+    that voluntarily take the lock. External writers (e.g., shell scripts using >>
+    or tee -a) that do NOT take the lock are NOT protected by this mechanism.
+
+    To prevent data loss from non-locking O_APPEND writers:
+    - Lines appended between readlines() and truncate() are detected via file size
+      comparison and re-read after truncate+write to prevent loss.
+    - This guarantees atomicity: archive + original == original content.
+
+    NOTE: The advisory lock serializes rotations against each other, but race
+    conditions with non-locking O_APPEND writers remain possible. For complete
+    safety, all writers (including external processes) must cooperate on locking.
 
     Args:
         logfile: Path to log file to rotate.
@@ -104,69 +162,101 @@ def rotate_log(logfile, max_lines, max_bytes, archive_dir, check_only=False):
               file=sys.stderr)
         return 1
 
-    # Read all lines
+    # Perform rotation with exclusive lock to prevent concurrent write races
     try:
-        lines = read_lines(str(logfile))
-    except IOError as e:
-        print(f"ERROR: {e}", file=sys.stderr)
-        return 1
-
-    if not lines:
-        return 0
-
-    # Determine split point based on which threshold was exceeded
-    current_lines = len(lines)
-    current_bytes = sum(len(line.encode('utf-8')) for line in lines)
+        with open(str(logfile), 'r+') as f:
+            # Acquire exclusive lock to guard read-compute-write sequence
+            acquire_lock(f.fileno())
+            try:
+                # Read all lines while locked
+                lines = f.readlines()
+
+                if not lines:
+                    return 0
+
+                # Determine split point based on which threshold was exceeded
+                current_lines = len(lines)
+                current_bytes = sum(len(line.encode('utf-8')) for line in lines)
+
+                keep_count = current_lines // 2  # Default: keep ~half
+
+                # If max_lines exceeded, keep lines just under threshold
+                if max_lines and current_lines > max_lines:
+                    keep_count = min(keep_count, max_lines)
+
+                # If max_bytes exceeded, calculate how many lines fit under threshold
+                if max_bytes and current_bytes > max_bytes:
+                    cumulative_bytes = 0
+                    bytes_keep_count = 0
+                    # Count from newest (end) backward
+                    for i in range(len(lines) - 1, -1, -1):
+                        line_bytes = len(lines[i].encode('utf-8'))
+                        if cumulative_bytes + line_bytes <= max_bytes:
+                            cumulative_bytes += line_bytes
+                            bytes_keep_count += 1
+                        else:
+                            break
+                    # Use the more conservative count
+                    keep_count = min(keep_count, bytes_keep_count)
+
+                # Guard: ensure we keep at least 1 line, archive the rest
+                if keep_count <= 0:
+                    # If calculated keep_count is 0 or negative, keep at least 1 line
+                    keep_count = 1
+
+                # Split lines
+                archive_lines = lines[:-keep_count] if keep_count < len(lines) else []
+                remaining_lines = lines[-keep_count:] if keep_count > 0 else []
+
+                if not archive_lines:
+                    # Nothing to archive
+                    return 0
+
+                # Generate archive filename with UTC timestamp
+                utc_now = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+                archive_filename = f"{logfile.stem}.{utc_now}.log"
+                archive_file = archive_path / archive_filename
+
+                # Write archive file
+                try:
+                    write_lines(str(archive_file), archive_lines)
+                except IOError as e:
+                    print(f"ERROR: {e}", file=sys.stderr)
+                    return 1
+
+                # MITIGATION for external O_APPEND writers:
+                # Before truncating, check if the file has grown since we initially read it.
+                # If external (non-locking) O_APPEND writers added content while we were
+                # computing, re-read and preserve those appends.
+                original_line_count = len(lines)
+
+                # Rewind to start and re-count lines to detect external appends
+                f.seek(0)
+                current_line_count = sum(1 for _ in f)
+
+                if current_line_count > original_line_count:
+                    # External appends occurred! Re-read the appended lines
+                    lines_appended = current_line_count - original_line_count
+
+                    # Re-read from line position (start of appended lines)
+                    f.seek(0)
+                    all_current_lines = f.readlines()
+
+                    # Extract only the new lines (the appended ones)
+                    external_lines = all_current_lines[-lines_appended:]
+                    if external_lines:
+                        remaining_lines.extend(external_lines)
+
+                # Atomically truncate and write remaining lines back to original
+                # while still holding the lock
+                f.seek(0)
+                f.truncate()
+                f.writelines(remaining_lines)
+
+            finally:
+                # Release lock after all writes complete
+                release_lock(f.fileno())
 
-    keep_count = current_lines // 2  # Default: keep ~half
-
-    # If max_lines exceeded, keep lines just under threshold
-    if max_lines and current_lines > max_lines:
-        keep_count = min(keep_count, max_lines)
-
-    # If max_bytes exceeded, calculate how many lines fit under threshold
-    if max_bytes and current_bytes > max_bytes:
-        cumulative_bytes = 0
-        bytes_keep_count = 0
-        # Count from newest (end) backward
-        for i in range(len(lines) - 1, -1, -1):
-            line_bytes = len(lines[i].encode('utf-8'))
-            if cumulative_bytes + line_bytes <= max_bytes:
-                cumulative_bytes += line_bytes
-                bytes_keep_count += 1
-            else:
-                break
-        # Use the more conservative count
-        keep_count = min(keep_count, bytes_keep_count)
-
-    # Guard: ensure we keep at least 1 line, archive the rest
-    if keep_count <= 0:
-        # If calculated keep_count is 0 or negative, keep at least 1 line
-        keep_count = 1
-
-    # Split lines
-    archive_lines = lines[:-keep_count] if keep_count < len(lines) else []
-    remaining_lines = lines[-keep_count:] if keep_count > 0 else []
-
-    if not archive_lines:
-        # Nothing to archive
-        return 0
-
-    # Generate archive filename with UTC timestamp
-    utc_now = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
-    archive_filename = f"{logfile.stem}.{utc_now}.log"
-    archive_file = archive_path / archive_filename
-
-    # Write archive file
-    try:
-        write_lines(str(archive_file), archive_lines)
-    except IOError as e:
-        print(f"ERROR: {e}", file=sys.stderr)
-        return 1
-
-    # Write remaining lines back to original
-    try:
-        write_lines(str(logfile), remaining_lines)
     except IOError as e:
         print(f"ERROR: {e}", file=sys.stderr)
         return 1