alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/config.py

@@ -0,0 +1,648 @@
+"""XDG-compliant configuration and session loading.
+
+The alter-runtime daemon reads its configuration from three sources, in order
+of precedence:
+
+1. Environment variables (ALTER_RUNTIME_*)
+2. User config file at $XDG_CONFIG_HOME/alter/runtime.yaml (default
+   ~/.config/alter/runtime.yaml)
+3. Built-in defaults
+
+The authoritative identity session is written by the separate `alter-cli`
+sibling repo at $XDG_CONFIG_HOME/alter/session.json. We read it but never
+mutate it - the daemon does not manage login.
+
+Paths per D-RT2 and the plan's macOS socket location decision:
+- Linux:   /run/user/$UID/alter.sock
+- macOS:   ~/Library/Application Support/alter/runtime.sock
+- Windows: \\\\.\\pipe\\alter-runtime   (Wave 3; Named Pipe, not Unix socket)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "ConfigError",
+    "DaemonConfig",
+    "Session",
+    "cache_dir",
+    "config_dir",
+    "data_dir",
+    "keypair_path",
+    "load_config",
+    "load_session",
+    "runtime_state_dir",
+    "state_dir",
+    "unix_socket_path",
+]
+
+
+# ---------------------------------------------------------------------------
+# XDG helpers
+# ---------------------------------------------------------------------------
+
+
+def _xdg_path(env_var: str, fallback: str) -> Path:
+    """Return $env_var if set, else $HOME/fallback."""
+    raw = os.environ.get(env_var)
+    if raw:
+        return Path(raw).expanduser()
+    return Path.home() / fallback
+
+
+def config_dir() -> Path:
+    """Return $XDG_CONFIG_HOME/alter (default ~/.config/alter)."""
+    return _xdg_path("XDG_CONFIG_HOME", ".config") / "alter"
+
+
+def cache_dir() -> Path:
+    """Return $XDG_CACHE_HOME/alter (default ~/.cache/alter)."""
+    return _xdg_path("XDG_CACHE_HOME", ".cache") / "alter"
+
+
+def state_dir() -> Path:
+    """Return $XDG_STATE_HOME/alter (default ~/.local/state/alter)."""
+    return _xdg_path("XDG_STATE_HOME", ".local/state") / "alter"
+
+
+def data_dir() -> Path:
+    """Return $XDG_DATA_HOME/alter-runtime (default ~/.local/share/alter-runtime).
+
+    The directory is created on first access with mode ``0o700`` so that the
+    ``inbox.jsonl`` cache cannot be world-read. Used by the InboxWriter
+    subscriber to persist alter-to-alter messages projected from the per-handle
+    DO SSE stream (§6.3 of *Alter-to-Alter Messaging*).
+    """
+    path = _xdg_path("XDG_DATA_HOME", ".local/share") / "alter-runtime"
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return path
+
+
+def runtime_state_dir() -> Path:
+    """Return $XDG_STATE_HOME/alter-runtime (default ~/.local/state/alter-runtime).
+
+    Distinct from :func:`state_dir` (which is the broader ``alter`` namespace
+    used by the alter-cli) - the runtime daemon owns its own state subtree so
+    that crash-recovery checkpoints (e.g. ``messaging.json``) cannot collide
+    with state written by sibling tools. Created on first access with mode
+    ``0o700``.
+    """
+    path = _xdg_path("XDG_STATE_HOME", ".local/state") / "alter-runtime"
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return path
+
+
+def keypair_path() -> Path:
+    """Path to the device Ed25519 keypair (generated by `alter-runtime init`)."""
+    return config_dir() / "keypair.json"
+
+
+def unix_socket_path() -> Path:
+    """Platform-appropriate local socket path.
+
+    On Linux we prefer $XDG_RUNTIME_DIR (which maps to /run/user/$UID on
+    systemd distros), falling back to /tmp. On macOS the socket lives under
+    Application Support because /run/user doesn't exist.
+    """
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "alter" / "runtime.sock"
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime:
+        return Path(runtime) / "alter.sock"
+    # Fallback: per-user socket under /tmp
+    uid = os.getuid() if hasattr(os, "getuid") else 0
+    return Path(f"/tmp/alter-{uid}.sock")
+
+
+# ---------------------------------------------------------------------------
+# Session (written by alter-cli, read-only here)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Session:
+    """Snapshot of the alter-cli session.json file.
+
+    Mirrors the shape from alter-cli/src/commands/login.ts:229-255.
+    """
+
+    handle: str
+    api: str
+    jwt: str
+    jwt_expires_at: str
+    consent_tier: int
+    user_id: str
+    email: str
+    orgs: list[dict[str, Any]] = field(default_factory=list)
+    id_token: str | None = None
+    refresh_token: str | None = None
+    refresh_expires_at: str | None = None
+    logged_in_at: str | None = None
+
+
+def session_path() -> Path:
+    """Path to alter-cli's session.json."""
+    override = os.environ.get("ALTER_SESSION_FILE")
+    if override:
+        return Path(override).expanduser()
+    return config_dir() / "session.json"
+
+
+def _parse_consent_tier(value: Any) -> int:
+    """Normalise ``consent_tier`` to the integer ALTER uses internally.
+
+    The alter-cli TypeScript side writes the consent tier as a string label
+    (``"L1"``, ``"L2"``, ``"L3"``, ``"L4"``) - see
+    ``packages/alter-identity/src/types.ts`` and the canonical session.json
+    written by ``alter login``. The Python runtime stores it as the numeric
+    tier. Accept both shapes plus the fallback default so a hand-edited
+    session file cannot brick the daemon.
+    """
+    if isinstance(value, bool):
+        # bool is a subclass of int - reject it explicitly to avoid
+        # True → 1 sneak-through from a typo in session.json.
+        return 1
+    if isinstance(value, int):
+        if 1 <= value <= 4:
+            return value
+        return 1
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return 1
+        # "L1".."L4" → 1..4
+        if len(stripped) == 2 and stripped[0] in ("L", "l") and stripped[1].isdigit():
+            tier = int(stripped[1])
+            if 1 <= tier <= 4:
+                return tier
+        # Raw numeric strings "1".."4" as a last resort.
+        try:
+            tier = int(stripped)
+        except ValueError:
+            return 1
+        if 1 <= tier <= 4:
+            return tier
+    return 1
+
+
+def load_session() -> Session | None:
+    """Load the alter-cli session, returning ``None`` if absent/invalid.
+
+    The daemon treats an absent session as "not yet logged in" and continues
+    running in degraded mode (can still ingest signals once the user runs
+    `alter login`).
+    """
+    path = session_path()
+    if not path.exists():
+        return None
+    try:
+        raw = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    try:
+        session = Session(
+            handle=raw["handle"],
+            api=raw.get("api", "https://api.truealter.com"),
+            jwt=raw["jwt"],
+            jwt_expires_at=raw["jwt_expires_at"],
+            consent_tier=_parse_consent_tier(raw.get("consent_tier", 1)),
+            user_id=raw.get("user_id", ""),
+            email=raw.get("email", ""),
+            orgs=list(raw.get("orgs", [])),
+            id_token=raw.get("id_token"),
+            refresh_token=raw.get("refresh_token"),
+            refresh_expires_at=raw.get("refresh_expires_at"),
+            logged_in_at=raw.get("logged_in_at"),
+        )
+    except KeyError:
+        return None
+    # M-E-1 (pentest-pass2 §6.4): reject http:// api endpoints - the subscriber
+    # POSTs session.jwt as a Bearer token; plaintext delivery is not acceptable.
+    try:
+        _require_https("session.api", session.api)
+    except ConfigError:
+        return None
+    return session
+
+
+# ---------------------------------------------------------------------------
+# Daemon configuration
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Pre-T-0 hardening (C-7 / M-J kill-switch, 2026-04-14)
+# ---------------------------------------------------------------------------
+#
+# The L3 daemon accepts IdentityEvent frames from its SSE subscriber and
+# projects them into ~/.cache/alter/identity.json and the inbox. Pre-T-0 the
+# full Ed25519 frame-signature verification (which needs a DO-side signer
+# counterpart) is out of scope for today; this module ships the *short-term*
+# kill-switch instead:
+#
+#   1.  ``http://`` endpoints are rejected with a loud error at load - TLS is
+#       not optional.
+#   2.  The ``runtime.yaml`` endpoint override (which previously let any local
+#       process swap the DO/MCP endpoint to an attacker-controlled URL) is
+#       gated behind ``ALTER_RUNTIME_DEV=1``.
+#   3.  A ``require_frame_signature`` placeholder flag is reserved so the
+#       follow-up PR that wires Ed25519 can flip it on without a config shape
+#       change.
+#
+# This block is deliberately small and documented so it can be ripped out
+# when the proper frame-signature verification lands.
+
+
+class ConfigError(RuntimeError):
+    """Raised when the loaded configuration fails a hardening invariant.
+
+    Never swallowed - if the daemon is misconfigured in a way that would
+    weaken the prompt-injection chain, we refuse to start. Louder than a log
+    line at this stage of the lifecycle.
+    """
+
+
+def _require_https(name: str, value: str) -> None:
+    """Reject any non-``https://`` endpoint at config load."""
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"{name} must be a non-empty https:// URL (got {value!r})")
+    # Normalise only for validation; the original string is kept for the
+    # httpx client so any path templating (``{handle}``) still works.
+    lowered = value.lower()
+    if lowered.startswith("http://"):
+        raise ConfigError(
+            f"{name}={value!r} uses http:// - TLS is mandatory. "
+            "Set the endpoint to an https:// URL or leave the default."
+        )
+    if not lowered.startswith("https://"):
+        raise ConfigError(
+            f"{name}={value!r} is not an https:// URL - only https:// endpoints are accepted."
+        )
+
+
+@dataclass
+class DaemonConfig:
+    """Runtime daemon configuration.
+
+    Defaults target the shipped L1 CF Worker endpoint and the backend MCP
+    fallback path per D-RT9.
+    """
+
+    # L1 primary - per-handle DO SSE endpoint template (handle is substituted at runtime)
+    do_sse_endpoint: str = "https://mcp.truealter.com/events/{handle}/stream"
+    do_state_endpoint: str = "https://mcp.truealter.com/events/{handle}/state"
+    do_ingest_endpoint: str = "https://mcp.truealter.com/events/{handle}/ingest"
+
+    # Fallback - direct MCP polling per D-RT9.
+    #
+    # ``fallback_trigger_after_seconds`` doubles as the SSE chunk read timeout
+    # in :class:`DoSseSubscriber._consume_stream`. The handle-alter Worker
+    # emits SSE keepalive comments every 25s
+    # (``cloudflare/workers/handle-alter/src/sse.ts:SSE_PING_INTERVAL_MS``),
+    # so this value MUST exceed the keepalive interval - otherwise the stall
+    # watchdog fires before any keepalive arrives, every connection is treated
+    # as stalled, and the daemon enters a tight reconnect loop (~4s/cycle =
+    # ~21,600 reconnects/day per handle, observed 2026-04-29 as 139k/day across
+    # ~blake + ~drew). 75s = 3× keepalive, absorbing one missed ping plus
+    # clock skew. If the SSE_PING_INTERVAL_MS server constant is changed,
+    # this floor must be re-derived.
+    mcp_fallback_endpoint: str = "https://api.truealter.com/api/v1/mcp"
+    fallback_poll_interval_seconds: float = 30.0
+    fallback_trigger_after_seconds: float = 75.0
+
+    # Cross-host session presence (session_presence intent + /queries/presence
+    # projection). The daemon polls on a cadence and writes a sessions.json
+    # cache file the alter monorepo's bash awareness hook reads. The writer
+    # path is on the alter monorepo (cc-broadcast.sh emits start/heartbeat,
+    # session-summary.sh emits stop). Cap-minted with the alter_org.read
+    # scope on each cycle.
+    org_alter_caps_endpoint: str = "https://api.truealter.com/api/v1/org-alter/caps"
+    org_alter_presence_endpoint: str = "https://mcp.truealter.com/orgs/alter/queries/presence"
+    session_presence_enabled: bool = True
+    session_presence_poll_interval_seconds: float = 30.0
+
+    # --- D-COORD-D2 Wave C: active-sessions DO publisher -----------------
+    #: Base URL for the per-``~handle`` Cloudflare DO Worker. The publisher
+    #: POSTs each new envelope to
+    #: ``{do_publish_url}/events/{handle}/sessions/ingest`` where
+    #: ``{handle}`` is read from the envelope payload. Trailing slashes are
+    #: stripped. Override via ``ALTER_RUNTIME_DO_PUBLISH_URL``.
+    do_publish_url: str = "https://mcp.truealter.com"
+    #: When ``True``, register :class:`ActiveSessionsDoPublisher` as a
+    #: supervised Component. Default ``True`` so the daemon ships the wire
+    #: publishing on by default; disable via
+    #: ``ALTER_RUNTIME_DO_PUBLISH_ENABLED=0`` on hosts that intentionally
+    #: run local-only. The publisher mints a cap-JWT scoped
+    #: ``alter_events.sessions.ingest`` via the backend cap-mint endpoint
+    #: using the alter-cli session.jwt - no static service-token env
+    #: variable; the credential follows the live session.
+    do_publish_enabled: bool = True
+    #: Tick interval for the publisher's tail loop. 5 s matches the rough
+    #: cadence at which CC hooks emit heartbeats, so cross-host visibility
+    #: lag stays roughly one tick + one DO round-trip. Override via
+    #: ``ALTER_RUNTIME_DO_PUBLISH_POLL_INTERVAL_SECONDS``.
+    do_publish_poll_interval_seconds: float = 5.0
+
+    # --- Active-sessions GC pass (D-COORD-D2 Wave B) ----------------------
+    #: Master toggle for the periodic GC sweep over the active-sessions
+    #: JSONL. When disabled the daemon never emits idle/terminated
+    #: transitions on its own - relies solely on tool-side
+    #: ``session_ended`` emissions.
+    active_sessions_gc_enabled: bool = True
+    #: Cadence of the GC tick. 60s is well below the default idle
+    #: threshold so a session moves from ``active`` to ``idle`` within
+    #: roughly one tick of crossing the boundary.
+    active_sessions_gc_interval_seconds: float = 60.0
+    #: A session whose ``last_activity`` is older than this is folded
+    #: from ``active`` to ``idle``. 5 minutes matches the existing
+    #: heartbeat cadence ceiling.
+    active_sessions_idle_after_seconds: float = 300.0
+    #: A session whose ``last_activity`` is older than this is folded
+    #: to ``complete``. For ``tool == "cc"`` the PID is additionally
+    #: probed via ``os.kill(pid, 0)`` - only dead PIDs are reaped.
+    active_sessions_terminated_after_seconds: float = 900.0
+
+    # Socket server
+    unix_socket: Path = field(default_factory=unix_socket_path)
+    enable_dbus: bool = sys.platform.startswith("linux")
+
+    # Cache
+    cache_ttl_seconds: int = 300  # matches scripts/alter-identity.sh CACHE_TTL
+
+    # Telemetry
+    log_level: str = "INFO"
+
+    # --- Claude Code JSONL token-usage watcher ---------------------------
+    #: When ``True``, register :class:`ClaudeJsonlWatcher` as a supervised
+    #: Component. Opt-in (default ``False``) because not every principal's
+    #: machine needs ops token-usage telemetry, and the watcher requires a
+    #: valid session JWT to POST events to the backend. Enable via env var
+    #: ``ALTER_RUNTIME_CLAUDE_JSONL_WATCHER=1`` or direct config mutation.
+    enable_claude_jsonl_watcher: bool = False
+
+    # --- Hardening (C-1 / C-7 frame-signature enforcement) --------------
+    #: When ``True``, every SSE frame received by :class:`DoSseSubscriber`
+    #: MUST carry a valid Ed25519 signature over the canonical (JCS-style
+    #: stable-key-sorted) JSON bytes of the payload with the ``signature``
+    #: field removed. Frames that are unsigned, carry a malformed signature,
+    #: declare a ``pubkey`` that differs from the pinned
+    #: :attr:`frame_signature_pubkey`, or fail Ed25519 verification are
+    #: dropped with a structured warning log; counters on the subscriber's
+    #: :class:`_ConnectionState` record each drop class.
+    #:
+    #: Default is ``True`` post-pentest 2026-04-26 - operators must now
+    #: deliberately disable enforcement (``ALTER_RUNTIME_REQUIRE_FRAME_SIG=0``)
+    #: rather than silently inheriting the migration-window pass-through. The
+    #: subscriber refuses to construct when enforcement is on without a pinned
+    #: pubkey (see C-1 kill-switch in ``do_sse.py``), so flipping the default
+    #: to ``True`` forces operators to either provide
+    #: ``ALTER_RUNTIME_FRAME_SIG_PUBKEY`` or explicitly opt out - preferable
+    #: to the previous failure mode where unsigned frames were accepted by
+    #: default if the operator forgot to flip the flag at deploy time.
+    #:
+    #: Disable via ``ALTER_RUNTIME_REQUIRE_FRAME_SIG=0`` (only valid during
+    #: the DO-side signer migration window).
+    require_frame_signature: bool = True
+
+    #: Pinned Sovereign-tier Ed25519 public key for the DO emitting the SSE
+    #: stream. Expected format: ``ed25519:<base64url>`` matching the
+    #: canonical-fragment envelope convention. When
+    #: :attr:`require_frame_signature` is ``True`` this MUST be set - the
+    #: subscriber refuses to construct otherwise (see C-7 kill-switch
+    #: pattern) to prevent self-certifying-frame attacks where a frame's
+    #: declared pubkey is trusted solely on its own authority.
+    #:
+    #: Override via ``ALTER_RUNTIME_FRAME_SIG_PUBKEY``.
+    #:
+    #: Follow-up: the durable source of truth is the DO's ``/state``
+    #: endpoint (returns the current envelope with epoch-rotating pubkey);
+    #: a future PR fetches it on subscriber start-up and pins dynamically.
+    #: Static env-var pin is the interim trust root.
+    frame_signature_pubkey: str | None = None
+
+    # --- D-AUTOUPDATE-1 daemon update loop (Phase 1 observation only) -----
+    #: Master toggle for the auto-update poll loop. Default ``True`` per
+    #: D-AUTOUPDATE-1 — install-once-never-think-about-it is the shipped
+    #: posture. Operators flip to ``False`` (``ALTER_RUNTIME_AUTOUPDATE=0``)
+    #: when they want zero outbound polling — e.g. air-gapped fleets, or
+    #: integration tests that don't want a phantom network call.
+    #:
+    #: Phase 1 scope: the loop only polls + logs. Download, signature
+    #: verification, and atomic-replace land in Phase 2+. Disabling at
+    #: Phase 1 saves a periodic HTTPS round-trip to releases.truealter.com.
+    autoupdate_enabled: bool = True
+    #: Override the manifest URL. Defaults to the production substrate. Used
+    #: by integration tests to point at ``releases-staging.truealter.com``
+    #: once that ingest path exists. Override via
+    #: ``ALTER_RUNTIME_AUTOUPDATE_MANIFEST_URL``.
+    autoupdate_manifest_url: str = "https://releases.truealter.com/manifest.json"
+    #: Poll cadence in seconds. 24h matches DR §2 (every-UTC-midnight ± jitter).
+    #: Lower in dev to exercise the loop quickly. Override via
+    #: ``ALTER_RUNTIME_AUTOUPDATE_POLL_INTERVAL_SECONDS``.
+    autoupdate_poll_interval_seconds: int = 24 * 60 * 60
+
+    @classmethod
+    def load(cls) -> DaemonConfig:
+        """Load config from environment + YAML file + defaults.
+
+        Raises
+        ------
+        ConfigError
+            If any endpoint is non-``https://`` after env/YAML overrides,
+            or if the YAML override is present without ``ALTER_RUNTIME_DEV=1``.
+        """
+        config = cls()
+        # Environment overrides
+        if endpoint := os.environ.get("ALTER_DO_SSE_ENDPOINT"):
+            config.do_sse_endpoint = endpoint
+        if endpoint := os.environ.get("ALTER_DO_STATE_ENDPOINT"):
+            config.do_state_endpoint = endpoint
+        if endpoint := os.environ.get("ALTER_DO_INGEST_ENDPOINT"):
+            config.do_ingest_endpoint = endpoint
+        if endpoint := os.environ.get("ALTER_MCP_FALLBACK_ENDPOINT"):
+            config.mcp_fallback_endpoint = endpoint
+        if endpoint := os.environ.get("ALTER_ORG_ALTER_CAPS_ENDPOINT"):
+            config.org_alter_caps_endpoint = endpoint
+        if endpoint := os.environ.get("ALTER_ORG_ALTER_PRESENCE_ENDPOINT"):
+            config.org_alter_presence_endpoint = endpoint
+        _sp_flag = os.environ.get("ALTER_SESSION_PRESENCE_ENABLED", "").lower()
+        if _sp_flag in ("0", "false", "no", "off"):
+            config.session_presence_enabled = False
+        elif _sp_flag in ("1", "true", "yes", "on"):
+            config.session_presence_enabled = True
+        if interval := os.environ.get("ALTER_SESSION_PRESENCE_POLL_INTERVAL_SECONDS"):
+            try:
+                config.session_presence_poll_interval_seconds = float(interval)
+            except ValueError:
+                pass  # Ignore malformed override; default stands.
+
+        # --- D-COORD-D2 Wave C: active-sessions DO publisher -------------
+        if publish_url := os.environ.get("ALTER_RUNTIME_DO_PUBLISH_URL"):
+            config.do_publish_url = publish_url
+        _dpe_flag = os.environ.get("ALTER_RUNTIME_DO_PUBLISH_ENABLED", "").lower()
+        if _dpe_flag in ("0", "false", "no", "off"):
+            config.do_publish_enabled = False
+        elif _dpe_flag in ("1", "true", "yes", "on"):
+            config.do_publish_enabled = True
+        if dpi := os.environ.get("ALTER_RUNTIME_DO_PUBLISH_POLL_INTERVAL_SECONDS"):
+            try:
+                config.do_publish_poll_interval_seconds = float(dpi)
+            except ValueError:
+                pass
+
+        # --- Active-sessions GC pass (D-COORD-D2 Wave B) -----------------
+        _gc_flag = os.environ.get("ALTER_ACTIVE_SESSIONS_GC_ENABLED", "").lower()
+        if _gc_flag in ("0", "false", "no", "off"):
+            config.active_sessions_gc_enabled = False
+        elif _gc_flag in ("1", "true", "yes", "on"):
+            config.active_sessions_gc_enabled = True
+        if gc_interval := os.environ.get("ALTER_ACTIVE_SESSIONS_GC_INTERVAL_SECONDS"):
+            try:
+                config.active_sessions_gc_interval_seconds = float(gc_interval)
+            except ValueError:
+                pass  # Ignore malformed override; default stands.
+        if idle_after := os.environ.get("ALTER_ACTIVE_SESSIONS_IDLE_AFTER_SECONDS"):
+            try:
+                config.active_sessions_idle_after_seconds = float(idle_after)
+            except ValueError:
+                pass
+        if terminated_after := os.environ.get("ALTER_ACTIVE_SESSIONS_TERMINATED_AFTER_SECONDS"):
+            try:
+                config.active_sessions_terminated_after_seconds = float(terminated_after)
+            except ValueError:
+                pass
+
+        # --- D-AUTOUPDATE-1 daemon update loop ---------------------------
+        _au_flag = os.environ.get("ALTER_RUNTIME_AUTOUPDATE", "").lower()
+        if _au_flag in ("0", "false", "no", "off"):
+            config.autoupdate_enabled = False
+        elif _au_flag in ("1", "true", "yes", "on"):
+            config.autoupdate_enabled = True
+        if au_url := os.environ.get("ALTER_RUNTIME_AUTOUPDATE_MANIFEST_URL"):
+            config.autoupdate_manifest_url = au_url
+        if au_interval := os.environ.get("ALTER_RUNTIME_AUTOUPDATE_POLL_INTERVAL_SECONDS"):
+            try:
+                config.autoupdate_poll_interval_seconds = int(au_interval)
+            except ValueError:
+                pass
+
+        if level := os.environ.get("ALTER_RUNTIME_LOG_LEVEL"):
+            config.log_level = level
+        if socket := os.environ.get("ALTER_RUNTIME_SOCKET"):
+            config.unix_socket = Path(socket).expanduser()
+        _cjw_flag = os.environ.get("ALTER_RUNTIME_CLAUDE_JSONL_WATCHER", "").lower()
+        if _cjw_flag in ("1", "true", "yes", "on"):
+            config.enable_claude_jsonl_watcher = True
+        elif _cjw_flag in ("0", "false", "no", "off"):
+            config.enable_claude_jsonl_watcher = False
+        # Post-pentest-2026-04-26: default is True. Env var still toggles -
+        # explicit "0"/"false"/"no"/"off" disables (migration-window opt-out),
+        # everything else (including unset) keeps the default True.
+        #
+        # Pentest S3-W-1 production-lock (2026-05-09): the opt-out is only
+        # valid when ALTER_RUNTIME_DEV=1 is also set. In any non-dev
+        # environment (ALTER_RUNTIME_DEV unset or not "1"/"true"/"yes") the
+        # =0 value is silently overridden back to True and a structured
+        # warning is emitted. This prevents a compromised or misconfigured
+        # env from disabling frame-signature enforcement in production.
+        _dev_mode = os.environ.get("ALTER_RUNTIME_DEV", "").lower() in (
+            "1",
+            "true",
+            "yes",
+        )
+        _flag = os.environ.get("ALTER_RUNTIME_REQUIRE_FRAME_SIG", "").lower()
+        if _flag in ("0", "false", "no", "off"):
+            if _dev_mode:
+                config.require_frame_signature = False
+            else:
+                # Production-lock: refuse the opt-out outside of dev mode.
+                import logging as _logging
+
+                _logging.getLogger(__name__).warning(
+                    "ALTER_RUNTIME_REQUIRE_FRAME_SIG=0 ignored - opt-out is "
+                    "only permitted when ALTER_RUNTIME_DEV=1 is set. "
+                    "Frame-signature enforcement remains ENABLED. "
+                    "If this is a migration-window deployment, set "
+                    "ALTER_RUNTIME_DEV=1 explicitly."
+                )
+                config.require_frame_signature = True
+        elif _flag in ("1", "true", "yes", "on"):
+            config.require_frame_signature = True
+        if pubkey := os.environ.get("ALTER_RUNTIME_FRAME_SIG_PUBKEY"):
+            config.frame_signature_pubkey = pubkey
+
+        # YAML file overrides - gated behind ALTER_RUNTIME_DEV=1 (C-7 / M-J).
+        # Previously any local process could drop a runtime.yaml onto disk
+        # and swap do_sse_endpoint to an attacker-controlled URL, which fed
+        # unverified events into every CC session's system message. The
+        # dev-only gate closes that path for shipped builds until the
+        # Ed25519-signed config file format lands.
+        yaml_path = config_dir() / "runtime.yaml"
+        if yaml_path.exists():
+            dev_mode = os.environ.get("ALTER_RUNTIME_DEV", "").lower() in (
+                "1",
+                "true",
+                "yes",
+            )
+            if not dev_mode:
+                raise ConfigError(
+                    f"{yaml_path} present but ALTER_RUNTIME_DEV is not set. "
+                    "File-based endpoint overrides are dev-only pre-T-0 - "
+                    "remove the file, set endpoints via ALTER_*_ENDPOINT env "
+                    "vars, or export ALTER_RUNTIME_DEV=1 explicitly."
+                )
+            try:
+                import yaml  # imported lazily so tests without PyYAML still run
+
+                with yaml_path.open("r") as f:
+                    data = yaml.safe_load(f) or {}
+                for key, value in data.items():
+                    if hasattr(config, key):
+                        setattr(config, key, value)
+            except ImportError:
+                # PyYAML not installed - surface loudly in dev mode so the
+                # operator knows their override was ignored.
+                raise
+            except OSError:
+                # Readable-but-broken YAML is swallowed (same as pre-harden
+                # behaviour) - avoids a disk-error crash loop in dev.
+                pass
+
+        # --- Post-override invariant checks -----------------------------
+        _require_https("do_sse_endpoint", config.do_sse_endpoint)
+        _require_https("do_state_endpoint", config.do_state_endpoint)
+        _require_https("do_ingest_endpoint", config.do_ingest_endpoint)
+        _require_https("mcp_fallback_endpoint", config.mcp_fallback_endpoint)
+        _require_https("org_alter_caps_endpoint", config.org_alter_caps_endpoint)
+        _require_https("org_alter_presence_endpoint", config.org_alter_presence_endpoint)
+        _require_https("do_publish_url", config.do_publish_url)
+
+        return config
+
+
+def load_config() -> DaemonConfig:
+    """Public entrypoint - load daemon configuration."""
+    return DaemonConfig.load()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def ensure_directories() -> None:
+    """Create required XDG directories if they don't exist.
+
+    Called by `alter-runtime init` and at daemon startup so that subsequent
+    writes don't fail with FileNotFoundError.
+    """
+    for d in (config_dir(), cache_dir(), state_dir()):
+        d.mkdir(parents=True, exist_ok=True, mode=0o700)
+    socket_path = unix_socket_path()
+    socket_path.parent.mkdir(parents=True, exist_ok=True)