@heretek-ai/epistemic-swarm 0.7.21 → 0.7.23

package/skills/swarm_config/configure.py

@@ -23,6 +23,7 @@ import hashlib
 import json
 import os
 import re
+import stat
 import sys
 import tempfile
 from contextlib import contextmanager
@@ -219,6 +220,38 @@ class ConfigStaleError(ConfigError):
         )
 
 
+class ConfigNullError(ConfigError):
+    """A caller-supplied null targets a schema-known non-nullable key.
+
+    Structural unification (R2): `save_config` emits the same
+    `NULL_FOR_NON_NULLABLE_KEY` code as the MCP `_handle_config` pre-check,
+    with dotted paths for nested nulls (e.g. `verify.min_fuzzy_confidence`).
+    Scoping: only schema-known paths are reported here; nulls under
+    unknown top-level keys or unknown roles (e.g. `agents.gamma`) carry no
+    nullability info and are preserved-verbatim for generic validation to
+    decide (unknown object keys are forward-compatible).
+    """
+
+    code = "NULL_FOR_NON_NULLABLE_KEY"
+
+    def __init__(self, paths: List[str]):
+        names = sorted(set(str(p) for p in paths))
+        super().__init__(
+            "null is not accepted for non-nullable key(s): "
+            + ", ".join(names)
+            + "; omit the key to leave it unchanged, or pass a valid value",
+            details={"errors": names},
+        )
+
+    @property
+    def null_errors(self) -> List[str]:
+        return list(self.details.get("errors") or [])
+
+    @property
+    def errors(self) -> List[str]:
+        return list(self.details.get("errors") or [])
+
+
 class ConfigHashError(ConfigError):
     """`expected_hash` is not a full sha256 / unique-prefix hex string."""
 
@@ -232,6 +265,85 @@ class ConfigHashError(ConfigError):
         )
 
 
+class ConfigUnreadableError(ConfigError):
+    """The config file exists but is not a readable, bounded regular file.
+
+    Phase-08 R2 (W17): `save_config` raises this (fail-closed, nothing
+    written) instead of hanging on a FIFO/special device or silently merging
+    over an unreadable/oversize file.
+    """
+
+    code = "CONFIG_UNREADABLE"
+
+
+# ---------------------------------------------------------------------------
+# bounded reads (phase-08 R2 FIFO hardening)
+# ---------------------------------------------------------------------------
+
+#: Cap for any single `config.json` read. The file is ~1KB in practice; the
+#: cap exists only so a pathological workspace entry can never wedge a reader
+#: on an unbounded slurp (mirrors `runner/preflight.py::STATE_MAX_BYTES`).
+CONFIG_MAX_BYTES = 1024 * 1024
+
+
+def _read_bounded_bytes(
+    path: Path, max_bytes: int = CONFIG_MAX_BYTES
+) -> Optional[bytes]:
+    """Read at most `max_bytes` from `path` iff it is a regular file.
+
+    Phase-08 R2 (W17): a FIFO named `config.json` hung `load_config` /
+    `heal_config` on a plain `open`. Ports the `runner/preflight.py`
+    `_read_bounded_text` semantics — `S_ISREG` on BOTH the pre-open `stat`
+    and the post-open `fstat` (closing the stat->open race), an `O_NONBLOCK`
+    open, and a byte cap — so a pathological workspace entry (FIFO, device,
+    socket, directory, runaway file) can never block a config reader.
+    Returns `None` when the path is absent, unreadable, non-regular, or
+    over the cap.
+
+    Symlinks are FOLLOWED (`os.stat`, no `O_NOFOLLOW`): the pre-fix reader
+    followed them too, so a symlinked config keeps working; a symlink to a
+    non-regular target is still refused by the `S_ISREG` checks. Residual
+    (documented): a symlink swapped for a FIFO between the pre-open stat and
+    the open races the check — the post-open `fstat` still refuses anything
+    that is non-regular at read time.
+    """
+    try:
+        if not stat.S_ISREG(os.stat(path).st_mode):
+            return None
+    except OSError:
+        return None
+    flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0)
+    try:
+        fd = os.open(path, flags)
+    except OSError:
+        return None
+    try:
+        try:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                return None
+        except OSError:
+            return None
+        chunks = []
+        remaining = max_bytes + 1
+        while remaining > 0:
+            try:
+                chunk = os.read(fd, min(remaining, 65536))
+            except BlockingIOError:
+                break
+            except OSError:
+                return None
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+    finally:
+        os.close(fd)
+    data = b"".join(chunks)
+    if len(data) > max_bytes:
+        return None
+    return data
+
+
 # ---------------------------------------------------------------------------
 # paths + snapshots
 # ---------------------------------------------------------------------------
@@ -250,11 +362,15 @@ def config_hash(base_dir: str = DEFAULT_RESEARCH_DIR) -> Optional[str]:
 
     The hash covers the file as written (whitespace included), so it doubles as
     an optimistic-concurrency version for `expected_hash` / the RPC bridge.
+    Phase-08 R2: read through the bounded reader, so a FIFO/special device
+    yields None (it has no stable bytes to hash; a guarded write then fails
+    closed as stale) instead of hanging the caller.
     """
     cfg_file = get_config_path(base_dir)
-    if not cfg_file.is_file():
+    raw = _read_bounded_bytes(cfg_file)
+    if raw is None:
         return None
-    return hashlib.sha256(cfg_file.read_bytes()).hexdigest()
+    return hashlib.sha256(raw).hexdigest()
 
 
 def snapshot(base_dir: str = DEFAULT_RESEARCH_DIR) -> Dict[str, Any]:
@@ -327,14 +443,83 @@ def validate_config(cfg: Any) -> List[str]:
 
 
 def _read_raw_config(cfg_file: Path) -> Optional[Dict[str, Any]]:
-    """Best-effort raw JSON object on disk (None when absent/malformed)."""
+    """Best-effort raw JSON object on disk (None when absent/malformed).
+
+    Phase-08 R2: read through the bounded reader, so a FIFO/special device
+    yields None (callers already treat None as absent/malformed) instead of
+    hanging the caller.
+    """
     try:
-        data = json.loads(cfg_file.read_text(encoding="utf-8"))
+        raw = _read_bounded_bytes(cfg_file)
+        if raw is None:
+            return None
+        data = json.loads(raw.decode("utf-8"))
     except (OSError, ValueError):
         return None
     return data if isinstance(data, dict) else None
 
 
+def _caller_schema_allows_null(subschema: Any) -> bool:
+    """True when a canonical subschema accepts null (type includes "null")."""
+    if not isinstance(subschema, dict):
+        return False
+    types = subschema.get("type")
+    if isinstance(types, list):
+        return "null" in types
+    return types == "null"
+
+
+def collect_caller_null_violations(caller: Any) -> List[str]:
+    """Dotted paths in caller-supplied `caller` where null is banned (R2).
+
+    Shared nested-null pre-check: `save_config` raises `ConfigNullError` for
+    these paths so ALL writers emit `NULL_FOR_NON_NULLABLE_KEY` for
+    schema-known paths (unifying the MCP `_handle_config` pre-check). Only
+    schema-known paths are reported; nulls under unknown top-level keys or
+    unknown roles (e.g. `agents.gamma`) carry no nullability info and are
+    preserved-verbatim for generic validation to decide. Degrades to `[]`
+    when the canonical schema is unavailable (standalone skill copy).
+    """
+    if not isinstance(caller, dict):
+        return []
+    if _CONFIG_SCHEMA is None:
+        return []
+    props = _CONFIG_SCHEMA.get("properties") or {}
+    found: List[str] = []
+
+    def walk(value: Any, subschema: Any, path: str) -> None:
+        if value is None:
+            if isinstance(subschema, dict) and not _caller_schema_allows_null(
+                subschema
+            ):
+                found.append(path)
+            return
+        if isinstance(value, dict) and isinstance(subschema, dict):
+            sub_props = subschema.get("properties") or {}
+            additional = subschema.get("additionalProperties")
+            for key, child in value.items():
+                if key in sub_props:
+                    walk(child, sub_props[key], f"{path}.{key}" if path else str(key))
+                elif isinstance(additional, dict):
+                    walk(child, additional, f"{path}.{key}" if path else str(key))
+            return
+        if isinstance(value, list) and isinstance(subschema, dict):
+            items = subschema.get("items")
+            if isinstance(items, dict):
+                for idx, child in enumerate(value):
+                    walk(child, items, f"{path}[{idx}]")
+
+    for key, value in caller.items():
+        if key not in props:
+            continue  # unknown top-level keys: preserved verbatim
+        if value is None:
+            if not _caller_schema_allows_null(props[key]):
+                found.append(str(key))
+        elif isinstance(value, (dict, list)):
+            walk(value, props[key], str(key))
+    return sorted(set(found))
+
+
 # ---------------------------------------------------------------------------
 # load / save
 # ---------------------------------------------------------------------------
@@ -392,17 +577,30 @@ def load_config(base_dir: str = DEFAULT_RESEARCH_DIR) -> Dict[str, Any]:
     """Load config merged over defaults. Pure — never writes to disk.
 
     Applies the legacy-pin migration in memory so a stale config stops forcing
-    Claude immediately; `heal_config` persists that migration on next touch.
-    Unknown keys are preserved verbatim (they are part of the contract's
-    forward-compatibility rule).
+    Claude immediately. No production read path persists that migration (reads
+    are non-healing by design, R12/F2): it is applied in memory on every load
+    and persisted opportunistically the next time a write leg merges the loaded
+    config (`configure.py` CLI save, the MCP `iumbtems_config` update leg);
+    `heal_config` remains available as an explicit opt-in repair helper but no
+    production read path calls it (phase-08 R3). Unknown keys are preserved
+    verbatim (they are part of the contract's forward-compatibility rule).
+
+    Phase-08 R2: the file is read through the bounded reader, so a FIFO /
+    special device / oversize file warns once and yields defaults instead of
+    hanging the caller.
     """
     base = copy.deepcopy(DEFAULT_CONFIG)
     cfg_file = get_config_path(base_dir)
-    if not cfg_file.exists():
+    raw_bytes = _read_bounded_bytes(cfg_file)
+    if raw_bytes is None:
+        if os.path.lexists(cfg_file):
+            sys.stderr.write(
+                f"[swarm-config] Warning: {cfg_file} is not a readable regular "
+                "file (or exceeds the read cap). Using defaults.\n"
+            )
         return base
     try:
-        with open(cfg_file, "r", encoding="utf-8") as f:
-            data = json.load(f)
+        data = json.loads(raw_bytes.decode("utf-8"))
     except Exception as e:
         sys.stderr.write(
             f"[swarm-config] Warning: Failed to parse {cfg_file}: {e}. Using defaults.\n"
@@ -426,21 +624,30 @@ def load_config(base_dir: str = DEFAULT_RESEARCH_DIR) -> Dict[str, Any]:
 def heal_config(base_dir: str = DEFAULT_RESEARCH_DIR) -> bool:
     """Persist a legacy agent-backend migration to disk; True if rewritten.
 
-    `load_config` stays side-effect free; the CLI and MCP surfaces call this so
-    an affected install self-heals instead of re-pinning Claude on every save.
-    The write is guarded by the hash of the bytes this call read, so a migration
-    never clobbers a concurrent writer (it simply defers to the next touch).
+    Explicit opt-in repair helper (exported, tested). Phase-08 R3 truth: NO
+    production read path calls this — `--show` / bare CLI, the MCP `show`
+    leg, and `load_config` itself are strictly non-healing (R12/F2); the
+    migration persists opportunistically when a write leg merges the loaded
+    (in-memory-migrated) config. Call this directly when you want the
+    migration persisted outside any other write. The write is guarded by the
+    hash of the bytes this call read, so a migration never clobbers a
+    concurrent writer (it simply defers to the next touch).
 
     The would-be-persisted dict is validated first (R1): a file that already
     fails the canonical schema is NOT rewritten — persisting it would legitimise
     the invalid values and feed them to SwarmRunner. The migration then stays in
     memory only, and a warning names every violation.
+
+    Phase-08 R2: the pre-read goes through the bounded reader, so a FIFO /
+    special device returns False instead of hanging the caller.
     """
     cfg_file = get_config_path(base_dir)
     if not cfg_file.exists():
         return False
     try:
-        raw_bytes = cfg_file.read_bytes()
+        raw_bytes = _read_bounded_bytes(cfg_file)
+        if raw_bytes is None:
+            return False
         raw = json.loads(raw_bytes.decode("utf-8"))
     except Exception:
         return False
@@ -486,7 +693,11 @@ def save_config(
     * Cross-process advisory lock over `.research/.config.lock` around the whole
       read-merge-write, so concurrent writers cannot lose each other's keys.
     * Unknown keys already on disk survive; `cfg` keys (deep-merged) win.
-    * Schema validation against `runner.schemas.CONFIG`; failures raise
+    * Caller-supplied null for a schema-known non-nullable key (any depth)
+      raises `ConfigNullError` (`NULL_FOR_NON_NULLABLE_KEY`) with dotted paths
+      before anything is written — the same code as the MCP surface; nulls
+      under unknown keys/roles stay preserved-verbatim for generic validation.
+    * Schema validation against `runner.schemas.CONFIG`; other failures raise
       `ConfigValidationError` with dotted paths and write nothing. `validate`
       may be disabled only by a caller that has already validated the exact
       dict it is persisting (see `heal_config`).
@@ -503,13 +714,39 @@ def save_config(
                 "(config must be a JSON object)"
             ]
         )
+    null_paths = collect_caller_null_violations(cfg)
+    if null_paths:
+        raise ConfigNullError(null_paths)
     guard = normalize_expected_hash(expected_hash)
     target_dir = Path(base_dir)
     target_dir.mkdir(parents=True, exist_ok=True)
     cfg_file = target_dir / "config.json"
 
     with _file_lock(get_lock_path(base_dir)):
-        existing_bytes = cfg_file.read_bytes() if cfg_file.is_file() else b""
+        # Phase-08 R2: bounded pre-read — a FIFO/special device here hung the
+        # writer on a plain `read_bytes`. Fail closed (nothing written) rather
+        # than hang or silently merge over an unreadable/oversize file.
+        if cfg_file.is_file():
+            existing_bytes = _read_bounded_bytes(cfg_file)
+            if existing_bytes is None:
+                raise ConfigUnreadableError(
+                    f"{cfg_file} exists but is not a readable, bounded "
+                    "regular file (FIFO, device, or over the read cap); "
+                    "refusing to merge over it.",
+                    details={"written": False},
+                )
+        elif os.path.lexists(cfg_file):
+            # A non-file entry (FIFO, directory, dangling symlink): the old
+            # code silently replaced it via merge-over-{} + os.replace.
+            # Refuse instead — replacing a caller's FIFO/symlink out from
+            # under them is never the safe default.
+            raise ConfigUnreadableError(
+                f"{cfg_file} exists but is not a regular file; "
+                "refusing to merge over it.",
+                details={"written": False},
+            )
+        else:
+            existing_bytes = b""
         current_hash = (
             hashlib.sha256(existing_bytes).hexdigest() if existing_bytes else None
         )