froid-loop 0.11.1__py3-none-any.whl

froid_loop/__init__.py

@@ -0,0 +1,11 @@
+"""Deterministic orchestrator for the FROID implementation phase.
+
+The control loop is plain Python; LLMs only run inside disposable
+coding-CLI sessions spawned per pipeline step. All durable state lives
+on disk: sprint-status.yaml (the orchestrator is its sole writer while a
+run is in flight — see :mod:`froid_loop.sprintstatus`; your own FROID skill
+runs still generate and edit it outside one), spec files, and the per-run
+directory under .froid-loop/runs/.
+"""
+
+__version__ = "0.11.1"

froid_loop/__main__.py

@@ -0,0 +1,12 @@
+"""``python -m froid_loop`` entry point — delegates to the console-script main().
+
+Mirrors the ``if __name__ == "__main__"`` guard at the foot of ``cli.py`` so the
+module form and the installed ``froid-loop`` script share one dispatch path.
+"""
+
+import sys
+
+from froid_loop.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

froid_loop/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .base import CodingCLIAdapter, SessionHandle, SessionResult, SessionSpec
+
+__all__ = ["CodingCLIAdapter", "SessionHandle", "SessionResult", "SessionSpec"]

froid_loop/adapters/base.py

@@ -0,0 +1,254 @@
+"""Coding-CLI adapter seam.
+
+Adapters differ along three orthogonal capability axes, declared as class
+attributes so the engine can reason about transport quality instead of
+treating every CLI as a dumb terminal:
+
+- injection:   how a prompt reaches the CLI
+               "tmux-initial-prompt" | "launch-flag" | "http"
+- observation: how turn/session completion is detected
+               "hook-signal" | "sse" | "transcript-poll"
+- state:       where session state is readable
+               "local-jsonl" | "local-json-tree" | "remote"
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..model import TokenUsage
+
+
+@dataclass(frozen=True)
+class SpecSnapshot:
+    """Launch-state fingerprint of a review session's spec, captured by the
+    engine immediately after the pre-review-launch marker strip
+    (``_reset_spec_for_review``) and threaded onto its ``SessionSpec``.
+
+    Lets the generic adapter's missing-marker fallback deterministically refuse
+    to synthesize from a candidate whose bytes are byte-identical to the spec's
+    launch state: such a spec is provably untouched by this session, so the
+    terminal ``status:`` it carries is the PRIOR pass's ``done`` (re-opened for
+    review), not proof this session finished (#276 M1).
+
+    Process-transient: it rides the live ``SessionSpec`` only and is deliberately
+    NOT persisted (no ``StoryTask.to_dict`` entry). A crash-resume that
+    reconstructs the ``SessionSpec`` therefore carries no snapshot, and the
+    fallback degrades to its conservative 2-observation fingerprint path."""
+
+    path: str
+    mtime_ns: int
+    sha256: str
+    fm_status: str
+
+
+@dataclass(frozen=True)
+class SessionSpec:
+    task_id: str
+    role: str  # "dev" | "review" | "retro"
+    prompt: str
+    cwd: Path
+    env: dict[str, str] = field(default_factory=dict)
+    model: str = ""  # empty = CLI default
+    # fallback only; real dev/review/retro sessions get limits.session_timeout_min * 60
+    timeout_s: float = 90 * 60
+    # total stall wake-nudges this session may ever receive; None (the raw
+    # constructor default) = unbounded. Unlike the adapter's refillable
+    # per-silence budget, this cap is monotonic — a session that keeps ending
+    # its turn without a result cannot re-earn nudges forever, because the
+    # nudge is itself a submitted turn whose reply refills the budget (#149).
+    # The engine sets it for every session it drives: workflow_stall_nudges_cap
+    # for injected workflow sessions, dev_stall_nudges_cap otherwise, so a
+    # missing completion artifact degrades to "stalled" instead of livelocking
+    # until timeout_s.
+    stall_nudges_cap: int | None = None
+    # Mid-session token-budget guard (#158): weighted per-session cap the wait
+    # loop samples cumulative usage against on its heartbeat cadence. None (the
+    # raw constructor default) or mode "off" leaves the guard inert, so adapters
+    # constructed outside the engine (tests, MockAdapter) are unaffected. The
+    # engine sets these from limits.max_tokens_per_session /
+    # limits.session_budget_mode / limits.session_budget_grace_s /
+    # limits.cache_read_weight for every session it drives.
+    token_budget: int | None = None
+    token_budget_mode: str = "off"  # "off" | "warn" | "enforce"
+    token_budget_grace_s: float = 240.0
+    cache_read_weight: float = 0.1
+    # Launch-state snapshot of a review session's spec (#276 M1): captured by the
+    # engine right after the pre-review-launch marker strip and threaded here so
+    # the generic adapter's missing-marker fallback can deterministically refuse
+    # to synthesize from a spec still byte-identical to its launch state. None for
+    # every non-review session and on a crash-resume (process-transient — see
+    # SpecSnapshot). Kept LAST so positional SessionSpec constructions stay valid.
+    spec_snapshot: SpecSnapshot | None = None
+    # The spec path this session is REQUIRED to write, when the orchestrator
+    # already knows it (#261): `StoryTask.spec_file`, recorded by verify_dev /
+    # verify_dev_bundle on dev success and handed to the review session in its own
+    # prompt. Set for every leg with a recorded spec — always a review, and a dev
+    # retry — and None on a dev attempt 1, whose spec does not exist yet.
+    #
+    # When set, the generic adapter reads back from THIS path instead of scanning
+    # the implementation-artifacts dir for the newest qualifying `*.md`. That scan
+    # is shared with every concurrent run: a foreign story's spec landing there
+    # after launch (a merge-back into the main checkout, a human edit, a sweep)
+    # wins on mtime and is adopted as this session's result, so a review that
+    # produced nothing is scored `completed:done` and unreviewed code merges.
+    #
+    # Deliberately independent of `spec_snapshot`, which degrades to None on a torn
+    # read: the identity constraint must not silently disappear with it.
+    #
+    # Unlike SpecSnapshot this SURVIVES a crash-resume. The field itself is not
+    # persisted, but its source is: `StoryTask.spec_file` round-trips through
+    # state.json (stored relative to the worktree, re-absolutized by
+    # WorktreeFlow on resume), and the engine re-derives this on every launch. So a
+    # resumed run is protected too — always an absolute path by the time it lands
+    # here. Kept LAST alongside spec_snapshot so positional constructions stay valid.
+    expected_spec: str | None = None
+
+
+@dataclass(frozen=True)
+class SessionHandle:
+    task_id: str
+    native_id: str  # tmux window id, HTTP session id, ...
+    launched_ns: int = 0  # wall-clock ns just before launch; floor for hook events
+
+
+@dataclass(frozen=True)
+class SessionResult:
+    # "aborted" is the in-session hard-stop verdict (#319): the wait loop saw a
+    # `mode: "hard"` stop-request.json and tore the session down. It is an abort,
+    # NEVER a completion — sessions complete only on hook Stop events or window
+    # death (AGENTS.md) — and it never escapes `Engine._run_session`, which
+    # unwinds it as a RunStopped before any SessionRecord is written.
+    status: str  # "completed" | "stalled" | "timeout" | "crashed" | "over_budget" | "aborted"
+    result_json: dict[str, Any] | None = None
+    session_id: str | None = None
+    transcript_path: str | None = None
+    # wall time.time() when wait_for_completion declared the deadline elapsed;
+    # None unless this session's timeout actually fired (#157).
+    timeout_fired_at: float | None = None
+    # which clock(s) had expired at fire time: "monotonic" | "wall" | "both".
+    # "wall" alone is the suspend signature — a frozen monotonic clock.
+    timeout_expired_clock: str | None = None
+    # weighted usage sampled when the session-budget guard tripped (#158); None
+    # unless the guard tripped. Set on every post-trip exit — warn-mode sessions
+    # that run to completion carry it too — so the engine can journal it.
+    budget_weighted: int | None = None
+    # transport-failure classification (#194): True when a non-completed session
+    # was post-mortem-matched as an *environment fault* (the coding CLI lost its
+    # API connection and idled out the session clock instead of doing real work).
+    # Set by the _classify_env_fault hook; env_fault_evidence carries the matched,
+    # ANSI-stripped log line. New fields are APPENDED below these, never inserted
+    # among them, so every positional SessionResult construction stays valid.
+    env_fault: bool = False
+    env_fault_evidence: str | None = None
+    # Whether a `Stop` hook event arrived during this session — the hook half of the
+    # #261 proof-of-work gate (see `_ResultFileMixin._produced_work`). Deliberately
+    # NOT `session_id is not None`: SessionStart and SessionEnd populate that too,
+    # and both fire on a CLI that launched and wedged without doing anything. Stop
+    # is the only canonical event that means a turn actually ended.
+    stop_seen: bool = False
+    # Set on a `crashed` verdict when the mux no longer reports the SESSION, not
+    # just its window (#489) — see `GenericAdapter._session_vanished` for why the
+    # two are otherwise indistinguishable. Diagnostic label only: it changes the
+    # reason text, never the routing. Deliberately NOT carried by
+    # `_post_kill_reconcile`'s hand-built result — that path gates on
+    # stalled/timeout/over_budget, which this flag can never accompany; add it
+    # there if `crashed` ever joins that rescue set.
+    session_vanished: bool = False
+
+
+class CodingCLIAdapter(ABC):
+    name: str = "abstract"
+    injection: str = ""
+    observation: str = ""
+    state: str = ""
+
+    @abstractmethod
+    def start_session(self, spec: SessionSpec) -> SessionHandle: ...
+
+    @abstractmethod
+    def wait_for_completion(self, handle: SessionHandle, spec: SessionSpec) -> SessionResult: ...
+
+    def send_text(self, handle: SessionHandle, text: str) -> None:
+        """Nudge a running session. Optional capability."""
+        raise NotImplementedError(f"{self.name} cannot inject into a running session")
+
+    def interactive_argv(self, spec: SessionSpec) -> list[str]:
+        """argv that launches the CLI agent attached to the caller's terminal,
+        seeded with spec.prompt. Used by the interactive escalation-resolution
+        flow; optional capability (e.g. HTTP adapters have no terminal)."""
+        raise NotImplementedError(f"{self.name} has no interactive (attached) session mode")
+
+    def interactive_env(self, spec: SessionSpec) -> dict[str, str]:
+        """Env vars to layer onto the caller's environment for interactive_argv."""
+        return dict(spec.env)
+
+    def kill(self, handle: SessionHandle) -> None:  # optional cleanup
+        pass
+
+    def read_usage(self, result: SessionResult) -> TokenUsage | None:
+        return None
+
+    def run(self, spec: SessionSpec) -> SessionResult:
+        handle = self.start_session(spec)
+        try:
+            result = self.wait_for_completion(handle, spec)
+        finally:
+            self.kill(handle)
+        result = self._post_kill_reconcile(handle, spec, result)
+        return self._classify_env_fault(handle, spec, result)
+
+    def _post_kill_reconcile(
+        self, handle: SessionHandle, spec: SessionSpec, result: SessionResult
+    ) -> SessionResult:
+        """Last-chance reconcile after the session's window has been torn down.
+
+        Runs only on the normal return path — a raising wait_for_completion
+        still kills the window and propagates without reaching this hook.
+        Base behavior: identity. Adapters whose completion trust keys on
+        window death (see GenericDevAdapter) may re-inspect on-disk state here,
+        now that the kill has settled the liveness question a live-window
+        verdict had to leave open."""
+        return result
+
+    def _observe_tick(self, handle: SessionHandle, spec: SessionSpec) -> None:
+        """Heartbeat-cadence hook for mid-session on-disk observation, called from
+        the wait loop's heartbeat-throttled block (~every HEARTBEAT_INTERVAL_S; the
+        first tick always fires). Base behavior: nothing. Adapters that drive a
+        skill whose terminal on-disk state is heuristic to attribute may sample it
+        here (see GenericDevAdapter's `_DevSynthesisMixin`, which records the spec's
+        first non-terminal status transition to make a later terminal frontmatter
+        deterministic proof this session wrote it, #276 M2). An observation seam
+        only — it MUST NOT mutate session state or the spec, and any read failure is
+        a sample it silently skips, never a verdict."""
+        return None
+
+    def _classify_env_fault(
+        self, handle: SessionHandle, spec: SessionSpec, result: SessionResult
+    ) -> SessionResult:
+        """Last-chance post-mortem: label a non-completed session an environment
+        fault (#194) when the CLI never got usable work out of the provider —
+        connection lost, or quota/rate limit refused — and idled out the session
+        clock rather than doing real work.
+
+        Runs LAST in ``run()`` — after ``_post_kill_reconcile`` — so a reconcile
+        upgrade to ``completed`` is never re-classified, and only a genuinely
+        non-completed verdict (``result_json is None``) is ever inspected. Base
+        behavior: identity, like ``_post_kill_reconcile``, so an adapter with no
+        session log at all (mock) stays inert.
+
+        Any adapter that writes a per-task diagnostic log should mix in
+        ``EnvFaultMixin``, which matches profile patterns against the tail of the
+        file its ``ENV_FAULT_LOG_SUFFIX`` names and stamps ``env_fault`` /
+        ``env_fault_evidence`` onto the result. That covers the tmux adapters
+        (pane capture, ``<task_id>.log``) and the opencode HTTP adapter (the
+        serve process's stdout/stderr, ``<task_id>.server.out``, NOT its
+        conversation transcript) alike — the signal is the log, not the
+        transport. This docstring used to say HTTP adapters had no
+        post-mortem signal; that stopped being true once opencode_http began
+        teeing its server log, and the stale premise is why a provider quota
+        outage went unclassified and burned three stories' retry budgets."""
+        return result

froid_loop/adapters/entrypoints.py

@@ -0,0 +1,63 @@
+"""Shared recording for the three ``froid_loop.*`` entry-point scans.
+
+The adapter registry (:mod:`~.registry`), the profile loader (:mod:`~.profile`)
+and the multiplexer registry (:mod:`~.multiplexer`) each scan their own
+entry-point group, and each degrades a broken third-party distribution to a
+*recorded* reason rather than a crash. This module owns the one thing all three
+recordings must agree on: how a failure becomes an entry in that map.
+
+A leaf on purpose — standard library only, and **no import of a sibling
+adapters module**. Those three do not import each other today, and the package's
+builtins load lazily to keep that so; an edge from here into any of them would
+put a cycle one refactor away.
+
+Why the map stays keyed on the entry-point NAME. The key is what reaches
+``detail["entry_point"]`` in ``froid-loop validate --json``. That document is
+schema-versioned and evolves additively (see ``documents.validate_document``,
+which contracts ``check`` as the matchable identity and states outright that
+``message``/``detail`` are for humans) — so widening the key to
+``(distribution, name)`` would change a value consumers can already see, while
+widening only the reason TEXT does not.
+
+Why reasons accumulate instead of overwriting.
+``importlib.metadata.entry_points(group=...)`` does not deduplicate across
+distributions: two installed packages may both advertise ``acme`` in one group,
+and the scan yields both. A plain assignment let the second failure silently
+overwrite the first, so an operator fixed one package and met the other on the
+next run with no sign it had ever been there. Reasons are joined with ``"; "``
+— reasons already contain colons, so a colon separator would be unreadable.
+
+Why the distribution labels each reason. The entry-point name is not the name
+you ``pip uninstall``, and two packages failing the same way otherwise render as
+the same sentence twice, with nothing to tell the operator there are two.
+
+The honest limit: a same-named collision still records ONE row, whose text now
+carries both reasons. The row count does not double — that is the price of
+leaving the key (and therefore ``--json``) untouched, and it still puts every
+reason in front of the operator.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def record_load_error(errors: dict[str, str], ep: Any, exc: BaseException) -> None:
+    """Record ``exc`` against ``ep``'s name in ``errors``, appending to whatever a
+    same-named entry point already recorded.
+
+    ``ep`` is annotated ``Any`` deliberately: the callers pass a real
+    ``importlib.metadata.EntryPoint`` but every test passes a hand-rolled double,
+    so naming ``EntryPoint`` here would claim a contract this function does not
+    require (it touches ``.name`` and, defensively, ``.dist.name``).
+
+    The doubled ``getattr`` tolerates a double with no ``dist`` attribute at all
+    as well as a real entry point whose ``dist`` is ``None``; the truthiness
+    check then treats an empty distribution name as absent, the same
+    normalization the scans' ``or ""`` sort keys apply."""
+    dist = getattr(getattr(ep, "dist", None), "name", None)
+    reason = f"{type(exc).__name__}: {exc}"
+    if dist:
+        reason = f"{dist}: {reason}"
+    prior = errors.get(ep.name)
+    errors[ep.name] = f"{prior}; {reason}" if prior else reason

froid_loop/adapters/env_fault.py

@@ -0,0 +1,290 @@
+"""Post-mortem environment-fault classification, shared across transports (#194).
+
+After a session's verdict and reconcile have settled, a single tail read of the
+session log can reclassify a non-completed verdict as an *environment fault* —
+the CLI never got usable work out of the provider, so the attempt proved nothing
+about the story. The engine routes that to a PAUSE (``env_fault_pause_reason``)
+instead of charging a dev attempt, and re-arming resets the budget.
+
+This lives in its own module rather than on one adapter because the signal is
+**transport-agnostic**: every adapter that writes a per-task diagnostic log can
+be classified from it, whatever produced the bytes. Which file that is per
+adapter is named by ``ENV_FAULT_LOG_SUFFIX``: the tmux adapters tee a pane
+capture to ``logs/<task_id>.log`` (``mux.pipe_pane``); the opencode HTTP adapter
+redirects the ``opencode serve`` process's own stdout/stderr to
+``logs/<task_id>.server.out`` — NOT its ``.log``, which is a model-written
+conversation transcript. Keeping the classifier attached to a single adapter is
+what let #194 ship covering only half the adapters, so the next sibling adapter
+inherits this instead of re-omitting it.
+
+Host-class contract: ``self.profile`` (a ``CLIProfile``), ``self.logs_dir``, and
+``_note_lifecycle`` (from ``_ResultFileMixin``). Mix in alongside that mixin.
+
+Note the two log flavors differ in how *dirty* they are, which is why the
+shipped patterns are anchored the way they are. A tmux pane capture contains the
+model's own output — a story that implements rate limiting will print "429" and
+"quota" in ordinary healthy work — whereas the opencode server log carries only
+server and provider lines. That difference sets the bar per profile, and the two
+bars are NOT the same. On a pane capture a pattern must reproduce a COMPLETE
+captured CLI error sentence: an error-shaped token plus a cause on the same line
+is precisely the shape a story writing ABOUT the error emits, so that weaker rule
+classified 44 of this repo's own tracked lines and had to be withdrawn (#507).
+The opencode server log tolerates the anchor-plus-cause form only because the
+model cannot write to it. Seed either from a captured line, never a plausible
+one; the profiles' own comments carry the provenance and
+tests/test_env_fault_patterns.py pins both halves.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from functools import cached_property
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import regex
+
+from .base import SessionHandle, SessionResult, SessionSpec
+from .profile import CLIProfile
+
+# Post-mortem transport-failure classification (#194): how much of the tee'd
+# session log's tail to scan, how long an evidence excerpt to keep, and which
+# non-completed statuses are eligible. over_budget is excluded — a budget
+# crossing proves real API traffic — and completed never reaches the scan.
+ENV_FAULT_TAIL_BYTES = 64 * 1024
+ENV_FAULT_EVIDENCE_MAX = 240
+# How much of the line *before* the match to keep when the line is too long to
+# quote whole. Truncating from the start instead loses the error on any log whose
+# lines lead with metadata: an opencode `level=ERROR message="stream error" …`
+# line carries ~250 characters of timestamp/provider/session fields before
+# `error.error=`, so a head-truncated excerpt showed the operator every field
+# except the failure. The evidence string is what lands in the pause reason and
+# the ATTENTION file — it has to contain the thing that matched.
+ENV_FAULT_EVIDENCE_LEAD = 40
+ENV_FAULT_STATUSES = frozenset({"timeout", "stalled", "crashed"})
+# Wall-clock bound on EACH pattern match (run via the `regex` module, not stdlib
+# `re`, whose `search` has no timeout), so a pathological profile regex cannot hang
+# run() teardown indefinitely. Note what this does and does not bound: it is
+# per-search, so the worst case for a scan is lines × patterns × this, not this.
+# A sane pattern over the ≤64 KiB tail matches in microseconds, and the first
+# search to blow the bound aborts the whole scan (TimeoutError → decline to
+# classify), so the realistic ceiling is one timeout — but an operator writing a
+# pattern that backtracks on many lines without exceeding the per-line bound can
+# still make teardown slow. Keep patterns anchored and non-nested.
+ENV_FAULT_MATCH_TIMEOUT_S = 2.0
+# Self-contained ANSI/terminal-control stripper for the log tail: CSI, OSC (BEL-
+# or ST-terminated), other two-char ESC sequences, and raw C1 bytes. Deliberately
+# NOT the TUI/pyte machinery — the classifier reads raw pane bytes best-effort and
+# must not pull a terminal emulator into the adapter. Inert on a log that was
+# never a terminal capture (the opencode server log), which costs one pass.
+_ANSI_RE = re.compile(
+    r"""
+    \x1b\[ [0-?]* [ -/]* [@-~]        # CSI ... final byte
+    | \x1b\] .*? (?: \x07 | \x1b\\ )   # OSC ... BEL or ST
+    | \x1b [@-Z\\-_]                   # 2-char ESC sequences (incl. C1 via ESC)
+    | [\x80-\x9f]                      # raw C1 control bytes
+    """,
+    re.VERBOSE,
+)
+
+
+class EnvFaultMixin:
+    """Classify a dead session as an environment fault from its log tail (#194).
+
+    Mixed into every adapter that writes a per-task diagnostic log; which file
+    is scanned is named by ``ENV_FAULT_LOG_SUFFIX``. Inert for a profile with no
+    ``env_fault_patterns``, so mixing it in is always safe."""
+
+    # Set by the concrete adapter's __init__; bare annotations (no runtime effect)
+    # tell the type checker which host attributes this mixin reads.
+    profile: CLIProfile
+    logs_dir: Path
+
+    # Which per-task file in logs_dir carries the CLI's DIAGNOSTIC output. Default
+    # ".log" is the tmux adapters' pane capture. Overridden by any adapter that
+    # writes its diagnostics elsewhere.
+    #
+    # This is a suffix and not a hardcoded path because the two are not the same
+    # file for every transport, and getting it wrong is silent: the scan simply
+    # finds nothing and every provider outage reads as a failed story. The opencode
+    # adapter split them (its ".log" became a curated conversation transcript,
+    # diagnostics moved to ".server.out"), and the classifier kept scanning ".log"
+    # — passing every unit test, because they write the fixture to whatever path
+    # this resolves to, and failing only end to end.
+    #
+    # It also carries the SAFETY property the shipped patterns depend on. A file
+    # containing the model's own output cannot be scanned with content-based
+    # patterns: a story that quotes a provider error verbatim is byte-identical to
+    # the real thing (see tests/test_env_fault_patterns.py). The tmux adapters
+    # accept that risk knowingly and their profile patterns are anchored for it;
+    # opencode's are anchored on the assumption of a model-free log, so pointing
+    # this at a transcript would make them unsound.
+    ENV_FAULT_LOG_SUFFIX = ".log"
+
+    def _env_fault_log_path(self, task_id: str) -> Path:
+        return self.logs_dir / f"{task_id}{self.ENV_FAULT_LOG_SUFFIX}"
+
+    if TYPE_CHECKING:
+        # Supplied by _ResultFileMixin, which every host of this mixin already
+        # uses. Declared rather than inherited: generic.py imports this module,
+        # so depending on _ResultFileMixin here would be a cycle.
+        def _note_lifecycle(self, task_id: str, event: str, **fields: object) -> None: ...
+
+    @cached_property
+    def _env_fault_patterns(self) -> tuple[regex.Pattern[str], ...]:
+        """Compiled once per adapter, on first classification. The profile
+        validated each pattern at parse time with this same engine, so
+        ``regex.compile`` cannot raise here; empty tuple = classification inert.
+
+        A ``cached_property`` rather than an ``__init__`` line so every adapter
+        gains the behavior by mixing the class in, with nothing to remember to
+        wire — the omission that caused this bug. Tests may still assign
+        ``adapter._env_fault_patterns`` directly; that shadows the property in
+        the instance ``__dict__``, as it did when this was a plain attribute.
+
+        CONSTRAINT: the cache is filled on first classification and never
+        invalidated, so reassigning ``self.profile`` afterwards leaves stale
+        patterns. Nothing in ``src/`` mutates ``profile`` after ``__init__`` (it
+        is constructor state), so this holds in production; a test that swaps the
+        profile must do so BEFORE the first classification, or assign
+        ``_env_fault_patterns`` directly instead."""
+        return tuple(regex.compile(p) for p in self.profile.env_fault_patterns)
+
+    def _classify_env_fault(
+        self, handle: SessionHandle, spec: SessionSpec, result: SessionResult
+    ) -> SessionResult:
+        """Post-mortem transport-failure classification (#194).
+
+        Runs last in ``run()`` (after ``_post_kill_reconcile``): only a
+        non-completed verdict (``result.status`` in ``ENV_FAULT_STATUSES``,
+        ``result_json is None``) with configured patterns is inspected, so a
+        reconcile upgrade to ``completed`` is never re-classified and adapters
+        without patterns stay inert. On a matching log-tail line, stamp
+        ``env_fault`` / ``env_fault_evidence`` and drop an ``env-fault-classified``
+        lifecycle breadcrumb. No match, no patterns, or an unreadable log leaves
+        the verdict untouched — best-effort, like ``_write_heartbeat``."""
+        if (
+            not self._env_fault_patterns
+            or result.status not in ENV_FAULT_STATUSES
+            or result.result_json is not None
+        ):
+            return result
+        evidence = self._env_fault_evidence(handle.task_id)
+        if evidence is None:
+            return result
+        self._note_lifecycle(
+            handle.task_id, "env-fault-classified", status=result.status, evidence=evidence
+        )
+        return dataclasses.replace(result, env_fault=True, env_fault_evidence=evidence)
+
+    def _env_fault_evidence(self, task_id: str) -> str | None:
+        """Scan the tail of the tee'd session log for a transport-failure pattern.
+
+        Reads the last ``ENV_FAULT_TAIL_BYTES`` (binary, decoded with
+        ``errors="replace"``, ``\\r``→``\\n``), strips ANSI, and matches each line
+        against the precompiled patterns under a per-match ``ENV_FAULT_MATCH_TIMEOUT_S``
+        bound. Returns the ANSI-stripped matching line (last match winning, windowed
+        to ``ENV_FAULT_EVIDENCE_MAX`` around the match), or None when nothing matches,
+        the log can't be read (any ``OSError``), or a pattern exceeds the match timeout
+        (``TimeoutError``) — no classification, the best-effort doctrine."""
+        try:
+            with self._env_fault_log_path(task_id).open("rb") as fh:
+                fh.seek(0, 2)  # SEEK_END
+                size = fh.tell()
+                offset = max(0, size - ENV_FAULT_TAIL_BYTES)
+                if offset:
+                    # The byte immediately BEFORE the window, read on its own so it
+                    # enters neither `raw` nor the ENV_FAULT_TAIL_BYTES budget — it
+                    # only answers whether the window opens mid-line. Inspected raw,
+                    # ahead of the \r→\n normalization below: a pane capture is
+                    # CR-terminated, so a \r here ends a line just as a \n does.
+                    fh.seek(offset - 1)
+                    boundary = fh.read(1)
+                else:
+                    fh.seek(0)
+                    boundary = b"\n"  # not truncated: the window is the whole file
+                raw = fh.read()
+        except OSError:
+            return None
+        straddles = boundary not in (b"\n", b"\r")
+        text = _ANSI_RE.sub("", raw.decode("utf-8", errors="replace").replace("\r", "\n"))
+        lines = text.split("\n")
+        if straddles and any(lines[1:]):
+            # The window opened mid-line, so the first element is a fragment of
+            # whatever line straddled the edge — not a line. Matching it would quote
+            # a half-line as evidence, and (because the cut can land mid-codepoint)
+            # its head may be a U+FFFD from the errors="replace" decode. Drop it:
+            # one lost line at the far end of a 64 KiB tail cannot matter, and a
+            # fabricated line can.
+            #
+            # Both halves of the guard are load-bearing, and each was once wrong:
+            # * `straddles`, not "the read truncated": an offset that happens to
+            #   land on the first byte after a newline yields a COMPLETE first line.
+            #   Discarding that on truncation alone loses a whole line, and if it
+            #   was the only provider-error match in the tail the outage goes
+            #   unclassified and the run burns a story attempt for nothing.
+            # * `any(lines[1:])`, not `len(lines) > 1`: the guard means "do not
+            #   discard if that leaves nothing to scan", and the length test does
+            #   not say that. `split("\n")` always yields a trailing "", so a window
+            #   holding one >64 KiB newline-terminated line splits to
+            #   [fragment, ""] — length 2, dropped, leaving only "". Degenerate,
+            #   but silently classifying nothing is exactly the failure this
+            #   classifier exists to prevent.
+            lines = lines[1:]
+        match_line: str | None = None
+        match_pos = 0
+        try:
+            for line in lines:
+                for pat in self._env_fault_patterns:
+                    hit = pat.search(line, timeout=ENV_FAULT_MATCH_TIMEOUT_S)
+                    if hit is not None:
+                        match_line, match_pos = line, hit.start()  # last match wins
+                        break
+        except TimeoutError:
+            return None  # runaway pattern → decline to classify (best-effort, like OSError)
+        if match_line is None:
+            return None
+        return _excerpt(match_line, match_pos)
+
+
+def _excerpt(line: str, match_pos: int) -> str:
+    """Quote at most ``ENV_FAULT_EVIDENCE_MAX`` characters of ``line``, keeping the
+    matched region rather than the line's head. Short lines are returned whole.
+
+    BOTH cut ends are marked with an ellipsis. Marking only the head (as this did
+    at first) makes a window that dropped a suffix read as a complete line that
+    simply ended there — which, for a string an operator reads out of a pause
+    reason to decide whether their run died of a provider outage, is the one thing
+    it must not do."""
+    stripped = line.strip()
+    if len(stripped) <= ENV_FAULT_EVIDENCE_MAX:
+        return stripped
+    usable = len(line.rstrip())
+    # The markers are spent FROM the budget, never added on top of it: this string
+    # is journalled and rendered in a pause reason, so ENV_FAULT_EVIDENCE_MAX has
+    # to be a real ceiling on what callers receive. But how many markers there are
+    # depends on the window, and the window depends on the budget, which depends on
+    # the markers. Resolve by fixed point over the only three possibilities — no
+    # marker, one, or two — taking the first that is self-consistent. Terminates in
+    # at most three passes; the final fallback (two markers) is always valid
+    # because a line long enough to reach here cannot need fewer than it reserves.
+    start, head, tail, budget = 0, False, False, ENV_FAULT_EVIDENCE_MAX
+    for reserved in (0, 1, 2):
+        budget = ENV_FAULT_EVIDENCE_MAX - reserved
+        # Prefer the match with LEAD chars of left context, but slide LEFT rather
+        # than return a short excerpt when the match sits near the end of the line.
+        # That is the common case here, not a corner: opencode's logfmt puts ~250
+        # characters of metadata before `error.error=`, so the match is near the
+        # end of almost every line this classifier quotes.
+        start = max(0, min(match_pos - ENV_FAULT_EVIDENCE_LEAD, usable - budget))
+        head = start > 0
+        tail = start + budget < usable
+        if (1 if head else 0) + (1 if tail else 0) == reserved:
+            break
+    window = line[start : start + budget].strip()
+    if head:
+        window = f"…{window}"
+    if tail:
+        window = f"{window}…"
+    return window