outerloop-science 0.1.0.dev0__py3-none-any.whl

outerloop/harness.py

@@ -0,0 +1,1449 @@
+"""The harness seam: one agent session in, one result out.
+
+`Harness.run` takes rendered brief text and a workspace directory and returns
+a :class:`SessionResult`. Provider quirks (auth, CLI flags, output parsing)
+live inside adapters; context policy lives in `brief` and is shared by every
+backend — that separation is what makes backend comparisons honest
+(docs/design/architecture.md, "The backend seam").
+
+Sessions run in a scrubbed environment: an explicit allowlist plus the one
+API key the backend needs. The bot PAT and anything else in the orchestrator's
+environment never reach a session (threat model: credential theft).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import signal
+import stat
+import subprocess
+import uuid
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any, Protocol
+
+log = logging.getLogger(__name__)
+
+# What a session's environment contains — nothing else survives from the
+# parent. HOME is deliberately NOT inherited: it is redirected to a per-run
+# directory so a session cannot read key files under the real home or poison
+# other runs via ~/.claude state. (Residual risk: the filesystem itself is
+# not sandboxed — same-user absolute paths remain readable. See the threat
+# model; the bot PAT must not live on the account that runs sessions until
+# OS-level sandboxing lands.)
+SESSION_ENV_ALLOWLIST = ("PATH", "TERM", "LANG", "LC_ALL", "TMPDIR")
+
+# Fallbacks only — every orchestrated path threads effective_limits in
+# explicitly (climb/steward CLIs pass turns and minutes; the follow-up CLI
+# derives its timeout from the job walltime). Kept at the session ceilings
+# so a site that forgets still grants the intended budget rather than
+# silently undercutting it.
+DEFAULT_TIMEOUT_S = 5400
+DEFAULT_MAX_TURNS = 120
+
+
+@dataclass(frozen=True)
+class SessionResult:
+    """What happened in one session — everything the orchestrator needs to
+    judge, bill, and report it. The workspace diff is captured by the caller
+    (it owns the git clone); the harness owns only the session.
+
+    On the "timeout" path, cost and session id are unknown (the CLI is killed
+    before it reports); budget accounting must treat a timeout as worst-case
+    spend, not zero.
+    """
+
+    stop_reason: str  # backend's stop reason, or "timeout" / "spawn-error"
+    is_error: bool
+    cost_usd: float
+    num_turns: int
+    session_id: str
+    final_text: str  # the agent's closing message (the research report draft)
+    transcript_path: str  # raw backend output, api-key-redacted, on disk
+    # human-readable cause when is_error: the backend's error subtype and
+    # messages (e.g. "error_max_turns: Reached maximum number of turns
+    # (60)"), or our own explanation on the timeout path. This is what
+    # reports and issue comments show — stop_reason alone reads as noise
+    # ("tool_use") when a session dies mid-tool-call.
+    error_detail: str = ""
+
+
+class Harness(Protocol):
+    """One coding session over a workspace. Implementations are adapters.
+
+    A *run* (one hypothesis) may span many sessions: a session that launches a
+    long experiment ends, and when results arrive the orchestrator wakes the
+    agent with `resume_session_id` — restoring its full working context — and
+    a wake prompt carrying the results. Session state lives in the per-run
+    HOME next to the workspace, so wakes survive orchestrator restarts and can
+    land on a different cluster node (shared filesystem).
+
+    A backend MAY declare a class attribute `supports_resume = False` when it
+    has no trustworthy headless resume. The revise loop checks it (via getattr,
+    default True) and DRAFTS instead of calling run() with a resume id — a resume
+    that silently starts fresh or fails would revise blind or lose a verified
+    improvement. All three current backends resume (`supports_resume=True`;
+    hermes via saved-transcript rehydration). Optional, so test doubles need not
+    declare it."""
+
+    def run(
+        self, brief_text: str, workspace: Path, resume_session_id: str | None = None
+    ) -> SessionResult: ...
+
+
+def session_env(api_key: str, key_variable: str, home: Path) -> dict[str, str]:
+    """The scrubbed environment a session runs with."""
+    env = {name: os.environ[name] for name in SESSION_ENV_ALLOWLIST if name in os.environ}
+    env["HOME"] = str(home)
+    env[key_variable] = api_key
+    return env
+
+
+def _open_nofollow_dir(name: str, dir_fd: int) -> int:
+    """`openat` `name` as a directory under `dir_fd` without following a final
+    symlink; -1 if it is missing, a symlink (ELOOP), or not a directory."""
+    try:
+        return os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_DIRECTORY, dir_fd=dir_fd)
+    except OSError:
+        return -1
+
+
+def _rmtree_at(dir_fd: int, name: str) -> None:
+    """Recursively delete directory `name` under `dir_fd`, anchored on file
+    descriptors and `O_NOFOLLOW` at every level. No path component is ever
+    resolved by name after the first open, so a session that swaps a directory
+    for a symlink mid-delete cannot divert it outside the tree (TOCTOU-safe).
+    Best-effort: a missing entry, a symlink, or a non-directory `name` is a
+    no-op."""
+    fd = _open_nofollow_dir(name, dir_fd)
+    if fd < 0:
+        return  # gone, a symlink (ELOOP), or not a directory
+    try:
+        for child in os.listdir(fd):
+            try:
+                st = os.stat(child, dir_fd=fd, follow_symlinks=False)
+            except OSError:
+                continue
+            if stat.S_ISDIR(st.st_mode):
+                _rmtree_at(fd, child)
+            else:
+                with contextlib.suppress(OSError):
+                    os.unlink(child, dir_fd=fd)
+    finally:
+        os.close(fd)
+    with contextlib.suppress(OSError):
+        os.rmdir(name, dir_fd=dir_fd)
+
+
+@dataclass(frozen=True)
+class VertexConfig:
+    """Claude-on-Vertex auth (ADC): set to bill Anthropic sessions to a GCP
+    project instead of an Anthropic API key. The single owner of the
+    AUTORESEARCH_VERTEX_* env contract is `vertex_from_env`."""
+
+    project: str
+    region: str = "global"
+    # GOOGLE_APPLICATION_CREDENTIALS. Sessions run with a scrubbed per-run
+    # HOME, so ambient ADC discovery inside the session can never find the
+    # real ~/.config/gcloud — vertex_from_env resolves that default to an
+    # explicit path up front. "" only where a metadata server provides
+    # credentials (GCE / workload identity).
+    adc_file: str = ""
+
+    def env(self) -> dict[str, str]:
+        out = {
+            "CLAUDE_CODE_USE_VERTEX": "1",
+            "ANTHROPIC_VERTEX_PROJECT_ID": self.project,
+            "CLOUD_ML_REGION": self.region,
+        }
+        if self.adc_file:
+            out["GOOGLE_APPLICATION_CREDENTIALS"] = self.adc_file
+        return out
+
+
+def vertex_from_env() -> VertexConfig | None:
+    """The deployment's Vertex coordinates, or None (Anthropic-direct). A live
+    flip needs only the env: set AUTORESEARCH_VERTEX_PROJECT to route every
+    claude session through Vertex; unset it to fall back to the API key."""
+    project = os.environ.get("AUTORESEARCH_VERTEX_PROJECT", "").strip()
+    if not project:
+        return None
+    adc = os.path.expanduser(os.environ.get("AUTORESEARCH_VERTEX_ADC", "").strip())
+    if not adc:
+        # resolve the gcloud default NOW, under the real HOME — the session's
+        # HOME is a scrubbed per-run directory where ambient discovery would
+        # find nothing. Absent file: leave "" for metadata-server credentials.
+        default = os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
+        if os.path.isfile(default):
+            adc = default
+    return VertexConfig(
+        project=project,
+        region=os.environ.get("AUTORESEARCH_VERTEX_REGION", "global").strip() or "global",
+        adc_file=adc,
+    )
+
+
+def redact(text: str, secrets: tuple[str, ...]) -> str:
+    """Strip known secrets from text before it is stored anywhere. Installation
+    tokens minted after a call site snapshotted its tuple are covered too: the
+    App provider rotates ~hourly, so the process-wide issued set is consulted
+    at write time, not capture time."""
+    from outerloop.appauth import issued_tokens
+
+    for secret in (*secrets, *issued_tokens()):
+        if secret:
+            text = text.replace(secret, "[redacted]")
+    return text
+
+
+def _error_result(stop_reason: str, transcript_path: str = "", detail: str = "") -> SessionResult:
+    return SessionResult(
+        stop_reason=stop_reason,
+        is_error=True,
+        error_detail=(detail or stop_reason)[:500],
+        cost_usd=0.0,
+        num_turns=0,
+        session_id="",
+        final_text="",
+        transcript_path=transcript_path,
+    )
+
+
+# Substrings that mean "the API itself is unavailable to us" — credit,
+# limit, auth, throttling. Matched only against error surfaces of an
+# is_error result (backend error text, never agent prose). The first group is
+# Anthropic-shaped; the second matches the OpenAI-compatible / hermes+OpenRouter
+# 401 shapes, whose text differs (e.g. "HTTP 401: Missing Authentication
+# header", "No auth credentials found") so the Anthropic patterns miss them.
+OUTAGE_PATTERNS = (
+    "credit balance",
+    "usage limit",
+    "spending limit",
+    "billing",
+    "authentication_error",
+    "invalid x-api-key",
+    "rate_limit_error",
+    "overloaded_error",
+    "401",
+    "missing authentication",
+    "no auth credentials",
+    "invalid api key",
+)
+
+
+def backend_id(harness: object) -> str:
+    """`backend/model` attribution for a round stamp — which reviewer wrote
+    this. Empty for unknown harness types (test fakes): the stamp then omits
+    the reviewer clause rather than naming something misleading."""
+    names = {
+        "ClaudeCodeHarness": "claude",
+        "CodexHarness": "codex",
+        "HermesHarness": "hermes",
+    }
+    backend = names.get(type(harness).__name__, "")
+    if not backend:
+        return ""
+    model = str(getattr(harness, "model", "") or "").strip()
+    return f"{backend}/{model}" if model else backend
+
+
+def outage(result: SessionResult) -> bool:
+    """True when the session failed because the API refused us — dead
+    credits, spend cap, bad key, throttling — not because of anything in
+    the run. Callers treat this as an infrastructure outage: pause the
+    lanes, and never bill the failure against a run's retry caps or a
+    work order's attempts."""
+    if not result.is_error:
+        return False
+    # error_detail is backend error text and always wins; final_text is
+    # consulted ONLY when no detail exists AND it carries the legacy CLI
+    # error shape ("API Error ..."), never agent prose — a failed session's
+    # report that merely MENTIONS billing or limits must not trip a latch
+    # that pauses every lane.
+    surface = result.error_detail.casefold()
+    if not surface:
+        text = result.final_text.strip().casefold()
+        if not text.startswith("api error"):
+            return False
+        surface = text
+    return any(pattern in surface for pattern in OUTAGE_PATTERNS)
+
+
+def budget_exhausted(result: SessionResult) -> bool:
+    """True when the session stopped because OUR limits ran out — turns or
+    session walltime — rather than because anything failed. Callers report
+    this as the budget-exhausted ending, never as an error: "caps hit
+    mid-run" is one of the six honest deaths, not a malfunction."""
+    return result.stop_reason == "timeout" or result.error_detail.startswith("error_max_turns")
+
+
+def _write_private(directory: Path, stem: str, suffix: str, text: str) -> str:
+    """Atomically create a fresh owner-only file and write `text` to it.
+
+    O_EXCL closes the TOCTOU between name choice and creation, and it also
+    refuses symlinks (a session could plant a dangling link where its own
+    transcript will land, redirecting the write to an arbitrary same-user
+    file). Returns the path written, or "" — storage failures must not crash
+    the adapter."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    for n in range(1, 1000):
+        path = directory / (f"{stem}{suffix}" if n == 1 else f"{stem}-{n}{suffix}")
+        try:
+            fd = os.open(path, flags, 0o600)
+        except FileExistsError:
+            continue
+        except OSError as exc:
+            log.warning("could not store transcript at %s: %s", path, exc)
+            return ""
+        with os.fdopen(fd, "w") as handle:
+            handle.write(text)
+        return str(path)
+    log.warning("could not find a free transcript name in %s", directory)
+    return ""
+
+
+def _write_private_fixed(path: Path, text: str) -> bool:
+    """Write `text` to a fixed path, refusing to follow a symlink (a
+    session-writable dir could hold a planted link redirecting the write to an
+    arbitrary same-user file). True on success. Truncates an existing regular
+    file; O_NOFOLLOW makes os.open raise on a symlink."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(path, flags, 0o600)
+        with os.fdopen(fd, "w") as handle:
+            handle.write(text)
+    except OSError:
+        return False
+    return True
+
+
+def _read_no_follow(path: Path) -> str | None:
+    """Read a file's text without following a symlink. None on any error (a
+    missing file lost to a race, or a planted link O_NOFOLLOW refuses)."""
+    try:
+        fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+        with os.fdopen(fd, "r", errors="replace") as handle:
+            return handle.read()
+    except OSError:
+        return None
+
+
+def _collect_hermes_sample(session_home: Path) -> Any:
+    """Load this run's trajectory (newest `sample_*.json`) and delete every one
+    of them. Hardened for a session-writable dir: the mtime sort key cannot
+    raise out of run() on a vanished file, the read does not follow symlinks,
+    and unlink removes the link itself (never its target). Returns the parsed
+    sample, or None."""
+
+    def _mtime(p: Path) -> float:
+        try:
+            return p.stat().st_mtime
+        except OSError:
+            return 0.0
+
+    candidates = sorted(session_home.glob("sample_*.json"), key=_mtime, reverse=True)
+    sample: Any = None
+    if candidates:
+        text = _read_no_follow(candidates[0])
+        if text is not None:
+            with contextlib.suppress(json.JSONDecodeError):
+                sample = json.loads(text)
+    for stale in candidates:
+        with contextlib.suppress(OSError):
+            stale.unlink()  # trajectories can embed the brief; don't accumulate
+    return sample
+
+
+# --- hermes headless resume -------------------------------------------------
+# A headless CLI "resumes" by restarting with its prior context restored (that
+# is all claude --resume and codex exec resume do). Hermes has no --resume flag,
+# but it reads its brief from a file, so resume = the next brief carries the
+# prior conversation. The harness keeps its OWN linear transcript (the message
+# it sent + the assistant reply it parsed each turn), rehydrates it into the
+# resume brief, and persists it in the per-run home beside the other resume
+# state — so a resumed hermes session physically cannot start context-blind.
+
+_RESUME_STEM = "resume-"
+
+
+def _resume_transcript_path(session_home: Path, session_id: str) -> Path:
+    # session_id is harness-minted (uuid hex) — no path traversal — but keep it
+    # to the basename defensively.
+    return session_home / f"{_RESUME_STEM}{os.path.basename(session_id)}.json"
+
+
+def _load_resume_transcript(session_home: Path, session_id: str) -> list[dict[str, str]] | None:
+    """Load a saved transcript for `session_id`. None = not found (the caller
+    must NOT silently start fresh — a resume with no restored context is an
+    error). The per-run home is session-writable, so read without following a
+    symlink."""
+    text = _read_no_follow(_resume_transcript_path(session_home, session_id))
+    if text is None:
+        return None
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    turns = data.get("turns") if isinstance(data, dict) else None
+    if not isinstance(turns, list) or not turns:
+        return None
+    # Accept ONLY a COMPLETE, well-formed conversation, and reject the whole file
+    # on any deviation. The transcript is one we write ([user, assistant] pairs
+    # with non-blank text) into a session-writable home, so anything else —
+    # empty, whitespace-only, a non-dict entry, an unknown role, or a partial
+    # exchange missing the user instructions or the assistant reply — is
+    # corruption or tampering and must surface as "unavailable" (the caller
+    # errors) rather than resume with missing context, the exact context-blind
+    # resume this path exists to reject. We distrust the file as a whole rather
+    # than salvage a subset.
+    cleaned: list[dict[str, str]] = []
+    for t in turns:
+        if not isinstance(t, dict):
+            return None
+        role = str(t.get("role", ""))
+        content = str(t.get("text", ""))
+        if role not in ("user", "assistant") or not content.strip():
+            return None
+        cleaned.append({"role": role, "text": content})
+    roles = {t["role"] for t in cleaned}
+    if "user" not in roles or "assistant" not in roles:
+        return None  # a real prior conversation has instructions AND a reply
+    return cleaned
+
+
+def _save_resume_transcript(
+    session_home: Path, session_id: str, turns: list[dict[str, str]]
+) -> None:
+    """Persist the transcript (0600, symlink-refusing) so the next resume can
+    rehydrate it. Best-effort: a failure just means the next resume errors
+    (resume-unavailable) rather than starting blind."""
+    _write_private_fixed(
+        _resume_transcript_path(session_home, session_id), json.dumps({"turns": turns})
+    )
+
+
+def _render_resume_transcript(turns: list[dict[str, str]]) -> str:
+    """Render prior turns as a readable prefix for the resume brief."""
+    blocks = ["=== Earlier in this session (your prior context) ==="]
+    for t in turns:
+        who = "You were told" if t["role"] == "user" else "You replied"
+        blocks.append(f"[{who}]\n{t['text']}")
+    blocks.append("=== End of prior context; continue with the new instructions below ===")
+    return "\n\n".join(blocks)
+
+
+def _float(value: Any, default: float = 0.0) -> float:
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return default
+
+
+def _int(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return default
+
+
+@dataclass
+class ClaudeCodeHarness:
+    """Headless Claude Code (`claude -p`): the JSON output carries cost,
+    usage, session id, and stop reason.
+
+    `run` never raises: every failure comes back as an error SessionResult.
+    """
+
+    api_key: str
+    binary: str = "claude"
+    model: str = "claude-opus-5"
+    max_turns: int = DEFAULT_MAX_TURNS
+    timeout_s: int = DEFAULT_TIMEOUT_S
+    # The working set for code + running the repo's own tests. Note the env
+    # DOES hold the session API key (the CLI needs it), so Bash here is a
+    # trusted-ish surface; the brief is the only untrusted-ish input and it
+    # passes the task-source gate upstream.
+    allowed_tools: tuple[str, ...] = ("Write", "Edit", "Read", "Glob", "Grep", "Bash")
+    extra_args: tuple[str, ...] = field(default_factory=tuple)
+    # --bare skips hooks, plugin sync, auto-memory, and CLAUDE.md
+    # auto-discovery, and restricts auth to ANTHROPIC_API_KEY. REQUIRED for
+    # judge sessions whose cwd contains an untrusted checkout: a PR-authored
+    # CLAUDE.md or .claude/settings.json (hooks run commands) must never load
+    # as instructions. Off for author sessions, where the target repo's own
+    # CLAUDE.md is useful contributor guidance.
+    bare: bool = False
+    # Apptainer image for session containment. When set,
+    # the session runs under `apptainer exec --containall --cleanenv`: no host
+    # $HOME, no host env, no same-user absolute paths — the session sees only
+    # the workspace, its per-run HOME, and the read-only claude binary. This
+    # closes the threat model's shared-filesystem residual risk. Images stay
+    # generic (python + uv + git); the binary is bind-mounted in.
+    container_image: str = ""
+    apptainer_binary: str = "apptainer"
+    # Claude-on-Vertex (ADC) instead of the Anthropic API key; the api_key is
+    # ignored when set. Contained sessions get the ADC file bind-mounted.
+    vertex: VertexConfig | None = None
+
+    CONTAINER_CLAUDE = "/opt/agent/claude"
+    CONTAINER_ADC = "/opt/agent/adc.json"
+    supports_resume = True  # native --resume
+
+    def run(
+        self, brief_text: str, workspace: Path, resume_session_id: str | None = None
+    ) -> SessionResult:
+        # Both live OUTSIDE the git clone: the transcript must never enter the
+        # diff that gets committed/pushed, and the per-RUN home (0700; reused
+        # across this run's sessions, never across runs — the orchestrator
+        # gives every run a fresh workspace path) is what lets a later wake
+        # restore the agent's working context.
+        transcript_stem = f"{workspace.name}-session"
+        session_home = workspace.parent / f"{workspace.name}-home"
+        try:
+            session_home.mkdir(parents=True, exist_ok=True, mode=0o700)
+            # mkdir's mode is umask-masked and ignored entirely on reuse;
+            # enforce it either way.
+            os.chmod(session_home, 0o700)
+        except OSError as exc:
+            log.warning("could not create session home %s: %s", session_home, exc)
+            return _error_result("workspace-error")
+        # A read-only session (no mutating tool) gets a permission mode that
+        # denies edits rather than auto-accepting them — defense in depth
+        # behind the tool allowlist, so a stray edit tool cannot auto-apply.
+        mutating = {"Write", "Edit", "Bash"}.intersection(self.allowed_tools)
+        permission_mode = "acceptEdits" if mutating else "default"
+        claude_argv = [
+            self.CONTAINER_CLAUDE if self.container_image else self.binary,
+            "-p",
+            # The brief travels on stdin: argv is world-readable via /proc on
+            # shared nodes, and briefs carry private research text.
+            "Follow the brief provided on stdin.",
+            "--model",
+            self.model,
+            "--output-format",
+            "json",
+            "--max-turns",
+            str(self.max_turns),
+            "--allowedTools",
+            ",".join(self.allowed_tools),
+            "--permission-mode",
+            permission_mode,
+            *(["--bare"] if self.bare else []),
+            *self.extra_args,
+        ]
+        if resume_session_id:
+            claude_argv += ["--resume", resume_session_id]
+        if self.container_image:
+            # bind sources must be absolute or apptainer fails at mount time
+            workspace = workspace.resolve()
+            session_home = session_home.resolve()
+            if not os.path.isabs(self.binary):
+                # a relative bind source fails at mount time deep inside
+                # apptainer; catch the misconfiguration here instead
+                log.warning("container sessions need an absolute claude path")
+                return _error_result("config-error")
+            command = [
+                self.apptainer_binary,
+                "exec",
+                "--containall",
+                "--cleanenv",
+                "--bind",
+                f"{workspace}:{workspace}",
+                # --home (NOT --env HOME=..., which apptainer silently
+                # refuses): mounts the per-run home at the same path inside
+                # and sets $HOME to it — native resume state survives
+                # contained/uncontained flips and lands on the shared FS,
+                # not a tmpfs that evaporates at session end.
+                "--home",
+                f"{session_home}:{session_home}",
+                "--bind",
+                f"{self.binary}:{self.CONTAINER_CLAUDE}:ro",
+                *(
+                    ["--bind", f"{Path(self.vertex.adc_file).resolve()}:{self.CONTAINER_ADC}:ro"]
+                    if self.vertex is not None and self.vertex.adc_file
+                    else []
+                ),
+                "--pwd",
+                str(workspace),
+                self.container_image,
+                *claude_argv,
+            ]
+        else:
+            command = claude_argv
+        try:
+            # start_new_session puts the CLI and every descendant (Bash-tool
+            # children included) in one process group we can kill as a unit —
+            # a timed-out session must not leave orphans holding the API key
+            # and writing into the clone.
+            if self.vertex is not None:
+                # vertex auth: ADC only — ANTHROPIC_API_KEY is deliberately
+                # absent so the CLI cannot fall back to direct billing
+                env = session_env("", "ANTHROPIC_API_KEY", session_home)
+                del env["ANTHROPIC_API_KEY"]
+                vertex_env = dict(self.vertex.env())
+                if self.container_image and self.vertex.adc_file:
+                    vertex_env["GOOGLE_APPLICATION_CREDENTIALS"] = self.CONTAINER_ADC
+                env |= vertex_env
+                if self.container_image:
+                    for k, v in vertex_env.items():
+                        env[f"APPTAINERENV_{k}"] = v
+            else:
+                env = session_env(self.api_key, "ANTHROPIC_API_KEY", session_home)
+                if self.container_image:
+                    # --cleanenv drops the host environment inside the container
+                    # EXCEPT APPTAINERENV_* variables, which apptainer injects
+                    # with the prefix stripped — the key travels via the
+                    # environment, never argv (argv is world-readable in /proc).
+                    env["APPTAINERENV_ANTHROPIC_API_KEY"] = self.api_key
+            process = subprocess.Popen(
+                command,
+                cwd=workspace,
+                env=env,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                start_new_session=True,
+            )
+        except OSError as exc:
+            log.warning("could not spawn %s: %s", self.binary, exc)
+            return _error_result("spawn-error")
+
+        try:
+            stdout, stderr = process.communicate(input=brief_text, timeout=self.timeout_s)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.killpg(process.pid, signal.SIGKILL)
+            # Bounded drain: a descendant that left the process group (setsid)
+            # can hold the pipe open past the kill; run() must still return.
+            try:
+                stdout, _ = process.communicate(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                stdout = ""
+                with contextlib.suppress(subprocess.TimeoutExpired):
+                    stdout, _ = process.communicate(timeout=5)
+            path = _write_private(
+                workspace.parent, transcript_stem, ".json", redact(stdout or "", (self.api_key,))
+            )
+            log.warning("session timed out after %ss in %s", self.timeout_s, workspace)
+            return _error_result(
+                "timeout",
+                path,
+                detail=f"session hit its {self.timeout_s}s walltime and was killed",
+            )
+
+        stdout = redact(stdout, (self.api_key,))
+        transcript_path = _write_private(workspace.parent, transcript_stem, ".json", stdout)
+        data = _parse_result(stdout)
+        if data is None:
+            stderr_tail = redact(stderr, (self.api_key,))[-500:]
+            log.warning("unparseable session output (exit %s): %s", process.returncode, stderr_tail)
+            return _error_result("unparseable-output", transcript_path)
+        # Field-level salvage: a quirky cost value must not cost us the
+        # session id (which resume depends on) or vice versa.
+        is_error = bool(data.get("is_error", process.returncode != 0))
+        subtype = str(data.get("subtype") or "")
+        errors = data.get("errors")
+        # capture a real backend cause in ANY form — a list of messages, or a
+        # non-list (dict/str) the CLI might return — so the lift guard below
+        # never mistakes a present cause for an absent one.
+        if isinstance(errors, list):
+            messages = "; ".join(str(e) for e in errors if e)
+        elif errors:
+            messages = str(errors)
+        else:
+            messages = ""
+        detail = f"{subtype}: {messages}" if subtype and messages else (subtype or messages)
+        final_text = str(data.get("result") or "")
+        # The CLI can flag is_error while stamping a content-free subtype
+        # ("success") and leaving the real cause only in `result` (is_error,
+        # subtype "success", result "API Error: 400 ... usage limits"). That
+        # machine "API Error ..." text (never agent prose) is the
+        # authoritative cause, so surface it as the detail: downstream notes,
+        # the operator log, and the outage latch (its classifier AND its
+        # throttle-duration check, which reads rate_limit/overloaded off the
+        # detail) all then see the real error instead of "success". Lift ONLY
+        # for the contradiction we have actually observed: an is_error whose
+        # subtype is empty or the self-contradictory "success", with no backend
+        # `messages`. Under those, `result` is machine error text, not agent
+        # prose. A REAL subtype (error_max_turns, error_during_execution, ...) is
+        # left alone: `result` there may be the agent's own closing message, and
+        # lifting a message that merely starts "API Error" would let agent prose
+        # trip the latch — a false outage pausing every lane is worse than the
+        # rare mis-scoped one.
+        if (
+            is_error
+            and not messages
+            and subtype in ("", "success")
+            and final_text.strip().casefold().startswith("api error")
+        ):
+            detail = final_text.strip()
+        # bounded here so every downstream note/report/comment inherits it
+        detail = detail[:500]
+        return SessionResult(
+            stop_reason=str(data.get("stop_reason") or data.get("subtype") or "unknown"),
+            is_error=is_error,
+            error_detail=detail if is_error else "",
+            cost_usd=_float(data.get("total_cost_usd")),
+            num_turns=_int(data.get("num_turns")),
+            session_id=str(data.get("session_id") or ""),
+            final_text=final_text,
+            transcript_path=transcript_path,
+        )
+
+
+def _parse_result(stdout: str) -> dict[str, Any] | None:
+    """The result object from the CLI's JSON output, or None.
+
+    When stdout is not one clean JSON object, prefer the FIRST candidate that
+    looks like the CLI's result (carries session_id/total_cost_usd): the CLI
+    prints its result before any stray output that follows it, so forward
+    order keeps a trailing look-alike from substituting its fields into
+    billing and resume.
+    """
+    text = stdout.strip()
+    if not text:
+        return None
+    with contextlib.suppress(json.JSONDecodeError):
+        data = json.loads(text)
+        return data if isinstance(data, dict) else None
+    candidates: list[dict[str, Any]] = []
+    for chunk in (*text.splitlines(), text[text.find("{") : text.rfind("}") + 1]):
+        with contextlib.suppress(json.JSONDecodeError):
+            data = json.loads(chunk)
+            if isinstance(data, dict):
+                candidates.append(data)
+    for candidate in candidates:
+        if "session_id" in candidate or "total_cost_usd" in candidate:
+            return candidate
+    return candidates[0] if candidates else None
+
+
+def _codex_command(
+    binary: str,
+    model: str,
+    sandbox: str,
+    workspace: Path,
+    last_message_path: Path,
+    resume_session_id: str | None,
+    extra_args: tuple[str, ...],
+) -> list[str]:
+    """Argv for one headless `codex exec` run.
+
+    The prompt is NOT an argument: `codex exec` reads it from stdin when no
+    positional prompt is given, keeping the brief out of world-readable /proc
+    argv (the same rule as the Claude adapter). Flags verified against
+    codex-cli 0.130.0 (`codex exec[ resume] --help`): --json, --model,
+    --output-last-message, --skip-git-repo-check, and the stdin prompt behavior.
+
+    Fresh and resume take DIFFERENT flags. `codex exec` has `--sandbox` and
+    `--cd`; `codex exec resume <id>` has NEITHER (passing them is an argparse
+    error) — it restores the recorded session, INCLUDING that session's sandbox
+    and cwd (verified on codex-cli 0.130.0). A `danger-full-access` session
+    (every role: the deployment's container or ephemeral runner is the
+    boundary, not codex's own sandbox) adds
+    `--dangerously-bypass-approvals-and-sandbox` on resume — the sandbox is
+    inherited anyway, but the flag also skips approvals so a headless
+    write-heavy turn cannot stall.
+    """
+    # --model is omitted when empty so codex uses its configured default; a
+    # wrong model id is a 404 ("Model not found"), so only pin a verified one.
+    model_flag = ["--model", model] if model else []
+    tail = [
+        "--output-last-message",  # final message -> file (reliable final_text)
+        str(last_message_path),
+        "--skip-git-repo-check",
+        *extra_args,
+    ]
+    if resume_session_id:
+        # no --sandbox/--cd on resume: the recorded session's sandbox is
+        # inherited; the bypass flag also skips approvals so a headless turn
+        # cannot stall waiting for one.
+        bypass = (
+            ["--dangerously-bypass-approvals-and-sandbox"]
+            if sandbox == "danger-full-access"
+            else []
+        )
+        return [binary, "exec", "resume", resume_session_id, "--json", *model_flag, *bypass, *tail]
+    return [
+        binary,
+        "exec",
+        "--json",  # JSONL events on stdout (session id, usage)
+        *model_flag,
+        "--sandbox",
+        sandbox,  # "danger-full-access": the deployment's boundary, not codex's
+        "--cd",
+        str(workspace),
+        *tail,
+    ]
+
+
+def _parse_codex_result(
+    stdout: str, last_message: str, returncode: int, transcript_path: str = "", stderr: str = ""
+) -> SessionResult:
+    """Best-effort SessionResult from `codex exec --json` output.
+
+    `final_text` comes from the --output-last-message file, which is reliable.
+    `session_id` is the `thread.started` event's `thread_id`, verified against
+    codex-cli 0.130.0 (a `codex exec resume <thread_id>` recalls the session).
+    Cost is left at 0 (these backends are subscription or token metered; the
+    budget layer meters them by a session/token proxy). Never raises.
+    """
+    # Event schema verified against codex-cli 0.130.0:
+    #   thread.started -> thread_id (the session id)
+    #   error          -> message
+    #   turn.failed    -> error.message
+    #   turn.completed -> success (usage carries tokens)
+    session_id = ""
+    saw_error = False
+    errors: list[str] = []
+    for line in stdout.splitlines():
+        text = line.strip()
+        if not text.startswith("{"):
+            continue  # timestamped log lines interleave the JSONL; skip them
+        try:
+            event = json.loads(text)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        etype = str(event.get("type", ""))
+        if etype == "thread.started" and not session_id:
+            thread_id = event.get("thread_id")
+            if isinstance(thread_id, str):
+                session_id = thread_id
+        elif etype == "error":
+            saw_error = True
+            message = event.get("message")
+            if isinstance(message, str):
+                errors.append(message)
+        elif etype == "turn.failed":
+            saw_error = True
+            err = event.get("error")
+            message = err.get("message") if isinstance(err, dict) else None
+            if isinstance(message, str):
+                errors.append(message)
+    is_error = returncode != 0 or saw_error
+    detail = "; ".join(errors)[:500]
+    # Fall back to stderr so a failed run (e.g. a bad flag, no matching event)
+    # carries some cause instead of an empty detail.
+    if is_error and not detail and stderr.strip():
+        detail = stderr.strip()[-500:]
+    return SessionResult(
+        stop_reason="error" if is_error else "completed",
+        is_error=is_error,
+        error_detail=detail if is_error else "",
+        cost_usd=0.0,
+        num_turns=0,
+        session_id=session_id,
+        final_text=last_message.strip(),
+        transcript_path=transcript_path,
+    )
+
+
+@dataclass
+class CodexHarness:
+    """Headless OpenAI Codex CLI (`codex exec`) — a second Harness backend.
+
+    Stage 1's swappability proof (docs/design/consolidation.md). CLI flags AND
+    headless resume are verified against codex-cli 0.130.0 (`session_id` = the
+    `thread.started` `thread_id`; resume recalls it); cost parsing stays
+    best-effort (these backends are metered by a session/token proxy in the
+    budget layer).
+
+    CONTAINED mode (`container_image` set): both `codex login` and `codex exec`
+    run inside `apptainer exec --containall --cleanenv`, sharing a bound
+    `--home` so the login's auth.json is visible to the exec. apptainer is the
+    boundary — no host FS beyond the two binds; `--cleanenv` scrubs the env
+    down to the role's own key, so the process tree carries no foreign token
+    for a /proc read to lift (the boundary is the scrubbed env, not PID
+    isolation) — the same posture as the Claude backend. `--sandbox
+    danger-full-access` uniformly: codex's own sandbox (`workspace-write`)
+    needs bubblewrap, absent in the image and unreliable nested in apptainer,
+    and the deployment's boundary (this container, or the ephemeral runner in
+    the uncontained case) already confines the session. The host codex binary
+    is bind-mounted read-only into the container (like claude), so the image
+    stays codex-free and codex updates by swapping one host binary.
+
+    `run` never raises: every failure comes back as an error SessionResult.
+    """
+
+    api_key: str
+    binary: str = "codex"
+    # empty -> codex's configured default (a wrong id 404s); pin only a verified one
+    model: str = ""
+    # the deployment's container or ephemeral runner is the boundary; codex's own
+    # sandbox stays off (it needs bubblewrap — absent/unreliable in apptainer)
+    sandbox: str = "danger-full-access"
+    timeout_s: int = DEFAULT_TIMEOUT_S
+    extra_args: tuple[str, ...] = field(default_factory=tuple)
+    # when set, login+exec run inside this apptainer image; empty = uncontained
+    # (the deployment's runner is the boundary)
+    container_image: str = ""
+    apptainer_binary: str = "apptainer"
+    # in-container path the host codex binary is bound to (bind-from-host, like
+    # ClaudeCodeHarness.CONTAINER_CLAUDE — the image stays codex-free, and codex
+    # is updated by swapping one host binary, no rebuild). A bare class attribute
+    # (no annotation) so the dataclass does not treat it as a field.
+    CONTAINER_CODEX = "/opt/agent/codex"
+    # Headless resume is validated on codex-cli 0.130.0: a contained
+    # `codex exec resume <thread_id>` recalls prior-turn context (the session id
+    # is the `thread.started` event's `thread_id`, restored from the bound
+    # --home). So the revise/wake/followup loops resume codex like Claude.
+    supports_resume = True
+
+    def _apptainer_argv(
+        self, inner: list[str], session_home: Path, workspace: Path | None
+    ) -> list[str]:
+        """Wrap a codex argv in `apptainer exec --containall --cleanenv`. The
+        run-home is bound via `--home` (auth.json survives login->exec and lands
+        on the shared FS); the host codex binary is bind-mounted read-only (like
+        the claude author); the workspace is bound and set as --pwd only for the
+        exec, never the login."""
+        argv = [
+            self.apptainer_binary,
+            "exec",
+            "--containall",
+            "--cleanenv",
+            "--home",
+            f"{session_home}:{session_home}",
+            "--bind",
+            f"{self.binary}:{self.CONTAINER_CODEX}:ro",
+        ]
+        if workspace is not None:
+            argv += ["--bind", f"{workspace}:{workspace}", "--pwd", str(workspace)]
+        return [*argv, self.container_image, *inner]
+
+    def _login(self, session_home: Path) -> SessionResult | None:
+        """Write auth.json into the per-run HOME. None on success, an error
+        SessionResult on failure. The key travels on stdin, never argv. In
+        AUTHOR mode the login runs inside apptainer with the same bound --home,
+        so auth.json lands where the contained exec will read it."""
+        env = session_env(self.api_key, "OPENAI_API_KEY", session_home)
+        if self.container_image:
+            # --cleanenv drops host env inside the container except APPTAINERENV_*
+            # (prefix stripped by apptainer): the key travels via env, not argv.
+            env["APPTAINERENV_OPENAI_API_KEY"] = self.api_key
+            login_argv = self._apptainer_argv(
+                [self.CONTAINER_CODEX, "login", "--with-api-key"], session_home, None
+            )
+        else:
+            login_argv = [self.binary, "login", "--with-api-key"]
+        try:
+            proc = subprocess.run(
+                login_argv,
+                input=self.api_key,
+                cwd=session_home,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+        except OSError as exc:
+            log.warning("could not spawn codex login: %s", exc)
+            return _error_result("codex-login-error", detail=str(exc)[:200])
+        except subprocess.TimeoutExpired:
+            return _error_result("codex-login-error", detail="codex login timed out")
+        if proc.returncode != 0:
+            detail = redact((proc.stderr or proc.stdout or "").strip(), (self.api_key,))[-300:]
+            log.warning("codex login failed: %s", detail)
+            return _error_result("codex-login-error", detail=detail or "codex login failed")
+        return None
+
+    def _purge_auth(self, session_home: Path) -> None:
+        """Delete the API key that `codex login` wrote to auth.json, so it does
+        not persist on disk past the session."""
+        with contextlib.suppress(OSError):
+            (session_home / ".codex" / "auth.json").unlink()
+
+    def run(
+        self, brief_text: str, workspace: Path, resume_session_id: str | None = None
+    ) -> SessionResult:
+        # Contained runs bind workspace + home into apptainer, whose bind sources
+        # must be ABSOLUTE (a relative one fails at mount time); resolving here
+        # also keeps codex's --cd / --output-last-message aligned with the mount
+        # points inside the container.
+        if self.container_image:
+            workspace = workspace.resolve()
+            if not os.path.isabs(self.binary):
+                # the host codex is bind-mounted; a relative bind source fails at
+                # mount time deep inside apptainer — catch it here instead
+                log.warning("contained codex needs an absolute binary path")
+                return _error_result("config-error")
+        transcript_stem = f"{workspace.name}-codex"
+        session_home = workspace.parent / f"{workspace.name}-home"
+        try:
+            session_home.mkdir(parents=True, exist_ok=True, mode=0o700)
+            os.chmod(session_home, 0o700)
+        except OSError as exc:
+            log.warning("could not create session home %s: %s", session_home, exc)
+            return _error_result("workspace-error")
+        # Codex leaks temp directories into .codex/.tmp and fails to remove
+        # them (the "stale arg0 temp dirs: Directory not empty" aborts); across
+        # a run's wakes they pile up into tens of thousands of files, the bulk
+        # of the per-run home. Clear codex's scratch before each run — its
+        # durable state (auth.json, sessions, the sqlite) is elsewhere under
+        # .codex and untouched. A prior session owns this home, so resolve every
+        # component it can write — the run home and .codex — with O_NOFOLLOW,
+        # anchored on the run directory the orchestrator owns (a contained
+        # session's binds expose only the run home and workspace, never their
+        # parent; an uncontained session runs as a plain host process, so
+        # guarding these two components is the boundary either way). A swap of
+        # ws-home or .codex for a symlink then cannot divert the delete out of
+        # the run home. Best-effort — this must never abort the run it precedes
+        # (the contract is to return a SessionResult, not raise), so an
+        # adversarially deep tree's RecursionError or any other error is caught.
+        try:
+            run_fd = os.open(session_home.parent, os.O_RDONLY | os.O_DIRECTORY)
+        except OSError:
+            run_fd = -1
+        if run_fd >= 0:
+            home_fd = _open_nofollow_dir(session_home.name, run_fd)
+            os.close(run_fd)
+            if home_fd >= 0:
+                codex_fd = _open_nofollow_dir(".codex", home_fd)
+                if codex_fd >= 0:
+                    try:
+                        for scratch in (".tmp", "tmp"):
+                            _rmtree_at(codex_fd, scratch)
+                    except Exception as exc:
+                        log.warning("codex scratch cleanup skipped: %s", exc)
+                    finally:
+                        os.close(codex_fd)
+                os.close(home_fd)
+        # Codex authenticates from ~/.codex/auth.json, not OPENAI_API_KEY alone
+        # (the responses endpoint 401s on env-only). Write auth.json
+        # into the scrubbed per-run HOME with `codex login --with-api-key`
+        # (key on stdin, never argv) before exec.
+        login_error = self._login(session_home)
+        if login_error is not None:
+            return login_error
+        # --output-last-message target lives inside the per-run home (0700),
+        # not the shared parent, so model output is not exposed there while
+        # codex is writing it; cleared first so a stale file can never be read
+        # as this run's result, and deleted again after reading.
+        last_message_path = session_home / "codex-last-message.txt"
+        with contextlib.suppress(OSError):
+            last_message_path.unlink()
+        # contained runs invoke the image's codex (on PATH); uncontained the
+        # host binary. The exec binds the workspace and sets it as --pwd.
+        codex_argv = _codex_command(
+            self.CONTAINER_CODEX if self.container_image else self.binary,
+            self.model,
+            self.sandbox,
+            workspace,
+            last_message_path,
+            resume_session_id,
+            self.extra_args,
+        )
+        command = (
+            self._apptainer_argv(codex_argv, session_home, workspace)
+            if self.container_image
+            else codex_argv
+        )
+        try:
+            env = session_env(self.api_key, "OPENAI_API_KEY", session_home)
+            if self.container_image:
+                env["APPTAINERENV_OPENAI_API_KEY"] = self.api_key
+            process = subprocess.Popen(
+                command,
+                cwd=workspace,
+                env=env,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                start_new_session=True,
+            )
+        except OSError as exc:
+            log.warning("could not spawn %s: %s", self.binary, exc)
+            self._purge_auth(session_home)
+            return _error_result("spawn-error")
+        try:
+            stdout, stderr = process.communicate(input=brief_text, timeout=self.timeout_s)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.killpg(process.pid, signal.SIGKILL)
+            try:
+                stdout, _ = process.communicate(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                stdout = ""
+                with contextlib.suppress(subprocess.TimeoutExpired):
+                    stdout, _ = process.communicate(timeout=5)
+            path = _write_private(
+                workspace.parent, transcript_stem, ".jsonl", redact(stdout or "", (self.api_key,))
+            )
+            with contextlib.suppress(OSError):
+                last_message_path.unlink()  # clean up on the timeout path too
+            self._purge_auth(session_home)
+            log.warning("codex session timed out after %ss in %s", self.timeout_s, workspace)
+            return _error_result(
+                "timeout",
+                path,
+                detail=f"session hit its {self.timeout_s}s walltime and was killed",
+            )
+        stdout = redact(stdout, (self.api_key,))
+        transcript_path = _write_private(workspace.parent, transcript_stem, ".jsonl", stdout)
+        last_message = ""
+        # errors="replace": a non-UTF-8 last-message file must not raise
+        # UnicodeDecodeError (not an OSError) and break the never-raises contract.
+        with contextlib.suppress(OSError):
+            last_message = redact(last_message_path.read_text(errors="replace"), (self.api_key,))
+        # The final message is preserved in the 0600 transcript; drop the raw
+        # file so model output is not left behind.
+        with contextlib.suppress(OSError):
+            last_message_path.unlink()
+        self._purge_auth(session_home)
+        return _parse_codex_result(
+            stdout,
+            last_message,
+            process.returncode,
+            transcript_path,
+            stderr=redact(stderr, (self.api_key,)),
+        )
+
+
+def _hermes_command(
+    repo_dir: Path,
+    query: str,
+    model: str,
+    base_url: str,
+    max_turns: int,
+    enabled_toolsets: tuple[str, ...],
+    disabled_toolsets: tuple[str, ...],
+    extra_args: tuple[str, ...],
+) -> list[str]:
+    """Argv for one headless hermes run (`run_agent.py`, fire-style flags,
+    hermes-agent v0.20.1).
+
+    The BRIEF is never in argv — it is written to a file and `query` is only a
+    short pointer instruction. The API key is never in argv either: hermes
+    reads it from the env var its SEEDED PROVIDER's registry names (the
+    harness exports it under key_env; openrouter reads OPENROUTER_API_KEY,
+    openai-api reads OPENAI_API_KEY). --save_sample makes hermes write a JSON
+    trajectory to its cwd, which is the machine-readable result channel."""
+    argv = [
+        "uv",
+        "run",
+        "--project",
+        str(repo_dir),
+        "python",
+        str(repo_dir / "run_agent.py"),
+        f"--query={query}",
+        f"--max_turns={max_turns}",
+        "--save_sample",
+    ]
+    if model:
+        argv.append(f"--model={model}")
+    if base_url:
+        argv.append(f"--base_url={base_url}")
+    # Embedded quotes are load-bearing: fire literal-evals flag values, so a
+    # bare `a,b` becomes a Python TUPLE and hermes's .split(",") crashes.
+    # `"a,b"` evals to the string hermes expects.
+    if enabled_toolsets:
+        argv.append(f'--enabled_toolsets="{",".join(enabled_toolsets)}"')
+    if disabled_toolsets:
+        argv.append(f'--disabled_toolsets="{",".join(disabled_toolsets)}"')
+    return [*argv, *extra_args]
+
+
+def _parse_hermes_result(
+    stdout: str, sample: Any, returncode: int, transcript_path: str = ""
+) -> SessionResult:
+    """Best-effort SessionResult from a hermes run.
+
+    Prefers the --save_sample trajectory JSON (assistant messages + turn
+    count); falls back to raw stdout as the final text. Cost is left at 0
+    (metered by the budget layer's proxy). Never raises."""
+    final_text = ""
+    num_turns = 0
+    # hermes saves ShareGPT-format trajectories ({"from": "gpt", "value": ...}),
+    # either as a bare list or wrapped in a dict; accept role/content too.
+    messages: list[Any] = []
+    if isinstance(sample, list):
+        messages = sample
+    elif isinstance(sample, dict):
+        # run_agent.py --save_sample wraps the ShareGPT turns under
+        # "conversations" (hermes v0.20.1); accept "messages"/"trajectory"
+        # too for other paths. Missing this key makes num_turns==0 and
+        # drops a real verdict as a bogus error.
+        wrapped = (
+            sample.get("conversations") or sample.get("messages") or sample.get("trajectory") or []
+        )
+        messages = wrapped if isinstance(wrapped, list) else []
+    assistant = [
+        m
+        for m in messages
+        if isinstance(m, dict)
+        and (m.get("role") == "assistant" or m.get("from") == "gpt")
+        and (m.get("content") or m.get("value"))
+    ]
+    num_turns = len(assistant)
+    if assistant:
+        content = assistant[-1].get("content") or assistant[-1].get("value")
+        final_text = content if isinstance(content, str) else str(content)
+    if not final_text:
+        final_text = stdout.strip()[-20_000:]
+    # hermes exits 0 even when every API call failed; a run with no
+    # assistant output is a failure, not a report
+    is_error = returncode != 0 or num_turns == 0
+    return SessionResult(
+        stop_reason="error" if is_error else "completed",
+        is_error=is_error,
+        error_detail=stdout.strip()[-500:] if is_error else "",
+        cost_usd=0.0,
+        num_turns=num_turns,
+        session_id="",  # HermesHarness.run injects the resume id (saved-transcript seam)
+        final_text=final_text,
+        transcript_path=transcript_path,
+    )
+
+
+@dataclass
+class HermesHarness:
+    """Headless hermes-agent (Nous Research, MIT) — the OSS backend behind the
+    Harness seam, driven via `uv run <repo>/run_agent.py` from a pinned clone.
+
+    A first-class, interchangeable backend: like claude and codex, its boundary
+    is the deployment's (a container where one exists, the ephemeral runner
+    where one doesn't) plus the tokenless split — the session is spawned with a
+    scrubbed environment and no credential beyond its own key, so its `file`
+    toolset's arbitrary-path reads (including /proc) find nothing to lift, and
+    its writes are confined to the disposable workspace. Roles differ by
+    prompt, never by a hermes-specific posture.
+    Instruction-file surface: hermes auto-loads AGENTS.md from the workspace,
+    which sanitize_checkout already neutralizes in untrusted trees.
+
+    RESUME: hermes has no `--resume` flag, but it reads its brief from a file, so
+    a resume rehydrates the prior conversation into the next brief (the harness
+    keeps its own transcript in the per-run home). A resumed session therefore
+    carries its full prior context — it cannot silently start blind — so the
+    revise/wake loops resume hermes like the other backends.
+
+    `run` never raises: every failure comes back as an error SessionResult.
+    """
+
+    supports_resume = True  # via saved-transcript rehydration (no native flag)
+
+    api_key: str  # exported via key_env (never argv)
+    repo_dir: Path  # pinned hermes-agent checkout
+    # hermes resolves credentials from provider-specific env vars (a registry:
+    # OPENROUTER_API_KEY for the OpenRouter default, ANTHROPIC_API_KEY for the
+    # direct anthropic provider, ...); name the one matching the provider
+    key_env: str = "OPENROUTER_API_KEY"
+    # hermes needs a provider in ~/.hermes/config.yaml (a scrubbed HOME has
+    # none, and it refuses to run "unconfigured"); when set, the harness
+    # pre-seeds a minimal config in the per-run home
+    provider: str = ""
+    # approvals.deny: fnmatch globs hermes refuses before any yolo/mode-off
+    # bypass (headless: a clean deny, never a hang). NOTE it matches SHELL
+    # COMMANDS (the terminal tool), NOT the write_file/patch tool calls.
+    # Useful to hardline-forbid specific dangerous commands.
+    approvals_deny: tuple[str, ...] = ()
+    model: str = ""  # OpenRouter format (provider/model); empty -> hermes default
+    base_url: str = ""  # empty -> the seeded provider's own endpoint
+    max_turns: int = DEFAULT_MAX_TURNS
+    timeout_s: int = DEFAULT_TIMEOUT_S
+    enabled_toolsets: tuple[str, ...] = ("file",)
+    disabled_toolsets: tuple[str, ...] = (
+        "terminal",
+        "web",
+        "search",
+        "browser",
+        "computer_use",
+        "code_execution",
+        "delegation",
+        "cronjob",
+        "skills",
+        "memory",
+    )
+    extra_args: tuple[str, ...] = field(default_factory=tuple)
+    # Apptainer image for session containment, same stance as the other
+    # backends: when set, the session runs under `apptainer exec --containall
+    # --cleanenv` seeing only the workspace, the per-run home, and a read-only
+    # bind of the pinned hermes repo. The project venv and uv cache live in
+    # the per-run home (UV_PROJECT_ENVIRONMENT/UV_CACHE_DIR), so the repo
+    # bind stays read-only and nothing survives across runs.
+    container_image: str = ""
+    apptainer_binary: str = "apptainer"
+
+    def run(
+        self, brief_text: str, workspace: Path, resume_session_id: str | None = None
+    ) -> SessionResult:
+        transcript_stem = f"{workspace.name}-hermes"
+        session_home = workspace.parent / f"{workspace.name}-home"
+        try:
+            session_home.mkdir(parents=True, exist_ok=True, mode=0o700)
+            os.chmod(session_home, 0o700)
+        except OSError as exc:
+            log.warning("could not create session home %s: %s", session_home, exc)
+            return _error_result("workspace-error")
+        # Resume: rehydrate the prior conversation into this brief. A missing
+        # transcript is a hard error, NOT a blind fresh start (the deployment
+        # must preserve the per-run home for resume, same as claude's $HOME /
+        # codex's --home). A fresh run mints a session id to persist under.
+        session_id = resume_session_id or uuid.uuid4().hex[:16]
+        prior_turns: list[dict[str, str]] = []
+        brief_to_send = brief_text
+        if resume_session_id:
+            loaded = _load_resume_transcript(session_home, resume_session_id)
+            if loaded is None:
+                log.warning("hermes resume %s: no saved transcript in %s", session_id, session_home)
+                return _error_result(
+                    "resume-unavailable",
+                    detail="no saved transcript to restore this session's context",
+                )
+            prior_turns = loaded
+            brief_to_send = f"{_render_resume_transcript(prior_turns)}\n\n{brief_text}"
+        if self.provider:
+            # minimal headless config: provider + default model, nothing else
+            hermes_dir = session_home / ".hermes"
+            try:
+                hermes_dir.mkdir(mode=0o700, exist_ok=True)
+                config_lines = ["model:\n", f'  provider: "{self.provider}"\n']
+                if self.model:
+                    config_lines.insert(1, f'  default: "{self.model}"\n')
+                if self.approvals_deny:
+                    config_lines.append("approvals:\n  deny:\n")
+                    config_lines += [f'    - "{glob}"\n' for glob in self.approvals_deny]
+                if not _write_private_fixed(hermes_dir / "config.yaml", "".join(config_lines)):
+                    raise OSError("hermes config write refused (symlink?) or failed")
+            except OSError as exc:
+                log.warning("could not seed hermes config: %s", exc)
+                return _error_result("workspace-error", detail="could not seed hermes config")
+        # The brief travels via a 0600 file (argv is world-readable in /proc);
+        # the --query is only a fixed pointer to it. On resume this file carries
+        # the rehydrated prior context ahead of the new instructions.
+        brief_path = Path(_write_private(session_home, "brief", ".md", brief_to_send))
+        if not brief_path.name:
+            return _error_result("workspace-error", detail="could not store the brief")
+        query = (
+            f"Read the file {brief_path} and follow it as your complete brief. "
+            f"The tree to work on is at {workspace.resolve()}."
+        )
+        command = _hermes_command(
+            Path(self.repo_dir),
+            query,
+            self.model,
+            self.base_url,
+            self.max_turns,
+            self.enabled_toolsets,
+            self.disabled_toolsets,
+            self.extra_args,
+        )
+        if self.container_image:
+            workspace_abs = workspace.resolve()
+            home_abs = session_home.resolve()
+            repo_abs = Path(self.repo_dir).resolve()
+            command = [
+                self.apptainer_binary,
+                "exec",
+                "--containall",
+                "--cleanenv",
+                "--bind",
+                f"{workspace_abs}:{workspace_abs}",
+                # --home mounts the per-run home at the same path inside and
+                # sets $HOME to it — hermes config, brief, samples, and the
+                # resume transcript all persist on the shared FS
+                "--home",
+                f"{home_abs}:{home_abs}",
+                "--bind",
+                f"{repo_abs}:{repo_abs}:ro",
+                "--pwd",
+                str(home_abs),
+                self.container_image,
+                *command,
+            ]
+        try:
+            env = session_env(self.api_key, self.key_env, session_home)
+            # the repo bind is read-only: uv builds the project venv and its
+            # cache in the per-run home instead (fresh per run; nothing shared
+            # across sessions)
+            env["UV_PROJECT_ENVIRONMENT"] = str(session_home / "venv")
+            env["UV_CACHE_DIR"] = str(session_home / "uv-cache")
+            env["UV_LINK_MODE"] = "copy"
+            if self.container_image:
+                # --cleanenv drops the host env inside the container EXCEPT
+                # APPTAINERENV_* — the key travels via env, never argv
+                for k in (self.key_env, "UV_PROJECT_ENVIRONMENT", "UV_CACHE_DIR", "UV_LINK_MODE"):
+                    env[f"APPTAINERENV_{k}"] = env[k]
+            # cwd is the per-run home, NOT the workspace: --save_sample writes
+            # its trajectory JSON to cwd, and artifacts must never land in the
+            # clone (they would enter the diff).
+            process = subprocess.Popen(
+                command,
+                cwd=session_home,
+                env=env,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                start_new_session=True,
+            )
+        except OSError as exc:
+            log.warning("could not spawn hermes: %s", exc)
+            return _error_result("spawn-error", detail=str(exc)[:200])
+        try:
+            stdout, _ = process.communicate(timeout=self.timeout_s)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.killpg(process.pid, signal.SIGKILL)
+            try:
+                stdout, _ = process.communicate(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                stdout = ""
+                with contextlib.suppress(subprocess.TimeoutExpired):
+                    stdout, _ = process.communicate(timeout=5)
+            path = _write_private(
+                workspace.parent, transcript_stem, ".log", redact(stdout or "", (self.api_key,))
+            )
+            log.warning("hermes session timed out after %ss in %s", self.timeout_s, workspace)
+            _collect_hermes_sample(session_home)  # drop trajectories (may embed the brief) too
+            with contextlib.suppress(OSError):
+                brief_path.unlink()  # the brief holds PR content; clean up on timeout too
+            return _error_result(
+                "timeout",
+                path,
+                detail=f"session hit its {self.timeout_s}s walltime and was killed",
+            )
+        stdout = redact(stdout, (self.api_key,))
+        transcript_path = _write_private(workspace.parent, transcript_stem, ".log", stdout)
+        sample = _collect_hermes_sample(session_home)
+        with contextlib.suppress(OSError):
+            brief_path.unlink()  # the brief holds PR content; don't leave it at rest
+        result = _parse_hermes_result(stdout, sample, process.returncode, transcript_path)
+        # Record this turn so a later resume can restore the context, and hand
+        # back the session id it lives under. Only on a real reply — a failed
+        # turn leaves the prior transcript intact (nothing useful to append).
+        # REDACT before persisting: final_text comes from the sample, not the
+        # already-redacted stdout, so an agent reply that echoed its session key
+        # must not be written to the resume transcript at rest.
+        if not result.is_error:
+            secrets = (self.api_key,)
+            prior_turns.append({"role": "user", "text": redact(brief_text, secrets)})
+            prior_turns.append({"role": "assistant", "text": redact(result.final_text, secrets)})
+            _save_resume_transcript(session_home, session_id, prior_turns)
+        return replace(result, session_id=session_id)
+
+
+@dataclass
+class FakeHarness:
+    """Deterministic in-process harness for tests and dry runs."""
+
+    result: SessionResult
+    script: Any = None  # optional callable(brief_text, workspace) for side effects
+    calls: list[tuple[str, str, str | None]] = field(default_factory=list)
+    supports_resume: bool = True  # a field so tests can exercise the no-resume path
+
+    def run(
+        self, brief_text: str, workspace: Path, resume_session_id: str | None = None
+    ) -> SessionResult:
+        self.calls.append((brief_text, str(workspace), resume_session_id))
+        if self.script is not None:
+            self.script(brief_text, workspace)
+        return self.result