feat(cli): --timeout wall-clock watchdog for --diff (#70 mitigation)

Claude-Session: https://claude.ai/code/session_0158oZrMt7GUUdyPq1ehvxom

Author: nikolay-e

QA.md

@@ -153,14 +153,13 @@ shadow:
 cd test-repos/<repo>
 git pull --ff-only
 # Hard-cap runtime. `--timeout` (true wall-clock bound, worker thread + watchdog,
-# fast-fails instead of hanging to OOM, #70, 3725f51b) lives ONLY on the
-# standalone Rust binary `diffctx/src/main.rs`. The **Python pipx wrapper does
-# NOT expose `--timeout` at all** — verified on the released `1.10.2`:
-# `diffctx --diff --help | grep timeout` → empty, and `grep -r timeout
-# src/diffctx/cli.py` → empty (the flag never crossed into the Python CLI). So
-# the external perl cap is MANDATORY for every pipx smoke regardless of release,
-# not just "until it ships" — the wrapper needs its own watchdog around the
-# pyo3 `compute_scored_state` call first. macOS has no `timeout`; use:
+# fast-fails instead of hanging to OOM, #70, 3725f51b) exists on the standalone
+# Rust binary AND — since the 2026-07-14 QA pass — on the Python CLI
+# (`_call_with_wall_clock_deadline` in `src/diffctx/main.py`, exit 124, daemon
+# worker + `os._exit` because a runaway pyo3 call cannot be cancelled). The
+# perl cap stays MANDATORY for pipx smokes until a release ≥1.12 ships that
+# commit (the released binary on PATH predates it); after that, `--timeout 200`
+# on the pipx binary replaces the perl wrapper. macOS has no `timeout`; use:
 perl -e 'alarm 200; exec @ARGV' /Users/nikolay/.local/bin/diffctx . --diff HEAD~1
 # (or, on the dev build, just pass `--timeout 200` — the watchdog bounds it.)
 ```

src/diffctx/cli.py

@@ -14,6 +14,8 @@
 DEFAULT_MAX_FILE_BYTES = 256 * 1024  # 256 KB
 _DEFAULT_ALPHA = 0.60
 _DEFAULT_TAU = 0.12
+# Mirrors DEFAULT_PIPELINE_TIMEOUT_SECONDS in diffctx/src/config/limits.rs.
+_DEFAULT_TIMEOUT = 300
 
 
 class _Unset:
@@ -68,6 +70,11 @@ def _validate_budget(budget: int | None) -> None:
         _exit_usage_error(f"--budget must be >= -1 (-1 = unlimited, 0 = changed code only), got {budget}")
 
 
+def _validate_timeout(timeout: int) -> None:
+    if timeout < 1:
+        _exit_usage_error(f"--timeout must be >= 1 second, got {timeout}")
+
+
 def _validate_alpha(alpha: float) -> None:
     if not (0 < alpha < 1):
         _exit_usage_error(f"--alpha must be between 0 and 1 (exclusive), got {alpha}")
@@ -241,6 +248,7 @@ class ParsedArgs:
     alpha: float = _DEFAULT_ALPHA
     tau: float = _DEFAULT_TAU
     scoring: str = "ego"
+    timeout: int = _DEFAULT_TIMEOUT
     full_diff: bool = False
     command: str | None = None
     graph: GraphArgs | None = None
@@ -299,6 +307,7 @@ class ParsedArgs:
   2  usage error (unknown flag or invalid value)
   3  environment error (git missing, not a repository, unknown revision)
   4  --diff produced no context (clean tree or empty range)
+  124  --diff exceeded the --timeout wall-clock deadline
 """
 
 
@@ -472,6 +481,16 @@ def _build_main_parser(prog: str = "diffctx", version: str = __version__) -> arg
             "bm25 = lexical similarity, for sparse cross-file structure"
         ),
     )
+    diff_group.add_argument(
+        "--timeout",
+        type=int,
+        default=_UNSET,
+        metavar="SECONDS",
+        help=(
+            f"Wall-clock deadline for --diff analysis (default: {_DEFAULT_TIMEOUT}); "
+            "on expiry diffctx aborts with exit code 124 instead of hanging"
+        ),
+    )
     diff_group.add_argument(
         "--full",
         action="store_true",
@@ -495,6 +514,8 @@ def _warn_diff_only_flags(args: argparse.Namespace) -> None:
         used.append("--full")
     if args.scoring is not _UNSET:
         used.append("--scoring")
+    if args.timeout is not _UNSET:
+        used.append("--timeout")
     if used:
         flags = ", ".join(used)
         _warn(f"diff-mode flags ignored without --diff: {flags}")
@@ -564,15 +585,17 @@ def _resolve_max_file_bytes(args: argparse.Namespace) -> int | None:
     return _validate_max_file_bytes(value, args.no_file_size_limit)
 
 
-def _resolve_diff_params(args: argparse.Namespace) -> tuple[str | None, int | None, float, float, str]:
+def _resolve_diff_params(args: argparse.Namespace) -> tuple[str | None, int | None, float, float, str, int]:
     budget = None if args.budget is _UNSET else args.budget
     alpha = _DEFAULT_ALPHA if args.alpha is _UNSET else args.alpha
     tau = _DEFAULT_TAU if args.tau is _UNSET else args.tau
     scoring = "ego" if args.scoring is _UNSET else args.scoring
+    timeout = _DEFAULT_TIMEOUT if args.timeout is _UNSET else args.timeout
 
     _validate_budget(budget)
     _validate_alpha(alpha)
     _validate_tau(tau)
+    _validate_timeout(timeout)
     _warn_diff_only_flags(args)
     _warn_full_selection_conflict(args)
     if args.diff_range and not args.full and args.alpha is not _UNSET and scoring != "ppr":
@@ -583,13 +606,13 @@ def _resolve_diff_params(args: argparse.Namespace) -> tuple[str | None, int | No
         diff_range = "HEAD"
     if diff_range and args.no_ignores:
         _exit_usage_error("--no-ignores is not supported with --diff (git's own ignore rules always apply in diff mode)")
-    return diff_range, budget, alpha, tau, scoring
+    return diff_range, budget, alpha, tau, scoring, timeout
 
 
 def _build_tree_parsed_args(args: argparse.Namespace) -> ParsedArgs:
     _validate_max_depth(args.max_depth)
     max_file_bytes = _resolve_max_file_bytes(args)
-    diff_range, budget, alpha, tau, scoring = _resolve_diff_params(args)
+    diff_range, budget, alpha, tau, scoring, timeout = _resolve_diff_params(args)
     _warn_quiet_log_level_conflict(args)
 
     dirs, files = _expand_paths(args.paths)
@@ -623,6 +646,7 @@ def _build_tree_parsed_args(args: argparse.Namespace) -> ParsedArgs:
         alpha=alpha,
         tau=tau,
         scoring=scoring,
+        timeout=timeout,
         full_diff=args.full,
         extra_dirs=extra_dirs,
         extra_files=extra_files,

src/diffctx/main.py

@@ -2,13 +2,17 @@
 
 import argparse
 import logging
+import os
 import re
 import signal
 import subprocess
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 from .version import __version__
 
 if TYPE_CHECKING:
@@ -20,6 +24,7 @@
 _EXIT_USAGE = 2
 _EXIT_ENVIRONMENT = 3
 _EXIT_EMPTY_DIFF = 4
+_EXIT_TIMEOUT = 124
 _EXIT_INTERRUPTED = 130
 _EXIT_BROKEN_PIPE = 141
 
@@ -104,24 +109,64 @@ def _warn_empty_diff_result(result: dict[str, Any], prog: str, args: ParsedArgs)
         )
 
 
+def _call_with_wall_clock_deadline(build: Callable[[], dict[str, Any]], timeout_seconds: int, prog: str) -> dict[str, Any]:
+    # The Rust extension releases the GIL but offers no cancellation, so a
+    # pathological repo can hang far past any per-phase git timeout (#70).
+    # Mirror the standalone binary's watchdog: run the pipeline on a worker
+    # thread and hard-exit 124 on deadline — the runaway worker cannot be
+    # stopped, so finalizers must not run (os._exit, not sys.exit).
+    import threading
+
+    outcome: list[Any] = []
+
+    def worker() -> None:
+        try:
+            outcome.append(("ok", build()))
+        except BaseException as exc:
+            outcome.append(("err", exc))
+
+    thread = threading.Thread(target=worker, name="diffctx-pipeline", daemon=True)
+    thread.start()
+    thread.join(timeout_seconds)
+    if thread.is_alive():
+        print(
+            f"{prog}: pipeline exceeded {timeout_seconds}s wall-clock deadline; aborting before "
+            "OOM/SIGKILL. Narrow the review with an explicit '--diff <from>..<to>' range, "
+            "run on a smaller subtree, or raise '--timeout'.",
+            file=sys.stderr,
+        )
+        sys.stderr.flush()
+        sys.stdout.flush()
+        os._exit(_EXIT_TIMEOUT)
+    status, value = outcome[0]
+    if status == "err":
+        raise value
+    return value  # type: ignore[no-any-return]
+
+
 def _build_diff_tree(args: ParsedArgs, prog: str) -> dict[str, Any]:
     from .diffctx import build_diff_context
 
     if not args.diff_range:
         raise RuntimeError("diff_range is required in diff mode")
     _ensure_git_repo(args.root_dir, prog)
-    result = build_diff_context(
-        root_dir=args.root_dir,
-        diff_range=args.diff_range,
-        budget_tokens=args.budget,
-        alpha=args.alpha,
-        tau=args.tau,
-        no_content=args.no_content,
-        ignore_file=args.ignore_file,
-        no_default_ignores=args.no_default_ignores,
-        full=args.full_diff,
-        whitelist_file=args.whitelist_file,
-        scoring_mode=getattr(args, "scoring", "ego"),
+    result = _call_with_wall_clock_deadline(
+        lambda: build_diff_context(
+            root_dir=args.root_dir,
+            diff_range=args.diff_range or "HEAD",
+            budget_tokens=args.budget,
+            alpha=args.alpha,
+            tau=args.tau,
+            no_content=args.no_content,
+            ignore_file=args.ignore_file,
+            no_default_ignores=args.no_default_ignores,
+            full=args.full_diff,
+            whitelist_file=args.whitelist_file,
+            scoring_mode=getattr(args, "scoring", "ego"),
+            timeout=args.timeout,
+        ),
+        args.timeout,
+        prog,
     )
     _warn_empty_diff_result(result, prog, args)
     return result

tests/test_e2e_cli_scenarios.py

@@ -10,21 +10,25 @@
 from __future__ import annotations
 
 import json
+import os
 import re
+import subprocess
+import sys
 
 import pytest
 import yaml
 
 from tests.framework.pygit2_backend import Pygit2Repo
 from tests.garbage_data import GARBAGE_FILES
 
-from .conftest import run_diffctx_subprocess
+from .conftest import SRC_DIR, run_diffctx_subprocess
 
 EXIT_OK = 0
 EXIT_RUNTIME = 1
 EXIT_USAGE = 2
 EXIT_ENVIRONMENT = 3
 EXIT_EMPTY_DIFF = 4
+EXIT_TIMEOUT = 124
 
 
 @pytest.fixture
@@ -282,6 +286,46 @@ def test_diff_invalid_range_fails_cleanly(self, diff_repo):
         assert "unknown git revision 'no_such_ref..HEAD'" in result.stderr
         assert "internal error" not in result.stderr
 
+    def test_timeout_flag_accepted_and_diff_completes(self, diff_repo):
+        result = run_diffctx_subprocess([".", "--diff", "HEAD~1..HEAD", "--timeout", "300", "-f", "yaml"], cwd=diff_repo.path)
+        assert result.returncode == EXIT_OK
+        assert yaml.safe_load(result.stdout)["type"] == "diff_context"
+
+    def test_timeout_below_one_second_is_usage_error(self, diff_repo):
+        result = run_diffctx_subprocess([".", "--diff", "HEAD~1..HEAD", "--timeout", "0"], cwd=diff_repo.path)
+        assert result.returncode == EXIT_USAGE
+        assert "--timeout must be >= 1" in result.stderr
+
+    def test_timeout_without_diff_warns_and_is_ignored(self, temp_project):
+        result = run_diffctx_subprocess([".", "--timeout", "5"], cwd=temp_project)
+        assert result.returncode == EXIT_OK
+        assert "diff-mode flags ignored without --diff" in result.stderr
+        assert "--timeout" in result.stderr
+
+    def test_expired_deadline_aborts_with_exit_124(self):
+        """The wall-clock watchdog must hard-abort a pipeline that outlives
+        --timeout (#70): a runaway Rust computation cannot be cancelled from
+        Python, so the process exits 124 like the standalone binary. Exercised
+        in a real subprocess with a genuinely slow (sleeping) pipeline call."""
+        watchdog_script = (
+            "import time\n"
+            "from diffctx.main import _call_with_wall_clock_deadline\n"
+            "_call_with_wall_clock_deadline(lambda: time.sleep(60), 1, 'diffctx')\n"
+        )
+        env = os.environ.copy()
+        env["PYTHONPATH"] = str(SRC_DIR)
+        result = subprocess.run(
+            [sys.executable, "-c", watchdog_script],
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=30,
+            check=False,
+        )
+        assert result.returncode == EXIT_TIMEOUT
+        assert "wall-clock deadline" in result.stderr
+        assert "--timeout" in result.stderr
+
     def test_diff_to_clipboard_writes_file_too(self, diff_repo, tmp_path):
         out = tmp_path / "diff.yaml"
         result = run_diffctx_subprocess([".", "--diff", "HEAD~1..HEAD", "-f", "yaml", "-o", str(out)], cwd=diff_repo.path)