Validate bounded CLI integer limits

Author: ZelAnton

CHANGELOG.md

@@ -128,6 +128,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Reject CR/LF, control, and whitespace characters in a `wait_for_http` host
   before HTTP serialization, preventing header injection.
+- Reject CLI resource and restart limit values above their binding widths with
+  an argparse usage error before constructing a `ProcessGroup` or `Supervisor`.
 - CLI duration, CPU, backoff, and health-check numeric options now reject
   non-finite values before constructing a command or supervisor.
 - Keep Nightly hardening actionable: its mutation sandbox now includes the

docs/changelog.md

@@ -131,6 +131,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Reject CR/LF, control, and whitespace characters in a `wait_for_http` host
   before HTTP serialization, preventing header injection.
+- Reject CLI resource and restart limit values above their binding widths with
+  an argparse usage error before constructing a `ProcessGroup` or `Supervisor`.
 - CLI duration, CPU, backoff, and health-check numeric options now reject
   non-finite values before constructing a command or supervisor.
 - Keep Nightly hardening actionable: its mutation sandbox now includes the

docs/cli.md

@@ -68,8 +68,8 @@ python -m processkit run --max-memory 536870912 --max-processes 64 -- ./build.sh
 | `--timeout SECONDS` | `Command.timeout(seconds)` | Kills the whole tree once the deadline passes. |
 | `--timeout-grace SECONDS` | `Command.timeout_grace(seconds)` | Signal first, hard-kill after `SECONDS`. Requires `--timeout`; a usage error otherwise. |
 | `--idle-timeout SECONDS` | `Command.idle_timeout(seconds)` | Kill the child if it emits no output line for `SECONDS`. Exit `123` (distinct from `--timeout`'s `124`). Pipes and re-emits stdout/stderr line-by-line; incompatible with `--profile` and `--stdout-file`. See [below](#--idle-timeout-a-silence-watchdog). |
-| `--max-memory BYTES` | `ProcessGroup(max_memory=...)` | Whole-tree memory cap. |
-| `--max-processes N` | `ProcessGroup(max_processes=...)` | Fork-bomb ceiling for the tree. |
+| `--max-memory BYTES` | `ProcessGroup(max_memory=...)` | Whole-tree memory cap; accepts `1..=2^64-1` bytes. |
+| `--max-processes N` | `ProcessGroup(max_processes=...)` | Fork-bomb ceiling for the tree; accepts `1..=2^32-1`. |
 | `--cpu-quota FLOAT` | `ProcessGroup(cpu_quota=...)` | Fraction of a **single** core (`0.5` = half, `2.0` = two cores). |
 | `--env-clear` | `Command.env_clear()` | Start the child with an empty environment. |
 | `--inherit-env NAME` | `Command.inherit_env([...])` | Allow-list a parent variable through (implies `--env-clear`). Repeatable. |
@@ -101,6 +101,12 @@ Files are UTF-8 (an optional BOM is accepted); values are literal and may contai
 additional `=` characters. Missing/unreadable files and non-comment lines
 without `=` are usage errors with the file and line number, never tracebacks.
 
+The resource and restart limits are parsed against the widths of their binding
+types before a `ProcessGroup` or `Supervisor` is constructed: `--max-memory`
+accepts `1..=2^64-1` (`u64`), while `--max-processes` and `--max-restarts`
+accept `1..=2^32-1` (`u32`). Values above those bounds are argparse usage
+errors; the other positive-integer flags keep their existing contracts.
+
 ### `--sanitize-vt`: clean terminal output
 
 Use `--sanitize-vt` for a color-sensitive tool whose output must become plain
@@ -290,14 +296,14 @@ just line-buffered rather than a byte-for-byte fd passthrough.
 | Flag | Description |
 |---|---|
 | `--restart {always,on_crash,never}` | Restart policy passed to `Supervisor`. |
-| `--max-restarts N` | Stop after `N` restarts. `N` must be positive. |
+| `--max-restarts N` | Stop after `N` restarts; accepts `1..=2^32-1` (`u32`). |
 | `--backoff-initial SECONDS` | Initial delay before a restart. Must be positive. |
 | `--backoff-factor FLOAT` | Multiplier for successive restart delays. Must be at least `1`. |
 | `--max-backoff SECONDS` | Upper bound for restart delay. Must be positive. |
 | `--no-jitter` | Disable restart-delay jitter; jitter is enabled by default. |
 | `--timeout SECONDS` | Apply `Command.timeout(seconds)` independently to every incarnation. A final timed-out incarnation exits `124`. |
-| `--max-memory BYTES` | Cap every incarnation's whole process tree memory. |
-| `--max-processes N` | Cap every incarnation's process-tree size. |
+| `--max-memory BYTES` | Cap every incarnation's whole process tree memory; accepts `1..=2^64-1` bytes (`u64`). |
+| `--max-processes N` | Cap every incarnation's process-tree size; accepts `1..=2^32-1` (`u32`). |
 | `--cpu-quota FLOAT` | Cap every incarnation's CPU as a fraction of one core. |
 | `--cpu-affinity CPU[,CPU...]` | Pin every incarnation to logical CPUs on Linux/Windows. |
 | `--create-no-window` | Apply `Command.create_no_window()` to every incarnation. |

docs/llms-full.txt

@@ -5238,8 +5238,8 @@ python -m processkit run --max-memory 536870912 --max-processes 64 -- ./build.sh
 | `--timeout SECONDS` | `Command.timeout(seconds)` | Kills the whole tree once the deadline passes. |
 | `--timeout-grace SECONDS` | `Command.timeout_grace(seconds)` | Signal first, hard-kill after `SECONDS`. Requires `--timeout`; a usage error otherwise. |
 | `--idle-timeout SECONDS` | `Command.idle_timeout(seconds)` | Kill the child if it emits no output line for `SECONDS`. Exit `123` (distinct from `--timeout`'s `124`). Pipes and re-emits stdout/stderr line-by-line; incompatible with `--profile` and `--stdout-file`. See [below](#--idle-timeout-a-silence-watchdog). |
-| `--max-memory BYTES` | `ProcessGroup(max_memory=...)` | Whole-tree memory cap. |
-| `--max-processes N` | `ProcessGroup(max_processes=...)` | Fork-bomb ceiling for the tree. |
+| `--max-memory BYTES` | `ProcessGroup(max_memory=...)` | Whole-tree memory cap; accepts `1..=2^64-1` bytes. |
+| `--max-processes N` | `ProcessGroup(max_processes=...)` | Fork-bomb ceiling for the tree; accepts `1..=2^32-1`. |
 | `--cpu-quota FLOAT` | `ProcessGroup(cpu_quota=...)` | Fraction of a **single** core (`0.5` = half, `2.0` = two cores). |
 | `--env-clear` | `Command.env_clear()` | Start the child with an empty environment. |
 | `--inherit-env NAME` | `Command.inherit_env([...])` | Allow-list a parent variable through (implies `--env-clear`). Repeatable. |
@@ -5271,6 +5271,12 @@ Files are UTF-8 (an optional BOM is accepted); values are literal and may contai
 additional `=` characters. Missing/unreadable files and non-comment lines
 without `=` are usage errors with the file and line number, never tracebacks.
 
+The resource and restart limits are parsed against the widths of their binding
+types before a `ProcessGroup` or `Supervisor` is constructed: `--max-memory`
+accepts `1..=2^64-1` (`u64`), while `--max-processes` and `--max-restarts`
+accept `1..=2^32-1` (`u32`). Values above those bounds are argparse usage
+errors; the other positive-integer flags keep their existing contracts.
+
 ### `--sanitize-vt`: clean terminal output
 
 Use `--sanitize-vt` for a color-sensitive tool whose output must become plain
@@ -5460,14 +5466,14 @@ just line-buffered rather than a byte-for-byte fd passthrough.
 | Flag | Description |
 |---|---|
 | `--restart {always,on_crash,never}` | Restart policy passed to `Supervisor`. |
-| `--max-restarts N` | Stop after `N` restarts. `N` must be positive. |
+| `--max-restarts N` | Stop after `N` restarts; accepts `1..=2^32-1` (`u32`). |
 | `--backoff-initial SECONDS` | Initial delay before a restart. Must be positive. |
 | `--backoff-factor FLOAT` | Multiplier for successive restart delays. Must be at least `1`. |
 | `--max-backoff SECONDS` | Upper bound for restart delay. Must be positive. |
 | `--no-jitter` | Disable restart-delay jitter; jitter is enabled by default. |
 | `--timeout SECONDS` | Apply `Command.timeout(seconds)` independently to every incarnation. A final timed-out incarnation exits `124`. |
-| `--max-memory BYTES` | Cap every incarnation's whole process tree memory. |
-| `--max-processes N` | Cap every incarnation's process-tree size. |
+| `--max-memory BYTES` | Cap every incarnation's whole process tree memory; accepts `1..=2^64-1` bytes (`u64`). |
+| `--max-processes N` | Cap every incarnation's process-tree size; accepts `1..=2^32-1` (`u32`). |
 | `--cpu-quota FLOAT` | Cap every incarnation's CPU as a fraction of one core. |
 | `--cpu-affinity CPU[,CPU...]` | Pin every incarnation to logical CPUs on Linux/Windows. |
 | `--create-no-window` | Apply `Command.create_no_window()` to every incarnation. |
@@ -6347,6 +6353,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Reject CR/LF, control, and whitespace characters in a `wait_for_http` host
   before HTTP serialization, preventing header injection.
+- Reject CLI resource and restart limit values above their binding widths with
+  an argparse usage error before constructing a `ProcessGroup` or `Supervisor`.
 - CLI duration, CPU, backoff, and health-check numeric options now reject
   non-finite values before constructing a command or supervisor.
 - Keep Nightly hardening actionable: its mutation sandbox now includes the

src/processkit/_cli/parser.py

@@ -6,7 +6,7 @@
 
 import argparse
 import math
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 
 #: Sentinel `const=` for ``--profile``'s optional `FILE` argument (`nargs="?"`):
 #: distinguishes "flag absent" (`args.profile is None`, the default) from
@@ -19,6 +19,8 @@
 #: a caller wants "collect a profile" and "where to put it" to vary
 #: independently of each other.
 PROFILE_STDERR_MARKER = object()
+_U32_MAX = (1 << 32) - 1
+_U64_MAX = (1 << 64) - 1
 
 
 def _positive_int(value: str) -> int:
@@ -28,6 +30,22 @@ def _positive_int(value: str) -> int:
     return parsed
 
 
+def _bounded_positive_int(maximum: int) -> Callable[[str], int]:
+    def parse(value: str) -> int:
+        parsed = _positive_int(value)
+        if parsed > maximum:
+            raise argparse.ArgumentTypeError(
+                f"must be a positive integer in the range 1..={maximum}, got {value!r}"
+            )
+        return parsed
+
+    return parse
+
+
+_U32_POSITIVE_INT = _bounded_positive_int(_U32_MAX)
+_U64_POSITIVE_INT = _bounded_positive_int(_U64_MAX)
+
+
 def _positive_float(value: str) -> float:
     parsed = float(value)
     if not math.isfinite(parsed) or parsed <= 0:
@@ -130,15 +148,15 @@ def _build_parser() -> tuple[
     run_parser.add_argument(
         "--max-memory",
         dest="max_memory",
-        type=_positive_int,
+        type=_U64_POSITIVE_INT,
         default=None,
         metavar="BYTES",
         help="Cap the whole child tree's memory, in bytes (needs a real container).",
     )
     run_parser.add_argument(
         "--max-processes",
         dest="max_processes",
-        type=_positive_int,
+        type=_U32_POSITIVE_INT,
         default=None,
         metavar="N",
         help="Cap the number of processes in the tree (needs a real container).",
@@ -323,7 +341,7 @@ def _build_parser() -> tuple[
     supervise_parser.add_argument(
         "--max-restarts",
         dest="max_restarts",
-        type=_positive_int,
+        type=_U32_POSITIVE_INT,
         default=None,
         metavar="N",
         help="Stop supervising after N restarts (Supervisor(max_restarts=...)).",
@@ -384,15 +402,15 @@ def _build_parser() -> tuple[
     supervise_parser.add_argument(
         "--max-memory",
         dest="max_memory",
-        type=_positive_int,
+        type=_U64_POSITIVE_INT,
         default=None,
         metavar="BYTES",
         help="Cap each incarnation's whole process tree memory, in bytes.",
     )
     supervise_parser.add_argument(
         "--max-processes",
         dest="max_processes",
-        type=_positive_int,
+        type=_U32_POSITIVE_INT,
         default=None,
         metavar="N",
         help="Cap each incarnation's process-tree size.",

tests/test_cli_main.py

@@ -527,6 +527,33 @@ def test_idle_timeout_rejects_nonpositive_value_as_usage_error() -> None:
     assert "positive, finite number" in result.stderr
 
 
+@pytest.mark.parametrize(
+    ("subcommand", "option", "overflow"),
+    [
+        ("run", "--max-memory", 1 << 64),
+        ("run", "--max-processes", 1 << 32),
+        ("supervise", "--max-memory", 1 << 64),
+        ("supervise", "--max-processes", 1 << 32),
+        ("supervise", "--max-restarts", 1 << 64),
+    ],
+)
+def test_resource_limit_overflow_is_argparse_usage_error_before_child_launch(
+    subcommand: str, option: str, overflow: int
+) -> None:
+    args = [subcommand]
+    if subcommand == "supervise":
+        args.extend(["--restart", "never"])
+    args.extend([option, str(overflow), "--", PY, "-c", "print('child started')"])
+
+    result = _run_cli(*args)
+
+    assert result.returncode == 2
+    assert "range 1..=" in result.stderr
+    assert f"usage: python -m processkit {subcommand}" in result.stderr
+    assert "child started" not in result.stdout
+    assert "Traceback (most recent call last)" not in result.stderr
+
+
 @pytest.mark.parametrize(
     "option", ["--timeout", "--timeout-grace", "--idle-timeout", "--cpu-quota"]
 )

tests/test_cli_units.py

@@ -102,6 +102,81 @@ def test_positive_int_rejects_non_positive_values(value: str) -> None:
         parser._positive_int(value)
 
 
+@pytest.mark.parametrize(
+    ("subcommand", "option", "destination", "maximum"),
+    [
+        ("run", "--max-memory", "max_memory", (1 << 64) - 1),
+        ("run", "--max-processes", "max_processes", (1 << 32) - 1),
+        ("supervise", "--max-memory", "max_memory", (1 << 64) - 1),
+        ("supervise", "--max-processes", "max_processes", (1 << 32) - 1),
+        ("supervise", "--max-restarts", "max_restarts", (1 << 32) - 1),
+    ],
+)
+def test_bounded_resource_integer_parsers_accept_binding_upper_bound(
+    subcommand: str, option: str, destination: str, maximum: int
+) -> None:
+    top, _, _, _ = parser._build_parser()
+    args = top.parse_args([subcommand, option, str(maximum)])
+    assert getattr(args, destination) == maximum
+
+
+@pytest.mark.parametrize(
+    ("subcommand", "option", "destination"),
+    [
+        ("run", "--max-memory", "max_memory"),
+        ("run", "--max-processes", "max_processes"),
+        ("supervise", "--max-memory", "max_memory"),
+        ("supervise", "--max-processes", "max_processes"),
+        ("supervise", "--max-restarts", "max_restarts"),
+    ],
+)
+def test_bounded_resource_integer_parsers_accept_binding_lower_bound(
+    subcommand: str, option: str, destination: str
+) -> None:
+    top, _, _, _ = parser._build_parser()
+    args = top.parse_args([subcommand, option, "1"])
+    assert getattr(args, destination) == 1
+
+
+@pytest.mark.parametrize(
+    ("subcommand", "option", "value"),
+    [
+        ("run", "--max-memory", 1 << 64),
+        ("run", "--max-processes", 1 << 32),
+        ("supervise", "--max-memory", 1 << 64),
+        ("supervise", "--max-processes", 1 << 32),
+        ("supervise", "--max-restarts", 1 << 32),
+    ],
+)
+def test_bounded_resource_integer_parsers_reject_first_value_above_binding_bound(
+    subcommand: str, option: str, value: int
+) -> None:
+    top, _, _, _ = parser._build_parser()
+    with pytest.raises(SystemExit) as exc_info:
+        top.parse_args([subcommand, option, str(value)])
+    assert exc_info.value.code == 2
+
+
+@pytest.mark.parametrize(
+    ("subcommand", "option"),
+    [
+        ("run", "--max-memory"),
+        ("run", "--max-processes"),
+        ("supervise", "--max-memory"),
+        ("supervise", "--max-processes"),
+        ("supervise", "--max-restarts"),
+    ],
+)
+@pytest.mark.parametrize("value", ["0", "-1"])
+def test_bounded_resource_integer_parsers_preserve_non_positive_rejection(
+    subcommand: str, option: str, value: str
+) -> None:
+    top, _, _, _ = parser._build_parser()
+    with pytest.raises(SystemExit) as exc_info:
+        top.parse_args([subcommand, option, value])
+    assert exc_info.value.code == 2
+
+
 @pytest.mark.parametrize("value", ["0", "-1", "nan", "inf", "+inf", "-inf"])
 def test_positive_float_rejects_non_positive_or_non_finite_values(value: str) -> None:
     with pytest.raises(argparse.ArgumentTypeError):