outerloop-science 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev3__py3-none-any.whl

outerloop/init.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import argparse
 import getpass
 import json
+import logging
 import os
 import shutil
 import sys
@@ -33,6 +34,8 @@ from outerloop.cli import ENV_FILE
 from outerloop.image import ensure_image
 from outerloop.paths import write_private
 
+log = logging.getLogger(__name__)
+
 CONFIG_DIR = ENV_FILE.parent
 DEFAULT_PAT_FILE = CONFIG_DIR / "bot_pat"
 API = "https://api.github.com"
@@ -69,6 +72,9 @@ def render_env(
             lines.append(f"OUTERLOOP_ACCOUNT={a.account}")
         if a.partition:  # optional: unset lets Slurm pick its default partition
             lines.append(f"OUTERLOOP_PARTITION={a.partition}")
+        # the checkout stays put until the operator upgrades; `release` follows
+        # the release tags, `main` every merge (docs/install.md)
+        lines.append("OUTERLOOP_AUTO_UPDATE=off")
     if a.image:
         lines.append(f"OUTERLOOP_IMAGE={a.image}")
     elif a.uncontained:
@@ -356,7 +362,8 @@ def _owner_type(owner: str) -> str:
     try:
         with urllib.request.urlopen(req, timeout=15) as resp:
             return str(json.loads(resp.read()).get("type", ""))
-    except Exception:
+    except Exception as exc:
+        log.warning("could not look up the account type of %s: %s", owner, exc)
         return ""
 
 
@@ -684,6 +691,17 @@ def main(argv: list[str] | None = None) -> int:
             if login:
                 write_private(env_path, render_env(answers, effective_pat, bot_login=login))
                 print(f"  posting as {login} (OUTERLOOP_BOT_LOGIN)")
+            else:
+                print(
+                    "  the token's login could not be read — set OUTERLOOP_BOT_LOGIN in "
+                    f"{env_path} before `outerloop start` (the tick skips a target without it)"
+                )
+        else:
+            print(
+                "  OUTERLOOP_BOT_LOGIN not recorded (the check did not pass) — rerun "
+                "`outerloop init --force` with network access, or set it in "
+                f"{env_path} (the tick skips a target without it)"
+            )
     else:
         print("  no PAT set — add OUTERLOOP_PAT_FILE before the agents can open PRs")
     _author_key_hint(answers)

outerloop/intake.py

@@ -13,11 +13,11 @@ from __future__ import annotations
 import logging
 from dataclasses import dataclass
 
-from outerloop.brief import MAX_TASK_CHARS, _cap, _fence
+from outerloop.brief import MAX_TASK_CHARS, cap, code_fence
 from outerloop.contract import Contract
 from outerloop.followup import QUALIFYING_ASSOCIATIONS
 from outerloop.github import is_own_login
-from outerloop.markers import has_label, has_marker, label_name, marker
+from outerloop.markers import has_label, has_marker, marker
 
 log = logging.getLogger(__name__)
 
@@ -29,9 +29,6 @@ RELEASE_MARKER = marker("claim-released")
 # failure must not claim/release (and comment) forever. Same idea as the
 # steward lane's MAX_STEWARD_ATTEMPTS.
 MAX_INTAKE_ATTEMPTS = 3
-# steward work orders carry this label; they are the STEWARD lane's,
-# never the solver's (a solver climb cannot touch env paths anyway)
-STEWARD_LABEL = label_name("steward")
 
 
 @dataclass(frozen=True)
@@ -119,8 +116,8 @@ def issue_hypothesis(task: IssueTask) -> str:
     The author passed the standing gate, so the REQUEST is legitimate; the
     fence marks where quoted text ends and the harness's authority resumes.
     """
-    quoted = _cap(f"{task.title}\n\n{task.body}".strip(), MAX_TASK_CHARS - 400)
-    fence = _fence(quoted)
+    quoted = cap(f"{task.title}\n\n{task.body}".strip(), MAX_TASK_CHARS - 400)
+    fence = code_fence(quoted)
     return (
         f"A maintainer (@{task.author}) opened issue #{task.number} requesting "
         f"work on the `{task.benchmark}` benchmark. Their request:\n"

outerloop/launchlog.py

@@ -0,0 +1,239 @@
+"""The per-run launch ledger: append-only JSON lines in the run directory, one
+record when a sleep's launches are submitted and one when each job's result
+comes back at the wake. It is what `history` reads and what labels a launch in
+the queue view (docs/design/session-watcher.md, "History"). Kernel-owned: the
+run directory is never the session's to write."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from outerloop.syscall import Launch, LaunchResult, launch_jobs
+
+LEDGER = "launches.jsonl"
+# generous: a run is depth_k launches x sleep_k sleeps x the array width, far below this
+MAX_LEDGER_BYTES = 4_000_000
+
+
+def _append(run_dir: Path, rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        return
+    run_dir.mkdir(parents=True, exist_ok=True)
+    path = run_dir / LEDGER
+    # a crash mid-append leaves a torn last line; start on a fresh one so the
+    # torn line is the only record lost, never the next one too
+    torn = False
+    try:
+        with path.open("rb") as fh:
+            fh.seek(-1, 2)
+            torn = fh.read(1) != b"\n"
+    except OSError:
+        pass
+    with path.open("a", encoding="utf-8") as fh:
+        if torn:
+            fh.write("\n")
+        for row in rows:
+            fh.write(json.dumps(row, sort_keys=True) + "\n")
+
+
+def append_submitted(
+    run_dir: Path, *, sleep: int, launches: tuple[Launch, ...], job_ids: list[str], at: float
+) -> None:
+    """One record per launch of a sleep, with the job ids it fanned out to. The
+    ids are positional over `launch_jobs` order, exactly as the park recorded
+    them; a launch whose ids are missing (an older park) gets none. A launch
+    already recorded under this (sleep, name) is not written again: a run
+    re-parks the same sleep through a multi-stage gate, and the first record
+    is the one with the author's words."""
+    known = {
+        (int(row.get("sleep") or 0), str(row.get("name") or ""))
+        for row in read_ledger(run_dir)
+        if row.get("event") == "submitted"
+    }
+    # one id per launch (a sweep is one Slurm job array), or one per task for
+    # a park recorded when arrays were separate jobs
+    per_launch = len(job_ids) == len(launches)
+    rows: list[dict[str, Any]] = []
+    k = 0
+    for launch in launches:
+        n = 1 if per_launch else len(launch_jobs(launch))
+        ids = job_ids[k : k + n]
+        k += n
+        if (sleep, launch.name) in known:
+            continue
+        rows.append(
+            {
+                "event": "submitted",
+                "sleep": sleep,
+                "name": launch.name,
+                "why": launch.why,
+                "minutes": launch.minutes,
+                "array": launch.array,
+                "concurrency": launch.concurrency,
+                "job_ids": list(ids),
+                "at": at,
+            }
+        )
+    _append(run_dir, rows)
+
+
+def append_ended(
+    run_dir: Path,
+    *,
+    sleep: int,
+    results: tuple[LaunchResult, ...],
+    at: float,
+    elapsed_seconds: list[int | None] | None = None,
+) -> None:
+    """One record per job that came back at the wake, keyed to its sleep, with
+    how long it ran when the compute could say (aligned with `results`) and
+    the last line it printed — captured now, because a later launch with the
+    same name overwrites the job dir. A job already recorded as ended under
+    this (sleep, name) is not written again: a submitted park's wake and the
+    author's wake may both see the same jobs."""
+    known = {
+        (int(row.get("sleep") or 0), str(row.get("name") or ""))
+        for row in read_ledger(run_dir)
+        if row.get("event") == "ended"
+    }
+    _append(
+        run_dir,
+        [
+            {
+                "event": "ended",
+                "sleep": sleep,
+                "name": r.name,
+                "exit_code": r.exit_code,
+                "state": r.slurm_state,
+                "elapsed": (
+                    elapsed_seconds[i]
+                    if elapsed_seconds is not None and i < len(elapsed_seconds)
+                    else None
+                ),
+                "last_line": last_line(r.stdout_tail),
+                "at": at,
+            }
+            for i, r in enumerate(results)
+            if (sleep, r.name) not in known
+        ],
+    )
+
+
+def last_line(text: str, cap: int = 160) -> str:
+    """The last non-empty line of a job's output — its result line, as the
+    wake shows the author — on one line and bounded. "" when there is none."""
+    for line in reversed(text.splitlines()):
+        flat = " ".join(line.split())
+        if flat:
+            return flat[:cap]
+    return ""
+
+
+def read_ledger(run_dir: Path) -> list[dict[str, Any]]:
+    """Every record, oldest first; a malformed line is skipped, a missing file
+    is an empty history."""
+    try:
+        with (run_dir / LEDGER).open("rb") as fh:
+            raw = fh.read(MAX_LEDGER_BYTES)
+    except OSError:
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in raw.decode("utf-8", "replace").splitlines():
+        try:
+            row = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(row, dict):
+            rows.append(row)
+    return rows
+
+
+def history(run_dir: Path) -> list[dict[str, Any]]:
+    """Submitted launches in order, each with the ended records of its jobs.
+    The identity is (sleep, name): a name is unique within one sleep only."""
+    rows = read_ledger(run_dir)
+    entries: dict[tuple[int, str], dict[str, Any]] = {}
+    for row in rows:
+        if row.get("event") != "submitted":
+            continue
+        key = (int(row.get("sleep") or 0), str(row.get("name") or ""))
+        entries[key] = {
+            "sleep": row.get("sleep"),
+            "name": row.get("name"),
+            "why": row.get("why", ""),
+            "minutes": row.get("minutes"),
+            "array": row.get("array", 1),
+            "concurrency": row.get("concurrency", 0),
+            "job_ids": list(row.get("job_ids") or []),
+            "submitted_at": row.get("at"),
+            "jobs": [],
+        }
+    for row in rows:
+        if row.get("event") != "ended":
+            continue
+        # an array member is `<name>.<i>`; the dot is outside the name alphabet
+        launch_name = str(row.get("name") or "").split(".", 1)[0]
+        entry = entries.get((int(row.get("sleep") or 0), launch_name))
+        if entry is not None:
+            entry["jobs"].append(
+                {
+                    "name": row.get("name"),
+                    "exit_code": row.get("exit_code"),
+                    "state": row.get("state", ""),
+                    "elapsed": row.get("elapsed"),
+                    "last_line": str(row.get("last_line") or ""),
+                    "ended_at": row.get("at"),
+                }
+            )
+    return list(entries.values())
+
+
+def experiments_rows(run_dir: Path) -> list[dict[str, Any]]:
+    """The pull request's experiments table: one row per job of every launch
+    this run — its sleep, name and why, how it ended and how long it ran, and
+    the last line it printed, all from the ledger (the job dir is overwritten
+    by a later launch of the same name). A job not back yet says so."""
+    rows: list[dict[str, Any]] = []
+    for entry in history(run_dir):
+        ended = {str(j.get("name")): j for j in entry["jobs"]}
+        array = int(entry.get("array") or 1)
+        name = str(entry.get("name") or "")
+        jobs = [name] if array <= 1 else [f"{name}.{k}" for k in range(array)]
+        for job in jobs:
+            j = ended.get(job)
+            rows.append(
+                {
+                    "sleep": entry.get("sleep"),
+                    "launch": name,
+                    "why": str(entry.get("why") or ""),
+                    "array": array,
+                    "concurrency": int(entry.get("concurrency") or 0),
+                    "job": job,
+                    "back": j is not None,
+                    "exit_code": j.get("exit_code") if j else None,
+                    "state": str(j.get("state") or "") if j else "",
+                    "elapsed": j.get("elapsed") if j else None,
+                    "result": str(j.get("last_line") or "") if j else "",
+                }
+            )
+    return rows
+
+
+def why_by_job(run_dir: Path) -> dict[str, dict[str, Any]]:
+    """Slurm job id -> the launch it belongs to (name, why, sleep): how the
+    queue view labels a launch job for every agent."""
+    out: dict[str, dict[str, Any]] = {}
+    for row in read_ledger(run_dir):
+        if row.get("event") != "submitted":
+            continue
+        for job_id in row.get("job_ids") or []:
+            out[str(job_id)] = {
+                "name": row.get("name", ""),
+                "why": row.get("why", ""),
+                "sleep": row.get("sleep"),
+                "array": int(row.get("array") or 1),
+                "concurrency": int(row.get("concurrency") or 0),
+            }
+    return out

outerloop/maintain.py

@@ -0,0 +1,325 @@
+"""The maintenance scan: a read-only agent session over a checkout of a
+repository's default branch that records cleanup, upgrade, test-health and
+performance items as findings, and the digest those findings render into.
+
+It reuses the reviewer's machinery — the FINDINGS_SCHEMA verdict through the
+syscall tool, lenses fanned out and merged by the summarizer, the emit/post
+split — and differs in three places: the brief scans a tree instead of a
+diff, nothing is blocking, and the destination is one rolling issue
+(docs/design/reviewer-infra.md, "Maintenance scan"). Any repository can run
+it from the reusable workflow; the brief assumes nothing about this one."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import urllib.parse
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+
+from outerloop.harness import Harness, backend_id
+from outerloop.markers import marker
+from outerloop.posting import EXPECTED_FAILURES
+from outerloop.review import DEFAULT_SYSCALL_CMD, Finding, ReviewResult, sanitize
+from outerloop.review_agent import emit_envelope
+from outerloop.role_runner import run_role
+from outerloop.rolespec import RoleSpec
+
+log = logging.getLogger(__name__)
+
+MARKER = marker("maintenance-digest")
+DIGEST_TITLE = "Maintainer digest"
+ADVISORY = (
+    "*Advisory findings from `outerloop`. The maintainer decides: items marked "
+    "**Decision** need a call before any change; the rest are mechanical and may "
+    "be taken as work orders. The scan edits nothing.*"
+)
+
+# Each lens is one section of the digest; `general` is the whole checklist.
+# The library lives here; which lenses run is the caller workflow's matrix.
+MAINTENANCE_LENSES: dict[str, str] = {
+    "pathways": (
+        "LENS — dead and unused pathways: symbols, CLI flags, config keys and "
+        "environment knobs with no caller or no documentation; compatibility "
+        "shims and what each still guards; test-only code living in the "
+        "package. Grep across source, tests, scripts and docs before calling "
+        "anything unused."
+    ),
+    "duplication": (
+        "LENS — logic with more than one owner: the same rule implemented in "
+        "two places (two parsers of one file format, two copies of one "
+        "sequence), private helpers imported across modules, argument groups "
+        "or fixtures copied between entry points or test files, version pins "
+        "repeated in several files."
+    ),
+    "structure": (
+        "LENS — size and shape: the largest modules and longest functions "
+        "(measure them), import cycles and the in-function imports that hide "
+        "them, templates or data embedded in code, and the natural seams a "
+        "split would follow."
+    ),
+    "upgrades": (
+        "LENS — dependencies and tooling: pinned versions against the latest "
+        "available (the package index, GitHub releases), CI action versions, "
+        "runner images, linter and type-checker settings that could be "
+        "tightened cheaply, interpreter versions exercised. Name the pin and "
+        "the current upstream for each."
+    ),
+    "tests": (
+        "LENS — test-suite health: the slowest tests and why, real sleeps and "
+        "real subprocesses where a fake would do, fixtures and fakes defined "
+        "several times, tests that no longer pin the behavior they name, "
+        "markers declared but unused."
+    ),
+    "performance": (
+        "LENS — repeated work on the hot path: find the loop or entry point "
+        "the repository runs most often and count what it re-reads, re-lists "
+        "or re-fetches per iteration and per record; caching that is missing, "
+        "network calls without conditional requests, files parsed more than "
+        "once."
+    ),
+    "docs": (
+        "LENS — documentation drift: comments that narrate history instead of "
+        "intent, changelog sections to consolidate, roadmap or design notes "
+        "whose status no longer matches the code, knobs and flags the docs "
+        "never name, wording that disagrees between two documents."
+    ),
+}
+
+SYSTEM_PROMPT = (
+    "You are the maintainer's periodic scan of this repository. You read the whole "
+    "tree, measure rather than guess, and record each item worth doing as a finding. "
+    "Nothing you find blocks anything: the maintainer reads the digest and decides.\n\n"
+    "What to record: cleanup, simplification, upgrade, test-health and performance "
+    "items — what a careful maintainer would put on their own list after a week away. "
+    "Skip style nits a linter already reports and work the repository's own roadmap "
+    "already tracks as planned.\n\n"
+    "Evidence: every item names a file and a line, and a measured fact where one "
+    "exists (a line count, a call count, the pinned and the latest version, a test "
+    "duration). Say what you ran.\n\n"
+    "Shape of each finding:\n"
+    "- --kind change: mechanical, safe for an agent to do in a pull request without a "
+    "design call.\n"
+    "- --kind question: needs the maintainer's decision first (when to drop a "
+    "compatibility path, whether to re-verify a pinned tool, which module owns a "
+    "duplicated rule).\n"
+    "- --kind note: worth knowing, not worth a change.\n"
+    "- --category: the digest section the item belongs to, one of {sections}.\n"
+    '- --detail: start with effort and risk, for example "S, low." (S is under an '
+    "hour, M an afternoon, L a day or more; risk is what could break), then the "
+    "evidence.\n"
+    "- never --blocking.\n\n"
+    "Your concluding notes open the digest: one line on what is healthy, then the "
+    "three items most worth doing, one sentence each."
+)
+
+
+def _investigation(ref: str, syscall_cmd: str) -> str:
+    return (
+        f"The repository is checked out in your working directory at commit {ref}. "
+        "Use Read, Grep and Glob, and run read-only commands in the shell: line "
+        "counts, the test suite with durations, the package manager's outdated "
+        "list, the linter's statistics. Do not modify the tree, do not install "
+        "anything beyond what its own lockfile describes, and do not push or "
+        "post anything — your only product is the verdict.\n\n"
+        "Record each item as you confirm it, one command per item:\n"
+        f"  {syscall_cmd} finding --file <path> [--line N] "
+        "--confidence <low|medium|high> --category <section> --summary <one line> "
+        "--detail <effort, risk, then the evidence> --kind <change|question|note>\n"
+        "When you are done, commit your verdict and end your turn:\n"
+        f"  {syscall_cmd} conclude --notes <what is healthy; the three items most worth doing>\n"
+        "The verdict you commit is your final answer — do not also restate it in a message."
+    )
+
+
+def build_maintenance_brief(
+    repo: str,
+    ref: str,
+    today: str | None = None,
+    *,
+    syscall_cmd: str = DEFAULT_SYSCALL_CMD,
+    lens: str = "",
+) -> str:
+    """The scan brief: the standing prompt, the lens (or every section for
+    `general`), the investigation instruction and the repository line. An
+    unknown lens fails loudly, as the reviewer's does."""
+    if lens and lens != "general" and lens not in MAINTENANCE_LENSES:
+        raise ValueError(f"unknown maintenance lens {lens!r} (have: {sorted(MAINTENANCE_LENSES)})")
+    sections = ", ".join(MAINTENANCE_LENSES)
+    if lens and lens != "general":
+        focus = MAINTENANCE_LENSES[lens]
+    else:
+        focus = "Cover every section:\n\n" + "\n\n".join(MAINTENANCE_LENSES.values())
+    header = f"Today's date: {today}\n" if today else ""
+    header += f"Repository: {repo} at {ref}"
+    return (
+        f"{SYSTEM_PROMPT.format(sections=sections)}\n\n{focus}\n\n"
+        f"{_investigation(ref, syscall_cmd)}\n\n{header}\n"
+    )
+
+
+_KIND_ORDER = {"question": 0, "change": 1, "suggestion": 1, "note": 2}
+_CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}
+_LABEL = {"question": "**Decision.** ", "note": "*Note.* "}
+
+
+def _item(finding: Finding, repo: str, ref: str) -> str:
+    # backticks stripped: a file value containing one would close the code
+    # span and render model markdown inline (same rule as the review body)
+    safe_file = finding.file.replace("`", "")
+    where = f"`{safe_file}`" + (f":{finding.line}" if finding.line else "")
+    link = (
+        f"https://github.com/{repo}/blob/{urllib.parse.quote(ref)}/{urllib.parse.quote(safe_file)}"
+    )
+    if finding.line:
+        link += f"#L{finding.line}"
+    summary = finding.summary.rstrip(".!?…")
+    if summary.count("`") % 2:
+        summary += "`"
+    detail = finding.detail + ("`" if finding.detail.count("`") % 2 else "")
+    label = _LABEL.get(finding.kind, "")
+    return f"- {label}**{summary}.** {detail} ([{where}]({link}); {finding.confidence})"
+
+
+def render_digest(
+    result: ReviewResult,
+    *,
+    repo: str,
+    ref: str,
+    today: str,
+    reviewed_by: str,
+) -> str:
+    """The rolling issue's body: marker first, the header and the advisory
+    line, the counts, the scan's own summary, then one section per category
+    with decisions first. Every string in `result` is already sanitized by
+    `result_from_data`; the marker leads so the poster can find the issue."""
+    findings = result.findings
+    decisions = sum(1 for f in findings if f.kind == "question")
+    notes = sum(1 for f in findings if f.kind == "note")
+    mechanical = len(findings) - decisions - notes
+    who = sanitize(reviewed_by, 120) or "unattributed"
+    lines = [
+        MARKER,
+        f"**{DIGEST_TITLE}** — {repo} at `{ref[:8]}` on {today}; scanned by `{who}`.",
+        "",
+        ADVISORY,
+        "",
+        f"{len(findings)} items: {decisions} need a decision, {mechanical} are "
+        f"mechanical, {notes} are notes.",
+        "",
+    ]
+    if result.notes:
+        lines += [result.notes, ""]
+    by_section: dict[str, list[Finding]] = {}
+    for f in findings:
+        section = f.category if f.category in MAINTENANCE_LENSES else "other"
+        by_section.setdefault(section, []).append(f)
+    for section in [*MAINTENANCE_LENSES, "other"]:
+        items = by_section.get(section)
+        if not items:
+            continue
+        items.sort(key=lambda f: (_KIND_ORDER.get(f.kind, 2), _CONFIDENCE_ORDER[f.confidence]))
+        lines += [f"### {section}", ""]
+        lines += [_item(f, repo, ref) for f in items]
+        lines.append("")
+    lines.append(
+        "_Each scan replaces this body; earlier digests are in the edit history. "
+        "Run a scan by hand from the Actions tab (maintenance → Run workflow)._"
+    )
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_stub(detail: str, *, repo: str, ref: str, today: str, who: str) -> str:
+    """What the poster writes when the scan could not run: the reason, on the
+    digest issue, never silence."""
+    reason = sanitize(detail, 300)
+    by = f" ({sanitize(who, 120)})" if who else ""
+    return (
+        f"{MARKER}\n**{DIGEST_TITLE}** — the scan of {repo} at `{ref[:8]}` on {today} "
+        f"could not run{by}: {reason}"
+    )
+
+
+def run_maintenance_scan(
+    repo: str,
+    ref: str,
+    harness: Harness,
+    workspace: Path,
+    *,
+    spec: RoleSpec | None = None,
+    emit_path: Path,
+    today: str | None = None,
+    lens: str = "",
+) -> str | None:
+    """One lens session over `workspace` (a default-branch checkout the caller
+    prepared and sanitized). EVERY outcome writes an envelope for the posting
+    job — findings, or a skip-stub naming why — so a missing artifact always
+    means a broken session. Returns "emitted", or None when it could not
+    produce a verdict. Advisory: never raises the expected failures."""
+    from outerloop.roles import maintainer_spec
+
+    spec = spec or maintainer_spec()
+    today = today or datetime.now(UTC).date().isoformat()
+    try:
+        from outerloop.syscall import tool_command
+
+        brief = build_maintenance_brief(
+            repo, ref, today, syscall_cmd=tool_command(workspace), lens=lens
+        )
+        role_result = run_role(spec, harness, brief, workspace)
+        if not role_result.ok or role_result.data is None:
+            detail = role_result.error or role_result.session.stop_reason
+            log.warning("maintenance scan produced no verdict on %s (%s): %s", repo, lens, detail)
+            emit_envelope(
+                emit_path,
+                repo,
+                0,
+                kind="skip-stub",
+                detail=detail,
+                reviewed_by=backend_id(harness),
+                lens=lens,
+            )
+            return None
+        emit_envelope(
+            emit_path,
+            repo,
+            0,
+            kind="findings",
+            data=role_result.data,
+            reviewed_by=backend_id(harness),
+            lens=lens,
+        )
+        cost = role_result.session.cost_usd
+        log.info(
+            "emitted maintenance findings for %s (%s; cost=%s turns=%d)",
+            repo,
+            lens or "general",
+            f"${cost:.2f}" if cost else "unreported",
+            role_result.session.num_turns,
+        )
+        return "emitted"
+    except EXPECTED_FAILURES as exc:  # advisory: never red the repository's Actions
+        log.warning("maintenance scan did not complete: %s: %s", type(exc).__name__, exc)
+        with contextlib.suppress(Exception):
+            emit_envelope(
+                emit_path,
+                repo,
+                0,
+                kind="skip-stub",
+                detail=f"{type(exc).__name__}: {exc}",
+                reviewed_by=backend_id(harness),
+                lens=lens,
+            )
+        return None
+
+
+def lens_names(lenses: Iterable[str]) -> list[str]:
+    """The lens names a caller configured, `general` included, unknown ones
+    refused — so a misspelled matrix entry fails at configuration time."""
+    out = []
+    for name in lenses:
+        if name != "general" and name not in MAINTENANCE_LENSES:
+            raise ValueError(f"unknown maintenance lens {name!r}")
+        out.append(name)
+    return out