python-config-type-coercion

Answer

Root cause: subprocess.run(timeout=...) requires an int/float/None. PyYAML loads test_timeout: 300s as the string '300s', which produced a TypeError inside check_go_tests — reproduced pre-fix:

unsupported operand type(s) for +: 'float' and 'str'

Fix: a single choke point _coerce_timeout in engine/guards.py, applied twice — eagerly at GuardManager.__init__ (both test_timeout and hook_timeout) and defensively inside check_go_tests at call time:

_DURATION_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)")

def _coerce_timeout(value, key, default=None):
    if value is None:
        return default
    if isinstance(value, bool):            # bool is an int subclass — check first
        raise ValueError(f"config key {key!r}: timeout must be a positive number "
                         f"of seconds, got bool {value!r}")
    if isinstance(value, numbers.Real):
        parsed = float(value)
    elif isinstance(value, str):
        match = _DURATION_RE.match(value)  # leading-digits parse: "300s" -> 300
        if match is None:
            raise ValueError(f"config key {key!r}: cannot parse timeout from {value!r} "
                             f"(expected a positive number or a duration string like '300s')")
        parsed = float(match.group(1))
    else:
        raise ValueError(f"config key {key!r}: unsupported timeout type "
                         f"{type(value).__name__} ({value!r})")
    if parsed <= 0:
        raise ValueError(f"config key {key!r}: timeout must be > 0 seconds, got {value!r}")
    return int(parsed) if parsed.is_integer() else parsed

GuardManager integration (engine/guards.py):

class GuardManager:
    def __init__(self, config=None, *,
                 default_test_timeout=DEFAULT_TEST_TIMEOUT,   # 600
                 default_hook_timeout=DEFAULT_HOOK_TIMEOUT):  # 300
        self.config = dict(config or {})
        self.test_timeout = _coerce_timeout(self.config.get("test_timeout"),
                                            "test_timeout", default_test_timeout)
        self.hook_timeout = _coerce_timeout(self.config.get("hook_timeout"),
                                            "hook_timeout", default_hook_timeout)

    def check_go_tests(self, cmd=None, timeout=None):
        raw = timeout if timeout is not None else self.config.get("test_timeout")
        safe_timeout = _coerce_timeout(raw, "test_timeout", self.test_timeout)
        return subprocess.run(cmd or ["go", "test", "./..."],
                              capture_output=True, text=True, timeout=safe_timeout)

Key properties: "300s" → 300 (int), "2.5" → 2.5, None → default (or None = no timeout), garbage/bool/<=0 → ValueError naming the exact YAML key so operators can find the bad line in the fleet config.