autoforge-cli 0.1.0a0__py3-none-any.whl

autoforge/runlog.py

@@ -0,0 +1,764 @@
+"""Run logging: one directory per agent invocation, everything redacted.
+
+Layout::
+
+    <state_dir>/logs/<run-id>/
+        events.jsonl                          # one JSON line per invocation, appended
+                                              # in place; never read by the controller
+        <seq>-<phase>-<attempt>/
+            progress.log      # agent steps only: the live progress lines, appended while
+                              # the agent runs (bounded, redacted; ``tail -f`` it)
+            request.json      # phase, profile, provider, model, effort, prompt version,
+                              # cwd, the limits (a command's timeout; an agent's idle
+                              # timeout and max runtime), redacted argv (no environment
+                              # dump)
+            prompt.md         # rendered prompt sent to the agent (redacted)
+            execution.json    # timestamps, exit code, timed_out and, when it did, the
+                              # limit that fired (idle / max_runtime) with the configured
+                              # limits and the last output seen, stdout/stderr sizes,
+                              # whether either stream was truncated at the capture bound
+                              # and what the invocation left behind (descendants killed,
+                              # a group member that survived SIGKILL, an abandoned capture);
+                              # the provider's own summary (provider_summary) when it gave one;
+                              # the outer sandbox's facts (sandbox: enforced, backend and
+                              # version, teardown, network, tmpfs bounds, unset environment
+                              # names, a setup failure) when the launch had one
+            stdout.log        # redacted stdout (head + omission marker + tail when truncated)
+            stderr.log        # redacted stderr (same)
+            control-result.json   # parsed CONTROL_RESULT when one was accepted (redacted)
+            error.txt         # controller-side error, when the step failed
+
+Logs never pollute state.json.
+
+An agent step's directory is published *before* the launch
+(:meth:`RunLogger.begin_step`), so that its ``progress.log`` can be followed
+while the agent runs and survives a kill; the rest of its artifacts are
+written after the agent returned, as for every other step. A crash in
+between leaves a step directory holding only ``progress.log``, which
+advances the sequence like any other step directory.
+
+The step sequence is recovered from the step directory names, not from the
+journal: a step directory is published (and fsynced) before its journal line
+is appended, so the highest directory number is never below the highest
+``seq`` in the journal, and listing the run's own directory is bounded
+(``MAX_RUN_LOG_ENTRIES``) while the journal is not. Those names are the
+one input the sequence has, and the run directory is where the agents
+write too, so only an entry of exactly the shape the controller publishes
+(``STEP_DIR_RE``) counts: an entry named like a step that is not a
+directory, or that numbers a step past ``MAX_STEP_SEQ``, is refused as a
+corrupt run log when the logger is opened, before any agent is launched,
+rather than believed and turned into the next step's path. The journal is
+write-only for the controller: it is opened for appending when the logger
+is opened, before any agent is launched -- created empty if absent, proved
+a single-named regular file no larger than ``MAX_EVENT_JOURNAL_BYTES``
+without being read -- and that descriptor is held until the line is
+appended after the agent returned, so the line can only ever land in the
+inode that was inspected before the launch. A file a same-user agent put
+at the journal's name while it ran (renamed over it, linked to it, planted
+after unlinking it) is refused at the append and receives nothing. The
+cost of recording an invocation is the line, however long the run.
+Nothing inspects the tail before a line is appended either, so a last line
+torn by a crash is glued to the line appended after it: a reader of the
+journal must resync on its own and cannot assume at most one bad line
+(ADR 0001 §5.5).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import threading
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager, suppress
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from .errors import StateError
+from .redaction import redact, redact_argv, redact_dict
+from .safefs import (
+    STATE_DIR_NEEDS_HARD_LINKS,
+    AppendHandle,
+    HardLinksUnavailable,
+    ReadLimitExceeded,
+    SafeRoot,
+    UnreadableEntryError,
+    WalkBudgetExceeded,
+    entry_kind,
+)
+
+# A run identifier is a *file name*: it names the directory this run's logs
+# live in.  `generate_run_id` produces "af-<UTC stamp>-<hex>", but the value
+# actually used comes back from `state.json`, so it is validated wherever it
+# is turned into a path rather than trusted because the controller once
+# generated it.
+RUN_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
+# The largest an event journal may be before the controller refuses to
+# extend it. The controller never reads the journal (the sequence comes from
+# the step directory names), so this bounds no read; it is the size past
+# which the file at that name is not one the controller wrote -- a real
+# journal is a few kilobytes to a few hundred kilobytes per line (the record
+# carries the redacted argv, which holds the rendered prompt, and the
+# accepted CONTROL_RESULT, itself capped) and at most a few thousand lines
+# (one per invocation, bounded by the run's step budget and the correction
+# attempts). It is checked on the opened descriptor's ``st_size``, which is
+# O(1) whatever the file holds, once before the agent is launched (so a
+# journal a same-user agent planted refuses before any work is done, #57)
+# and once at the append after it returned (the one moment the agent has
+# had to enlarge it, #55), on the descriptor held since the first. The
+# budget bounds what the controller is willing to append to, not the
+# file's final size: a journal at exactly the budget is still appended to,
+# and the file that results is refused by the next check.
+MAX_EVENT_JOURNAL_BYTES = 64 * 1024 * 1024
+# The most entries the run's own log directory may hold before the listing
+# that recovers the step sequence refuses instead of listing without end
+# (#56). A run publishes one step directory per invocation, and a run's
+# invocations number in the thousands at most (the step budget times the
+# correction attempts); the journal itself, and the copies an operator moved
+# aside as a refusal told them to, are a handful of names against this. Only
+# the run's own directory is listed: sibling runs under ``logs/`` never
+# count, so a state directory with a long history of runs cannot exhaust
+# this for a reason unrelated to the run being resumed. It is a budget on the
+# listing work, checked when the logger is opened, not a ceiling on what the
+# directory may come to hold: a logger opened at the budget still publishes
+# its step directory, and the next open refuses.
+MAX_RUN_LOG_ENTRIES = 200_000
+# The highest step number the controller will believe from a directory
+# name. A step number is assigned once per invocation and one directory is
+# published for each, so the number of a run's newest step is at most the
+# number of invocations the run has made, and ``MAX_RUN_LOG_ENTRIES`` is
+# already the statement of how many of those a run can have. A name
+# numbering a step past it was not published by this controller, and the
+# number would decide the width of the next step's path (``_step_name``):
+# a same-user agent that plants a name with a few hundred digits must be
+# refused at the logger open, not believed and turned into a name the
+# filesystem rejects after the agent has returned (PR #91 review, fourth
+# round). Like the listing budget it bounds what is believed, not what is
+# published: a logger opened at the bound still records its step, and the
+# next open refuses the result.
+MAX_STEP_SEQ = MAX_RUN_LOG_ENTRIES
+# The exact shape of a step directory name, as ``RunLogger._step_name``
+# publishes it: the zero-padded step number, the lower-cased phase and the
+# attempt. Only an entry of this shape is a sequence record; the journal,
+# the pre-launch probe, and whatever an operator moved aside are not, and
+# are ignored rather than parsed for a number.
+STEP_DIR_RE = re.compile(r"^(\d+)-[a-z0-9._-]+-\d+$")
+# The most one step's ``progress.log`` may grow to. A line is at most a few
+# hundred bytes and thinking is coalesced, so an hour of a busy agent is
+# well under this; past it, lines are counted and a last line says how many
+# were left out.
+MAX_PROGRESS_LOG_BYTES = 1024 * 1024
+
+
+def validate_run_id(run_id: str) -> str:
+    """Return ``run_id`` if it is a safe single path component, else raise.
+
+    ``logs/<run_id>` is a controller write path, so a ``run_id`` of
+    ``"../.."`` (or ``"/etc"``, or one holding a NUL) would move every log
+    artifact of the run out of the state directory.  A state file carrying
+    one is corruption and must fail loudly; :func:`validate_run_id` is the
+    last line before the path is built, and
+    :meth:`autoforge.state.AutoForgeState.from_dict` applies the same rule on
+    load so the failure names the state file rather than the first log write.
+    """
+    if not isinstance(run_id, str) or not RUN_ID_RE.match(run_id) or run_id in (".", ".."):
+        raise StateError(
+            f"invalid run_id {run_id!r}: it names the run's log directory, so it must be a "
+            "single path component of letters, digits, '.', '_' or '-' (at most 128 "
+            "characters, not starting with '.'), never a path, an absolute name or '..'"
+        )
+    return run_id
+
+
+class StepLog:
+    """An agent step's directory, published before the launch, and its ``progress.log``.
+
+    Returned by :meth:`RunLogger.begin_step`. :meth:`append` is a progress
+    output (:class:`autoforge.progress.ProgressReporter`): each line is
+    redacted and written through the descriptor opened before the launch
+    (:meth:`~autoforge.safefs.SafeRoot.append_to`), so a file an agent put
+    at that name while it ran receives nothing and the append refuses. Past
+    :data:`MAX_PROGRESS_LOG_BYTES` lines are counted instead, and
+    :meth:`close` appends one line saying how many were left out.
+    """
+
+    def __init__(self, seq: int, name: str, path: Path, root: SafeRoot, handle: AppendHandle):
+        self.seq = seq
+        self.name = name
+        self.path = path
+        self._root = root
+        self._handle = handle
+        self._written = 0
+        self._omitted = 0
+        self._closed = False
+        self._lock = threading.Lock()
+
+    def append(self, line: str) -> None:
+        """Append one line (an LF is added), within the bound."""
+        data = redact(line).replace("\n", " ") + "\n"
+        size = len(data.encode("utf-8"))
+        with self._lock:
+            if self._closed:
+                return
+            if self._written + size > MAX_PROGRESS_LOG_BYTES:
+                self._omitted += 1
+                return
+            self._root.append_to(self._handle, data)
+            self._written += size
+
+    def close(self) -> None:
+        """Note the omitted lines, if any, and release the file. Idempotent."""
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            try:
+                if self._omitted:
+                    # Past the budget by one bounded line at most.
+                    with suppress(StateError):
+                        self._root.append_to(
+                            self._handle,
+                            f"[{self._omitted} progress line(s) omitted past the "
+                            f"{MAX_PROGRESS_LOG_BYTES}-byte bound]\n",
+                        )
+            finally:
+                self._handle.close()
+                self._root.close()
+
+
+@dataclass
+class ExecutionRecord:
+    run_id: str
+    seq: int
+    phase: str
+    attempt: int = 1
+    correction: bool = False
+    issue_url: str = ""
+    pr_url: str = ""
+    review_round: int = 0
+    profile: str = ""
+    provider: str = ""
+    model: str = ""
+    effort: str = ""
+    prompt_version: str = ""
+    command: list[str] = field(default_factory=list)
+    cwd: str = ""
+    # The wall-clock limit of a controller-run command (a validation or
+    # pre-merge verification command); 0 for an agent, which runs under
+    # the limits below instead.
+    timeout_seconds: int = 0
+    # The agent's limits (``config.AgentLimits``, #193): ``None`` is an idle
+    # limit its CLI cannot be held to, or no wall-clock ceiling.
+    idle_timeout_seconds: int | None = None
+    max_runtime_seconds: int | None = None
+    started_at: str = ""
+    finished_at: str = ""
+    exit_code: int = 0
+    timed_out: bool = False
+    # When it timed out: which limit fired (``executor.LIMIT_IDLE`` /
+    # ``LIMIT_MAX_RUNTIME``). Whatever happened: when its last output was
+    # seen (UTC ISO 8601), ``None`` when it wrote nothing.
+    timeout_limit: str = ""
+    last_activity_at: str | None = None
+    # An agent's invocation (#194): how it ended (``exit``, or the limit that
+    # killed it: ``idle``, ``max_runtime`` or ``loop``; empty when it could
+    # not be run), the loop detector's settings
+    # (``LoopDetectionConfig.as_dict``), what the detector found
+    # (``LoopReport.record``: names, counts and times, never a tool input,
+    # result, output line or digest; ``None`` when nothing) and how many
+    # warnings it printed. All empty for a controller-run command.
+    ended_by: str = ""
+    loop_detection: dict[str, object] = field(default_factory=dict)
+    loop: dict[str, object] | None = None
+    loop_warnings: int = 0
+    # The executor kept head + marker + tail of the stream (see
+    # ``executor.DEFAULT_MAX_OUTPUT_BYTES``); ``stdout.log`` shows the cut.
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+    # What the invocation left behind (see ``executor.ExecutionResult``):
+    # the child exited but its leftovers had to be killed; a process was
+    # still in its group after SIGKILL; a pipe never reached EOF. All False
+    # for a clean exit or a clean kill.
+    descendants_killed: bool = False
+    group_survived_kill: bool = False
+    capture_abandoned: bool = False
+    # Processes it left outside its group (re-parented to the controller)
+    # were killed; one survived SIGKILL; the platform could not check (see
+    # ``executor._Containment``).
+    orphans_killed: bool = False
+    orphan_survived_kill: bool = False
+    orphans_unchecked: bool = False
+    dry_run: bool = False
+    parsed_result: dict | None = None
+    error: str = ""
+    log_dir: str = ""
+    metadata: dict[str, object] = field(default_factory=dict)
+    # A provider's own summary of the run (``AgentExecutionResult.provider_summary``),
+    # written to ``execution.json`` only when the provider gave one.
+    provider_summary: dict[str, object] = field(default_factory=dict)
+    # What the outer sandbox recorded for a sandboxed launch
+    # (``sandbox.SandboxFacts.record``, ADR 0005 D10.4): names, paths, sizes
+    # and a bounded reason, never an environment value. Written to
+    # ``execution.json`` only when the launch had a sandbox.
+    sandbox: dict[str, object] = field(default_factory=dict)
+    # What the launch's interaction broker recorded (``InteractionBroker.record``
+    # plus the ``lifecycle``, ADR 0007 D5.2, #134): the policy, its limits
+    # and, per request, its id, kind, what was asked, the offers, the
+    # directive and the kinds of decision delivered; never an answer's text,
+    # guidance or a tool input. Written to ``execution.json`` only when the
+    # launch had a broker.
+    interaction: dict[str, object] = field(default_factory=dict)
+
+
+class RunLogger:
+    """Writes one directory per agent invocation under ``<logs_dir>/<run_id>``.
+
+    The log tree lives in the controller's state directory, on a machine
+    where the agents the controller launches run as the same user.  So no
+    path here is trusted by name: ``run_id`` must be a single safe path
+    component (it comes from ``state.json``, which a hand edit or a truncated
+    write can corrupt), and every directory and artifact is reached through a
+    :class:`~autoforge.safefs.SafeRoot` -- descriptor-relative, so neither
+    ``logs`` nor ``logs/<run_id>`` nor any step directory can be swapped for a
+    symbolic link that puts controller artifacts somewhere else, and no
+    artifact write can land on a FIFO, a device or a second name for someone
+    else's file.
+
+    The engine passes ``open_state_root`` -- :meth:`autoforge.state
+    .StatePaths.open_root`, which walks from the one directory AutoForge did
+    not create down to the state directory -- so every component from that
+    anchor to a step artifact is checked. A caller with only a pathname gets
+    an anchor at the state directory's parent instead, which still reaches
+    ``logs`` and everything below it without following a link.
+
+    Opening the logger opens the run's event journal for appending and
+    holds it (:class:`~autoforge.safefs.AppendHandle`) until the logger is
+    closed or dropped; every :meth:`log_execution` appends through that
+    handle, so a line reaches the inode proved before the launch or is
+    refused. The engine opens one logger per invocation, immediately before
+    the launch, and lets it go once the invocation is recorded.
+    """
+
+    def __init__(
+        self,
+        logs_dir: str | Path,
+        run_id: str,
+        *,
+        open_state_root: Callable[[], SafeRoot] | None = None,
+    ) -> None:
+        self.run_id = validate_run_id(run_id)
+        self._open_state_root = open_state_root
+        absolute = Path(os.path.abspath(logs_dir))
+        self._anchor = absolute.parent
+        self._logs_name = absolute.name
+        self.run_dir = Path(logs_dir) / self.run_id
+        self.events_path = self.run_dir / "events.jsonl"
+        with self._logs_root() as logs:
+            logs.ensure_dir(self.run_id)
+            self._verify_publishable(logs)
+            # Sequence counter resumes across process restarts.
+            self._seq = self._recover_sequence(logs)
+            # Last, so that nothing above can fail with the handle open.
+            self._journal = self._open_journal(logs)
+
+    def close(self) -> None:
+        """Release the held journal; a later :meth:`log_execution` refuses."""
+        self._journal.close()
+
+    def __enter__(self) -> RunLogger:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    @contextmanager
+    def _logs_root(self) -> Iterator[SafeRoot]:
+        """The ``logs`` directory as a capability, for the duration of one call."""
+        base = (
+            self._open_state_root()
+            if self._open_state_root is not None
+            else SafeRoot.open(self._anchor, create=True)
+        )
+        try:
+            root = base.subroot(self._logs_name, create=True)
+        finally:
+            base.close()
+        try:
+            yield root
+        finally:
+            root.close()
+
+    def _journal_remedy(self, step: str) -> str:
+        """The way to resume that a refused journal leaves the operator."""
+        return (
+            f"The controller only appends to the journal and never reads it, so {step} to "
+            "resume; the step directories are kept and the sequence continues from their "
+            "names"
+        )
+
+    @contextmanager
+    def _refusing_journal(self, unrecorded: str = "") -> Iterator[None]:
+        """Word a refusal of the journal so that it names the manual step.
+
+        The journal is proved twice per invocation, at the open before the
+        launch (:meth:`_open_journal`) and again on the held descriptor at
+        the append after the agent returned (:meth:`log_execution`), and
+        both refuse for the same causes. Every refusal must leave the
+        operator a way to resume, and the cause decides what that is: a
+        file past the size budget is not a controller journal and is moved
+        aside; a journal the controller may not open for writing
+        (``EACCES``: the in-place append needs a writable file where a
+        whole-file replacement needed only a writable directory, and the
+        controller creates the journal ``0600``, so this is a file planted
+        or ``chmod``-ed by someone else) is made writable or moved aside; a
+        link, a FIFO, a directory, or a journal replaced or removed while
+        the agent ran already says what was found and what to move aside.
+        The error keeps its type, so the filesystem cause stays
+        distinguishable; only the message grows. ``unrecorded`` says where
+        an invocation's artifacts are when the refusal is the
+        append's.
+        """
+        journal = f"logs/{self.run_id}/events.jsonl"
+        tail = f"; {unrecorded}" if unrecorded else ""
+        try:
+            yield
+        except ReadLimitExceeded:
+            raise StateError(
+                f"corrupted event journal for run {self.run_id}: larger than "
+                f"{MAX_EVENT_JOURNAL_BYTES} bytes, which no controller journal can be. "
+                f"{self._journal_remedy(f'move {journal} aside')}{tail}"
+            ) from None
+        except UnreadableEntryError as exc:
+            remedy = self._journal_remedy(f"make {journal} writable, or move it aside,")
+            exc.args = (f"{exc}. {remedy}{tail}",)
+            raise
+        except StateError as exc:
+            if tail:
+                exc.args = (f"{exc}{tail}",)
+            raise
+
+    def _refuse_run_dir(self, why: str) -> StateError:
+        return StateError(
+            f"corrupted run log directory for run {self.run_id}: {why}. The directory is "
+            "only listed to continue the step sequence from the step directories it "
+            f"holds, so move the entries AutoForge did not create out of "
+            f"logs/{self.run_id}/ to resume"
+        )
+
+    def _verify_publishable(self, logs: SafeRoot) -> None:
+        """Prove, before the launch, that the run directory takes a new entry.
+
+        The logger is opened before the agent is launched so that a refusal
+        of the run log lands then, charging no launch (#57), rather than
+        after a write-capable agent has returned with work that would go
+        unlogged. That refusal is only as good as what is proved here, and
+        the post-agent record needs the run directory to take a new entry
+        (the step directory's ``mkdir``, then its artifacts). ``logs/<run>``
+        is created ``0700`` by this controller, but an existing one is
+        whatever is there -- a ``0500`` directory, a read-only mount, a
+        filesystem without ``link(2)`` -- and it passes every other check.
+        The last is refused on purpose, not worked around: every artifact is
+        published by ``link(2)`` (``SafeRoot.create_exclusive``), and the
+        refusal says so (:data:`~autoforge.safefs.STATE_DIR_NEEDS_HARD_LINKS`)
+        rather than leaving a generic failed write to explain it (#120).
+        So it is proved the way ``doctor`` proves the state directory: an
+        entry is created there through the same capability and removed
+        again. The proof does not outlive the launch, since the agent runs
+        as the same user and can undo it while it runs; it is the refusal
+        that can land before it does. A crash between the probe's create
+        and its unlink leaves one ``.af-probe-*`` entry, which the sequence
+        listing ignores like any other non-step name. The journal is proved
+        separately, by being opened and held (:meth:`_open_journal`).
+        """
+        run_dir = f"logs/{self.run_id}/"
+        probe = f"{self.run_id}/.af-probe-{os.getpid():x}-{secrets.token_hex(8)}"
+        try:
+            try:
+                logs.create_exclusive(probe, b"")
+            except StateError:
+                # The probe is published before its directory entry is
+                # fsynced, so a create that failed at that last step left
+                # the name behind; it is this controller's and empty, and
+                # removing it is best effort behind the refusal itself.
+                with suppress(StateError):
+                    logs.unlink(probe)
+                raise
+            logs.unlink(probe)
+        except UnreadableEntryError as exc:
+            exc.args = (
+                f"cannot publish into {run_dir}: {exc}. A step directory and its artifacts "
+                f"are published there after every agent invocation, so make {run_dir} "
+                "writable to resume; the step directories are kept and the sequence "
+                "continues from their names",
+            )
+            raise
+        except HardLinksUnavailable as exc:
+            exc.args = (
+                f"cannot publish into {run_dir}: {exc}. A step directory and its artifacts "
+                "are published there after every agent invocation, and "
+                f"{STATE_DIR_NEEDS_HARD_LINKS}",
+            )
+            raise
+        except StateError as exc:
+            exc.args = (
+                f"cannot publish into {run_dir}: {exc}. A step directory and its artifacts "
+                "are published there after every agent invocation",
+            )
+            raise
+
+    def _open_journal(self, logs: SafeRoot) -> AppendHandle:
+        """Open the journal for appending, before the launch, and keep it open.
+
+        The open is the pre-launch proof of the journal (a link, a FIFO, a
+        second name, a file the controller may not write or one past
+        ``MAX_EVENT_JOURNAL_BYTES`` refuses here, charging no launch, #57)
+        and, because the descriptor is held rather than closed, the proof
+        the post-agent append relies on: the line is written through this
+        descriptor, so whatever a same-user agent puts at the journal's name
+        while it runs -- a foreign file renamed over it, a hard link, a
+        fresh file after an unlink -- can never receive it (PR #91 review,
+        fifth round). An absent journal is created here, empty, so that
+        there is an inode to hold; a run directory holding only
+        ``events.jsonl`` is a run whose first launch has not returned.
+        """
+        with self._refusing_journal():
+            return logs.open_append(f"{self.run_id}/events.jsonl", limit=MAX_EVENT_JOURNAL_BYTES)
+
+    def _recover_sequence(self, logs: SafeRoot) -> int:
+        """The highest step number this run has published, from the directory names.
+
+        The journal is not consulted. A step directory is published before
+        its journal line, so the directory names are never behind the
+        journal, and they are what a crash between the two leaves behind;
+        reading the journal as well would only add a cost that grows with
+        the run (#51).
+
+        The names are untrusted: the agents write under the same user. An
+        entry counts only if it has exactly the shape :meth:`_step_name`
+        publishes (``STEP_DIR_RE``), and an entry of that shape must then
+        be what the controller would have published, a directory numbered
+        at most ``MAX_STEP_SEQ``, or the run log is refused as corrupt
+        here, before the launch, with the manual step (move the entry
+        aside). Believing the number would build the next step's path
+        from it; ignoring a step-shaped file would let the next step's
+        ``mkdir`` collide with it after the agent had returned. Any other
+        name (the journal, the probe, an operator's moved-aside copy) is
+        not a step and is skipped without being parsed.
+        """
+        # Only the run's own directory and its immediate children matter, so
+        # the walk starts *at* the run directory (a sub-root, so sibling runs
+        # under ``logs/`` are never listed -- #56) and descends no further:
+        # every entry is skipped, so the step directories' contents are not
+        # listed either. The listing is budgeted (``MAX_RUN_LOG_ENTRIES``):
+        # more entries than a run can publish is not a run directory the
+        # controller wrote, and the walk refuses while listing rather than
+        # after holding a planted million names.
+        highest = 0
+        with logs.subroot(self.run_id) as run:
+            try:
+                for entry in run.walk(max_entries=MAX_RUN_LOG_ENTRIES):
+                    entry.skip = True
+                    match = STEP_DIR_RE.match(entry.name)
+                    if match is None:
+                        continue
+                    if not entry.is_dir:
+                        kind = entry_kind(entry.st.st_mode) or "regular file"
+                        raise self._refuse_run_dir(
+                            f"{entry.name} is named like a step directory but is a {kind}"
+                        )
+                    # A name is at most NAME_MAX bytes, so the conversion
+                    # is bounded by the filesystem before it is bounded here.
+                    seq = int(match.group(1))
+                    if seq > MAX_STEP_SEQ:
+                        raise self._refuse_run_dir(
+                            f"{entry.name} numbers a step past {MAX_STEP_SEQ}, which is more "
+                            "invocations than a run can make"
+                        )
+                    highest = max(highest, seq)
+            except WalkBudgetExceeded:
+                raise self._refuse_run_dir(
+                    f"more than {MAX_RUN_LOG_ENTRIES} entries, which no controller run "
+                    "directory can hold (at most one step directory per invocation)"
+                ) from None
+        return highest
+
+    def _step_name(self, seq: int, phase: str, attempt: int) -> str:
+        safe_phase = re.sub(r"[^a-z0-9._-]", "-", phase.lower()) or "unknown"
+        return f"{seq:03d}-{safe_phase}-{attempt}"
+
+    def begin_step(self, phase: str, attempt: int) -> StepLog:
+        """Publish the next step's directory and open its ``progress.log``, before a launch.
+
+        The step number is taken here, and the record written after the
+        agent returns (:meth:`log_execution` with ``step=``) lands in this
+        directory. Like the logger's own open, this runs before the agent is
+        launched, so a refusal (a name planted where the directory or the
+        file goes) lands while nothing has run. The directory is held as a
+        capability for the appends; the caller closes the returned log, and
+        :meth:`log_execution` closes it too.
+        """
+        seq = self._seq + 1
+        name = self._step_name(seq, phase, attempt)
+        with self._logs_root() as logs:
+            logs.ensure_dir(f"{self.run_id}/{name}")
+            root = logs.subroot(f"{self.run_id}/{name}")
+        try:
+            handle = root.open_append("progress.log", limit=MAX_PROGRESS_LOG_BYTES)
+        except BaseException:
+            root.close()
+            raise
+        self._seq = seq
+        return StepLog(seq, name, self.run_dir / name, root, handle)
+
+    def log_execution(
+        self,
+        record: ExecutionRecord,
+        prompt: str = "",
+        stdout: str = "",
+        stderr: str = "",
+        *,
+        step_log: StepLog | None = None,
+    ) -> Path:
+        """Persist one execution record + artifacts. Returns the step dir.
+
+        With ``step_log`` (an agent step, :meth:`begin_step`) the artifacts
+        go into the directory published before the launch, under its step
+        number, and the progress log is closed first.
+        """
+        if step_log is not None:
+            step_log.close()
+            record.seq = step_log.seq
+            step = step_log.name
+        else:
+            self._seq += 1
+            record.seq = self._seq
+            step = self._step_name(self._seq, record.phase, record.attempt)
+        step_dir = self.run_dir / step
+        record.log_dir = str(step_dir)
+        record.command = redact_argv(record.command)
+        # Metadata is caller-supplied and can quote untrusted text (a
+        # validation command's argv, a feature path). It is written to both
+        # request.json and events.jsonl, so it passes the same boundary the
+        # command and the parsed result do.
+        record.metadata = redact_dict(record.metadata)
+        # The adapter bounds and redacts its summary already; it is redacted
+        # again here because it is written twice, like the metadata.
+        record.provider_summary = redact_dict(record.provider_summary)
+        # Paths and a backend's message; redacted for the same reason.
+        record.sandbox = redact_dict(record.sandbox)
+        # Built from bounded, redacted request fields; redacted again
+        # because it is written twice, like the summary.
+        record.interaction = redact_dict(record.interaction)
+        if record.loop is not None:
+            # Built from cleaned tool names and counts; redacted again
+            # because it is written twice, like the summary.
+            record.loop = redact_dict(record.loop)
+        # Redacted on the record itself, not at each write site: `error` is
+        # persisted three times (execution.json, error.txt and the whole
+        # record in events.jsonl) and a controller-side error quotes agent
+        # stdout, a failing command line and the occasional environment
+        # value. Redacting per call site left the journal -- which serialises
+        # the record wholesale -- with the only unredacted copy.
+        record.error = redact(record.error)
+        # String by string, like the metadata, never as its serialized text:
+        # redacting the JSON and parsing it back let a pattern consume the
+        # syntax around a value (an empty ``GITHUB_TOKEN=`` took the closing
+        # quote, a value before an escaped quote its backslash), so an
+        # accepted result crashed the controller here, and it missed a secret
+        # right after an escape such as ``\n`` (#206).
+        if isinstance(record.parsed_result, dict):
+            record.parsed_result = redact_dict(record.parsed_result)
+        request = {
+            "run_id": record.run_id,
+            "seq": record.seq,
+            "phase": record.phase,
+            "attempt": record.attempt,
+            "correction": record.correction,
+            "issue_url": record.issue_url,
+            "pr_url": record.pr_url,
+            "review_round": record.review_round,
+            "profile": record.profile,
+            "provider": record.provider,
+            "model": record.model,
+            "effort": record.effort,
+            "prompt_version": record.prompt_version,
+            "cwd": record.cwd,
+            "timeout_seconds": record.timeout_seconds,
+            "idle_timeout_seconds": record.idle_timeout_seconds,
+            "max_runtime_seconds": record.max_runtime_seconds,
+            "command": record.command,
+            "metadata": record.metadata,
+        }
+        if record.loop_detection:
+            request["loop_detection"] = record.loop_detection
+        execution = {
+            "started_at": record.started_at,
+            "finished_at": record.finished_at,
+            "exit_code": record.exit_code,
+            "timed_out": record.timed_out,
+            "timeout_limit": record.timeout_limit,
+            "idle_timeout_seconds": record.idle_timeout_seconds,
+            "max_runtime_seconds": record.max_runtime_seconds,
+            "last_activity_at": record.last_activity_at,
+            "stdout_truncated": record.stdout_truncated,
+            "stderr_truncated": record.stderr_truncated,
+            "descendants_killed": record.descendants_killed,
+            "group_survived_kill": record.group_survived_kill,
+            "capture_abandoned": record.capture_abandoned,
+            "orphans_killed": record.orphans_killed,
+            "orphan_survived_kill": record.orphan_survived_kill,
+            "orphans_unchecked": record.orphans_unchecked,
+            "stdout_chars": len(stdout or ""),
+            "stderr_chars": len(stderr or ""),
+            "error": record.error,
+        }
+        if record.provider_summary:
+            execution["provider_summary"] = record.provider_summary
+        if record.sandbox:
+            execution["sandbox"] = record.sandbox
+        if record.interaction:
+            execution["interaction"] = record.interaction
+        if record.loop_detection:
+            execution["ended_by"] = record.ended_by
+            execution["loop_detection"] = record.loop_detection
+            execution["loop_warnings"] = record.loop_warnings
+            if record.loop is not None:
+                execution["loop"] = record.loop
+        base = f"{self.run_id}/{step}"
+        with self._logs_root() as logs:
+            logs.ensure_dir(base)
+            logs.write_text(
+                f"{base}/request.json", json.dumps(request, indent=2, sort_keys=True) + "\n"
+            )
+            logs.write_text(f"{base}/prompt.md", redact(prompt or ""))
+            logs.write_text(
+                f"{base}/execution.json", json.dumps(execution, indent=2, sort_keys=True) + "\n"
+            )
+            logs.write_text(f"{base}/stdout.log", redact(stdout))
+            logs.write_text(f"{base}/stderr.log", redact(stderr))
+            if isinstance(record.parsed_result, dict):
+                logs.write_text(
+                    f"{base}/control-result.json",
+                    json.dumps(record.parsed_result, indent=2, sort_keys=True) + "\n",
+                )
+            if record.error:
+                logs.write_text(f"{base}/error.txt", record.error + "\n")
+            # The step directory and its artifacts are published above,
+            # before the journal line, so a refusal here leaves the sequence
+            # recoverable from the directory names. The append happens after
+            # the agent returned, which is the one moment an agent has had
+            # to replace or enlarge the journal; it goes through the
+            # descriptor held since before the launch, after proving that
+            # the name under this (re-verified) root still names that
+            # inode, that the inode still has one name, and that it is
+            # within the budget, none of it reading a byte (#55). A refusal
+            # of any cause says where the invocation's record is.
+            unrecorded = (
+                f"the invocation's artifacts are in logs/{self.run_id}/{step}/ but its "
+                "journal line was not written"
+            )
+            with self._refusing_journal(unrecorded):
+                logs.append_to(self._journal, json.dumps(asdict(record), sort_keys=True) + "\n")
+        return step_dir