autoforge-cli 0.1.0a0__py3-none-any.whl

autoforge/premerge.py

@@ -0,0 +1,181 @@
+"""Pre-merge evidence the controller produces itself (issue #42).
+
+A green required check proves that the workflow defining it ran to
+completion on the PR. It does not prove *which* definition ran (GitHub runs
+the PR's own workflow files and reports the result under the same name) and
+it does not prove what the tests in the PR *assert* (the commands execute
+the PR's own code). This module holds the two controller-side answers the
+merge gate adds on top of the hosted check:
+
+- :func:`describe_definition_difference` compares the job/step structure
+  of the run that produced the PR's check with the base branch's own run of
+  the same workflow, so a redefined workflow is a named difference rather
+  than a green check.
+- :func:`export_commit_tree` materialises the exact reviewed commit into a
+  private temporary directory -- no worktree, no branch, no ``.git`` -- so
+  ``merge.verification_commands`` can run the reviewed code on the
+  operator's machine without touching the operator's checkout. The bytes
+  are the committed bytes, proven by hashing them back to the commit's tree
+  (:mod:`autoforge.materialize`, #171).
+
+Both are pure with respect to workflow state; the engine decides what a
+difference or a failing command means for the phase.
+
+The git processes here run in the operator's repository, whose refs,
+configuration and hooks an agent could have written (ADR 0004 §2.11). Each
+one therefore reads a commit as itself (ADR 0004 D7.5): replacement objects
+and the commit-graph are off, so a ``refs/replace/*`` entry or a forged
+``objects/info/commit-graph`` can neither make a missing commit present nor
+swap the tree the export writes. Hooks and the file-system monitor are off
+too (D7.3), and each process starts from an allow-listed environment that
+holds no credential and no operator ``GIT_*`` variable. The export reads
+objects only (``ls-tree`` and ``cat-file``), so no attribute, filter driver
+or eol conversion the operator or the candidate configured takes part.
+Fetching the reviewed commit is not done here: it is the controller's own
+network operation, :meth:`autoforge.git_transport.GitTransport.fetch`, which
+reads no repository configuration at all (D7.1).
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import GitTransportError, VerificationError
+from .executor import ExecutionRequest, ExecutionResult
+from .git_transport import GitTransport, local_git_request
+from .github import WorkflowRunJobs
+from .materialize import materialize, read_object_format
+
+Runner = Callable[[ExecutionRequest], ExecutionResult]
+
+# The export is plumbing, never a checkout: objects are read by id and
+# written out by the controller. The operator's index, HEAD, working tree
+# and stash are not read or written.
+_GIT_TIMEOUT_SECONDS = 600
+
+# Where the merge gate's export is created, under the system temporary
+# directory (ADR 0006 D6.2).
+EXPORT_PREFIX = "autoforge-premerge-"
+
+
+def _local_request(repo: str, args: list[str]) -> ExecutionRequest:
+    """One hardened git process in the operator's repository ``repo``."""
+    return local_git_request(["-C", repo, *args], timeout_seconds=_GIT_TIMEOUT_SECONDS)
+
+
+def describe_definition_difference(pr_jobs: WorkflowRunJobs, base_jobs: WorkflowRunJobs) -> str:
+    """Name the first way the PR run's structure differs from the base run's.
+
+    Returns "" only when both runs have the same jobs and, per job, the same
+    step names in the same order. Job order is irrelevant (matrix legs start
+    in any order); step order is part of the definition and is compared.
+
+    Jobs are compared as a multiset: two jobs of one run may share a name
+    (``name:`` set without interpolating the matrix, two job ids with the
+    same display name), and a job added under a name the run already has
+    must be an extra job, not a duplicate that collapses into the one kept.
+    """
+    pr_shape = pr_jobs.structure()
+    base_shape = base_jobs.structure()
+    if pr_shape == base_shape:
+        return ""
+    pr_names = Counter(name for name, _ in pr_shape)
+    base_names = Counter(name for name, _ in base_shape)
+    for name in sorted(base_names):
+        if pr_names[name] < base_names[name]:
+            if base_names[name] == 1:
+                return f"job {name!r} of the base branch's run is missing from the PR's run"
+            return (
+                f"the base branch's run has {base_names[name]} jobs named {name!r}, the PR's "
+                f"run has {pr_names[name]}"
+            )
+    for name in sorted(pr_names):
+        if pr_names[name] > base_names[name]:
+            if base_names[name] == 0:
+                return f"job {name!r} of the PR's run does not exist in the base branch's run"
+            return (
+                f"the PR's run has {pr_names[name]} jobs named {name!r}, the base branch's "
+                f"run has {base_names[name]}"
+            )
+    # Same job names with the same multiplicities; the sorted shapes pair
+    # same-named jobs up by their step lists, so the first pair that differs
+    # is a real difference even when the name is shared.
+    for (name, base_steps), (_, pr_steps) in zip(base_shape, pr_shape, strict=True):
+        if base_steps == pr_steps:
+            continue
+        for index, (base_step, pr_step) in enumerate(zip(base_steps, pr_steps, strict=False)):
+            if base_step != pr_step:
+                return (
+                    f"job {name!r} step {index + 1} is {pr_step!r} in the PR's run but "
+                    f"{base_step!r} in the base branch's run"
+                )
+        if len(pr_steps) < len(base_steps):
+            return f"job {name!r} lacks step {base_steps[len(pr_steps)]!r} of the base branch's run"
+        return f"job {name!r} has an extra step {pr_steps[len(base_steps)]!r} in the PR's run"
+    # Unreachable when the shapes differ, but a difference must never be
+    # reported as "" -- the gate fails closed on what it could not name.
+    return "the PR's run and the base branch's run differ in structure"
+
+
+@dataclass(frozen=True)
+class ExportedTree:
+    """A commit's tree written out under ``root``; ``root`` is deleted afterwards."""
+
+    sha: str
+    root: Path
+
+
+def commit_is_local(runner: Runner, repo: str, sha: str) -> bool:
+    """Whether ``repo``'s object store holds a commit named ``sha``.
+
+    A missing commit is missing even when a replacement ref or the
+    commit-graph names it: neither is consulted. Existence only; the bytes
+    are not authenticated here.
+    """
+    res = runner(_local_request(repo, ["cat-file", "-e", f"{sha}^{{commit}}"]))
+    return not res.timed_out and res.exit_code == 0
+
+
+def fetch_pr_head(transport: GitTransport, pr_number: int) -> None:
+    """Fetch the objects of ``refs/pull/<n>/head`` so the reviewed commit is local.
+
+    The controller's own fetch (ADR 0004 D6.4, D7.1): an explicit URL, no
+    repository configuration, objects only. No ref is created or moved, so
+    the operator's branches are untouched. A failure is a
+    :class:`VerificationError`, which the caller reads as inconclusive.
+    """
+    try:
+        transport.fetch([f"refs/pull/{pr_number}/head"])
+    except GitTransportError as exc:
+        raise VerificationError(f"fetching refs/pull/{pr_number}/head failed: {exc}") from exc
+
+
+@contextmanager
+def export_commit_tree(runner: Runner, repo: str, sha: str) -> Iterator[ExportedTree]:
+    """Write the tree of ``sha`` into a fresh temporary directory, then delete it.
+
+    The byte-exact materializer (:func:`autoforge.materialize.materialize`)
+    writes every blob of exactly that commit as its committed bytes and
+    proves the directory hashes back to the commit's tree before the body
+    runs: no ``.git`` (the exported code cannot reach the repository through
+    git), no attribute, eol conversion, ``ident`` or filter driver (unlike a
+    checkout, whose bytes depend on the operator's git configuration and
+    which runs the filter programs it names), nothing dropped (unlike ``git
+    archive``'s ``export-ignore``), no worktree or branch (nothing for the
+    operator to clean up, nothing that collides with their checkout).
+    Submodules are not populated: a gitlink is an empty directory. The
+    directory is ``EXPORT_PREFIX`` + a random suffix in the system temporary
+    directory, and is deleted when the context exits.
+
+    Raises VerificationError (a :class:`~autoforge.errors.MaterializationError`
+    or :class:`~autoforge.errors.CandidateNotMaterializableError` among them)
+    when the commit cannot be materialised; the caller decides whether that
+    is inconclusive or conclusive.
+    """
+    object_format = read_object_format(runner, repo)
+    with materialize(runner, repo, sha, object_format, prefix=EXPORT_PREFIX) as tree:
+        yield ExportedTree(sha=sha, root=tree.root)

autoforge/profiles.py

@@ -0,0 +1,106 @@
+"""Agent execution profile routing (pure, easily tested logic)."""
+
+from __future__ import annotations
+
+from .config import AutoForgeConfig, ProfileConfig
+from .errors import ConfigurationError
+from .transitions import Phase
+
+REVIEW_ROUND_1 = "review_round_1"
+REVIEW_ROUND_2_5 = "review_round_2_5"
+REVIEW_ROUND_6_PLUS = "review_round_6_plus"
+
+
+def review_profile_name(round: int) -> str:
+    """Route a 1-based review round to its logical profile name.
+
+    round == 1      -> review_round_1
+    2 <= round <= 5 -> review_round_2_5
+    round >= 6      -> review_round_6_plus
+    """
+    if round < 1:
+        raise ConfigurationError(f"review round must be >= 1, got {round}")
+    if round == 1:
+        return REVIEW_ROUND_1
+    if 2 <= round <= 5:
+        return REVIEW_ROUND_2_5
+    return REVIEW_ROUND_6_PLUS
+
+
+# Every profile a REMOTE run can reach, so a missing or unusable one is a
+# config-time failure (`ControllerEngine.validate_config`) rather than one
+# discovered mid-run. `doctor` checks the same list, so what it reports as
+# runnable is exactly what a run accepts. `update_epic` is not listed: that
+# phase is still gated (see `config.py`). Keep this in step with the
+# `profile_for_phase` mapping below and `review_profile_name` above.
+REQUIRED_PROFILES = [
+    "analyze_execute",
+    "fix",
+    REVIEW_ROUND_1,
+    REVIEW_ROUND_2_5,
+    REVIEW_ROUND_6_PLUS,
+    "replan_reexecute",
+]
+
+# The only profile every LOCAL run reaches whatever its bound is. `fix` and
+# the reviewer profiles are conditional (see `local_required_profiles`).
+LOCAL_BASE_PROFILES = ["analyze_execute"]
+
+# Lowest review round that routes to each reviewer profile, matching
+# `review_profile_name`. Deriving the requirement from these thresholds keeps
+# `local_required_profiles` O(1): a configured bound of 10**9 fix rounds still
+# reaches exactly three reviewer profiles, so validation must not walk the
+# rounds one by one to discover that.
+REVIEW_PROFILE_THRESHOLDS: tuple[tuple[int, str], ...] = (
+    (1, REVIEW_ROUND_1),
+    (2, REVIEW_ROUND_2_5),
+    (6, REVIEW_ROUND_6_PLUS),
+)
+
+
+def local_required_profiles(cfg: AutoForgeConfig) -> list[str]:
+    """Profiles a LOCAL run can actually reach, given its configured bound.
+
+    A local run never replans and never updates an EPIC, so those profiles are
+    not required. The rest follows from ``local.max_fix_rounds``:
+
+    - ``fix`` only when at least one fix round is allowed. With
+      ``max_fix_rounds == 0`` a review with findings goes straight to BLOCKED
+      and FIX is never invoked, so requiring a valid ``fix`` profile would
+      reject a perfectly runnable one-pass configuration.
+    - the reviewer profiles follow exactly the same round routing as remote:
+      with ``local.max_fix_rounds >= 5`` a local run can complete review round
+      6 and will ask for ``review_round_6_plus``. Deriving the requirement
+      from the configured bound keeps a missing reviewer profile a config-time
+      failure instead of one discovered five fix rounds into a run; the
+      inverse also holds, so ``max_fix_rounds == 0`` requires only
+      ``review_round_1``.
+    """
+    names = list(LOCAL_BASE_PROFILES)
+    if cfg.local.max_fix_rounds > 0:
+        names.append("fix")
+    rounds = cfg.local.max_review_rounds
+    names.extend(name for threshold, name in REVIEW_PROFILE_THRESHOLDS if rounds >= threshold)
+    return names
+
+
+def profile_for_phase(cfg: AutoForgeConfig, phase: Phase, review_round: int = 0) -> ProfileConfig:
+    """Select the execution profile for a phase (REVIEW uses round routing)."""
+    if phase == Phase.REVIEW:
+        # review_round stores completed rounds; the upcoming execution is +1.
+        upcoming = review_round + 1
+        return cfg.profile(review_profile_name(upcoming))
+    if phase == Phase.MERGE:
+        raise ConfigurationError(
+            "phase MERGE has no execution profile: the controller performs the merge "
+            "itself (gh pr merge via GitHubClient); agents never merge"
+        )
+    mapping = {
+        Phase.ANALYZE_EXECUTE: "analyze_execute",
+        Phase.FIX: "fix",
+        Phase.REPLAN_REEXECUTE: "replan_reexecute",
+        Phase.UPDATE_EPIC: "update_epic",
+    }
+    if phase not in mapping:
+        raise ConfigurationError(f"phase {phase.value} has no execution profile")
+    return cfg.profile(mapping[phase])

autoforge/progress.py

@@ -0,0 +1,392 @@
+"""Live agent progress: a provider-neutral event and its terminal renderer (#192).
+
+A provider adapter maps its own protocol (Claude's stream-json, Pi's RPC
+events, OpenCode's stderr) into :class:`ProgressEvent` and hands each one to
+the :data:`ProgressSink` the engine put in the request. The engine and the
+CLI never see a provider record: an event is a closed ``kind``, a tool name,
+one allow-listed ``detail`` and a token estimate, and nothing else. The kinds
+are the subset of #154's shared lifecycle events that a CLI provider can
+report today (started, tool started/finished/failed, provider retry) plus
+the liveness kinds a stream adds (thinking, assistant text, activity); #154
+extends this set rather than defining a second one. One kind is not the
+agent's: ``loop_suspected`` carries the controller's loop detector warning
+(#194, :mod:`autoforge.loop_detect`), is printed as it is and is never
+counted as the agent's activity.
+
+Every string an event carries is made safe when the event is built, not
+where it is printed: ANSI escape sequences, control, format and line
+separator characters are removed first, so a secret split by an escape is
+whole again; the text is then redacted; and only then clipped, because a
+secret cut by the clip would no longer match its pattern. A value too long
+to be a path, a pattern or a description (:data:`MAX_RAW_CHARS`) is not
+shown at all. A detail is one of the allow-listed tool inputs an adapter
+names (a file path, a search pattern, a command's *description*), never a
+command line, a tool result, thinking or assistant text.
+
+:class:`ProgressReporter` turns events into lines for the operator. Each
+line is prefixed with the time elapsed since the launch and a label (phase
+and issue), is redacted again as a whole, and goes to every output: the
+step's ``progress.log`` and, when the CLI asks for it, stderr. Thinking and
+assistant text are coalesced to one line per :data:`THINKING_INTERVAL_SECONDS`;
+a finished tool and bare activity print nothing; and when nothing has been
+printed for :data:`HEARTBEAT_AFTER_SECONDS` a heartbeat line says how long
+ago the agent last did anything. The reporter never raises into the
+adapter or the engine: an output that fails is dropped and never called
+again, with one line saying so on the others; an output that fails while
+receiving that line is dropped in turn.
+"""
+
+from __future__ import annotations
+
+import enum
+import re
+import threading
+import time
+import unicodedata
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from types import TracebackType
+
+from .redaction import redact
+
+
+class ProgressKind(enum.StrEnum):
+    """What happened. Closed: an adapter maps anything else to ``ACTIVITY``."""
+
+    STARTED = "started"
+    THINKING = "thinking"
+    ASSISTANT_TEXT = "assistant_text"
+    TOOL_STARTED = "tool_started"
+    TOOL_FINISHED = "tool_finished"
+    TOOL_FAILED = "tool_failed"
+    PROVIDER_RETRY = "provider_retry"
+    # Any other sign of life: a record that is none of the above.
+    ACTIVITY = "activity"
+    # Not the agent's: the controller's loop detector (#194) warns that the
+    # agent may be repeating itself; ``detail`` is its short description.
+    LOOP_SUSPECTED = "loop_suspected"
+
+
+# A raw value longer than this is no path, pattern or description an
+# operator needs to read, and redacting it would cost work proportional to
+# whatever an agent put in a tool input; it is shown as an ellipsis.
+MAX_RAW_CHARS = 4096
+MAX_TOOL_CHARS = 64
+MAX_DETAIL_CHARS = 160
+MAX_LABEL_CHARS = 80
+MAX_LINE_CHARS = 400
+MAX_TOKENS = 10**12
+ELLIPSIS = "…"
+
+# ANSI/VT escape sequences: CSI (7-bit and the C1 byte), OSC up to BEL or
+# ST (or the end, when unterminated), DCS/SOS/PM/APC strings, and the
+# two-character escapes. What is left of a broken sequence is removed with
+# the other controls below.
+_ESCAPES = re.compile(
+    r"\x1b\[[0-?]*[ -/]*[@-~]"
+    r"|\x9b[0-?]*[ -/]*[@-~]"
+    r"|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?"
+    r"|\x1b[PX^_][^\x1b]*(?:\x1b\\)?"
+    r"|\x1b[ -/]*[0-~]"
+)
+_SPACES = re.compile(r"\s+")
+
+
+def clean(value: object, limit: int) -> str:
+    """``value`` as one safe, bounded line: stripped, redacted, then clipped.
+
+    A non-string is empty; a string longer than :data:`MAX_RAW_CHARS` is an
+    ellipsis. Escape sequences go first, then every control (C0, C1, DEL),
+    format (bidirectional overrides, zero-width characters) and line or
+    paragraph separator character; whitespace controls become spaces. The
+    result is redacted and only then clipped to ``limit`` characters.
+    """
+    if not isinstance(value, str) or limit <= 0:
+        return ""
+    if len(value) > MAX_RAW_CHARS:
+        return ELLIPSIS
+    text = _ESCAPES.sub("", value)
+    kept: list[str] = []
+    for ch in text:
+        category = unicodedata.category(ch)
+        if category == "Cc":
+            if ch in "\t\n\r\v\f":
+                kept.append(" ")
+        elif category in ("Zl", "Zp"):
+            kept.append(" ")
+        elif category == "Cs":
+            kept.append("�")
+        elif category != "Cf":
+            kept.append(ch)
+    text = _SPACES.sub(" ", redact("".join(kept))).strip()
+    if len(text) > limit:
+        text = text[: limit - 1].rstrip() + ELLIPSIS
+    return text
+
+
+@dataclass(frozen=True)
+class ProgressEvent:
+    """One provider-neutral progress event, made safe on construction.
+
+    ``tool`` is the tool's name; ``detail`` is the one allow-listed input
+    the adapter chose for it; ``tokens`` an adapter's token estimate (0 when
+    it has none); ``at`` the monotonic time the adapter saw it.
+    """
+
+    kind: ProgressKind
+    tool: str = ""
+    detail: str = ""
+    tokens: int = 0
+    at: float = field(default_factory=time.monotonic)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "kind", ProgressKind(self.kind))
+        object.__setattr__(self, "tool", clean(self.tool, MAX_TOOL_CHARS))
+        object.__setattr__(self, "detail", clean(self.detail, MAX_DETAIL_CHARS))
+        tokens = self.tokens
+        if isinstance(tokens, bool) or not isinstance(tokens, int) or tokens < 0:
+            tokens = 0
+        object.__setattr__(self, "tokens", min(tokens, MAX_TOKENS))
+
+
+ProgressSink = Callable[[ProgressEvent], None]
+
+
+def guarded(sink: ProgressSink | None) -> ProgressSink | None:
+    """``sink`` wrapped so that it can never fail the invocation reporting to it.
+
+    The first exception the sink raises drops it for the rest of the
+    invocation; progress is observability, never part of the outcome.
+    """
+    if sink is None:
+        return None
+    live = [sink]
+
+    def emit(event: ProgressEvent) -> None:
+        if not live:
+            return
+        try:
+            live[0](event)
+        except Exception:
+            live.clear()
+
+    return emit
+
+
+def relative_path(path: object, cwd: str) -> str:
+    """``path`` relative to ``cwd`` when it lies under it; ``""`` when it is no string."""
+    if not isinstance(path, str):
+        return ""
+    if cwd:
+        base = cwd.rstrip("/") + "/"
+        if path.startswith(base) and len(path) > len(base):
+            return path[len(base) :]
+    return path
+
+
+THINKING_INTERVAL_SECONDS = 30.0
+HEARTBEAT_AFTER_SECONDS = 120.0
+HEARTBEAT_POLL_SECONDS = 5.0
+# How long closing the reporter waits for its heartbeat thread.
+_JOIN_SECONDS = 10.0
+
+Output = Callable[[str], None]
+
+
+def _clock_text(seconds: float) -> str:
+    total = max(0, int(seconds))
+    hours, rest = divmod(total, 3600)
+    minutes, secs = divmod(rest, 60)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}"
+
+
+def _ago(seconds: float) -> str:
+    total = max(0, int(seconds))
+    if total < 60:
+        return f"{total}s"
+    if total < 3600:
+        return f"{total // 60}m{total % 60:02d}s"
+    return f"{total // 3600}h{total % 3600 // 60:02d}m"
+
+
+def _tokens_text(tokens: int) -> str:
+    if tokens >= 1000:
+        return f"~{tokens // 1000}k tokens"
+    return f"~{tokens} tokens"
+
+
+class ProgressReporter:
+    """Renders one invocation's progress events as prefixed lines.
+
+    Use as a context manager around the launch: entering starts the
+    heartbeat thread, leaving stops and joins it, so nothing it starts
+    outlives the invocation. :meth:`sink` is the :data:`ProgressSink` handed
+    to the adapter and may be called from any thread; lines are written
+    under one lock, in order, to every output.
+    """
+
+    def __init__(
+        self,
+        label: str,
+        outputs: Sequence[Output],
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        thinking_interval: float = THINKING_INTERVAL_SECONDS,
+        heartbeat_after: float = HEARTBEAT_AFTER_SECONDS,
+        poll_seconds: float = HEARTBEAT_POLL_SECONDS,
+    ) -> None:
+        self._label = clean(label, MAX_LABEL_CHARS)
+        self._outputs = list(outputs)
+        self._clock = clock
+        self._thinking_interval = thinking_interval
+        self._heartbeat_after = heartbeat_after
+        self._poll_seconds = poll_seconds
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._start = clock()
+        self._last_printed = self._start
+        self._last_event: float | None = None
+        self._last_quiet_line: float | None = None
+        self._events = 0
+        self._tokens = 0
+
+    @property
+    def events(self) -> int:
+        """How many events the sink has received."""
+        return self._events
+
+    def __enter__(self) -> ProgressReporter:
+        thread = threading.Thread(target=self._heartbeat, name="autoforge-progress", daemon=True)
+        try:
+            thread.start()
+        except RuntimeError:
+            # The system refused a thread: the launch goes on without a
+            # heartbeat, since progress never decides whether an agent runs.
+            self.line("no heartbeat: the progress thread could not be started")
+            return self
+        self._thread = thread
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Stop the heartbeat thread and wait for it. Idempotent."""
+        self._stop.set()
+        thread, self._thread = self._thread, None
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(_JOIN_SECONDS)
+
+    def line(self, text: str) -> None:
+        """Print one controller line (the pre-launch facts, the end) with the prefix.
+
+        The text is cleaned like an event's detail, since it can quote a
+        provider's failure reason or a path. Never raises: progress does not
+        decide whether an agent runs or what its result is.
+        """
+        try:
+            with self._lock:
+                self._emit(clean(text, MAX_LINE_CHARS), self._clock())
+        except Exception:  # pragma: no cover - _emit already contains output failures
+            pass
+
+    def sink(self, event: ProgressEvent) -> None:
+        """Take one event from the adapter. Never raises."""
+        try:
+            with self._lock:
+                self._take(event, self._clock())
+        except Exception:  # pragma: no cover - _emit already contains output failures
+            pass
+
+    def poll(self) -> None:
+        """Print a heartbeat when nothing has been printed for the heartbeat interval."""
+        with self._lock:
+            now = self._clock()
+            if now - self._last_printed < self._heartbeat_after:
+                return
+            if self._last_event is None:
+                text = "still running, no activity yet"
+            else:
+                text = (
+                    f"still running, last activity {_ago(now - self._last_event)} ago, "
+                    f"{self._events} events"
+                )
+            self._emit(text, now)
+
+    # -- internals -----------------------------------------------------------
+    def _heartbeat(self) -> None:
+        while not self._stop.wait(self._poll_seconds):
+            try:
+                self.poll()
+            except Exception:  # pragma: no cover - _emit already contains output failures
+                pass
+
+    def _take(self, event: ProgressEvent, now: float) -> None:
+        if event.kind is ProgressKind.LOOP_SUSPECTED:
+            # The controller's own observation, not a sign of the agent's life.
+            self._emit(event.detail or "possible loop", now)
+            return
+        self._events += 1
+        self._last_event = now
+        kind = event.kind
+        if kind in (ProgressKind.THINKING, ProgressKind.ASSISTANT_TEXT):
+            if event.tokens:
+                self._tokens = event.tokens
+            last = self._last_quiet_line
+            if last is not None and now - last < self._thinking_interval:
+                return
+            self._last_quiet_line = now
+            if kind is ProgressKind.ASSISTANT_TEXT:
+                self._emit("writing…", now)
+            elif self._tokens:
+                self._emit(f"thinking… {_tokens_text(self._tokens)}", now)
+            else:
+                self._emit("thinking…", now)
+        elif kind is ProgressKind.TOOL_STARTED:
+            self._emit(f"{event.tool or 'tool'} {event.detail}".rstrip(), now)
+        elif kind is ProgressKind.TOOL_FAILED:
+            self._emit(f"{event.tool or 'tool'} failed", now)
+        elif kind is ProgressKind.STARTED:
+            self._emit(f"agent started ({event.detail})" if event.detail else "agent started", now)
+        elif kind is ProgressKind.PROVIDER_RETRY:
+            self._emit(
+                f"provider retry ({event.detail})" if event.detail else "provider retry", now
+            )
+        # TOOL_FINISHED and ACTIVITY are liveness only: counted, not printed.
+
+    def _emit(self, text: str, now: float) -> None:
+        prefix = f"[{_clock_text(now - self._start)} {self._label}]"
+        line = redact(f"{prefix} {text}")
+        if len(line) > MAX_LINE_CHARS:
+            line = line[: MAX_LINE_CHARS - 1] + ELLIPSIS
+        self._last_printed = now
+        failed = self._deliver(line)
+        # Each dropped output is noted on the ones still live; one that fails
+        # receiving a note is dropped and noted in turn, until none fails.
+        while failed:
+            error = failed.pop(0)
+            note = redact(
+                f"{prefix} progress output dropped: "
+                f"{type(error).__name__}: {clean(str(error), MAX_DETAIL_CHARS)}"
+            )
+            failed.extend(self._deliver(note))
+
+    def _deliver(self, line: str) -> list[Exception]:
+        """Write ``line`` to every live output; drop each that fails and return its errors."""
+        kept: list[Output] = []
+        failed: list[Exception] = []
+        for output in self._outputs:
+            try:
+                output(line)
+            except Exception as exc:
+                failed.append(exc)
+            else:
+                kept.append(output)
+        self._outputs = kept
+        return failed