froid-loop 0.11.1__py3-none-any.whl

froid_loop/envvars.py

@@ -0,0 +1,111 @@
+"""Central registry of the ``FROID_LOOP_*`` runtime environment variables.
+
+These operator/test override knobs used to be read inline at scattered call
+sites (`engine`, `adapters.multiplexer`, `cli`, `process_host`), which left them
+undiscoverable and undocumented. This module is the one place each is named,
+typed, and given a reader; the operator-facing table lives in the README under
+"Environment variables".
+
+Each reader preserves its call site's exact semantics — same parse, same
+fallback — so routing a site through here changes nothing observable. Only the
+core operator/test knobs belong here (the count is deliberately not stated — it
+has already changed once); the `FROID_LOOP_UNITY_*` / `FROID_LOOP_ENGINE_*` family
+read by the bundled Unity plugin's stand-alone helper scripts is that plugin's
+own contract (documented in the game-engine guide) and stays with it. Nor do the
+session-protocol vars the engine *injects* into a child session
+(`FROID_LOOP_RUN_DIR`, `FROID_LOOP_TASK_ID`, …): those have a producing side inside
+the orchestrator, and the stdlib-only relays that read them back cannot import
+this module at all.
+
+Note what the carve-out is and is not: "has a producing side" does not qualify a
+name, "is read only by a stdlib-only relay that cannot import this module" does.
+Anything core orchestration reads back belongs here, and
+`test_portability_guard.test_froid_loop_env_reads_only_in_the_registry` is the
+enforced form of that rule.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+
+#: Overrides the per-session wall-clock budget, in seconds (test / E2E hook).
+SESSION_TIMEOUT_S = "FROID_LOOP_SESSION_TIMEOUT_S"
+#: Forces the terminal-multiplexer backend by registered name.
+MUX_BACKEND = "FROID_LOOP_MUX_BACKEND"
+#: Forces the process-host implementation by registered name (test / override).
+PROCESS_HOST = "FROID_LOOP_PROCESS_HOST"
+#: Overrides the user-scoped state root that per-run control-plane state lives
+#: under (see :func:`runs.state_root`), replacing the whole platform cascade.
+STATE_DIR = "FROID_LOOP_STATE_DIR"
+
+
+def session_timeout_s() -> float | None:
+    """The per-session wall-clock override in seconds, or ``None`` when unset.
+
+    Anything that is not a finite positive number of seconds reads as ``None``
+    (ignored), and the guard is deliberately two-sided. Rejecting zero and
+    negatives keeps a fat-fingered override from silently *shortening* a real
+    run's budget; rejecting non-finite values keeps ``inf`` / ``1e999`` /
+    ``Infinity`` — all of which ``float()`` accepts and all of which pass a bare
+    ``> 0`` — from silently *removing* it. That second half matters more than it
+    looks: both adapters build their monotonic and wall-clock deadlines by
+    adding this to the current time, so a non-finite budget yields a deadline
+    that can never expire, and this is the outer bound every stall-grace and
+    wake-nudge window defers to. Losing it means an unattended run can wedge
+    with no backstop left.
+
+    A very large *finite* value is still honoured. It is a duration, however
+    unwise, and an operator asking for one is expressing intent; ``inf`` is not
+    a duration at all.
+    """
+    raw = os.environ.get(SESSION_TIMEOUT_S)
+    if raw is None:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    if not math.isfinite(value) or value <= 0:
+        return None
+    return value
+
+
+def mux_backend() -> str | None:
+    """The forced terminal-multiplexer backend name, or ``None`` when unset.
+
+    Returned verbatim (callers test truthiness and resolve the name), so the
+    forced-selection semantics match the raw env read exactly.
+    """
+    return os.environ.get(MUX_BACKEND)
+
+
+def process_host() -> str | None:
+    """The forced process-host name, or ``None`` when unset."""
+    return os.environ.get(PROCESS_HOST)
+
+
+def state_dir() -> str | None:
+    """The overriding froid-loop state root, or ``None`` when unset.
+
+    Verbatim like the two name readers above — :func:`runs.state_root` uses the
+    value as the state root itself, so an operator who names a directory gets that
+    directory. Silently ignoring a stated override in favour of the platform
+    cascade would be the same failure :func:`mux_backend` refuses: a loud
+    misconfiguration turned into a quiet auto-select, discoverable only by
+    noticing where a run's events did *not* appear.
+
+    Reading verbatim is not the same as accepting anything: this reader reports
+    what is set, and :func:`runs.state_root` judges it. A **relative** value is
+    refused there rather than resolved, because the root is read by two processes
+    with different working directories — see that function for the full reason.
+    The split is deliberate; a reader that silently rewrote its variable would
+    make the refusal impossible to state.
+
+    The one value not passed through is the empty string, which reads as unset.
+    ``export FROID_LOOP_STATE_DIR=`` is what an unset-looking export leaves behind,
+    and it is not a directory an operator can have meant: ``Path("")`` is the
+    *current directory*, so honouring it would silently root the control plane at
+    whatever cwd the loop happened to be launched from.
+    """
+    return os.environ.get(STATE_DIR) or None

froid_loop/escalation.py

@@ -0,0 +1,225 @@
+"""Retry budgets and typed escalation.
+
+CRITICAL escalations pause the run for a human; PREFERENCE escalations are
+journaled and the run continues. Exhausted budgets plateau-defer: the story
+is skipped and the run stays alive.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from .adapters.base import SessionResult
+from .model import StoryTask, VerifyOutcome
+from .policy import Policy
+
+SEVERITY_CRITICAL = "CRITICAL"
+SEVERITY_PREFERENCE = "PREFERENCE"
+
+
+class Action(StrEnum):
+    PROCEED = "proceed"
+    RETRY = "retry"
+    DEFER = "defer"
+    PAUSE = "pause"
+    # review.on_timeout = "salvage-if-done" only (#271): the engine attempts to
+    # commit the already-finalized dev product instead of burning another review
+    # cycle; when salvage is not applicable it falls back through
+    # `review_retry_or_exhaust`. Produced only by `decide_review_session`.
+    SALVAGE = "salvage"
+
+
+# Timeout-like review verdicts review.on_timeout governs (#271): deliberately the
+# same set `_post_kill_reconcile` treats as rescue-eligible. `crashed` is excluded
+# — a hard window death is cheap to retry and already honors on-disk artifacts via
+# the crash-path read-back — and env-fault (#194) short-circuits before this.
+REVIEW_TIMEOUT_STATUSES = frozenset({"timeout", "stalled", "over_budget"})
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: Action
+    reason: str = ""
+
+
+def critical_escalations(result_json: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not result_json:
+        return []
+    return [
+        e
+        for e in result_json.get("escalations", [])
+        if isinstance(e, dict) and str(e.get("severity", "")).upper() == SEVERITY_CRITICAL
+    ]
+
+
+def preference_escalations(result_json: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not result_json:
+        return []
+    return [
+        e
+        for e in result_json.get("escalations", [])
+        if isinstance(e, dict) and str(e.get("severity", "")).upper() != SEVERITY_CRITICAL
+    ]
+
+
+def env_fault_detail(result: SessionResult) -> str:
+    """The evidence excerpt for an environment-fault pause reason, or a generic
+    fallback when the adapter classified a fault but kept no line (#194). Shared
+    by every site that pauses a transport-failed session — dev/review here, plus
+    fix/workflow/sweep in the engine — so the reason wording stays uniform:
+    ``environment fault: <role> session <status> (<detail>)``."""
+    return result.env_fault_evidence or "transport-failure pattern in session log"
+
+
+def env_fault_pause_reason(role: str, result: SessionResult) -> str:
+    """The uniform pause/escalation reason for a transport-failed session (#194).
+    `role` is the descriptor placed before "session" — e.g. "dev", "review",
+    "fix", "migration", "triage", or a richer "blocking workflow 'x' (y)". Keeps
+    the wording identical across escalation/engine/sweep (see env_fault_detail).
+
+    Composed over `session_failure_reason` so the two diagnoses cannot cancel
+    each other out (#489): `crashed` is in `ENV_FAULT_STATUSES`, and both deciders
+    test `env_fault` FIRST, so a session destroyed under the run whose pane-log
+    tail also matches a transport pattern would otherwise pause blaming only the
+    provider. Both facts hold and the operator needs both — a lost session is not
+    evidence about the API, and a log pattern is not evidence the session
+    survived."""
+    return f"environment fault: {session_failure_reason(role, result)} ({env_fault_detail(result)})"
+
+
+def session_failure_reason(role: str, result: SessionResult) -> str:
+    """The reason text for a non-completed session: ``<role> session <status>``,
+    plus the lost-session diagnosis (#489).
+
+    Without the suffix a session destroyed under the run reads exactly like a CLI
+    that ran and produced nothing, and the operator debugs the agent instead of
+    the host. Routing is unchanged either way — the verdict was already correct,
+    only its explanation was missing.
+
+    Only a ``crashed`` verdict can ever carry the suffix (``session_vanished`` is
+    stamped nowhere else), so on the timeout/stall paths the suffix never appears.
+
+    The wording states what the evidence *withdraws*, not what it proves. All the
+    probe establishes is that a session lookup came back negative — see
+    ``TerminalMultiplexer.has_session``, whose False is "the backend did not
+    confirm it", not "the session provably no longer exists". That is enough to
+    stop an operator reading window death as a CLI exit, and not enough to assert
+    the session was destroyed."""
+    reason = f"{role} session {result.status}"
+    if result.session_vanished:
+        return (
+            f"{reason}: the multiplexer no longer reports the session, so the window's "
+            "disappearance is not evidence the CLI exited"
+        )
+    return reason
+
+
+def decide_dev(
+    task: StoryTask,
+    result: SessionResult,
+    outcome: VerifyOutcome | None,
+    policy: Policy,
+) -> Decision:
+    """After a dev session (and its verification, when the session completed)."""
+    crits = critical_escalations(result.result_json)
+    if crits:
+        details = "; ".join(str(e.get("detail", e.get("type", "?"))) for e in crits)
+        return Decision(Action.PAUSE, f"CRITICAL escalation from dev session: {details}")
+
+    budget_left = task.attempt < policy.limits.max_dev_attempts
+    exhausted = _exhausted_action(task)
+
+    if result.status != "completed":
+        if result.env_fault:
+            # A transport/API failure (the CLI never reached the API, #194): the
+            # attempt did no real work, so pause for a human instead of charging
+            # it — re-arm resets the budget, exactly like a verify env-fault (rc
+            # 126/127). The crits check above already ran (env-fault results carry
+            # result_json=None, so it found nothing).
+            return Decision(
+                Action.PAUSE,
+                env_fault_pause_reason("dev", result),
+            )
+        reason = session_failure_reason("dev", result)
+        if budget_left:
+            return Decision(Action.RETRY, reason)
+        return Decision(exhausted, _exhaust_reason(task, reason))
+
+    assert outcome is not None
+    if outcome.ok:
+        return Decision(Action.PROCEED)
+    if outcome.severity == SEVERITY_CRITICAL:
+        return Decision(Action.PAUSE, outcome.reason)
+    if budget_left:
+        return Decision(Action.RETRY, outcome.reason)
+    return Decision(exhausted, _exhaust_reason(task, outcome.reason))
+
+
+def decide_review_session(task: StoryTask, result: SessionResult, policy: Policy) -> Decision:
+    """After a review session returns, before interpreting its done/followup status."""
+    crits = critical_escalations(result.result_json)
+    if crits:
+        details = "; ".join(str(e.get("detail", e.get("type", "?"))) for e in crits)
+        return Decision(Action.PAUSE, f"CRITICAL escalation from review session: {details}")
+
+    if result.status != "completed":
+        if result.env_fault:
+            # transport/API failure (#194): pause rather than charge a review
+            # cycle for a session that never reached the API (see decide_dev).
+            return Decision(
+                Action.PAUSE,
+                env_fault_pause_reason("review", result),
+            )
+        reason = session_failure_reason("review", result)
+        if result.status in REVIEW_TIMEOUT_STATUSES:
+            mode = policy.review.on_timeout
+            if mode == "defer":
+                return Decision(
+                    _exhausted_action(task),
+                    _exhaust_reason(task, f"{reason} (review.on_timeout=defer)"),
+                )
+            if mode == "salvage-if-done":
+                return Decision(Action.SALVAGE, reason)
+        return review_retry_or_exhaust(task, policy, reason)
+    return Decision(Action.PROCEED)
+
+
+def review_retry_or_exhaust(task: StoryTask, policy: Policy, reason: str) -> Decision:
+    """The default routing for a failed review session: RETRY while the outer
+    cycle budget lasts, then plateau-defer (or re-escalate mid re-drive). Module-
+    level so the engine can fall back through it when a SALVAGE attempt turns out
+    not to be applicable (#271)."""
+    if task.review_cycle < policy.limits.max_review_cycles:
+        return Decision(Action.RETRY, reason)
+    return review_exhausted(task, reason)
+
+
+def review_exhausted(task: StoryTask, reason: str) -> Decision:
+    """Terminal review-side failure routing without spending another session.
+
+    Used when a deterministic post-review repair has exhausted its own local
+    retry bound and launching another reviewer would be unsafe. It preserves the
+    same resolved-CRITICAL re-drive rule as ordinary review-budget exhaustion.
+    """
+    return Decision(_exhausted_action(task), _exhaust_reason(task, reason))
+
+
+def _exhausted_action(task: StoryTask) -> Action:
+    """What a budget-exhausted, non-CRITICAL failure resolves to. Normally a
+    plateau-defer (skip the story, keep the run alive). But a story mid re-drive
+    of a human-resolved CRITICAL escalation (``resolved_redrive`` latched, not
+    yet re-committed) must NOT silently downgrade to a defer — that would file an
+    unresolved escalation as deferred work and roll back the human's correction.
+    Re-escalate so the human sees it again; ``_escalate`` preserves the tree."""
+    return Action.PAUSE if task.resolved_redrive else Action.DEFER
+
+
+def _exhaust_reason(task: StoryTask, reason: str) -> str:
+    if task.resolved_redrive:
+        return (
+            "resolved-escalation re-drive did not converge — re-escalating "
+            f"instead of deferring: {reason}"
+        )
+    return reason

froid_loop/events.py

@@ -0,0 +1,266 @@
+"""Importable twin of the hardened event write in ``data/froid_loop_hook.py``.
+
+The hook script is COPIED into every target project and runs inside the coding
+CLI's process under whatever interpreter the host has, so it is stdlib-only by
+contract (its docstring says so) and cannot import ``froid_loop`` to reach this
+module — and this module cannot import it back, since it ships as package DATA
+rather than as an importable module. Hence a twin rather than shared code:
+``_LINK_REPARSE_TAGS``, ``_first_workspace``, ``_is_link_like``, ``_write_all``
+and ``_write_event`` below are byte-identical copies of the hook's, pinned that
+way by ``tests/test_events.py::test_the_twinned_source_is_identical`` — which
+AST-extracts both sides and compares the source segments, so a fix applied to one
+writer of the events control plane and not the other cannot pass review silently.
+
+Because they are byte-identical, their docstrings and comments are written from
+the hook script's vantage point ("this relay runs under whatever interpreter the
+host has") and stay that way on purpose: rewording either side to suit its own
+file breaks parity, and diverging is exactly what two separately-hardened writers
+of one control plane must not do. What the shared text says about the attack, the
+platform branches, and the residual Windows windows holds for both.
+
+The rest of the module is this side's own: the payload shaping the hook does
+inline in its ``main()``, and :func:`relay`, which backs ``froid-loop relay
+<Event>`` — the #461 Phase 2 hook target, an installed console script instead of
+a file path inside the workspace that a branch switch can take away.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import time
+from typing import IO, Any
+
+# Windows reparse tags that make a directory entry REDIRECT somewhere else,
+# compared against os.lstat().st_reparse_tag (Windows, 3.8+). Deliberately not
+# os.path.isjunction(), which is 3.12+ — this relay runs under whatever
+# interpreter the host has, not under the orchestrator's. Deliberately not "any
+# reparse tag" either: cloud placeholders (OneDrive) and dedup stubs are reparse
+# points too, and refusing those would stall a legitimate run. Empty on POSIX.
+_LINK_REPARSE_TAGS = tuple(
+    tag
+    for tag in (
+        getattr(stat, "IO_REPARSE_TAG_SYMLINK", None),
+        getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", None),
+    )
+    if tag is not None
+)
+
+
+def _first_workspace(payload):
+    paths = payload.get("workspacePaths")
+    if isinstance(paths, list) and paths and isinstance(paths[0], str):
+        return paths[0]
+    return None
+
+
+def _is_link_like(path):
+    """True when `path` redirects elsewhere: a POSIX symlink, or a Windows
+    symlink OR DIRECTORY JUNCTION.
+
+    `os.path.islink()` is False for a junction — junctions are a distinct
+    reparse kind, which is why `os.path.isjunction()` exists at all. On Windows
+    the junction is the arm that matters: `mklink /J` needs no elevation, while
+    a directory symlink needs SeCreateSymbolicLinkPrivilege or Developer Mode —
+    so the unprivileged attack is exactly the one `islink()` misses.
+    """
+    if os.path.islink(path):
+        return True
+    try:
+        return getattr(os.lstat(path), "st_reparse_tag", 0) in _LINK_REPARSE_TAGS
+    except OSError:
+        return False
+
+
+def _write_all(fd, data):
+    """Write every byte of `data` to `fd`.
+
+    `os.write()` may write FEWER bytes than asked and simply return the count. A
+    truncated event file is not merely retried, it is lost: `SignalWatcher.poll`
+    adds a filename to its consumed set BEFORE parsing it (signals.py), so
+    malformed JSON is skipped and never re-read — the session's Stop signal is
+    gone for good and the run waits out `session_timeout_min`. The buffered
+    `open()` this replaced looped internally; the raw fd needed for
+    O_NOFOLLOW/dir_fd does not, so loop here.
+    """
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        if written <= 0:  # not observed in practice; a spinning hook is worse
+            raise OSError("short write to the event file")
+        view = view[written:]
+
+
+def _write_event(events_dir, name, event):
+    """Write one event file into `events_dir`, refusing to follow a redirect.
+
+    The events dir is the orchestrator's control plane. A driven session has
+    write access to the project, so it could plant `<run_dir>/events` as a
+    symlink (or, on Windows, a junction) and redirect — or swallow — the
+    completion signal, stalling the run to `session_timeout_min` instead of
+    completing. `os.makedirs(exist_ok=True)` `isdir()`-checks THROUGH such a
+    link, so the refusal has to come before it. That refusal works on every
+    platform.
+
+    Where the platform has them, the create+replace is anchored to a dir_fd
+    opened O_NOFOLLOW: every later operation goes through that fd, so a swap
+    after the check cannot reach the write. Windows has neither
+    O_NOFOLLOW/O_DIRECTORY nor a handle-relative open (`os.supports_dir_fd` is
+    empty — dir_fd is implemented with the POSIX `*at` calls), so its fallback
+    re-resolves the path and the check-to-write window stays open there. It is
+    NARROWED, not closed: the redirect check runs again after the payload is
+    written and before it is published, so a swap still in place is refused and
+    the temp file removed. Two windows stay open on that path (#494), both
+    measured: a swap-and-restore around the create is undetectable from stdlib
+    Python, and a swap landing after the second check leaves the path-based
+    publish unable to find the temp file it wrote — it either raises or renames
+    a file the attacker planted inside the attacker's own directory. Neither
+    redirects the payload, and both end where a refusal ends: no event, so the
+    run waits out session_timeout_min. That is the same outcome an attacker gets
+    for free by leaving a redirect in place, which is refused without any race —
+    winning the race buys no capability, which is why the residual is accepted
+    rather than chased into ctypes/NtCreateFile inside a stdlib-only relay.
+
+    Mode is 0o600 (narrowed from the umask-derived mode an ordinary `open()`
+    produced): only the operator running the loop reads these.
+
+    Raises OSError on any refusal or failure; the caller degrades to a no-op.
+    """
+    if _is_link_like(events_dir):
+        raise OSError(f"refusing to write events into a redirected directory: {events_dir}")
+    os.makedirs(events_dir, exist_ok=True)
+    data = json.dumps(event).encode("utf-8")
+    tmp = name + ".tmp"
+    o_nofollow = getattr(os, "O_NOFOLLOW", 0)
+    o_directory = getattr(os, "O_DIRECTORY", 0)
+    # O_BINARY is a no-op flag on POSIX; on Windows it stops the fd from
+    # newline-translating what os.write() puts through it.
+    create = os.O_WRONLY | os.O_CREAT | os.O_EXCL | o_nofollow | getattr(os, "O_BINARY", 0)
+    # Probe os.rename, not os.replace: CPython omits os.replace from
+    # supports_dir_fd on Linux even though it accepts src_dir_fd/dst_dir_fd, so
+    # probing it would leave this whole branch dead everywhere. This branch is
+    # POSIX-only by construction, and there rename(2) IS the atomic-replace
+    # primitive os.replace wraps — probe the function actually called.
+    if o_nofollow and o_directory and {os.open, os.rename} <= os.supports_dir_fd:
+        dir_fd = os.open(events_dir, os.O_RDONLY | o_directory | o_nofollow)
+        try:
+            fd = os.open(tmp, create, 0o600, dir_fd=dir_fd)
+            try:
+                _write_all(fd, data)
+            finally:
+                os.close(fd)
+            os.rename(tmp, name, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+        finally:
+            os.close(dir_fd)
+        return
+    # Fallback (Windows): no dir_fd to anchor to, so the create below re-resolves
+    # events_dir by path. A swap into a junction between the check above and this
+    # create would have put the temp file inside the attacker's directory. Check
+    # again before publishing, so a swap that is still in place is refused rather
+    # than followed — the realistic shape, since a junction has to persist to
+    # capture the events the attacker is after.
+    tmp_path = os.path.join(events_dir, tmp)
+    fd = os.open(tmp_path, create, 0o600)
+    try:
+        _write_all(fd, data)
+    finally:
+        os.close(fd)
+    if _is_link_like(events_dir):
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise OSError(f"events directory was redirected mid-write: {events_dir}")
+    os.replace(tmp_path, os.path.join(events_dir, name))
+
+
+# --------------------------------------------------------------- this side only
+
+
+def event_file_name(ts: int, task_id: str, event_name: str) -> str:
+    """The event file's name. Sorted-by-time by construction (``ts`` first, fixed
+    width in practice), and carrying the task id so ``SignalWatcher`` can attribute
+    a file without opening it. Mirrors the hook's f-string exactly; the twin above
+    stops at the write, so this and :func:`shape_event` are pinned behaviorally
+    instead (``test_relay_and_hook_produce_the_same_event``)."""
+    return f"{ts}-{task_id}-{event_name}.json"
+
+
+def shape_event(ts: int, event_name: str, task_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    """The event record the orchestrator consumes, built from one hook payload."""
+    return {
+        "ts": ts,
+        "event": event_name,
+        "task_id": task_id,
+        # Payload keys vary by CLI: snake_case (claude/codex), conversation_id
+        # (cursor), or camelCase (copilot's sessionId/transcriptPath, agy's
+        # conversationId). Try each.
+        "session_id": (
+            payload.get("session_id")
+            or payload.get("conversation_id")
+            or payload.get("sessionId")
+            or payload.get("conversationId")
+        ),
+        "transcript_path": payload.get("transcript_path") or payload.get("transcriptPath"),
+        # agy sends no cwd — it sends workspacePaths, a list of workspace roots.
+        "cwd": payload.get("cwd") or _first_workspace(payload),
+    }
+
+
+def _read_payload(stdin: IO[str]) -> dict[str, Any]:
+    """The hook payload, or an empty dict for anything unreadable.
+
+    A hook that fires with nothing on stdin, half a JSON document, undecodable
+    bytes, or a bare list is not an error the operator can act on — the event still
+    has to be written, because the run's completion signal rides on it. Every
+    non-dict outcome collapses to ``{}`` and the shaped event simply carries nulls.
+    ``UnicodeDecodeError`` and ``json.JSONDecodeError`` are both ``ValueError``
+    subclasses and ride the same arm; ``OSError`` covers a closed or unreadable
+    descriptor.
+    """
+    try:
+        payload = json.load(stdin)
+    except (ValueError, OSError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def relay(event_name: str, stdin: IO[str]) -> int:
+    """Write one event file for the session this process was spawned inside.
+
+    The contract is the hook script's, because the hook config points at one or
+    the other and the orchestrator must not be able to tell which ran: a silent
+    no-op when the session was not spawned by froid-loop (the env vars are the
+    detector), garbage stdin tolerated, and any ``OSError`` from a hostile or
+    broken events dir degrading to rc 0. Never anything on stdout — the CLI hosts
+    parse hook stdout — and never a non-zero rc, which several of them surface as
+    a failed tool call inside the very session whose completion this reports.
+
+    Returns 0 unconditionally. Nothing here is worth failing a session over: the
+    orchestrator's fallback for a missing event is ``session_timeout_min``, and an
+    attacker who can suppress the event can already get that outcome by planting
+    the redirect ``_write_event`` refuses.
+    """
+    run_dir = os.environ.get("FROID_LOOP_RUN_DIR")
+    task_id = os.environ.get("FROID_LOOP_TASK_ID")
+    if not run_dir or not task_id:
+        return 0
+    ts = time.time_ns()
+    event = shape_event(ts, event_name, task_id, _read_payload(stdin))
+    # $FROID_LOOP_EVENTS_DIR when the orchestrator names one (#494 moved the
+    # channel out of the project tree), else the legacy in-tree location — the
+    # same preference, spelled the same way, as the copied hook script's `main()`.
+    # `or`, not a presence test: an exported-but-empty value names the launch cwd.
+    # The no-op detector above stays RUN_DIR + TASK_ID for the reason the hook's
+    # docstring gives: an older orchestrator sets neither the new variable nor any
+    # expectation that this relay needs it, and its sessions must still complete.
+    events_dir = os.environ.get("FROID_LOOP_EVENTS_DIR") or os.path.join(run_dir, "events")
+    try:
+        _write_event(events_dir, event_file_name(ts, task_id, event_name), event)
+    except OSError:
+        # A hostile or broken events dir must degrade to the orchestrator's normal
+        # session_timeout_min path, never surface as a hook failure that fails the
+        # CLI window (mirrors the hook script's own write wrap).
+        return 0
+    return 0